FCPTPA#

class FDApy.preprocessing.FCPTPA(n_components=5, normalize=False)[source]#

Functional canonical polyadic-tensor power algorithm.

This module implements the Functional CP-TPA algorithm [1]. This method computes an eigendecomposition of image observations, which can be interpreted as functions on a two-dimensional domain. We assume \(N\) observations of 2D images with dimension \(M_1 \times M_2\). The results are given in a CANDECOMP/PARAFRAC (CP) model format

\[X = \sum_{k = 1}^K c_k \cdot u_k \circ v_k \circ w_k\]

where \(\circ\) stands for the outer product, \(c_k\) is a coefficient (scalar) and \(u_k, v_k, w_k\) are eigenvectors for each direction of the tensor. In this representation, the outer product \(v_k \circ w_k\) can be regarded as the \(k\)-th eigenimage, while \(d_k \cdot u_k\) represents the vector of individual scores for this eigenimage and each observation.

The smoothness of the eigenvectors \(v_k, w_k\) is induced by penalty matrices for both image directions, that are weighted by smoothing parameters \(\alpha_{v_k}, \alpha_{w_k}\). The eigenvectors \(u_k\) are not smoothed, hence the algorithm does not induce smoothness along observations.

Optimal smoothing parameters are found via a nested generalized cross validation [4]. In each iteration of the TPA (tensor power algorithm), the GCV criterion is optimized via scipy.optimize on the intervals specified via alpha_range.

The FCP-TPA algorithm is an iterative algorithm. Convergence is assumed if the relative difference between the actual and the previous values are all below the tolerance level tolerance. The tolerance level is increased automatically, if the algorithm has not converged after max_iteration steps and if adapt_tolerance = TRUE. If the algorithm did not converge after max_iteration steps steps, the function throws a warning. The code is adapted from [2] and [3].

Parameters:

  • n_components (int) – Number of components to be calculated.

  • normalize (bool) – Should the results be normalied?

Attributes:

  • eigenvalues (npt.NDArray[np.float64], shape=(n_components,)) – The singular values corresponding to each of selected components.

  • eigenfunctions (DenseFunctionalData) – Principal axes in feature space, representing the directions of maximum variance in the data.

References

Methods

fit(data, penalty_matrices, alpha_range[, ...])

Fit the model on data.

inverse_transform(scores)

Transform the data back to its original space.

transform(data[, method])

Apply dimension reduction to the data.
fit(data, penalty_matrices, alpha_range, tolerance=0.0001, max_iteration=15, adapt_tolerance=True, verbose=False)[source]#

Fit the model on data.

This function is used to fit a model on the data.

Parameters:

  • data (DenseFunctionalData) – Training data used to estimate the eigencomponents. The dimension of its value parameter is \(N \times M_1 \times M_2\).

  • penalty_matrices (Dict[str, ndarray[Any, dtype[float64]]]) – A dictionary with entries \(v\) and \(w\), containing a roughness penalty matrix for each direction of the image. The algorithm does not induce smoothness along observations.

  • alpha_range (Dict[str, Tuple[float, float]]) – A dictionary with entries \(v\) and \(w\), containing the range of smoothness parameters \(\alpha_{v_k}, \alpha_{w_k}\) as a tuple.

  • tolerance (float) – A numeric value, giving the tolerance for relative error values in the algorithm. It is automatically multiplyed by 10 after max_iter steps, if adapt_tol = True.

  • max_iteration (int) – An integer, the maximal iteration steps. Can be doubled, if adapt_tol = True.

  • adapt_tolerance (bool) – If True, the tolerance is adapted (multiply by 10), if the algorithm has not converged after max_iter steps and another max_iter steps are allowed with the increased tolerance.

  • verbose (bool) – If True, computational details are given on the standard output during the computation. Here for debug purpose.

Return type:

None

Examples

Simulate some data.

>>> kl = KarhunenLoeve(
...     basis_name='bsplines',
...     n_functions=5,
...     dimension='2D',
...     argvals={'input_dim_0': np.linspace(0, 1, 101)},
...     random_state=42
... )
>>> kl.new(n_obs=50)
>>> data = kl.data

Define some parameters.

>>> n_points = data.n_points
>>> mat_v = np.diff(np.identity(n_points['input_dim_0']))
>>> mat_w = np.diff(np.identity(n_points['input_dim_1']))

Fit the FCP-TPA algorithm.

>>> fcptpa = FCPTPA(n_components=10)
>>> fcptpa.fit(
...     data,
...     penalty_matrices={
...         'v': np.dot(mat_v, mat_v.T),
...         'w': np.dot(mat_w, mat_w.T)
...     },
...     alpha_range={
...         'v': (1e-2, 1e2),
...         'w': (1e-2, 1e2)
...     },
...     tolerance=1e-4,
...     max_iteration=15,
...     adapt_tolerance=True
... )
inverse_transform(scores)[source]#

Transform the data back to its original space.

Return a DenseFunctionalData whose transform would be scores.

Parameters:

scores (ndarray[Any, dtype[float64]]) – A set of coefficients to generate new data, where n_obs is the number of observations and n_components is the number of components.

Returns:

The transformation of the scores into the original space.

Return type:

DenseFunctionalData

Examples

Using the model fitted using the fit function.

>>> data_f = fcptpa.inverse_transform(scores)
transform(data, method='NumInt')[source]#

Apply dimension reduction to the data.

Parameters:

  • data (DenseFunctionalData) – Functional data object to be transformed. It has to be 2-dimensional data.

  • method (str) – Not used. To be compliant with other methods.

Returns:

An array representing the projection of the data onto the basis of functions defined by the eigenimages.

Return type:

npt.NDArray[np.float64], shape=(n_obs, n_components)

Examples

Using the model fitted using the fit function.

>>> scores = fcptpa.transform(data, 'NumInt')

Examples using FDApy.preprocessing.FCPTPA#

FPCA of 2-dimensional data

FPCA of 2-dimensional data