pca-web 0.1.0

package/dist/pca.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Principal component analysis matching `sklearn.decomposition.PCA` (1.9).
+ *
+ * Naming is idiomatic TypeScript camelCase; every option and fitted attribute
+ * maps 1:1 to its sklearn counterpart (`nComponents` ↔ `n_components`,
+ * `explainedVarianceRatio` ↔ `explained_variance_ratio_`, …). Numerics follow
+ * sklearn's exact computation order, including its deterministic
+ * `svd_flip(u_based_decision=False)` sign convention.
+ */
+import { BasePCA } from './base.js';
+import { Matrix, type MatrixInput } from './matrix.js';
+import { type PCAModel } from './model.js';
+import { RandomState } from './numeric/rng.js';
+import { type SvdResult } from './numeric/svd.js';
+import { type FitAsyncOptions, type FitObserver, type ProgressReporter } from './progress.js';
+import { type FloatArray } from './types.js';
+export type SvdSolver = 'auto' | 'full' | 'covariance_eigh' | 'arpack' | 'randomized';
+export type PowerIterationNormalizer = 'auto' | 'QR' | 'LU' | 'none';
+export interface PCAOptions {
+    /**
+     * Number of components to keep. An integer ≥ 0, a fraction in (0, 1) to
+     * select by explained-variance ratio (full/covariance_eigh solvers),
+     * 'mle' for Minka's MLE (full/covariance_eigh), or null (default) to keep
+     * min(nSamples, nFeatures) components (min − 1 for arpack).
+     */
+    nComponents?: number | 'mle' | null;
+    /** When false, fit may overwrite the training Matrix's data (like sklearn's copy=False). */
+    copy?: boolean;
+    /** Scale transformed output to unit component-wise variance. */
+    whiten?: boolean;
+    svdSolver?: SvdSolver;
+    /**
+     * Accepted for API parity with sklearn's arpack tolerance. The built-in
+     * Lanczos solver always converges the requested triplets to machine
+     * precision (equivalent to sklearn's default tol=0.0).
+     */
+    tol?: number;
+    /** Power-iteration count for the randomized solver ('auto' → 7 or 4 like sklearn). */
+    iteratedPower?: number | 'auto';
+    /** Extra random test vectors for the randomized solver's range finder. */
+    nOversamples?: number;
+    powerIterationNormalizer?: PowerIterationNormalizer;
+    /** Integer seed (or RandomState) making arpack/randomized reproducible — sklearn-stream compatible. */
+    randomState?: number | RandomState | null;
+}
+interface ResolvedOptions {
+    nComponents: number | 'mle' | null;
+    copy: boolean;
+    whiten: boolean;
+    svdSolver: SvdSolver;
+    tol: number;
+    iteratedPower: number | 'auto';
+    nOversamples: number;
+    powerIterationNormalizer: PowerIterationNormalizer;
+    randomState: number | RandomState | null;
+}
+interface FitResult {
+    /** Left singular vectors from the fit, null for covariance_eigh. */
+    u: Float64Array | null;
+    uCols: number;
+    s: Float64Array;
+    x: Matrix;
+}
+/**
+ * sklearn 1.9's auto-solver heuristic (`PCA._fit`), as a pure function so the
+ * WebGPU frontend dispatches identically. `nComponents` is the raw option
+ * (null → min(shape) for the heuristic, like sklearn's unset default).
+ */
+export declare function resolveSvdSolver(rows: number, cols: number, nComponents: number | 'mle' | null, requested: SvdSolver): Exclude<SvdSolver, 'auto'>;
+/**
+ * Fit-time nComponents/solver compatibility checks, shared by the CPU and
+ * WebGPU frontends. Message text mirrors the sklearn errors it was ported
+ * from (camelCased).
+ */
+export declare function validateNcForSolver(nc: number | 'mle', n: number, p: number, solver: Exclude<SvdSolver, 'auto'>): void;
+export declare class PCA extends BasePCA {
+    private readonly opts;
+    private nSamples_;
+    private fitSvdSolver_;
+    constructor(options?: PCAOptions);
+    /** sklearn's `n_samples_`. */
+    get nSamples(): number;
+    /** The solver actually used by fit (sklearn's `_fit_svd_solver`). */
+    get resolvedSvdSolver(): Exclude<SvdSolver, 'auto'>;
+    /** Fit the model on X — sklearn's `fit`. X must have at least 2 samples. */
+    fit(X: MatrixInput, observer?: FitObserver): this;
+    /** Fit and return the embedding of X — sklearn's `fit_transform` fast path. */
+    fitTransform(X: MatrixInput, observer?: FitObserver): Matrix;
+    /**
+     * Non-blocking fit: runs the exact same steps as `fit`, time-sliced on
+     * the event loop (`budgetMs` of work per slice), so the UI stays
+     * responsive. Results are bit-identical to the synchronous fit.
+     */
+    fitAsync(X: MatrixInput, options?: FitAsyncOptions): Promise<this>;
+    /** Non-blocking fitTransform — the same U·S fast path as the sync version. */
+    fitTransformAsync(X: MatrixInput, options?: FitAsyncOptions): Promise<Matrix>;
+    /** The U·S fast path shared by fitTransform and fitTransformAsync. */
+    private fitTransformFromResult;
+    /**
+     * @internal The fit as a step generator — every `yield` is a suspension
+     * and abort checkpoint for the drivers (sync drain, time-sliced async,
+     * worker). Runs the exact statement sequence of the classic fit. Progress
+     * events (including the identical sequence for sync and async drives) are
+     * emitted synchronously between steps; on any exit before completion —
+     * abort, input error, callback throw — the estimator ends up unfitted.
+     */
+    _fitSteps(X: Matrix, observer?: FitObserver): Generator<void, FitResult, void>;
+    private fitFullSteps;
+    /**
+     * The XᵀX Gram product in row chunks, yielding between chunks. Chunked
+     * accumulation is strictly row-sequential, so the result is bitwise
+     * identical to one monolithic syrkT pass.
+     */
+    private gramSteps;
+    private fitTruncatedSteps;
+    /** Post-decomposition tail of the truncated solvers (flip, variances, store). */
+    private finishTruncated;
+    /**
+     * @internal Completes a covariance_eigh fit from an externally computed
+     * raw Gram matrix XᵀX (uncentered, float64, p×p). Used by the WebGPU
+     * frontend; all semantics downstream of the Gram product are shared with
+     * the CPU path. `rawGram` is consumed (mutated in place).
+     */
+    _fitGram(X: Matrix, rawGram: Float64Array): void;
+    /**
+     * @internal Completes a randomized fit from an externally computed
+     * decomposition of the centered data. `xc` must be the centered training
+     * buffer (X.data itself when copy=false, matching sklearn's destructive
+     * semantics) and `meanF64` the original column means.
+     */
+    _fitDecomposed(X: Matrix, xc: FloatArray, meanF64: Float64Array, dec: SvdResult): void;
+    /** @internal Option access for the WebGPU frontend (read-only). */
+    _resolvedOptions(): Readonly<ResolvedOptions>;
+    /** The fitCore preamble shared by the internal fit bridges. */
+    private prepareFit;
+    /**
+     * @internal Emits the finalize event (fraction 1, snapshot of the final
+     * model) after storeFitted — shared by _fitSteps and the WebGPU frontend.
+     * `u`/`s` are the fit's left vectors and singular values when the solver
+     * produced them (already sign-flipped), used for U·S snapshot scores.
+     */
+    _emitFinalize(reporter: ProgressReporter, x: Matrix, u: Float64Array | null, uCols: number, s: Float64Array | null): void;
+    /**
+     * The final model as a snapshot (fresh float64 copies of the stored
+     * attributes — float32 fits produce float32-rounded values, faithfully
+     * reflecting the model). Scores use U·S when the solver produced a U
+     * (`fitTransform`'s math) and one projection GEMM for covariance_eigh,
+     * whose fit never mutates X.
+     */
+    private finalizeSnapshot;
+    private storeFitted;
+    /**
+     * The fitted model as a plain structured-clone-friendly object (tight
+     * typed-array copies) — for `postMessage`, IndexedDB, or `modelToJSON`.
+     * A live `RandomState` in the options serializes as null.
+     */
+    toModel(): PCAModel;
+    /**
+     * Rehydrates a fitted PCA from `toModel()` output (validated first).
+     * The model's arrays are adopted without copying — pass a copy if the
+     * caller keeps mutating the model object.
+     */
+    static fromModel(model: PCAModel): PCA;
+    /** Per-sample log-likelihood under the Tipping–Bishop probabilistic PCA model. */
+    scoreSamples(X: MatrixInput): FloatArray;
+    /** Mean log-likelihood of all samples — sklearn's `score`. */
+    score(X: MatrixInput): number;
+}
+export { RandomState };
+//# sourceMappingURL=pca.d.ts.map

package/dist/pca.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pca.d.ts","sourceRoot":"","sources":["../src/pca.ts"],"names":[],"mappings":"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"}