Struct PcaProjection 

pub struct PcaProjection { /* private fields */ }

Corpus-fitted projection via spherical PCA.

Finds the 3 principal directions of maximum angular variance in the embedding space, then projects new embeddings onto them. This preserves angular (cosine similarity) relationships as faithfully as possible in 3 dimensions.

Fitting: O(N·n·k·iters) where N=corpus size, n=dimension, k=3. Projection: O(n) per embedding.

Implementations

impl PcaProjection

pub fn fit( embeddings: &[Embedding], radial: RadialStrategy, ) -> Result<Self, ProjectionError>

Fit the top-3 principal components on embeddings.

Returns ProjectionError::EmptyCorpus if the slice is empty, ProjectionError::DimensionTooLow if dim < 3, and ProjectionError::InconsistentDimension if any row’s dimensionality disagrees with the first. Previously these paths panicked via assert!, which surfaced as a PanicException in Python / WASM bindings.

pub fn fit_default(embeddings: &[Embedding]) -> Result<Self, ProjectionError>

pub fn fit_weighted( embeddings: &[Embedding], weights: &[f64], radial: RadialStrategy, ) -> Result<Self, ProjectionError>

Fit the top-3 principal components with per-sample weights.

Weighted PCA finds the top eigenvectors of the weighted covariance matrix Σ wᵢ (xᵢ − μ_w)(xᵢ − μ_w)ᵀ / Σ wᵢ, where μ_w = Σ wᵢ xᵢ / Σ wᵢ. With uniform weights this collapses to the same answer as Self::fit.

The intended use is rebalancing covariance estimates over imbalanced corpora. Setting wᵢ = 1 / sqrt(|category(i)|) gives a category of size m total covariance mass m · (1/√m) = √m, compressing category influence from linear to square-root in its size. For exactly equal per-category mass use wᵢ = 1 / |category(i)|; the square-root compromise keeps large categories’ internal variance structure from being washed out entirely while still letting small categories register.

Returns the same error variants as Self::fit, plus ProjectionError::SliceLengthMismatch when weights.len() != embeddings.len(). Negative weights are treated as zero.

pub fn with_volumetric(self, enabled: bool) -> Self

Enable volumetric mode: r comes from the PCA projection magnitude instead of the embedding magnitude. Points distribute through the full 3D volume rather than clustering on the sphere surface.

pub fn explained_variance_ratio(&self) -> f64

The fraction of total variance captured by the top-3 PCA components. A global quality metric for the projection — higher means less information lost.

Trait Implementations

impl Clone for PcaProjection

fn clone(&self) -> PcaProjection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<PcaProjection> for ConfiguredProjection

fn from(p: PcaProjection) -> Self

Converts to this type from the input type.

impl Projection for PcaProjection

fn project(&self, embedding: &Embedding) -> SphericalPoint

fn project_rich(&self, embedding: &Embedding) -> ProjectedPoint

Project with rich metadata: certainty, intensity, projection magnitude.

fn dimensionality(&self) -> usize