Fit results and learning curves¶

The low-level pca_full() function returns a regular dictionary with the historical keys. Its return annotation is PCAResult, available from vbpca_py.results. The type describes the current runtime contract; it does not wrap or copy the fitted arrays.

import numpy as np

from vbpca_py._pca_full import pca_full
from vbpca_py import PCAResult

data = np.array([[1., 2., 3.], [3., 1., 2.]])
result: PCAResult = pca_full(
    data, n_components=1, maxiters=2, niter_broadprior=0, random_state=4
)
loadings = result["A"]  # features by components
scores = result["S"]    # components by samples

This two-iteration example demonstrates the return structure; a scientific fit needs separate convergence checks.

Xrec, Vr, Vpred, ExplainedVar and ExplainedVarRatio are None when diagnostics are disabled. Covariances can be a sequence of blocks or a stacked array; Isv, when present, maps samples to shared score covariance blocks. When reusing score covariances in a warm start, retain Sv and its Isv together; source bank labels and the next fit's prepared pattern labels have different roles. The warm-start layout contract defines their indexing and retained-feature/sample behavior. Float-array aliases specify float64 dtype. Pattern indices use NumPy's default integer dtype, which can depend on platform and NumPy version. Shape and ownership requirements remain documented runtime contracts, rather than checks performed by typing.

LearningCurve describes both metric histories and fit metadata. For example, rms is a list of floats, returned_iteration is an integer, convergence_reason is a string and optional prior_trace is a list of vectors. The estimator exposes this mapping through learning_curve_ after fitting. Optional fields can be absent; use get() when reading them.

curve = result["lc"]
returned_iteration = curve.get("returned_iteration")
best_probe_rms = curve.get("best_probe_rms")

Strict type checking checks example consumers as well as the library. The test suite runs the result and pca_full docstring examples and checks that unknown result keys and incorrectly typed metadata produce type-checking errors.

results ¶

Typed dictionaries for the existing PCA_FULL results and learning curves.

These annotations describe ordinary dictionaries; they do not copy arrays, change mutability or rename result keys. Matrix orientation remains features by samples. Array dimensions below use p features, n samples and q fitted components. NumPy typing specifies dtype but does not check shapes.

Examples:

>>> import numpy as np
>>> from vbpca_py._pca_full import pca_full
>>> data = np.array([[1.0, 2.0, 3.0], [3.0, 1.0, 2.0]])
>>> result = pca_full(
...     data,
...     1,
...     maxiters=2,
...     niter_broadprior=0,
...     return_diagnostics=False,
...     random_state=4,
... )
>>> result["A"].shape, result["S"].shape
((2, 1), (1, 3))
>>> result["Xrec"] is None
True
>>> isinstance(result["lc"]["returned_iteration"], int)
True

PCAResult ¶

Bases: TypedDict

Full-covariance PCA result with the historical key names.

A and S have shapes (p, q) and (q, n). Mu holds the feature means and V the observation-noise variance. Av/Sv are covariance blocks, also available through cv. They are not elementwise variance matrices. Muv contains posterior mean variances; Va/Vmu are prior variances, also available through hp.

With diagnostics enabled, Xrec, Vr and Vpred have shape (p, n): reconstruction, latent reconstruction variance and predictive variance for a new observed entry, respectively. Vpred adds V to Vr. These arrays and the explained-variance arrays are None when diagnostics are disabled. RuntimeReport is optional runtime metadata.

RMS, PRMS and Cost describe the returned model, which may be an earlier probe-selected state. Missing metrics are NaN. Probe iteration and RMS fields are None when no finite probe optimum was recorded.

LearningCurve ¶

Bases: TypedDict

Metric histories and metadata from a fit, including optional fields.

Numeric histories include the initial state at index zero. Metadata are scalars, strings or mappings, rather than numeric histories. prior_trace contains one vector per recorded update when prior tracing is requested. Fields beginning with an underscore support the live training loop.

CovarianceResult ¶

Bases: TypedDict

Posterior covariance blocks and optional sample-to-pattern index.

HyperparameterResult ¶

Bases: TypedDict

Prior variances for loadings (Va) and the mean (Vmu).