pyppur package

Projection pursuit dimensionality reduction.

class pyppur.GridOptimizer(objective_func, n_components, n_directions=250, n_iterations=10, max_iter=1000, tol=1e-06, random_state=None, verbose=False, **kwargs)

Bases: BaseOptimizer

Optimizer using a grid-based search approach.

This optimizer is particularly useful for projection indices that are not differentiable or have many local minima. It systematically explores the space of projection directions using a grid-based approach.

Parameters:

• objective_func (Callable[[...], float])

• n_components (int)

• n_directions (int)

• n_iterations (int)

• max_iter (int)

• tol (float)

• random_state (int | None)

• verbose (bool)

• kwargs (Any)

optimize(X, initial_guess=None, **kwargs)

Optimize the projection directions using a grid-based approach.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• initial_guess (ndarray | None) – Optional initial guess for projection directions.

• **kwargs (Any) – Additional arguments for the objective function.

Returns:

• Optimized projection directions, shape (n_components, n_features)

• Final objective value

• Additional optimizer information

Return type:

Tuple containing

class pyppur.Objective(*values)

Bases: StrEnum

Objective types for projection pursuit.

DISTANCE_DISTORTION = 'distance_distortion'

RECONSTRUCTION = 'reconstruction'

class pyppur.ProjectionPursuit(n_components=2, objective='distance_distortion', alpha=0.1, max_iter=500, tol=1e-06, random_state=None, optimizer='L-BFGS-B', n_init=3, verbose=False, center=True, scale=True, weight_by_distance=False, tied_weights=True, l2_reg=0.0, use_nonlinearity_in_distance=True, distance_metric='correlation')

Bases: TransformerMixin, BaseEstimator

Implementation of Projection Pursuit for dimensionality reduction.

This class provides methods to find optimal projections by minimizing either reconstruction loss or distance distortion. It supports both initialization strategies and different optimizers.

Parameters:

• n_components (int)

• objective (Objective | str)

• alpha (float)

• max_iter (int)

• tol (float)

• random_state (int | None)

• optimizer (str)

• n_init (int)

• verbose (bool)

• center (bool)

• scale (bool)

• weight_by_distance (bool)

• tied_weights (bool)

• l2_reg (float)

• use_nonlinearity_in_distance (bool)

• distance_metric (Literal['mse', 'correlation', 'spearman'])

fit(X, y=None)

Fit the ProjectionPursuit model to the data.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• y (Any) – Ignored. Accepted for scikit-learn estimator API compatibility.

Returns:

The fitted model.

Return type:

ProjectionPursuit

transform(X)

Apply dimensionality reduction to X.

Parameters:

X (ndarray) – Input data, shape (n_samples, n_features).

Returns:

Transformed data, shape (n_samples, n_components).

Return type:

ndarray

fit_transform(X, y=None, **fit_params)

Fit the model with X and apply dimensionality reduction on X.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• y (Any) – Ignored. Accepted for scikit-learn estimator API compatibility.

• **fit_params (Any) – Ignored. Accepted for scikit-learn API compatibility.

Returns:

Transformed data, shape (n_samples, n_components).

Return type:

ndarray

reconstruct(X)

Reconstruct X from the projected data.

Parameters:

X (ndarray) – Input data, shape (n_samples, n_features).

Returns:

Reconstructed data, shape (n_samples, n_features).

Return type:

ndarray

reconstruction_error(X)

Compute the reconstruction error for X.

Parameters:

X (ndarray) – Input data, shape (n_samples, n_features).

Returns:

Mean squared reconstruction error.

Return type:

float

distance_distortion(X)

Compute the distance distortion for X.

Parameters:

X (ndarray) – Input data, shape (n_samples, n_features).

Returns:

Mean squared distance distortion.

Return type:

float

compute_trustworthiness(X, n_neighbors=5)

Compute the trustworthiness score for the dimensionality reduction.

Trustworthiness measures how well the local structure is preserved. A score of 1.0 indicates perfect trustworthiness, while a score of 0.0 indicates that the local structure is not preserved at all.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• n_neighbors (int) – Number of neighbors to consider for trustworthiness.

Returns:

Trustworthiness score between 0.0 and 1.0.

Return type:

float

compute_silhouette(X, labels)

Compute the silhouette score for the dimensionality reduction.

Silhouette score measures how well clusters are separated. A score close to 1.0 indicates that clusters are well separated, while a score close to -1.0 indicates poor separation.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• labels (ndarray) – Cluster labels for each sample.

Returns:

Silhouette score between -1.0 and 1.0.

Return type:

float

evaluate(X, labels=None, n_neighbors=5)

Evaluate the dimensionality reduction with multiple metrics.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• labels (ndarray | None) – Optional cluster labels for silhouette score.

• n_neighbors (int) – Number of neighbors for trustworthiness.

Returns:

Dictionary with evaluation metrics.

Return type:

dict[str, float]

property n_components_: int

Number of components actually used by the fit.

This equals the n_components constructor argument, except when that exceeded the number of features, in which case it is the number of features. The constructor argument itself is never modified.

Returns:

Number of projection directions found.

property x_loadings_: ndarray

Projection directions (encoder).

Returns:

Projection directions, shape (n_components, n_features).

property decoder_weights_: ndarray | None

Decoder weights (for untied weights only).

Returns:

Decoder weights, shape (n_components, n_features), or None if using tied weights.

property loss_curve_: list[float]

Loss curve during optimization.

Returns:

Loss values during optimization.

property best_loss_: float

Best loss value achieved.

Returns:

Best loss value.

property fit_time_: float

Time taken to fit the model.

Returns:

Time in seconds.

property optimizer_info_: dict[str, Any]

Additional information from the optimizer.

Returns:

Optimizer information.

class pyppur.ScipyOptimizer(objective_func, n_components, method='L-BFGS-B', max_iter=1000, tol=1e-06, random_state=None, verbose=False, **kwargs)

Bases: BaseOptimizer

Optimizer using SciPy’s optimization methods.

This optimizer leverages SciPy’s optimization functionality, particularly the L-BFGS-B method which is well-suited for projection pursuit problems.

Parameters:

• objective_func (Callable[[...], float])

• n_components (int)

• method (str)

• max_iter (int)

• tol (float)

• random_state (int | None)

• verbose (bool)

• kwargs (Any)

optimize(X, initial_guess=None, **kwargs)

Optimize the projection directions using SciPy’s optimization methods.

Parameters:

• X (ndarray) – Input data, shape (n_samples, n_features).

• initial_guess (ndarray | None) – Optional initial guess for projection directions.

• **kwargs (Any) – Additional arguments for the objective function.

Returns:

• Optimized projection directions, shape (n_components, n_features)

• Final objective value

• Additional optimizer information

Return type:

Tuple containing

Subpackages

• pyppur.objectives package
  • Submodules
    • pyppur.objectives.base module
    • pyppur.objectives.distance module
    • pyppur.objectives.reconstruction module
• pyppur.optimizers package
  • Submodules
    • pyppur.optimizers.base module
    • pyppur.optimizers.scipy_optimizer module
    • pyppur.optimizers.grid_optimizer module
• pyppur.utils package
  • compute_silhouette()
  • compute_trustworthiness()
  • standardize_data()
  • Submodules
    • pyppur.utils.metrics module
    • pyppur.utils.preprocessing module
    • pyppur.utils.visualization module

Note

For detailed API documentation including methods and properties, see the API Reference page.