cajigaslab · iahncajigas · Mar 10, 2026 · Mar 10, 2026
diff --git a/docs/ClassDefinitions.md b/docs/ClassDefinitions.md
@@ -1,26 +1,255 @@
 # Class Definitions
 
 The Python port preserves the MATLAB-facing class names as canonical imports or
-compatibility adapters.
-
-| MATLAB-facing name | Python target | Primary example surface |
-|---|---|---|
-| `SignalObj` | `nstat.SignalObj` | `notebooks/SignalObjExamples.ipynb` |
-| `Covariate` | `nstat.Covariate` | `notebooks/CovariateExamples.ipynb` |
-| `ConfidenceInterval` | `nstat.ConfidenceInterval` | `notebooks/ConfidenceIntervalOverview.ipynb` |
-| `CovColl` | `nstat.CovColl` | `notebooks/CovCollExamples.ipynb` |
-| `Events` | `nstat.Events` | `notebooks/EventsExamples.ipynb` |
-| `History` | `nstat.History` | `notebooks/HistoryExamples.ipynb` |
-| `Trial` | `nstat.Trial` | `notebooks/TrialExamples.ipynb` |
-| `TrialConfig` | `nstat.TrialConfig` | `notebooks/TrialConfigExamples.ipynb` |
-| `ConfigColl` | `nstat.ConfigColl` | `notebooks/ConfigCollExamples.ipynb` |
-| `nspikeTrain` | `nstat.nspikeTrain` | `notebooks/nSpikeTrainExamples.ipynb` |
-| `nstColl` | `nstat.nstColl` | `notebooks/nstCollExamples.ipynb` |
-| `Analysis` | `nstat.Analysis` | `notebooks/AnalysisExamples.ipynb` |
-| `FitResult` | `nstat.FitResult` | `notebooks/FitResultExamples.ipynb` |
-| `FitResSummary` | `nstat.FitResSummary` | `notebooks/FitResSummaryExamples.ipynb` |
-| `CIF` | `nstat.CIF` | `notebooks/PPSimExample.ipynb` |
-| `DecodingAlgorithms` | `nstat.DecodingAlgorithms` | `notebooks/DecodingExample.ipynb` |
+compatibility adapters. Each class below lists its key public methods grouped by
+category.
+
+## Signal and Covariate Primitives
+
+### `SignalObj` (`nstat.SignalObj`)
+
+Primary notebook: `notebooks/SignalObjExamples.ipynb`
+
+**Construction and metadata**:
+`copySignal`, `setName`, `setXlabel`, `setYLabel`, `setUnits`, `setXUnits`,
+`setYUnits`, `setSampleRate`, `setDataLabels`, `setPlotProps`, `with_metadata`
+
+**Accessors**:
+`getTime`, `getData`, `getOriginalData`, `getOrigDataSig`, `getPlotProps`,
+`getValueAt`, `getSubSignalFromInd`, `getSubSignalFromNames`, `getSubSignal`,
+`findNearestTimeIndex`, `findNearestTimeIndices`, `dataToMatrix`,
+`dataToStructure`, `toStructure`, `signalFromStruct`
+
+**Masking**:
+`setDataMask`, `setMaskByInd`, `setMaskByLabels`, `setMask`, `resetMask`,
+`restoreToOriginal`, `findIndFromDataMask`, `isMaskSet`
+
+**Time windowing**:
+`setMinTime`, `setMaxTime`, `getSigInTimeWindow`, `makeCompatible`
+
+**Math and transforms**:
+`abs`, `log`, `power`, `sqrt`, `median`, `mode`, `mean`, `std`, `max`, `min`,
+`derivative`, `derivativeAt`, `integral`, `resample`, `resampleMe`,
+`filter`, `filtfilt`, `merge`
+
+**Shift and alignment**:
+`shift`, `shiftMe`, `alignTime`
+
+**Correlation**:
+`autocorrelation`, `crosscorrelation`, `xcorr`, `xcov`
+
+**Spectral analysis**:
+`periodogram`, `MTMspectrum`, `spectrogram`
+
+**Peak-finding**:
+`findPeaks`, `findMaxima`, `findMinima`, `findGlobalPeak`
+
+**Plotting**:
+`plot`
+
+### `Covariate` (`nstat.Covariate`)
+
+Primary notebook: `notebooks/CovariateExamples.ipynb`
+
+Inherits from `SignalObj`. Adds confidence interval support:
+`setConfInterval`, `mu`, `sigma`
+
+### `ConfidenceInterval` (`nstat.ConfidenceInterval`)
+
+Primary notebook: `notebooks/ConfidenceIntervalOverview.ipynb`
+
+### `CovColl` (`nstat.CovColl`)
+
+Primary notebook: `notebooks/CovCollExamples.ipynb`
+
+**Collection management**:
+`add`, `addCovariate`, `addCovCollection`, `addToColl`, `removeCovariate`,
+`copy`, `get`, `getCov`, `getCovIndFromName`, `getCovIndicesFromNames`,
+`isCovPresent`
+
+**Time and sample rate**:
+`findMinTime`, `findMaxTime`, `findMaxSampleRate`, `setMinTime`, `setMaxTime`,
+`restrictToTimeWindow`, `setSampleRate`, `resample`, `enforceSampleRate`
+
+**Masking**:
+`resetMask`, `getCovDataMask`, `isCovMaskSet`, `flattenCovMask`,
+`getSelectorFromMasks`, `generateSelectorCell`, `setMasksFromSelector`,
+`setMask`, `nActCovar`, `maskAwayCov`, `maskAwayOnlyCov`, `maskAwayAllExcept`
+
+**Shift and restore**:
+`setCovShift`, `resetCovShift`, `restoreToOriginal`
+
+**Data export**:
+`getAllCovLabels`, `getCovLabelsFromMask`, `matrixWithTime`, `dataToMatrix`,
+`dataToStructure`, `toStructure`, `fromStructure`
+
+---
+
+## Spiking Data Structures
+
+### `nspikeTrain` (`nstat.nspikeTrain`)
+
+Primary notebook: `notebooks/nSpikeTrainExamples.ipynb`
+
+### `nstColl` (`nstat.nstColl`)
+
+Primary notebook: `notebooks/nstCollExamples.ipynb`
+
+**Collection management**:
+`addSingleSpikeToColl`, `addToColl`, `merge`, `length`, `get_nst`, `getNST`,
+`getNSTnames`, `getUniqueNSTnames`, `toSpikeTrain`
+
+**Time operations**:
+`shiftTime`, `setMinTime`, `setMaxTime`
+
+**SSGLM (state-space GLM)**:
+`ssglm`, `ssglmFB`
+
+**Basis generation**:
+`generateUnitImpulseBasis`
+
+### `History` (`nstat.History`)
+
+Primary notebook: `notebooks/HistoryExamples.ipynb`
+
+### `Events` (`nstat.Events`)
+
+Primary notebook: `notebooks/EventsExamples.ipynb`
+
+---
+
+## Experiment and Configuration Objects
+
+### `Trial` (`nstat.Trial`)
+
+Primary notebook: `notebooks/TrialExamples.ipynb`
+
+**Partitioning**:
+`getTrialPartition`, `setTrialPartition`, `setTrialTimesFor`,
+`updateTimePartitions`
+
+**Time and sample rate**:
+`setMinTime`, `setMaxTime`, `setSampleRate`, `resample`,
+`makeConsistentSampleRate`, `makeConsistentTime`, `isSampleRateConsistent`,
+`findMaxSampleRate`, `findMinTime`, `findMaxTime`
+
+**Covariate and neuron masks**:
+`setCovMask`, `resetCovMask`, `setNeuronMask`, `resetNeuronMask`,
+`setNeighbors`, `setHistory`, `resetHistory`, `setEnsCovHist`, `setEnsCovMask`,
+`resetEnsCovMask`, `isNeuronMaskSet`, `isCovMaskSet`, `isMaskSet`, `isHistSet`,
+`isEnsCovHistSet`
+
+**Data access**:
+`addCov`, `removeCov`, `getSpikeVector`, `get_covariate_matrix`,
+`getDesignMatrix`, `getHistForNeurons`, `getHistMatrices`,
+`getEnsembleNeuronCovariates`, `getEnsCovMatrix`, `getNeuronIndFromMask`,
+`getNumUniqueNeurons`, `getNeuronNames`, `getUniqueNeuronNames`,
+`getNeuronIndFromName`, `getAllCovLabels`, `getCovLabelsFromMask`,
+`getHistLabels`, `getEnsCovLabels`, `getLabelsFromMask`, `flattenCovMask`,
+`flattenMask`
+
+**Utilities**:
+`shiftCovariates`, `resampleEnsColl`, `restoreToOriginal`, `plot`
+
+### `TrialConfig` (`nstat.TrialConfig`)
+
+Primary notebook: `notebooks/TrialConfigExamples.ipynb`
+
+### `ConfigColl` (`nstat.ConfigColl`)
+
+Primary notebook: `notebooks/ConfigCollExamples.ipynb`
+
+---
+
+## Modeling and Inference
+
+### `CIF` (`nstat.CIF`)
+
+Primary notebook: `notebooks/PPSimExample.ipynb`
+
+Conditional intensity function (CIF) primitives and point-process simulation
+via thinning.
+
+### `Analysis` (`nstat.Analysis`)
+
+Primary notebook: `notebooks/AnalysisExamples.ipynb`
+
+**Core fitting**:
+`GLMFit`, `run_analysis_for_neuron`, `run_analysis_for_all_neurons`,
+`RunAnalysisForNeuron`, `RunAnalysisForAllNeurons`
+
+**PSTH**:
+`psth`
+
+**Diagnostics**:
+`computeKSStats`, `computeInvGausTrans`, `computeFitResidual`,
+`KSPlot`, `plotFitResidual`, `plotInvGausTrans`, `plotSeqCorr`, `plotCoeffs`
+
+**History and model selection**:
+`computeHistLag`, `computeHistLagForAll`, `compHistEnsCoeff`,
+`compHistEnsCoeffForAll`
+
+**Network and Granger causality**:
+`computeGrangerCausalityMatrix`, `computeNeighbors`, `spikeTrigAvg`
+
+### `FitResult` (`nstat.FitResult`)
+
+Primary notebook: `notebooks/FitResultExamples.ipynb`
+
+**Coefficient access**:
+`getCoeffs`, `getHistCoeffs`, `getCoeffIndex`, `getHistIndex`, `getParam`,
+`getCoeffsWithLabels`, `computePlotParams`, `getPlotParams`
+
+**Lambda (conditional intensity) access**:
+`lambdaSignal`, `lambda_obj`, `lambda_model`, `lambda_result`, `lambdaObj`,
+`lambdaCov`, `lambda_sig`, `lambda_data`, `lambda_values`, `lambda_time`,
+`lambda_rate`, `evalLambda`
+
+**Diagnostics and statistics**:
+`computeKSStats`, `computeInvGausTrans`, `computeFitResidual`
+
+**Plotting**:
+`plotResults`, `KSPlot`, `plotResidual`, `plotInvGausTrans`, `plotSeqCorr`,
+`plotCoeffs`, `plotCoeffsWithoutHistory`, `plotHistCoeffs`, `plotValidation`
+
+**Serialization**:
+`toStructure`, `fromStructure`, `CellArrayToStructure`, `mergeResults`
+
+### `FitResSummary` (`nstat.FitResSummary`)
+
+Primary notebook: `notebooks/FitResSummaryExamples.ipynb`
+
+Alias of `FitSummary`. Aggregates multiple `FitResult` objects.
+
+**Information criterion**:
+`getDiffAIC`, `getDiffBIC`, `getDifflogLL`
+
+**Coefficient extraction**:
+`getCoeffs`, `getHistCoeffs`, `getSigCoeffs`, `binCoeffs`, `setCoeffRange`,
+`mapCovLabelsToUniqueLabels`
+
+**Plotting**:
+`plotIC`, `plotAIC`, `plotBIC`, `plotlogLL`, `plotResidualSummary`,
+`plotSummary`, `boxPlot`
+
+### `DecodingAlgorithms` (`nstat.DecodingAlgorithms`)
+
+Primary notebook: `notebooks/DecodingExample.ipynb`
+
+**Point-process decode filters**:
+`PPDecodeFilterLinear`, `PPDecodeFilter`, `PPHybridFilterLinear`,
+`ComputeStimulusCIs`
+
+**Kalman and unscented Kalman filters**:
+`kalman_filter`, `PP_fixedIntervalSmoother`, `ukf`
+
+**State-space GLM (SSGLM) — EM algorithm**:
+`PPSS_EStep`, `PPSS_MStep`, `PPSS_EM`, `PPSS_EMFB`
+
+**SSGLM utilities**:
+`estimateInfoMat`, `prepareEMResults`
+
+---
 
 See [Examples](Examples.md) for the full help-style index and
 [API Reference](api.rst) for the module layout.
