TS_PCA

class TS_PCA.TS_PCA_class.TS_PCA_(kernel_velocity_arg={'c_0': 1.0, 'c_1': 0.1, 's_sigma': 1.0, 't_sigma_1': 60, 't_sigma_2': 1.0}, kernel_varifold_arg={'s_sigma_1': 1.0, 's_sigma_2': 0.6, 't_sigma_1': 2.0, 't_sigma_2': 2.0})

Bases: object

fit_TS_LDDMM_representations(Dataset, Dataset_mask, niter=100, schedule=<function join_schedules.<locals>.schedule>, gamma_loss=0.001, learning_graph_ref=True, graph_ref=None, graph_ref_mask=None, dataloss=None)

Fit TS-LDDMM representations of a dataset of time series graphs.

This method computes the TS-LDDMM embeddings of the input dataset by optimizing initial momentums (\(p_0\)) and optionally the reference graph (\(G_0\)) using a velocity kernel and a varifold data term. If learning_graph_ref is True, the reference graph is estimated via a barycenter procedure; otherwise, a fixed reference graph must be provided.

Parameters:

  • Dataset (array of shape (n_time_series, n_samples_max, d+1)) – Input time series graphs. The first column corresponds to time points, the remaining columns are spatial values of dimension d.

  • Dataset_mask (array of shape (n_time_series, n_samples_max, 1)) – Mask indicating valid samples in each time series graph.

  • niter (int, optional) – Number of iterations for the optimization (default: niter_defaut).

  • schedule (object, optional) – Learning rate schedule for the optax optimizer (default: schedule_defaut).

  • gamma_loss (float, optional) – Weighting factor for the data loss term in the optimization (default: 1e-3).

  • learning_graph_ref (bool, optional) – If True, the reference graph graph_ref is estimated jointly with momentums; if False, a fixed reference graph must be provided (default: True).

  • graph_ref (array of shape (n_samples_max, d+1), optional) – Reference graph to use if learning_graph_ref=False. Must be provided together with graph_ref_mask.

  • graph_ref_mask (array of shape (n_samples_max, 1), optional) – Mask for the reference graph.

  • dataloss (object, optional) – Data loss object used for registration. If None, a default SumVarifoldLoss with the internal varifold kernel is used.

Returns:

momentumsarray

Optimized initial momentums (\(p_0\)) for the TS-LDDMM mapping.

graph_refarray

Learned or provided reference graph (\(G_0\)) after optimization.

graph_ref_maskarray

Mask for the reference graph.

fit_TS_LDDMM_bool

Flag indicating that TS-LDDMM representations have been fitted successfully (set to True at the end of the method).

Type:

bool

Notes

  • This function internally uses batching via batch_dataset and the Shooting object.

  • Optimization is performed using the Adabelief optimizer from optax.

  • Raises a ValueError if learning_graph_ref=False and graph_ref or graph_ref_mask are not provided.

fit_kernel_PCA(n_comp=3, momentums=None, graph_ref=None, graph_ref_mask=None)

Fit a Kernel PCA on TS-LDDMM momentums to extract principal components.

This method performs Kernel Principal Component Analysis (KPCA) on the initial momentums (\(p_0\)) obtained from TS-LDDMM representations. It computes a low-dimensional embedding of the momentums, capturing the main modes of variation in the dataset.

If momentums are not provided, the method uses the momentums, reference graph, and reference graph mask stored in the object (from a previous call to fit_TS_LDDMM_representations).

Parameters:

  • n_comp (int, optional) – Number of principal components to extract (default: 3).

  • momentums (array of shape (n_ind, n_samples, n_dim+1), optional) – TS-LDDMM initial momentums (\(p_0\)). If None, the method uses the internal momentums stored in the object.

  • graph_ref (array of shape (n_samples, d+1), optional) – Reference graph (\(G_0\)) corresponding to the momentums. Required if momentums is provided.

  • graph_ref_mask (array of shape (n_samples, 1), optional) – Mask for the reference graph. Required if momentums is provided.

Returns:

None

n_comp

Number of components used for KPCA.

Type:

int

mean_

Mean momentum (\(\bar{p}_0\)) computed across samples.

Type:

array

singular_values_

Standard deviation of principal components.

Type:

array

components_

Principal components matrix, each row corresponds to a component.

Type:

array

n_samples_

Number of time series in the dataset.

Type:

int

coordinates_

Projected coordinates of each momentum in the KPCA space.

Type:

array

fit_kernel_PCA_bool

Flag indicating that Kernel PCA has been successfully fitted (set to True).

Type:

bool

Raises:

ValueError – If momentums, graph_ref, or graph_ref_mask are not provided and cannot be inferred from the object. Suggests using fit_TS_LDDMM_representations to generate these inputs.

Notes

  • The method internally uses MomentaPCA with covariance-based KPCA.

  • Each momentum is reshaped to match the expected input dimensions for KPCA.

  • Kernel PCA captures the main modes of variation of TS-LDDMM momentums,

which can then be used for visualization or downstream analysis.

fit_transform(n_comp=2, momentums=None, graph_ref=None, graph_ref_mask=None)

Apply fit_kernel_PCA and return the Projected coordinates of each momentum in the Kernel PCA space.

plot_components()

Plot the the effect of the components of Kernel PCA as deformations on the reference graph