gfa.simulation#

Simulate data from the group factor analysis (GFA) generative model.

Classes

GFASimulationResult

Complete output of a GFA simulation run.

Functions

`simulate`	Generate samples from the full group factor analysis model.
`sample_observations`	Generate observed data via the GFA observation model.
`save_simulation`	Save complete simulation result to safetensors file.
`save_simulation_recipe`	Save simulation recipe (config + hyperprior only).
`load_simulation`	Load complete simulation from file.
`load_simulation_recipe`	Load simulation recipe from file.

class GFASimulationResult( config: GFASimConfig, hyperprior: ObsParamsHyperPrior | ObsParamsHyperPriorStructured, obs_params: ObsParamsRealization, latents: LatentsRealization, observations: ObsStatic, )[source]#

Complete output of a GFA simulation run.

Bundles the specification (config + hyperprior) with the sampled outputs (obs_params, latents, observations). This is a run artifact analogous to a fitted GFAModel.

Parameters:

configGFASimConfig: Experimental design parameters used for simulation.
hyperpriorObsParamsHyperPrior or ObsParamsHyperPriorStructured: Probabilistic model specification.
obs_paramsObsParamsRealization: Sampled observation model parameters (C, d, phi, alpha).
latentsLatentsRealization: Sampled latent variables.
observationsObsStatic: Generated observed data.

simulate( config: GFASimConfig, hyperprior: ObsParamsHyperPrior | ObsParamsHyperPriorStructured, ) → GFASimulationResult[source]#

Generate samples from the full group factor analysis model.

Parameters:

configGFASimConfig: Experimental design parameters (n_samples, y_dims, x_dim, snr, seed).
hyperpriorObsParamsHyperPrior or ObsParamsHyperPriorStructured: Probabilistic model specification. For structured sparsity patterns, use ObsParamsHyperPriorStructured where a_alpha and b_alpha arrays specify group- and column-specific patterns. Use np.inf in a_alpha to force zero loadings.

Returns:

GFASimulationResult: Complete simulation output including config, hyperprior, sampled parameters, latents, and observations.

Examples

>>> config = GFASimConfig(
...     n_samples=100,
...     y_dims=np.array([10, 10]),
...     x_dim=5,
...     random_seed=42,
... )
>>> hyperprior = ObsParamsHyperPrior(
...     a_alpha=1.0, b_alpha=1.0, a_phi=1.0, b_phi=1.0, beta_d=1.0
... )
>>> result = simulate(config, hyperprior)
>>> result.observations.data.shape
(20, 100)

sample_observations( latents: LatentsRealization, obs_params: ObsParamsRealization | ObsParamsPoint, rng: Generator, ) → ObsStatic[source]#

Generate observed data via the GFA observation model.

Parameters:

latentsLatentsRealization: Sampled latent data.
obs_paramsObsParamsRealization or ObsParamsPoint: GFA observation model parameters, either as a full realization or as point estimates.
rngnumpy.random.Generator: NumPy random number generator.

Returns:

ObsStatic: Generated observed data.

save_simulation( path: str | PathLike[str], result: GFASimulationResult, ) → None[source]#

Save complete simulation result to safetensors file.

Saves the full snapshot: config, hyperprior, obs_params, latents, and observations. Use load_simulation() to restore.

Parameters:

pathstr or PathLike: Output file path (conventionally ends in .safetensors).
resultGFASimulationResult: Complete simulation result to save.