gfa.model#

GFAModel class for Group Factor Analysis.

class GFAModel( config: GFAFitConfig | None = None, obs_hyperprior: ObsParamsHyperPrior | None = None, )[source]#

High-level interface for Group Factor Analysis.

Parameters:

configGFAFitConfig or None, default None: Fitting configuration. If None, uses default GFAFitConfig().
obs_hyperpriorObsParamsHyperPrior or None, default None: Prior hyperparameters for observation model. If None, uses default.

Attributes:

configGFAFitConfig: Fitting configuration (immutable after construction).
obs_posteriorObsParamsPosterior or None: Posterior over observation model parameters. None until fit.
latents_posteriorLatentsPosteriorStatic or None: Posterior over latent variables. None until fit.
trackerGFAFitTracker or None: Fitting progress tracker. None until fit.
flagsGFAFitFlags or None: Fitting status flags. None until fit.

Examples

Basic usage: fit and infer

>>> from latents.gfa import GFAModel, GFAFitConfig
>>> from latents.callbacks import ProgressCallback
>>> config = GFAFitConfig(x_dim_init=10)
>>> model = GFAModel(config=config)
>>> model.fit(Y, callbacks=[ProgressCallback()])
>>> X_new = model.infer_latents(Y_new)

Persistence: save and load

>>> model.save("fitted_model.safetensors")
>>> loaded = GFAModel.load("fitted_model.safetensors")

Methods:

`fit`	Fit model to data via variational inference.
`resume_fit`	Resume an interrupted fit.
`clear_fit`	Clear fit results for fresh initialization on next fit().
`infer_latents`	Infer latent posterior for new data given fitted parameters.
`recompute_latents`	Recompute latents from data.
`recompute_loadings`	Recompute loading posterior from data.
`save`	Save model to a safetensors file.
`load`	Load model from a safetensors file.

property obs_hyperprior: ObsParamsHyperPrior#: Observation model hyperprior parameters.

property obs_prior: ObsParamsPrior#: Observation model prior.

property latents_prior: LatentsPriorStatic#: Latent variable prior.

fit( Y: ObsStatic, callbacks: list | None = None, ) → Self[source]#

Fit model to data via variational inference.

Resets tracker and flags. Warm-starts from posteriors if present, otherwise initializes from scratch.

Parameters:

YObsStatic: Observed data.
callbackslist of Callback or None, default None: List of callback objects for progress, logging, checkpointing, etc. See callbacks module.

Returns:

Self: The fitted model (for method chaining).

Examples

>>> from latents.gfa import GFAModel, GFAFitConfig
>>> from latents.callbacks import ProgressCallback
>>> config = GFAFitConfig(x_dim_init=10, max_iter=100)
>>> model = GFAModel(config=config)
>>> model.fit(Y, callbacks=[ProgressCallback()])

resume_fit( Y: ObsStatic, max_iter: int | None = None, callbacks: list | None = None, ) → Self[source]#

Resume an interrupted fit.

Appends to tracker, preserves convergence baseline.

Parameters:

YObsStatic: Observed data.
max_iterint or None, default None: Maximum iterations for this resume run. If None, uses config.max_iter.
callbackslist of Callback or None, default None: List of callback objects for progress, logging, checkpointing, etc.

Returns:

Self: The model (for method chaining).

Raises:

ValueError: If no fit to resume (posteriors not initialized).

clear_fit() → Self[source]#

Clear fit results for fresh initialization on next fit().

Returns:

Self: The model (for method chaining).

infer_latents( Y: ObsStatic, ) → LatentsPosteriorStatic[source]#

Infer latent posterior for new data given fitted parameters.

Does not modify the model’s stored latents_posterior.

Parameters:

YObsStatic: Observed data.

Returns:

LatentsPosteriorStatic: Posterior over latent variables for the given data.

Raises:

ValueError: If model has not been fitted.

Examples

>>> model.fit(Y_train)
>>> X_test = model.infer_latents(Y_test)
>>> X_test.mean.shape
(5, 50)

recompute_latents(Y: ObsStatic) → Self[source]#

Recompute latents from data. Updates self.latents_posterior.

Use this to restore latents after loading a model saved with save_x=False.

Parameters:

YObsStatic: Observed data (typically the training data).

Returns:

Self: The model (for method chaining).

Raises:

ValueError: If model has not been fitted.

recompute_loadings(Y: ObsStatic) → Self[source]#

Recompute loading posterior from data. Updates self.obs_posterior.C.

Use this to restore C.cov after loading a model saved with save_c_cov=False.

Note: At convergence, the recomputed values are essentially identical to the original fitted values. Pre-convergence, there may be non-negligible differences because the reconstruction uses the final latents posterior rather than the latents posterior from the previous iteration.

Parameters:

YObsStatic: Observed data (typically the training data).

Returns:

Self: The model (for method chaining).

Raises:

ValueError: If model has not been fitted, or if latents are not available.

save(path: str | PathLike[str]) → None[source]#

Save model to a safetensors file.

Uses safetensors format for secure serialization (no arbitrary code execution on load). Arrays are stored as tensors; scalars and config are stored as JSON in metadata.

Parameters:

pathstr or PathLike: Output file path (conventionally ends in .safetensors).

classmethod load(path: str | PathLike[str]) → GFAModel[source]#

Load model from a safetensors file.

Parameters:

pathstr or PathLike: Path to .safetensors file.

Returns:

GFAModel: Loaded model, ready for inference or continued fitting.