ReVAR

ReVAR#

The ReVAR class implements ReVAR (Re-whitened Vector AutoRegression), which combines the PCA and Long-Range AutoRegression modules to generate synthetic time series of images with the same spatial and temporal statistics as input data.

This implementation is object-oriented, with the ReVAR class used to both i) fit the model to measured data and ii) generate synthetic data.

Constructor#

class aomodel.ReVAR(data_mask=None, time_lags=1, num_low_pass_filters=0, load_file=None, prediction_window_structure=None, **kwargs)[source]#

Bases: LongRangeAR

Implements the Re-whitened Vector AutoRegression (ReVAR) algorithm to generate synthetic time series of images with the same spatial and temporal statistics as an input data set. For a thorough description of this model, see Theory.

Parameters:

  • data_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, then load_file must be provided. In this case, the class loads the mask from the file.

  • time_lags (Union[int, list, ndarray], optional) – [Default=1] either an integer, list, or numpy 1-D array indicating the time lags to use for the model.

    • If time_lags is an integer, the function uses the previous time-steps up to this integer value.

    • If time_lags is a list or numpy 1-D array, the model uses these time lags.

  • num_low_pass_filters (int, optional) – [Default=0] the number of low-pass filters to use in the linear time predictive model.

  • load_file (str, optional) – [Default=None] directory to a file from which the model’s instance variables can be loaded.

  • prediction_window_structure (PredictionWindowStructure, optional) – [Default=None] an instance of a sub-class of PredictionWindowStructure implementing get_mask(). Passed as input to the constructor of LongRangeAR.

    • If set to None, the method builds a prediction window structure from **kwargs.

  • **kwargs (dict, optional) – Keyword arguments passed to LongRangeAR.

    • prediction_subspace_dimension (int) – number of (top) vector components to use for linear time prediction.

    • low_pass_filter_params (ndarray) – numpy 1-D array of length num_low_pass_filters containing the parameters of each low-pass filter.

Model Fitting#

ReVAR.fit(training_data, percent_variance=None, cutoff_frequency=None, tps_block_size=None)[source]#

Estimates the parameters of ReVAR from training data. Uses LongRangeAR.fit to compute the prediction weights, low-pass filter parameters (if used), and noise modulation matrix.

Parameters:

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

  • percent_variance (float, optional) – [Default=None] percent variance of the subspace to use for linear time prediction in the Long-Range AR model.

    • If set to None, linear prediction is applied to all principal coefficients.

  • cutoff_frequency (float, optional) – [Default=None] cutoff frequency (in units of cycles/sample) to use for estimation of the low-pass filter parameters.

    • If set to None and low-pass filters are used, this method estimates the cutoff frequency as the peak frequency of the temporal power spectrum (TPS) of the training data.

  • tps_block_size (int, optional) – [Default=None] time-block size for calculating the TPS of the principal coefficients.

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

ReVAR.pre_processing(training_data, percent_variance=None)[source]#

Pre-processing step of ReVAR parameter estimation: i) normalize the training data by its sample mean and standard deviation vectors and ii) compute a spatial PCA from the normalized training data.

Parameters:

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

  • percent_variance (float, optional) – [Default=None] percent variance of the subspace to use for linear time prediction in the LongRangeAR model.

    • If set to None, linear prediction is applied to all principal coefficients.

Returns:

principal_coefficients (ndarray) – numpy 2-D array of shape (vector dimensionality, number of images) containing the principal coefficient vectors of the (normalized) training data.

Saving and Loading Models#

ReVAR.save(save_file)[source]#

Saves all necessary information to re-construct the trained ReVAR model with a new instance.

Parameters:

save_file (str) – directory of the file to which the data will be saved

ReVAR.load(load_file, print_statements=False)[source]#

Loads the ReVAR model information as saved by the self.save method and re-constructs the model.

Parameters:

  • load_file (str) – directory of the file from which the data will be loaded

  • print_statements (str, optional) – [Default=False] whether to print out LongRangeAR loading statements.

Generating Synthetic Data#

ReVAR.run(num_time_steps, initial_vectors=None, print_statements=False)[source]#

Runs the ReVAR data synthesis algorithm using estimated parameters from training data, as set by either the self.fit or self.load instance methods. This model generates synthetic data with the same statistics as training data.

Parameters:

  • num_time_steps (int) – the number of time-steps of synthetic data to generate.

  • initial_vectors (ndarray, optional) – [Default=None] numpy 2-D array of shape (data vector dimensionality, number of time lags) containing the initial data vectors used by the data synthesis algorithm.

    • If set to None, generates initial vectors that have the same spatial distribution as the principal coefficients of training data.

  • print_statements (str, optional) – [Default=False] whether to print out LongRangeAR statements.

Returns:

synthetic_data (ndarray) – numpy 3-D array of shape (num_time_steps, image height, image width) containing the model’s output synthetic data.

Raises:

RuntimeError – if the attribute self._if_fitted is not True (indicating that the model has not been fit).

Properties#

property ReVAR.num_parameters#

Calculates the number of parameters in the model. These parameters are estimated from training data and used to generate synthetic data.

Returns:

total_num_params (int) – total number of parameters in the model.

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