pysensors.reconstruction package

Module contents

class pysensors.reconstruction.SSPOR(basis=None, optimizer=None, n_sensors=None)[source]

Bases: BaseEstimator

Sparse Sensor Placement Optimization for Reconstruction: a model for selecting the best sensor locations for state reconstruction.

Given a basis in which to represent the state (e.g. PCA modes) along with measurement data, a SSPOR instance produces a list of sensor locations (a permutation of the numbers 0, 1, …, n_input_features - 1) ranked in descending order of importance. One can then select the top k sensors and take future measurements at that limited set of locations.

The overall time complexity of fitting a SSPOR object is O(n_basis_modes * n_input_features * n_input_features) plus the cost for fitting the basis. Different bases have different complexities. The space complexity is O(n_basis_modes * n_input_features).

Parameters:

  • basis (basis object, optional (default pysensors.basis.Identity)) – Basis in which to represent the data. Default is the identity basis (i.e. raw features).

  • optimizer (optimizer object, optional (default pysensors.optimizers.QR)) – Optimization method used to rank sensor locations.

  • n_sensors (int, optional (default n_input_features)) – Number of sensors to select. Note that s = SSPOR(n_sensors=10); s.fit(x) is equivalent to s = SSPOR(); s.fit(x); s.set_number_of_sensors(10).

Attributes:

  • n_basis_modes (int) – Number of basis modes considered during fitting.

  • basis_matrix_ (np.ndarray) – Internal representation of the basis.

  • ranked_sensors_ (np.ndarray) – Sensor locations ranked in descending order of importance.

  • singular_values (np.ndarray) – Normalized singular values of the fitted data

Examples

>>> import numpy as np
>>> from pysensors import SSPOR
>>>
>>> x = np.linspace(0, 1, 501)
>>> monomials = np.vander(x, 15).T
>>>
>>> model = SSPOR(n_sensors=5)
>>> model.fit(monomials)
SSPOR(basis=Identity(n_basis_modes=15), n_sensors=5, optimizer=QR())
>>> print(model.selected_sensors)
[500 377   0 460 185]
>>> print(x[model.selected_sensors])
[1.    0.754 0.    0.92  0.37 ]
>>> model.set_n_sensors(7)
>>> print(x[model.selected_sensors])
[1.    0.754 0.    0.92  0.37  0.572 0.134]
>>> f = np.sin(3*x)
>>> f_pred = model.predict(f[model.selected_sensors], method='unregularized')
>>> print(np.linalg.norm(f - f_pred))
0.022405698005838044
fit(x, quiet=False, prefit_basis=False, seed=None, **optimizer_kws)[source]

Fit the SSPOR model, determining which sensors are relevant.

Parameters:

  • x (array-like, shape (n_samples, n_input_features)) – Training data.

  • quiet (boolean, optional (default False)) – Whether or not to suppress warnings during fitting.

  • prefit_basis (boolean, optional (default False)) – Whether or not the basis has already been fit to x. For example, you may have already fit and experimented with a SVD object to determine the optimal number of modes. This option allows you to avoid an unnecessary SVD.

  • seed (int, optional (default None)) – Seed for the random number generator used to shuffle sensors after the self.basis.n_basis_modes sensor. Most optimizers only rank the top self.basis.n_basis_modes sensors, leaving the rest virtually untouched. As a result the remaining samples are randomly permuted.

  • optimizer_kws (dict, optional) – Keyword arguments to be passed to the get_sensors method of the optimizer.

Returns:

self

Return type:

a fitted SSPOR instance

predict(x, method=None, prior='decreasing', noise=None, **solve_kws)[source]

Predict values at all positions given measurements at sensor locations.

Parameters:

  • x (array-like, shape (n_samples, n_sensors)) – Measurements from which to form prediction. The measurements should be taken at the sensor locations specified by self.get_selected_sensors().

  • method ({'unregularized', None}, optional) – If None (default), performs regularized reconstruction using the prior and noise. If ‘unregularized’, uses direct or least-squares inversion depending on matrix shape.

  • prior (str or np.ndarray, shape (n_basis_modes,), optional) – (default=’decreasing’) Prior Covariance Vector, typically a scaled identity vector or a vector containing normalized singular values. If ‘decreasing’, normalized singular values are used.

  • noise (float (default None)) – Magnitude of the gaussian uncorrelated sensor measurement noise. If None, noise will default to the average of the computed prior.

  • solve_kws (dict, optional) – keyword arguments to be passed to the linear solver used to invert the basis matrix.

