nstat.extras.latents.gpfa_bridge

Gaussian-Process Factor Analysis bridge via Elephant.

Wraps elephant.gpfa.GPFA (Yu et al. 2009, J. Neurophysiol. 102(1)) — smooth low-dimensional latent trajectories inferred from simultaneous multi-trial spike trains.

Scope

  • GPFAConfig — frozen dataclass capturing the fit hyper-parameters.

  • fit_gpfa() — main entry point. Accepts list[Trial] (native nstat) or list[list[neo.SpikeTrain]] (Elephant’s native shape).

  • GPFAResult — frozen dataclass with per-trial latent trajectories (n_bins, x_dim) plus the underlying elephant.gpfa.GPFA instance (exposed so callers can re- transform() held-out data).

GPFA has no MATLAB nSTAT counterpart; this is a pure Python-only extension and is opt-in via pip install nstat-toolbox[latents].

Install

pip install nstat-toolbox[latents]

Pulls Elephant (>=1.2) + Neo + quantities.

Functions

fit_gpfa(spike_trains, *[, config, seed])

Fit a GPFA model to multi-trial spike data.

Classes

GPFAConfig(x_dim[, bin_size_s, em_max_iter, ...])

Configuration for a GPFA fit.

GPFAResult(latent_trajectories, x_dim, ...)

Fitted GPFA model and latent trajectories.
class nstat.extras.latents.gpfa_bridge.GPFAConfig(x_dim, bin_size_s=0.02, em_max_iter=500, em_tol=1e-08, min_var_frac=0.01)[source]

Bases: object

Configuration for a GPFA fit.

Parameters:

  • x_dim (int) – Number of latent dimensions to recover.

  • bin_size_s (float) – Discretisation bin size in seconds. Default 0.02 (20 ms — the Yu et al. 2009 default).

  • em_max_iter (int) – Maximum EM iterations. Default 500.

  • em_tol (float) – Relative log-likelihood tolerance for convergence. Default 1e-8.

  • min_var_frac (float) – Minimum variance per latent dimension (numerical stability floor). Default 0.01.

x_dim: int
bin_size_s: float = 0.02
em_max_iter: int = 500
em_tol: float = 1e-08
min_var_frac: float = 0.01
class nstat.extras.latents.gpfa_bridge.GPFAResult(latent_trajectories, x_dim, bin_size_s, n_trials, log_likelihood, elephant_model)[source]

Bases: object

Fitted GPFA model and latent trajectories.

Variables:

  • latent_trajectories (list of (n_time_bins, x_dim) ndarrays) – Per-trial latent trajectories. Axis order is (time, latent) — the nstat population-data convention. Elephant’s native order is (latent, time); this bridge transposes for consistency with other nstat extras.

  • x_dim (int) – Number of recovered latent dimensions.

  • bin_size_s (float) – Bin size used for fitting (seconds).

  • n_trials (int) – Number of trials the model was fit on.

  • log_likelihood (float or None) – Final EM log-likelihood, or None if elephant did not surface a finite value. (Elephant reports the LL only every freq_ll iterations; intermediate entries are NaN — the bridge picks the last finite entry.)

  • elephant_model (object) – The underlying elephant.gpfa.GPFA fitted instance, exposed so callers can re-transform() held-out data via result.elephant_model.transform(new_spiketrains).

Parameters:
latent_trajectories: list[ndarray]
x_dim: int
bin_size_s: float
n_trials: int
log_likelihood: float | None
elephant_model: object
nstat.extras.latents.gpfa_bridge.fit_gpfa(spike_trains, *, config=None, seed=None)[source]

Fit a GPFA model to multi-trial spike data.

Parameters:

  • spike_trains (Any) – Either a list[Trial] of native nstat trial objects (each carrying an nspikeColl SpikeTrainCollection), or a list[list[neo.SpikeTrain]] matching Elephant’s native input shape. Any other shape raises TypeError.

  • config (GPFAConfig | None) – Fit configuration. None defaults to GPFAConfig(x_dim=3) (the Elephant default).

  • seed (int | None) – Optional integer seed. When provided, the legacy numpy global seed is temporarily set so the FA-init + EM fit are reproducible; the caller’s previous RNG state is restored on exit.

Return type:

GPFAResult

Raises:

  • TypeError – If spike_trains is not one of the accepted shapes.

  • ValueError – If len(spike_trains) < 2 — GPFA’s EM covariance estimation is degenerate on a single trial (Yu et al. 2009 §2.3).

  • ImportError – If the elephant / neo / quantities optional dependency is missing. The error names the install command.

Notes

Elephant’s elephant.gpfa.GPFA consumes the module-level numpy random state (no rng= parameter). When seed is provided, this bridge wraps the fit in np.random.get_state() / np.random.set_state() so reproducibility works AND the caller’s RNG context is preserved — a deliberate, isolated exception to the “default_rng-only” convention.