diff --git a/docs/Examples.md b/docs/Examples.md
@@ -49,7 +49,26 @@ Paper cross-reference:
 
 ## Consolidated Paper Workflow
 
-- `nSTATPaperExamples`: `notebooks/nSTATPaperExamples.ipynb`
-- Canonical standalone scripts: `examples/paper/example01_mepsc_poisson.py`
-  through `examples/paper/example05_decoding_ppaf_pphf.py`
+All five paper examples are self-contained scripts mirroring their MATLAB
+counterparts:
+
+| Example | Script | What it demonstrates |
+|---|---|---|
+| 01 — mEPSC Poisson | [example01_mepsc_poisson.py](../examples/paper/example01_mepsc_poisson.py) | Constant vs piecewise Poisson under Mg2+ washout |
+| 02 — Whisker Stimulus | [example02_whisker_stimulus_thalamus.py](../examples/paper/example02_whisker_stimulus_thalamus.py) | Explicit-stimulus GLM with lag and history selection |
+| 03 — PSTH and SSGLM | [example03_psth_and_ssglm.py](../examples/paper/example03_psth_and_ssglm.py) | PSTH comparison and state-space GLM dynamics |
+| 04 — Place Cells | [example04_place_cells_continuous_stimulus.py](../examples/paper/example04_place_cells_continuous_stimulus.py) | Gaussian vs Zernike receptive-field models |
+| 05 — PPAF and PPHF | [example05_decoding_ppaf_pphf.py](../examples/paper/example05_decoding_ppaf_pphf.py) | Adaptive and hybrid point-process decoding |
+
 - Generated gallery and figure index: [Paper Examples](paper_examples.md)
