Long-Range AutoRegression

Long-Range AutoRegression#

The Long-Range AutoRegression class implements a Long-Range AR model to generate synthetic time series of vectors with the same short-range and long-range temporal statistics as input data.

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

Constructor#

class aomodel.LongRangeAR(vector_dimensionality=None, time_lags=1, num_low_pass_filters=0, load_file=None, prediction_window_structure=None, print_statements=True, **kwargs)[source]#

Bases: object

Implements a Long-Range Auto-Regressive model for generating synthetic time series of vectors with the same spatial and temporal statistics as an input data set. For a thorough description of this model, see Theory. This implementation of Long-Range AR is partially adapted from a Vector AR model, which is described in [1].

Parameters:

  • vector_dimensionality (int, optional) – [Default=None] length of the data vectors.

    • If set to None, then a load_file must be provided. In this case, the class loads the vector dimension 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 self.define_prediction_window.

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

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

  • **kwargs (dict, optional) – Keyword arguments for legacy support.

    • prediction_window_distance (int) – an index distance used to define the prediction window. Passed as input to self.define_prediction_window.

    • prediction_subspace_dimension (int) – number of (top) vector components to use for linear time prediction. If included, the function uses this subspace as the prediction window. A prediction subspace and a prediction window distance cannot both be used. Passed as input to self.define_prediction_window.

    • 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#

LongRangeAR.fit(training_data, cutoff_frequency=None, tps_block_size=None, print_statements=True)[source]#

Calculates the model prediction weights and noise modulation matrix using least squares regression from the input data values and Principal Component Analysis (respectively).

Parameters:

  • training_data (ndarray) – numpy 2-D array of shape (data vector dimensionality, number of time samples) containing the data to fit.

  • 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 data.

    • 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.

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

Saving and Loading Models#

LongRangeAR.save(save_file)[source]#

Saves all necessary Long-Range AR model information to re-construct the trained LongRangeAR instance.

Parameters:

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

LongRangeAR.load(load_file, print_statements=True)[source]#

Loads the Long-Range AR 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=True] whether to print out model loading statements.

Generating Synthetic Data#

LongRangeAR.run(num_time_steps, initial_vectors=None, print_statements=True)[source]#

Uses a trained Long-Range AR model (as set by either self.fit or self.load) to generate synthetic data with the same temporal statistics as the training data.

Parameters:

  • num_time_steps (int) – the number of time-steps of synthetic data vectors 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 linear predictive model.

    • If set to None, vectors of zeros are used.

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

Returns:

synthetic_data (ndarray) – a 2-D numpy array of shape (data vector dimensionality, num_time_steps) 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).

Defining Model Parameters#

LongRangeAR.create_model_structure(prediction_window_structure=None, **kwargs)[source]#

Creates the linear predictive model structure by specifying:

  1. The “prediction window” indicating which components of previous vectors to use for linear prediction (i.e., for which the model estimates prediction weights).

  2. The time-lags (i.e., backwards time-index shifts) to use for next-state prediction.

  3. The low-pass filter structure to use in next-state prediction. This includes both the number of low-pass filters and the parameters of each filter.

Note

Calling this function re-defines the model structure. If there is already an existing structure including prediction weights and low-pass filter parameters, calling this function resets both of these objects. Only call this function if you intend to then call self.fit to estimate the prediction weights and low-pass filter parameters from data.

Parameters:

  • prediction_window_structure (PredictionWindowStructure, optional) – [Default=None] an instance of a sub-class of PredictionWindowStructure implementing get_mask(). Used to define the prediction window mask.

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

  • **kwargs (dict, optional) – Keyword arguments for prediction window structure configuration:

    • prediction_window_mask (ndarray) – numpy boolean 2-D array of shape (data vector dimensionality, data vector dimensionality) indicating which prediction weights to solve for in the model fitting. Remaining weights are automatically set to zero. This mask determines the prediction mask for each time-lag and low-pass filter.

    • prediction_window_distance (int) – an index distance used to define the prediction window.

    • prediction_subspace_dimension (int) – number of (top) vector components to use for linear time prediction. If included, the function uses this subspace as the prediction window. A prediction subspace and a prediction window distance cannot both be used.

    • predicted_components (ndarray) – numpy 1-D integer array containing the indices of the data vector components for which the model will compute prediction weights.

    • time_lags (Union[int, list, ndarray, None]) – 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) – the number of low-pass filters to use in the linear time predictive model.

Raises:

ValueError – if both prediction_window_distance and prediction_subspace_dimension are used.

Properties#

property LongRangeAR.prediction_window_mask#

Computes the full prediction window mask by extending the base mask (which contains the prediction window mask for each time-lag) to all time-lags and low-pass filters.

Returns:

prediction_window_mask (ndarray) – numpy 2-D boolean array of shape (self.vector_dimensionality, total_lags * self.vector_dimensionality) containing the prediction window mask.

property LongRangeAR.predicted_components#

Finds the indices of the vector components for which any non-zero prediction weights have been assigned by the prediction window mask.

Returns:

predicted_components (ndarray) – numpy 1-D integer array containing the indices of the predicted components.

property LongRangeAR.remaining_components#

Finds the indices of the vector components for which there are no prediction weights assigned by the prediction window mask. These components are not predicted, and instead are modeled purely as noise.

Returns:

remaining_components (ndarray) – numpy 1-D array containing the indices of the remaining (non-predicted) vector components.

property LongRangeAR.num_low_pass_filters#

Finds the number of low-pass filters used in the Long-Range AR model.

Returns:

num_low_pass_filters (int) – the number of low-pass filters.

property LongRangeAR.num_prediction_weights#

Computes the number of (non-zero) prediction weights in the Long-Range AR model.

Returns:

num_prediction_weights (int) – the number of (non-zero) prediction weights.

property LongRangeAR.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.