Skip to content

PaperOverview.md

Latest commit

 

History

History
170 lines (122 loc) · 6.86 KB

PaperOverview.md

File metadata and controls

170 lines (122 loc) · 6.86 KB

Paper-Aligned Toolbox Map

This page aligns the Python port with the original nSTAT toolbox paper:

Class Hierarchy and Object Model

The Python port preserves the MATLAB toolbox's core object groupings:

  • Signal and covariate primitives: SignalObj, Covariate, ConfidenceInterval, CovColl
  • Spiking data structures: nspikeTrain, nstColl, History, Events
  • Experiment and configuration objects: Trial, TrialConfig, ConfigColl
  • Modeling and inference objects: CIF, Analysis, FitResult, FitResSummary, DecodingAlgorithms

Related navigation pages:

Fitting and Assessment Workflow

The paper's core GLM workflow (Section 2.3) maps to Python as:

  1. Build trial data with Trial, CovColl, and nstColl.
  2. Define model configurations with TrialConfig and ConfigColl.
  3. Fit and evaluate analyses with Analysis and FitResult.
  4. Summarize across fits with FitResSummary.

Key Analysis methods for model selection:

  • computeHistLag / computeHistLagForAll — sweep spike-history window configurations and select optimal lag via AIC/BIC/KS.
  • computeGrangerCausalityMatrix — ensemble Granger causality analysis.
  • compHistEnsCoeff / compHistEnsCoeffForAll — ensemble history coefficients.
  • computeNeighbors — identify functionally connected neighbors.

Key FitResSummary plotting methods:

  • plotIC, plotAIC, plotBIC, plotlogLL — information criterion plots.
  • plotSummary, plotResidualSummary — aggregate diagnostics.
  • boxPlot, binCoeffs — coefficient distribution analysis.

Representative notebooks are indexed in Examples, especially AnalysisExamples, FitResultExamples, and FitResSummaryExamples.

Simulation Workflow

The simulation workflow remains centered on conditional intensity functions and thinning-based point-process simulation (Section 2.2):

  • CIF — conditional intensity function primitives, including simulateCIF
  • PPThinning — point-process thinning simulation
  • PPSimExample — complete simulation workflow

These are covered by the corresponding notebooks listed in Examples.

State-Space GLM (SSGLM) Workflow

The state-space GLM estimation (Section 2.4) is now fully implemented:

  • DecodingAlgorithms.PPSS_EMFB — full EM algorithm with forward-backward Kalman smoothing. Estimates across-trial coefficient dynamics with confidence intervals.
  • DecodingAlgorithms.PPSS_EStep — E-step: forward Kalman filter + backward RTS smoother + cross-covariance computation.
  • DecodingAlgorithms.PPSS_MStep — M-step: Newton-Raphson update for observation model parameters.
  • DecodingAlgorithms.PPSS_EM — single-neuron EM driver.
  • nstColl.ssglm / nstColl.ssglmFB — collection-level convenience wrappers that run SSGLM across all neurons in a spike train collection.

This workflow is demonstrated in Example 03 (PSTH and SSGLM dynamics).

Decoding Workflow

The adaptive filtering and decoding portions of the paper (Sections 2.5-2.6) map to:

Point-process adaptive filters (Section 2.5):

  • DecodingAlgorithms.PPDecodeFilterLinear — linear-CIF point-process adaptive filter for continuous stimulus decoding. Supports goal-directed decoding via backward information filter (Srinivasan et al. 2006) when yT and PiT target parameters are provided.
  • DecodingAlgorithms.PPDecodeFilter — general CIF version using symbolic gradients/Jacobians.
  • DecodingAlgorithms.ComputeStimulusCIs — stimulus confidence intervals via Monte Carlo sampling (dual-path: 4-D SSGLM cross-trial + 3-D smoother z-score).
  • DecodingAlgorithms.computeSpikeRateCIs — spike rate confidence intervals and pairwise significance testing across trials.
  • DecodingAlgorithms.PP_fixedIntervalSmoother — fixed-interval smoother for off-line smoothing of decode estimates.

Hybrid filter (Section 2.6):

  • DecodingAlgorithms.PPHybridFilterLinear — joint discrete/continuous state estimation combining point-process observations with a hidden Markov model over discrete states and Kalman filtering over continuous kinematics. Supports goal-directed decoding via per-model backward information filters when yT and PiT are provided.

Kalman and UKF filters:

  • DecodingAlgorithms.kalman_filter — standard linear Kalman filter.
  • DecodingAlgorithms.ukf — unscented Kalman filter for nonlinear state estimation.

Related notebooks:

  • DecodingExample, DecodingExampleWithHist, StimulusDecode2D, HybridFilterExample

Signal Processing Methods

SignalObj now includes a full suite of signal processing methods mirroring the MATLAB toolbox:

Spectral analysis:

  • MTMspectrum — multi-taper spectral estimation using DPSS tapers.
  • spectrogram — time-frequency decomposition.
  • periodogram — standard periodogram PSD estimate.

Correlation and cross-covariance:

  • xcorr — cross-correlation (or auto-correlation).
  • xcov — cross-covariance with lag support.
  • autocorrelation, crosscorrelation — normalized correlation functions.

Time manipulation:

  • shift / shiftMe — shift signal in time (copy vs in-place).
  • alignTime — re-reference time axis to a marker.
  • power, sqrt — element-wise transforms.

Peak-finding:

  • findPeaks, findMaxima, findMinima — local extrema via scipy.signal.find_peaks.
  • findGlobalPeak — global maximum or minimum per channel.

Example-to-Paper Section Mapping

The paper's representative workflows align to the following Python surfaces:

Paper section Example Python surface
2.3.1 — mEPSC Poisson Example 01 examples/paper/example01_mepsc_poisson.py
2.3.2 — Whisker stimulus Example 02 examples/paper/example02_whisker_stimulus_thalamus.py
2.3.3 — PSTH Example 03, Part A examples/paper/example03_psth_and_ssglm.py
2.4 — SSGLM Example 03, Part B examples/paper/example03_psth_and_ssglm.py
2.3.4 — Place cells Example 04 examples/paper/example04_place_cells_continuous_stimulus.py
2.5 — PPAF decoding Example 05, Parts A-B examples/paper/example05_decoding_ppaf_pphf.py
2.6 — Hybrid filter Example 05, Part C examples/paper/example05_decoding_ppaf_pphf.py

See also:

  • nSTATPaperExamples notebook and the canonical gallery in Paper Examples
  • All five paper examples are now self-contained scripts with full analysis workflows, matching their MATLAB counterparts.