+- Master notebook: `notebooks/nSTATPaperExamples.ipynb`
+
+## Supplementary (README) Examples
+
+These smaller demos serve as quick install and plotting checks:
+
+| Example | Run command |
+|---|---|
+| Multitaper spectrum + spectrogram | `python examples/readme_examples/example1_multitaper_and_spectrogram.py` |
+| Simulated CIF spike train | `python examples/readme_examples/example2_simulate_cif_spiketrain_10s.py` |
+| Spike-train raster | `python examples/readme_examples/example3_nstcoll_raster_from_example2.py` |
diff --git a/docs/NeuralSpikeAnalysis_top.md b/docs/NeuralSpikeAnalysis_top.md
@@ -1,33 +1,56 @@
 # Neural Spike Train Analysis Toolbox (nSTAT)
 
 `nSTAT-python` is the standalone Python port of the neural spike-train analysis
-toolbox. It preserves the MATLAB toolbox's public API naming, paper-example
+toolbox. It implements a range of models and algorithms for neural spike train
+data analysis, with a focus on point-process generalized linear models (GLMs),
+model fitting, model-order analysis, and adaptive decoding. In addition to
+point-process algorithms, nSTAT also provides tools for Gaussian signals — from
+correlation analysis to the Kalman filter — applicable to continuous neural
+signals such as LFP, EEG, and ECoG.
+
+The port preserves the MATLAB toolbox's public API naming, paper-example
 structure, and help/example coverage wherever a Python equivalent is
 reasonable.
 
 ## Documentation Navigation
 
