Subspaces

Utilities for computing active and inactive subspaces.

class active_subspaces.subspaces.Subspaces

A class for computing active and inactive subspaces.

eigenvals

ndarray

m-by-1 matrix of eigenvalues

eigenvecs

ndarray

m-by-m matrix, eigenvectors oriented column-wise

W1

ndarray

m-by-n matrix, basis for the active subspace

W2

ndarray

m-by-(m-n) matrix, basis for the inactive subspace

e_br

ndarray

m-by-2 matrix, bootstrap ranges for the eigenvalues

sub_br

ndarray

m-by-3 matrix, bootstrap ranges (first and third column) and the mean (second column) of the error in the estimated active subspace approximated by bootstrap

Notes

The attributes W1 and W2 are convenience variables. They are identical to the first n and last (m-n) columns of eigenvecs, respectively.

compute(X=None, f=None, df=None, weights=None, sstype='AS', ptype='EVG', nboot=0)

Compute the active and inactive subspaces.

Given input points and corresponding outputs, or given samples of the gradients, estimate an active subspace. This method has four different algorithms for estimating the active subspace: ‘AS’ is the standard active subspace that requires gradients, ‘OLS’ uses a global linear model to estimate a one-dimensional active subspace, ‘QPHD’ uses a global quadratic model to estimate subspaces, and ‘OPG’ uses a set of local linear models computed from subsets of give input/output pairs.

The function also sets the dimension of the active subspace (and, consequently, the dimenison of the inactive subspace). There are three heuristic choices for the dimension of the active subspace. The default is the largest gap in the eigenvalue spectrum, which is ‘EVG’. The other two choices are ‘RS’, which estimates the error in a low-dimensional response surface using the eigenvalues and the estimated subspace errors, and ‘LI’ which is a heuristic from Bing Li on order determination.

Note that either df or X and f must be given, although formally all are optional.

Parameters:
  • X (ndarray, optional) – M-by-m matrix of samples of inputs points, arranged as rows (default None)
  • f (ndarray, optional) – M-by-1 matrix of outputs corresponding to rows of X (default None)
  • df (ndarray, optional) – M-by-m matrix of samples of gradients, arranged as rows (default None)
  • weights (ndarray, optional) – M-by-1 matrix of weights associated with rows of X
  • sstype (str, optional) – defines subspace type to compute. Default is ‘AS’ for active subspace, which requires df. Other options are OLS for a global linear model, QPHD for a global quadratic model, and OPG for local linear models. The latter three require X and f.
  • ptype (str, optional) – defines the partition type. Default is ‘EVG’ for largest eigenvalue gap. Other options are ‘RS’, which is an estimate of the response surface error, and ‘LI’, which is a heuristic proposed by Bing Li based on subspace errors and eigenvalue decay.
  • nboot (int, optional) – number of bootstrap samples used to estimate the error in the estimated subspace (default 0 means no bootstrap estimates)

Notes

Partition type ‘RS’ and ‘LI’ require nboot to be greater than 0 (and probably something more like 100) to get bootstrap estimates of the subspace error.

partition(n)

Partition the eigenvectors to define the active subspace.

A convenience function for partitioning the full set of eigenvectors to separate the active from inactive subspaces.

Parameters:n (int) – the dimension of the active subspace
active_subspaces.subspaces.active_subspace(df, weights)

Compute the active subspace.

Parameters:
  • df (ndarray) – M-by-m matrix containing the gradient samples oriented as rows
  • weights (ndarray) – M-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace
Returns:

  • e (ndarray) – m-by-1 vector of eigenvalues
  • W (ndarray) – m-by-m orthogonal matrix of eigenvectors
active_subspaces.subspaces.eig_partition(e)

Partition the active subspace according to largest eigenvalue gap.

Parameters:e (ndarray) – m-by-1 vector of eigenvalues
Returns:
  • n (int) – dimension of active subspace
  • ediff (float) – largest eigenvalue gap
active_subspaces.subspaces.errbnd_partition(e, sub_err)

Partition the active subspace according to response surface error.

Uses an a priori estimate of the response surface error based on the eigenvalues and subspace error to determine the active subspace dimension.

Parameters:
  • e (ndarray) – m-by-1 vector of eigenvalues
  • sub_err (ndarray) – m-by-1 vector of estimates of subspace error
Returns:

  • n (int) – dimension of active subspace
  • errbnd (float) – estimate of error bound

Notes

The error bound should not be used as an estimated error. The bound is only used to estimate the subspace dimension.

active_subspaces.subspaces.ladle_partition(e, li_F)

Partition the active subspace according to Li’s criterion.

Uses a criterion proposed by Bing Li that combines estimates of the subspace with estimates of the eigenvalues.

Parameters:
  • e (ndarray) – m-by-1 vector of eigenvalues
  • li_F (float) – measures error in the subspace
Returns:

  • n (int) – dimension of active subspace
  • G (ndarray) – metrics used to determine active subspace dimension
active_subspaces.subspaces.ols_subspace(X, f, weights)

Estimate one-dimensional subspace with global linear model.

Parameters:
  • X (ndarray) – M-by-m matrix of input samples, oriented as rows
  • f (ndarray) – M-by-1 vector of output samples corresponding to the rows of X
  • weights (ndarray) – M-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace
Returns:

  • e (ndarray) – m-by-1 vector of eigenvalues
  • W (ndarray) – m-by-m orthogonal matrix of eigenvectors

Notes

Although the method returns a full set of eigenpairs (to be consistent with the other subspace functions), only the first eigenvalue will be nonzero, and only the first eigenvector will have any relationship to the input parameters. The remaining m-1 eigenvectors are only orthogonal to the first.

active_subspaces.subspaces.opg_subspace(X, f, weights)

Estimate active subspace with 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.

Parameters:
  • X (ndarray) – M-by-m matrix of input samples, oriented as rows
  • f (ndarray) – M-by-1 vector of output samples corresponding to the rows of X
  • weights (ndarray) – M-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace
Returns:

  • e (ndarray) – m-by-1 vector of eigenvalues
  • W (ndarray) – m-by-m orthogonal matrix of eigenvectors
active_subspaces.subspaces.qphd_subspace(X, f, weights)

Estimate active subspace with global quadratic model.

This approach is similar to Ker-Chau Li’s approach for principal Hessian directions based on a global quadratic model of the data. In contrast to Li’s approach, this method uses the average outer product of the gradient of the quadratic model, as opposed to just its Hessian.

Parameters:
  • X (ndarray) – M-by-m matrix of input samples, oriented as rows
  • f (ndarray) – M-by-1 vector of output samples corresponding to the rows of X
  • weights (ndarray) – M-by-1 weight vector, corresponds to numerical quadrature rule used to estimate matrix whose eigenspaces define the active subspace
Returns:

  • e (ndarray) – m-by-1 vector of eigenvalues
  • W (ndarray) – m-by-m orthogonal matrix of eigenvectors
active_subspaces.subspaces.sorted_eigh(C)

Compute eigenpairs and sort.

Parameters:C (ndarray) – matrix whose eigenpairs you want
Returns:
  • e (ndarray) – vector of sorted eigenvalues
  • W (ndarray) – orthogonal matrix of corresponding eigenvectors

Notes

Eigenvectors are unique up to a sign. We make the choice to normalize the eigenvectors so that the first component of each eigenvector is positive. This normalization is very helpful for the bootstrapping.