nstat.extras.latents.gpfa_bridge

Gaussian-Process Factor Analysis (Yu et al. 2009, J. Neurophysiol. 102(1)) for inferring smooth low-dimensional latent trajectories from simultaneous spike trains. Bridges elephant.gpfa.GPFA; pure Python-only extension, no MATLAB nSTAT counterpart.

Install

pip install nstat-toolbox[latents]

Pulls Elephant (>=1.2) plus Neo and quantities (~50 MB combined).

API

Symbol

Notes

GPFAConfig(x_dim, bin_size_s=0.02, em_max_iter=500, em_tol=1e-8, min_var_frac=0.01)

Fit configuration; frozen dataclass with __post_init__ validation.

fit_gpfa(spike_trains, *, config=None, seed=None) -> GPFAResult

Main entry point. Accepts list[Trial] or list[list[neo.SpikeTrain]]; requires >=2 trials.

GPFAResult

Frozen dataclass: latent_trajectories: list[(n_bins, x_dim) ndarray], x_dim, bin_size_s, n_trials, log_likelihood, elephant_model.

Worked example

see examples/extras/latents_gpfa_demo.py

Notes

  • Multi-trial requirement. GPFA’s EM covariance estimation is degenerate on a single trial; the bridge raises ValueError if len(spike_trains) < 2.

  • Axis order. Latent trajectories are returned as (n_bins, x_dim) — nstat’s (time, feature) convention. Elephant’s native order is (x_dim, n_bins), transposed inside the bridge.

  • Log-likelihood reporting. Elephant evaluates the log-likelihood only every freq_ll=5 iterations; intermediate trace entries are NaN. GPFAResult.log_likelihood returns the last finite entry, or None if elephant produced no finite value.

  • Seed semantics. Elephant’s GPFA uses module-level numpy random. Passing seed to fit_gpfa temporarily sets the legacy seed and restores the previous state on exit, so the caller’s RNG context is preserved. This is the sole legacy-np.random.seed use in nstat — the default_rng-only convention applies everywhere else.

References

  • Yu BM, Cunningham JP, Santhanam G, Ryu SI, Shenoy KV, Sahani M. (2009). Gaussian-process factor analysis for low-dimensional single-trial analysis of neural population activity. J. Neurophysiol. 102(1): 614–635.