VBPCA¶
VBPCA ¶
VBPCA(n_components: int, *, bias: bool = True, maxiters: int | None = None, tol: float | None = None, verbose: int | bool = 0, hp_va: float | None = None, hp_vb: float | None = None, hp_v: float | None = None, niter_broadprior: int | None = None, va_init: float | None = None, xprobe_fraction: float = 0.0, criterion_order: list[str] | None = None, convergence_criteria: dict[str, bool] | None = None, **opts: object)
Variational Bayesian PCA with a sklearn-like interface.
Initialize the estimator with common VB-PCA options.
Args:
n_components: Number of principal components to infer.
bias: If True, include a bias (mean) term in the model.
maxiters: Maximum number of iterations for the training loop.
tol: Tolerance for convergence.
verbose: Verbosity level; can be an integer or a boolean.
hp_va: Prior hyperparameter for loadings variance (default 0.001).
hp_vb: Prior hyperparameter for score variance (default 0.001).
hp_v: Prior hyperparameter for noise variance (default 0.001).
niter_broadprior: Number of iterations to run under the broad
prior before convergence checks activate (default 100).
va_init: Initial broad prior value for loadings and bias
variances (default 1000).
xprobe_fraction: Fraction of observed entries to hold out as
probe data (default 0.0, disabled). When positive and no
explicit xprobe is passed to :meth:fit, a random probe
set is generated automatically.
criterion_order: Priority order for convergence criteria.
Defaults to DEFAULT_CRITERION_ORDER when None.
convergence_criteria: Per-criterion enable/disable dict. Keys
are criterion names, values are booleans. Criteria set to
False are still evaluated for diagnostics but excluded
from the stop decision. Defaults to all enabled.
**opts: Additional options passed to the underlying PCA_FULL implementation.
fit ¶
Fit the model to data, optionally supplying a mask.
Args:
x: Data matrix of shape (n_features, n_samples).
mask: Optional boolean mask of the same shape as x, where True
indicates observed entries.
xprobe: Optional probe matrix of the same shape as x used for
early-stopping diagnostics. Entries that are not NaN
(dense) or explicitly stored (sparse) are treated as held-out
observations. When provided, the model monitors probe-RMS
and can stop early before ARD over-prunes components.
Returns: The fitted estimator instance.
Raises:
ValueError: If mask shape does not match x.
get_options ¶
Return the resolved pca_full options (defaults + overrides).
transform ¶
Return scores from the fitted model; new data not yet supported.
Raises: RuntimeError: If the model is not fitted.
fit_transform ¶
Convenience wrapper for fit + transform on the training data.
Returns: Scores for the training data.
inverse_transform ¶
Reconstruct data from scores using fitted loadings and mean.
Returns: Reconstructed data matrix with shape (n_features, n_samples).
Raises: RuntimeError: If the model is not fitted.
select_n_components ¶
select_n_components(x: Matrix, *, mask: Matrix | None = None, components: list[int] | range | None = None, config: SelectionConfig | None = None, **opts: object) -> tuple[int, dict[str, object], list[dict[str, object]], VBPCA | None]
Delegate to model selection helper using this estimator's defaults.
Returns: Tuple of (best_k, best_metrics, trace, best_model) from the shared model-selection helper.