-- [Paper-Aligned Toolbox Map](PaperOverview.md)
-- [Class Definitions](ClassDefinitions.md)
-- [Example Index](Examples.md)
-- [nSTAT Paper Examples](paper_examples.md)
-- [Documentation Setup](DocumentationSetup.md)
-- [API Reference](api.rst)
-
-## Purpose
-
-The toolbox consolidates point-process and GLM-based neural data analysis into
-a coherent Python package with:
-
-- MATLAB-compatible public entry points such as `Analysis`, `TrialConfig`,
-  `FitResult`, `DecodingAlgorithms`, `nSTAT_Install`, and `getPaperDataDirs`
-- Canonical paper examples exported as `examples/paper/example01` through
-  `example05`
-- Notebook-backed help workflows mirroring the MATLAB helpfiles
-- A generated figure gallery under `docs/figures/`
+- [Paper-Aligned Toolbox Map](PaperOverview.md) — maps classes and methods to
+  the 2012 paper's sections
+- [Class Definitions](ClassDefinitions.md) — all classes with grouped method
+  listings
+- [Example Index](Examples.md) — full help-style index of notebooks and scripts
+- [nSTAT Paper Examples](paper_examples.md) — generated gallery with figures
+  from all 5 paper examples
+- [Documentation Setup](DocumentationSetup.md) — installation, build, and
+  troubleshooting
+- [Data Installation](data_installation.rst) — example dataset download
+- [API Reference](api.rst) — module layout
+
+## Key Capabilities
+
+- **GLM fitting and assessment**: Point-process GLMs with stimulus, history,
+  and ensemble covariates. AIC/BIC model selection, KS goodness-of-fit,
+  residual analysis.
+- **SSGLM (state-space GLM)**: Full EM algorithm (`PPSS_EMFB`) for estimating
+  across-trial coefficient dynamics with forward-backward Kalman smoothing.
+- **Adaptive decoding**: Point-process adaptive filter (PPAF) for real-time
+  stimulus and state decoding from neural spike trains.
+- **Hybrid filter**: Joint discrete/continuous state estimation combining
+  point-process observations with hidden Markov models.
+- **UKF support**: Unscented Kalman filter for nonlinear state estimation.
+- **Signal processing**: Multi-taper spectral estimation, spectrograms,
+  cross-covariance, peak-finding, and time-domain signal manipulation.
+- **Granger causality**: Ensemble Granger causality analysis for network
+  connectivity inference.
 
 ## Citation
 
 Cajigas I, Malik WQ, Brown EN. *nSTAT: Open-source neural spike train analysis
 toolbox for Matlab*. Journal of Neuroscience Methods 211:245-264 (2012).
 DOI: [10.1016/j.jneumeth.2012.08.009](https://doi.org/10.1016/j.jneumeth.2012.08.009)
+PMID: [22981419](https://pubmed.ncbi.nlm.nih.gov/22981419/)
+
+## Lab Websites
+
+- Neuroscience Statistics Research Laboratory: [neurostat.mit.edu](https://www.neurostat.mit.edu)
+- RESToRe Lab: [cajigaslab](https://www.med.upenn.edu/cajigaslab/)