Returns:

y – Predicted values at every location.

Return type:

numpy array, shape (n_samples, n_features)

get_selected_sensors()[source]

Get the indices of the sensors chosen by the model.

Returns:

sensors – Indices of the sensors chosen by the model (i.e. the sensor locations) ranked in descending order of importance.

Return type:

numpy array, shape (n_sensors,)

property selected_sensors

Get the indices of the sensors chosen by the model.

Returns:

sensors – Indices of the sensors chosen by the model (i.e. the sensor locations) ranked in descending order of importance.

Return type:

numpy array, shape (n_sensors,)

get_all_sensors()[source]

Get a ranked list consisting of all the sensors. The sensors are given in descending order of importance.

Returns:

sensors – Indices of sensors in descending order of importance.

Return type:

numpy array, shape (n_features,)

property all_sensors

Get a ranked list consisting of all the sensors. The sensors are given in descending order of importance.

Returns:

sensors – Indices of sensors in descending order of importance.

Return type:

numpy array, shape (n_features,)

set_number_of_sensors(n_sensors)[source]

Set n_sensors, the number of sensors to be used for prediction.

Parameters:

n_sensors (int) – The number of sensors. Must be a positive integer. Cannot exceed the number of available sensors (n_features).

set_n_sensors(n_sensors)[source]

A convenience function accomplishing the same thing as set_number_of_sensors. Set n_sensors, the number of sensors to be used for prediction.

Parameters:

n_sensors (int) – The number of sensors. Must be a positive integer. Cannot exceed the number of available sensors (n_features).

update_n_basis_modes(n_basis_modes, x=None, quiet=False)[source]

Re-fit the SSPOR object using a different value of n_basis_modes.

This method allows one to relearn sensor locations for a different number of basis modes _without_ re-fitting the basis in many cases. Specifically, if n_basis_modes <= self.basis.n_basis_modes then the basis does not need to be refit. Otherwise this function does not save any computational resources.

Parameters:

  • n_basis_modes (positive int, optional (default None)) – Number of basis modes to be used during fit. Must be less than or equal to n_samples.

  • x (numpy array, shape (n_examples, n_features), optional (default None)) – Only used if n_basis_modes exceeds the number of available basis modes for the already fit basis.

  • quiet (boolean, optional (default False)) – Whether or not to suppress warnings during refitting.

score(x, y=None, score_function=None, score_kws={}, solve_kws={})[source]

Compute the reconstruction error for a given set of measurements.

Parameters:

  • x (numpy array, shape (n_examples, n_features)) – Measurements with which to compute the score. Note that x should consist of measurements at every location, not just the recommended sensor location, i.e. its shape should be (n_examples, n_features) rather than (n_examples, n_sensors).

  • y (None) – Dummy input to maintain compatibility with Scikit-learn.

  • score_function (callable, optional (default None)) – Function used to compute the score. Should have the call signature score_function(y_true, y_pred, **score_kws). Default is the negative of the root mean squared error (sklearn expects higher scores to correspond to better performance).

  • score_kws (dict, optional) – Keyword arguments to be passed to score_function. Ignored if score_function is None.

  • solve_kws (dict, optional) – Keyword arguments to be passed to the predict method.

Returns:

score – The score.

Return type:

float

reconstruction_error(x_test, sensor_range=None, score=None, **solve_kws)[source]

Compute the reconstruction error for different numbers of sensors.

Parameters:

  • x_test (numpy array, shape (n_examples, n_features)) – Measurements to be reconstructed.

  • sensor_range (1D numpy array, optional (default None)) – Numbers of sensors at which to compute the reconstruction error. If None, will be set to [1, 2, … , min(n_sensors, basis.n_basis_modes)].

  • score (callable, optional (default None)) – Function used to compute the reconstruction error. Should have the signature score(x, x_pred). If None, the root mean squared error is used.

  • solve_kws (dict, optional) – Keyword arguments to be passed to the linear solver.

