Metrics

Metrics#

The Metrics module contains functions which compute the statistics of either measured or synthetic data. Comparison of these statistics between measured and synthetic data can be used to evaluate the accuracy of the methods used in ReVAR, Long-RangeAR, and PCA..

  • slopes_tps and temporal_power_spectrum evaluate the temporal statistics of data.

  • structure_function_2d evaluate spatial statistics of data.

Functions:

slopes_tps(data_values[, locations, axis, ...])

Takes the temporal power spectrum (TPS) of the slopes (i.e., gradient) of input data with respect to a specified axis.

temporal_power_spectrum(data_values[, ...])

Uses the vector_temporal_psd function from Estimation to estimate the temporal power spectrum (TPS) of an input time series of 2-D arrays (i.e., images).

structure_function_2d(data[, mask, ...])

Estimate the 2-D spatial structure function of an input time-series of 2-D data.
aomodel.metrics.slopes_tps(data_values, locations=None, axis=2, time_block_size=None, sampling_frequency=None, remove_mean=True, use_overlapping_blocks=True)[source]#

Takes the temporal power spectrum (TPS) of the slopes (i.e., gradient) of input data with respect to a specified axis. This function i) approximates the slopes of the data (using a second order finite difference method) with respect to the specified axis and ii) calls temporal_power_spectrum to estimate the TPS of these slopes.

Parameters:

  • data_values (ndarray) – numpy 3-D array of shape (number of images, image height, image width) containing the data values.

  • locations (Union[int, ndarray], optional) – [Default=None] either a numpy 1-D array containing the coordinates of the axis to which the gradient is to be calculated or an integer specifying a uniform distance between bins. Sent as an argument to numpy.gradient.

    • If set to None, this argument is not included in the call to numpy.gradient.

  • axis (int, optional) – [Default=2] the axis of data values to take the gradient with respect to.

    • If axis = 2, the gradient is calculated with respect to the x-axis.

    • If axis = 1, the gradient is calculated with respect to the y-axis.

    • If axis = 0, the gradient is calculated with respect to time.

  • time_block_size (int, optional) – [Default=None] the size of each time block to use for the TPS estimation. The full time-series is broken up into “time-blocks” of the indicated size. For each time-block, the TPS is calculated independently. The final TPS calculation is then the average over each time-block. This value must be a positive integer and can be at most the number of time-steps in data_values.

    • If set to None, the function finds the block size so that the TPS estimates are averaged over at least 100 blocks. This ensures that the signal-to-noise ratio of each 1-D TPS estimate is at least 10.

  • sampling_frequency (float, optional) – [Default=None] the temporal sampling frequency of the discrete-time signal data_values. This input should be included if the desired TPS units are energy per unit time instead of energy per unit sample. In this case, the frequency bins are in units of cycles per unit time instead of cycles per unit sample.

    • If set to None, the TPS units are energy/sample and the frequency units are cycles/sample.

  • remove_mean (bool, optional) – [Default=True] choice of removing the temporal mean of each vector component before computing the TPS. It is recommended to set this to True in most cases. If set to False, the lowest frequencies may be offset.

  • use_overlapping_blocks (bool, optional) – [Default=True] whether to use overlapping time-blocks when calculating the TPS. If set to True, then the time-blocks will have a 50% overlap. This method allows one to maintain the same block size while also reducing noise in the TPS calculation. If set to False, then the time-blocks will have no overlap.

Returns:

  • frequencies (ndarray) – numpy 1-D array containing the frequency bins of the TPS calculation.

  • tps_estimate (ndarray) – numpy 1-D array containing the TPS estimates for each frequency bin.

aomodel.metrics.structure_function_2d(data, mask=None, compute_square_root=False)[source]#

Estimate the 2-D spatial structure function of an input time-series of 2-D data. As described in [5, 6], the 2-D structure function is defined as a function of a two-dimensional separation vector, instead of a one-dimensional separation distance. This function first normalizes the data by its sample mean and standard deviation (which is called the quasi-homogeneous structure matrix in [8]) and then estimates the structure function.

Parameters:

  • data (ndarray) – numpy 3-D array of shape (number of images, image height, image width) containing the data from which we would like to estimate the 2-D structure function.

  • mask (ndarray, optional) – [Default=None] numpy 2-D boolean array of shape (image height, image width) indicating which 2-D indices of each time-step correspond to valid pixel values.

    • If set to None, the function infers the mask based on which data values are “nan.”

  • compute_square_root (bool, optional) – [Default=False] choice of whether to compute (and return) the square root of the structure function values (instead of the structure function values themselves).

Returns:

  • structure_function_inputs (ndarray) – numpy 2-D array of shape (number of pixel differences, 2) containing the 2-D inputs to the structure function (in polar coordinates).

  • structure_function (ndarray) – numpy 1-D array of length (number of pixel differences) containing the estimated structure function values (in the same order as the first output).

aomodel.metrics.temporal_power_spectrum(data_values, time_block_size=None, mask=None, sampling_frequency=None, remove_mean=True, use_overlapping_blocks=True)[source]#

Uses the vector_temporal_psd function from Estimation to estimate the temporal power spectrum (TPS) of an input time series of 2-D arrays (i.e., images).

Parameters:

  • data_values (ndarray) – numpy 3-D array of shape (number of images, image height, image width) containing the data values

  • time_block_size (int, optional) – [Default=None] the size of each time block to use for the TPS estimation. The full time-series is broken up into “time-blocks” of the indicated size. For each time-block, the TPS is calculated independently. The final TPS calculation is then the average over each time-block. This value must be a positive integer and can be at most the number of time-steps in data_values.

    • If set to None, the function finds the block size so that the TPS estimates are averaged over at least 100 blocks. This ensures that the signal-to-noise ratio of each 1-D TPS estimate is at least 10.

  • mask (ndarray, optional) – [Default=None] numpy 2-D boolean array of shape (image height, image width) indicating which 2-D indices of each time-step correspond to valid pixel values.

    • If set to None, the function infers the mask based on which data values are “nan.”

  • sampling_frequency (float, optional) – [Default=None] the temporal sampling frequency of the discrete-time signal data_values. This input should be included if the desired TPS units are energy per unit time instead of energy per unit sample. In this case, the frequency bins are in units of cycles per unit time instead of cycles per unit sample.

    • If set to None, the TPS units are energy/sample and the frequency units are cycles/sample.

  • remove_mean (bool, optional) – [Default=True] choice of removing the temporal mean of each vector component before computing the TPS. It is recommended to set this to True in most cases. If set to False, the lowest frequencies may be offset.

  • use_overlapping_blocks (bool, optional) – [Default=True] whether to use overlapping time-blocks when calculating the TPS. If set to True, then the time-blocks will have a 50% overlap. This method allows one to maintain the same block size while also reducing noise in the TPS calculation. If set to False, then the time-blocks will have no overlap.

Returns:

  • frequencies (ndarray) – numpy 1-D array containing the frequency bins of the TPS calculation.

  • tps_estimate (ndarray) – numpy 1-D array containing the TPS estimates for each frequency bin.

Disclaimer: Approved for public release; distribution is unlimited. Public Affairs release approval # AFRL-2026-1309.