PCAModel

class menpo.model.pca.PCAModel(samples, center=True, bias=False)

Bases: MeanInstanceLinearModel

A MeanInstanceLinearModel where components Principal Components.

Principal Component Analysis (PCA) by eigenvalue decomposition of the data’s scatter matrix. For details of the implementation of PCA, see principal_component_decomposition.

Parameters:

samples : list of Vectorizable

List of samples to build the model from.

center : bool, optional

When True (True by default) PCA is performed after mean centering the data. If False the data is assumed to be centred, and the mean will be 0.

bias: bool, optional

When True (False by default) a biased estimator of the covariance matrix is used. See notes.

..notes:

True bias mean that we calculate the covariance as

:math:`

rac{1}{N} sum_i^N mathbf{x}_i mathbf{x}_i^T` :

instead of default

:math:`

rac{1}{N-1} sum_i^N mathbf{x}_i mathbf{x}_i^T` :

component(index, with_mean=True, scale=1.0)

Return a particular component of the linear model.

Parameters:

index : int

The component that is to be returned

with_mean: boolean (optional) :

If True, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own.

Default: True

scale : float

A scale factor that should be applied to the component. Only valid in the case where with_mean is True. See component_vector() for how this scale factor is interpreted.

:type: `type(self.template_instance)` :

component_vector(index, with_mean=True, scale=1.0)

A particular component of the model, in vectorized form.

Parameters:

index : int

The component that is to be returned

with_mean: boolean (optional) :

If True, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own.

Default: True

scale : float

A scale factor that should be applied to the component. Only valid in the case where with_mean is True. The scale is applied in units of standard deviations (so a scale of 1.0 with_mean visualizes the mean plus 1 std. dev of the component in question).

:type: (n_features,) ndarray :

distance_to_subspace(instance)

Returns a version of instance where all the basis of the model have been projected out and which has been scaled by the inverse of the noise_variance

Parameters:

instance : Vectorizable

A novel instance.

Returns:

scaled_projected_out : self.instance_class

A copy of instance, with all basis of the model projected out and scaled by the inverse of the noise_variance.

distance_to_subspace_vector(vector_instance)

Returns a version of instance where all the basis of the model have been projected out and which has been scaled by the inverse of the noise_variance.

Parameters:

vector_instance : (n_features,) ndarray

A novel vector.

Returns:

scaled_projected_out: (n_features,) ndarray :

A copy of vector_instance with all basis of the model projected out and scaled by the inverse of the noise_variance.

instance(weights)

Creates a new instance of the model using the first len(weights) components.

Parameters:

weights : (n_weights,) ndarray or list

weights[i] is the linear contribution of the i’th component to the instance vector.

Returns:

instance : type(self.template_instance)

An instance of the model.

Raises:

ValueError: If n_weights > n_components :

instance_vector(weights)

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights : (n_weights,) ndarray or list

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns:

vector : (n_features,) ndarray

The instance vector for the weighting provided.

instance_vectors(weights)

Creates new vectorized instances of the model using the first components in a particular weighting.

Parameters:

weights : (n_vectors, n_weights) ndarray or list of lists

The weightings for the first n_weights components that should be used per instance that is to be produced

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced. Note that if n_weights < n_components, only the first n_weight components are used in the reconstruction (i.e. unspecified weights are implicitly 0)

Returns:

vectors : (n_vectors, n_features) ndarray

The instance vectors for the weighting provided.

Raises:

ValueError: If n_weights > n_components :

orthonormalize_against_inplace(linear_model)

Enforces that the union of this model’s components and another are both mutually orthonormal.

Note that the model passed in is guaranteed to not have it’s number of available components changed. This model, however, may loose some dimensionality due to reaching a degenerate state.

The removed components will always be trimmed from the end of components (i.e. the components which capture the least variance). If trimming is performed, n_components and n_available_components would be altered - see trim_components() for details.

Parameters:

linear_model : LinearModel

A second linear model to orthonormalize this against.

orthonormalize_inplace()

Enforces that this models components are orthonormalized

