Subspaces¶

Base module for Active Subspaces and Kernel-based Active Subspaces.

References

Paul Constantine. Active subspaces: Emerging ideas for dimension reduction in parameter studies, vol. 2 of SIAM Spotlights, SIAM, 2015.
Francesco Romor, Marco Tezzele, Andrea Lario, Gianluigi Rozza. Kernel-based Active Subspaces with application to CFD problems using Discontinuous Galerkin Method. 2020. arxiv: https://arxiv.org/abs/2008.12083

`Subspaces._bootstrap_replicate`	Return a bootstrap replicate.
`Subspaces._build_decompose_cov_matrix`	Build and decompose the covariance matrix of the gradients.
`Subspaces._compute_bootstrap_ranges`	Compute bootstrap ranges for eigenvalues and subspaces.
`Subspaces._partition`	Partition the eigenvectors to define the active and inactive subspaces.
`Subspaces.fit`	Abstract method to compute the active subspaces.
`Subspaces.inverse_transform`	Abstract method to find points in full space that map to reduced variable points.
`Subspaces.plot_eigenvalues`	Plot the eigenvalues.
`Subspaces.plot_eigenvectors`	Plot the eigenvectors.
`Subspaces.plot_sufficient_summary`	Plot the sufficient summary.
`Subspaces.transform`	Abstract method to map full variables to active and inactive variables.

class Subspaces(dim, method='exact', n_boot=100)[source]

Bases: object

Active Subspaces base class

Parameters

dim – The dimension of the active subspace. If 0, the method computes the spectral gap and uses it for truncation; if positive interger, the method uses the dim argument for the truncation; if float between 0 and 1, a truncation with retained energy.The dim parameter is available using all the available methods.
method (str) – method to compute the AS. Possible choices are ‘exact’ when the gradients are provided, or ‘local’ to use local linear models. This approach is related to the sufficient dimension reduction method known sometimes as the outer product of gradient method. See the 2001 paper ‘Structure adaptive approach for dimension reduction’ from Hristache, et al.
n_boot (int) – number of bootstrap samples. Default is 100.

static _bootstrap_replicate(matrix, weights)[source]

Return a bootstrap replicate.

A bootstrap replicate is a sampling-with-replacement strategy from a given data set.

Parameters

matrix (numpy.ndarray) – matrix from which will be sampled N rows. N corresponds to the number of rows of weights.
weights (numpy.ndarray) – n_samples-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace.

_build_decompose_cov_matrix(gradients=None, weights=None, metric=None)[source]

Build and decompose the covariance matrix of the gradients.

Parameters

gradients (numpy.ndarray) – n_samples-by-n_params matrix containing the gradient samples oriented as rows.
weights (numpy.ndarray) – n_samples-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace.
metric (numpy.ndarray) – metric matrix output_dim-by-output-dim for vectorial active subspaces.

Returns

the sorted eigenvalues, and the corresponding eigenvectors.

Return type

numpy.ndarray, numpy.ndarray

_check_rsvd(n_samples, n_pars, dim)[source]: Check if random svd is to be applied.

_compute_bootstrap_ranges(gradients, weights, metric=None)[source]

Compute bootstrap ranges for eigenvalues and subspaces.

An implementation of the nonparametric bootstrap that we use in conjunction with the subspace estimation methods to estimate the errors in the eigenvalues and subspaces.

Parameters

gradients (numpy.ndarray) – n_samples-by-n_params matrix containing the gradient samples oriented as rows.
weights (numpy.ndarray) – n_samples-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace.
metric (numpy.ndarray) – metric matrix output_dim-by-output-dim for vectorial active subspaces.

Returns

array e_br is a m-by-2 matrix, first column contains bootstrap lower bound on eigenvalues, second column contains bootstrap upper bound on eigenvalues; array sub_br is a (m-1)-by-3 matrix, first column contains bootstrap lower bound on estimated subspace error, second column contains estimated mean of subspace error (a reasonable subspace error estimate), third column contains estimated upper bound on subspace error.

Return type

numpy.ndarray, numpy.ndarray

_partition()[source]

Partition the eigenvectors to define the active and inactive subspaces.

Raises: TypeError, ValueError

_set_dim()[source]

Set the active subspace dimension based on the spectral gap if self.dim is 0, residual energy if 0<self.dim<1 or manual set of AS dimension if self.dim>=1.

Raises: ValueError

_set_dim_residual_energy(tol=0.99)[source]

Set the active subspace dimension based on the residual energy normalized to 1: the normalized sum of the eigenvalues corresponding to the active components will be lower than tol.

Parameters: tol (float) – threshold for the residual energy.
Raises: TypeError, ValueError

_set_dim_spectral_gap()[source]

Set the active subspace dimension based on the highest spectral gap of the ordered eigenvalues.

Raises: ValueError

fit(*args, **kwargs)[source]: Abstract method to compute the active subspaces. Not implemented, it has to be implemented in subclasses.

inverse_transform(reduced_inputs, n_points)[source]

Abstract method to find points in full space that map to reduced variable points. Not implemented, it has to be implemented in subclasses.

Parameters

reduced_inputs (numpy.ndarray) – n_samples-by-n_params matrix that contains points in the space of active variables.
n_points (int) – the number of points in the original parameter space that are returned that map to the given active variables.

plot_eigenvalues(n_evals=None, filename=None, figsize=(8, 8), title='')[source]

Plot the eigenvalues.

Parameters

n_evals (int) – number of eigenvalues to plot. If not provided all the eigenvalues will be plotted.
filename (str) – if specified, the plot is saved at filename.
figsize (tuple(int,int)) – tuple in inches defining the figure size. Default is (8, 8).
title (str) – title of the plot.

Raises

TypeError

Warning

self.fit has to be called in advance.

plot_eigenvectors(n_evects=None, filename=None, figsize=None, labels=None, title='')[source]

Plot the eigenvectors.

Parameters

n_evects (int) – number of eigenvectors to plot. Default is self.dim.
filename (str) – if specified, the plot is saved at filename.
figsize (tuple(int,int)) – tuple in inches defining the figure size. Default is (8, 2 * n_evects).
labels (str) – labels for the components of the eigenvectors.
title (str) – title of the plot.

Raises

ValueError, TypeError

Warning

self.fit has to be called in advance.

plot_sufficient_summary(inputs, outputs, filename=None, figsize=(10, 8), title='')[source]

Plot the sufficient summary.

Parameters

inputs (numpy.ndarray) – array n_samples-by-n_params containing the points in the full input space.
outputs (numpy.ndarray) – array n_samples-by-1 containing the corresponding function evaluations.
filename (str) – if specified, the plot is saved at filename.
figsize (tuple(int,int)) – tuple in inches defining the figure size. Defaults to (10, 8).
title (str) – title of the plot.

Raises

ValueError, TypeError

Warning

self.fit has to be called in advance.

Plot only available for partitions up to dimension 2.

transform(inputs)[source]

Abstract method to map full variables to active and inactive variables.

Points in the original input space are mapped to the active and inactive subspace.

Parameters: inputs (numpy.ndarray) – array n_samples-by-n_params containing the points in the original parameter space.
Returns: array n_samples-by-active_dim containing the mapped active variables; array n_samples-by-inactive_dim containing the mapped inactive variables.
Return type: numpy.ndarray, numpy.ndarray