Returns:

error – Reconstruction scores for each number of sensors in sensor_range.

Return type:

numpy array, shape (len(sensor_range),)

std(prior, noise=None)[source]

Compute standard deviation of noise in each pixel of the reconstructed state.

See the following reference for more information

Klishin, Andrei A., et. al. Data-Induced Interactions of Sparse Sensors. 2023. arXiv:2307.11838 [cond-mat.stat-mech]

Parameters:

  • prior (str or np.ndarray, shape (n_basis_modes,), optional) – (default=’decreasing’) Prior Covariance Vector, typically a scaled identity vector or a vector containing normalized singular values. If ‘decreasing’, normalized singular values are used.

  • noise (float (default None)) – Magnitude of the gaussian uncorrelated sensor measurement noise. If None, noise will default to the average of the computed prior.

Returns:

sigma – Level of uncertainty of each pixel of the reconstructed state

Return type:

numpy array, shape (n_features,)

one_pt_energy_landscape(prior='decreasing', noise=None)[source]

Compute the one-point energy landscape of the sensors

See the following reference for more information

Klishin, Andrei A., et. al. Data-Induced Interactions of Sparse Sensors. 2023. arXiv:2307.11838 [cond-mat.stat-mech]

Parameters:

  • prior (str or np.ndarray, shape (n_basis_modes,), optional) – (default=’decreasing’) Prior Covariance Vector, typically a scaled identity vector or a vector containing normalized singular values. If ‘decreasing’, normalized singular values are used.

  • noise (float (default None)) – Magnitude of the gaussian uncorrelated sensor measurement noise. If None, noise will default to the average of the computed prior.

Return type:

np.ndarray, shape (n_features,)

set_fit_request(*, prefit_basis: bool | None | str = '$UNCHANGED$', quiet: bool | None | str = '$UNCHANGED$', seed: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$') → SSPOR

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • prefit_basis (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for prefit_basis parameter in fit.

  • quiet (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for quiet parameter in fit.

  • seed (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for seed parameter in fit.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in fit.

Returns:

self – The updated object.

Return type:

object

set_predict_request(*, method: bool | None | str = '$UNCHANGED$', noise: bool | None | str = '$UNCHANGED$', prior: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$') → SSPOR

Configure whether metadata should be requested to be passed to the predict method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • method (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for method parameter in predict.

  • noise (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for noise parameter in predict.

  • prior (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for prior parameter in predict.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in predict.

Returns:

self – The updated object.

Return type:

object

set_score_request(*, score_function: bool | None | str = '$UNCHANGED$', score_kws: bool | None | str = '$UNCHANGED$', solve_kws: bool | None | str = '$UNCHANGED$', x: bool | None | str = '$UNCHANGED$') → SSPOR

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to score.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • score_function (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for score_function parameter in score.

  • score_kws (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for score_kws parameter in score.

  • solve_kws (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for solve_kws parameter in score.

  • x (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for x parameter in score.

Returns:

self – The updated object.

Return type:

object

two_pt_energy_landscape(selected_sensors, prior='decreasing', noise=None)[source]

Compute the two-point energy landscape of the sensors. If selected_sensors is a singular sensor, the landscape will be the two point energy interations of that sensor with the remaining sensors. If selected_sensors is a list of sensors, the landscape will be the sum of two point energy interactions of the selected sensors with the remaining sensors.

See the following reference for more information

Klishin, Andrei A., et. al. Data-Induced Interactions of Sparse Sensors. 2023. arXiv:2307.11838 [cond-mat.stat-mech]

Parameters:

  • prior (str or np.ndarray, shape (n_basis_modes,), optional) – (default=’decreasing’) Prior Covariance Vector, typically a scaled identity vector or a vector containing normalized singular values. If ‘decreasing’, normalized singular values are used.

  • noise (float (default None)) – Magnitude of the gaussian uncorrelated sensor measurement noise. If None, noise will default to the average of the computed prior.

  • selected_sensors (list) – Indices of selected sensors for two point energy computation.

Return type:

np.ndarray, shape (n_features,)