s.t. component_vector(i).dot(component_vector(j) = dirac_delta

project(instance)

Projects the instance onto the model, retrieving the optimal linear weightings.

Parameters:

novel_instance : Vectorizable

A novel instance.

Returns:

projected : (n_components,)

A vector of optimal linear weightings

project_out(instance)

Returns a version of instance where all the basis of the model have been projected out.

Parameters:

instance : Vectorizable

A novel instance.

Returns:

projected_out : self.instance_class

A copy of instance, with all basis of the model projected out.

project_out_vector(vector)

Returns a version of vector where all the basis of the model have been projected out.

Parameters:

vector : (n_features,) ndarray

A novel vector.

Returns:

projected_out : (n_features,) ndarray

A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:

vectors : (n_vectors, n_features) ndarray

A matrix of novel vectors.

Returns:

projected_out : (n_vectors, n_features) ndarray

A copy of vectors with all basis of the model projected out.

project_vector(vector)

Projects the vector onto the model, retrieving the optimal linear reconstruction weights

Parameters:

vector : (n_features,) ndarray

A vectorized novel instance.

Returns:

weights : (n_components,)

A vector of optimal linear weights

project_vectors(vectors)

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:

vectors : (n_samples, n_features) ndarray

Returns:

projected: (n_samples, n_components) ndarray :

The matrix of optimal linear weights

project_whitened(instance)

Returns a sheared (non-orthogonal) reconstruction of instance.

Parameters:

instance : Vectorizable

A novel instance.

Returns:

sheared_reconstruction : self.instance_class

A sheared (non-orthogonal) reconstruction of instance.

project_whitened_vector(vector_instance)

Returns a sheared (non-orthogonal) reconstruction of vector_instance.

Parameters:

vector_instance : (n_features,) ndarray

A novel vector.

Returns:

sheared_reconstruction : (n_features,) ndarray

A sheared (non-orthogonal) reconstruction of vector_instance

reconstruct(instance)

Projects a instance onto the linear space and rebuilds from the weights found.

Syntactic sugar for:

>>> instance(project(instance))

but faster, as it avoids the conversion that takes place each time.

Parameters:

instance : Vectorizable

A novel instance of Vectorizable

Returns:

reconstructed : self.instance_class

The reconstructed object.

reconstruct_vector(vector)

Project a vector onto the linear space and rebuild from the weights found.

Parameters:

vector : (n_features, ) ndarray

A vectorized novel instance to project

Returns:

reconstructed : (n_features,) ndarray

The reconstructed vector.

reconstruct_vectors(vectors)

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:

vectors : (n_vectors, n_features) ndarray

A set of vectors to project

Returns:

reconstructed : (n_vectors, n_features) ndarray

The reconstructed vectors.

trim_components(n_components=None)

Permanently trims the components down to a certain amount. The number of active components will be automatically reset to this particular value.

This will reduce self.n_components down to n_components (if None self.n_active_components will be used), freeing up memory in the process.

Once the model is trimmed, the trimmed components cannot be recovered.

Parameters:

n_components: int >= 1 or float > 0.0, optional :

The number of components that are kept or else the amount (ratio) of variance that is kept. If None, self.n_active_components is used.

Notes

In case n_components is greater than the total number of components or greater than the amount of variance currently kept, this method does not perform any action.

components

Returns the active components of the model.

type: (n_active_components, n_features) ndarray

d_dp

eigenvalues

Returns the eigenvalues associated to the active components of the model, i.e. the amount of variance captured by each active component.

type: (n_active_components,) ndarray

eigenvalues_cumulative_ratio

Returns the cumulative ratio between the variance captured by the active components and the total amount of variance present on the original samples.

type: (n_active_components,) ndarray

eigenvalues_ratio

Returns the ratio between the variance captured by each active component and the total amount of variance present on the original samples.

type: (n_active_components,) ndarray

inverse_noise_variance

Returns the inverse of the noise variance.

type: float

n_active_components

The number of components currently in use on this model.

n_components

The number of bases of the model

type: int

n_features

The number of elements in each linear component.

type: int

noise_variance

Returns the average variance captured by the inactive components, i.e. the sample noise assumed in a PPCA formulation.

If all components are active, noise variance is equal to 0.0

type: float

noise_variance_ratio

Returns the ratio between the noise variance and the total amount of variance present on the original samples.

type: float

original_variance

Returns the total amount of variance captured by the original model, i.e. the amount of variance present on the original samples.

type: float

variance

Returns the total amount of variance retained by the active components.

type: float

variance_ratio

Returns the ratio between the amount of variance retained by the active components and the total amount of variance present on the original samples.

type: float

whitened_components

Returns the active components of the model whitened.

type: (n_active_components, n_features) ndarray