cajigaslab · iahncajigas · Feb 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,6 @@
+.DS_Store
 __pycache__/
 *.pyc
 .pytest_cache/
-.ipynb_checkpoints/
-
 docs/_build/
 plots/
-
-reports/pytest.log
-reports/pytest.xml
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Python nSTAT
 
-This repository contains the standalone Python implementation of nSTAT.
+Standalone Python port of the nSTAT toolbox, organized around core MATLAB-mirroring classes with a Pythonic API.
 
-## Canonical API modules
+## Core API
 
 - `nstat.signal`: `Signal`, `Covariate`
 - `nstat.spikes`: `SpikeTrain`, `SpikeTrainCollection`
@@ -13,135 +13,26 @@ This repository contains the standalone Python implementation of nSTAT.
 - `nstat.analysis`: `Analysis`
 - `nstat.fit`: `FitResult`, `FitSummary`
 - `nstat.decoding`: `DecoderSuite`
-- `nstat.datasets`: dataset registry and checksum verification
+- `nstat.datasets`: `list_datasets`, `get_dataset_path`, `verify_checksums`
 
-MATLAB-style entry points remain importable as compatibility adapters with `DeprecationWarning` messages.
+MATLAB-style module names remain importable as compatibility adapters and emit `DeprecationWarning`.
 
 ## Install
 
 ```bash
 python3 -m pip install -e .
 ```
 
-## Run paper examples equivalent
+## Run basic examples
 
 ```bash
-python3 examples/nstat_paper_examples.py --repo-root .
+python3 examples/basic_data_workflow.py
+python3 examples/fit_poisson_glm.py
+python3 examples/simulate_population_psth.py
 ```
 
-## Generate docs and notebooks
+## Run tests
 
 ```bash
-python3 tools/generate_help_topic_docs.py
-python3 tools/generate_example_notebooks.py
-```
-
-## Validation
-
-```bash
-python3 tools/freeze_port_baseline.py
-python3 tools/generate_method_parity_matrix.py
-python3 tools/generate_implemented_method_coverage.py
-python3 tools/verify_examples_notebooks.py
-NSTAT_MATLAB_EXTRA_ARGS='-maca64 -nodisplay -noFigureWindows -softwareopengl' \
-  python3 tools/verify_python_vs_matlab_similarity.py --enforce-gate
-python3 tools/freeze_similarity_baseline.py
-python3 tools/verify_offline_standalone.py
 python3 -m pytest
 ```
-
-If Git LFS assets are unavailable (for example, CI quota exhaustion), set
-`NSTAT_ALLOW_SYNTHETIC_DATA=1` to use deterministic synthetic fallbacks for
-data-heavy paper example loaders.
-
-### Local parity block debugging
-
-```bash
-python3 tools/debug_parity_blocks.py \
-  --set-actions-runner-svc \
-  --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-```
-
-Single wrapper command (fail-fast ladder):
-
-```bash
-tools/run_parity_ladder.sh
-```
-
-Single preflight command (Stage A ladder + selected Stage B topics):
-
-```bash
-tools/run_parity_preflight.sh
-```
-
-Notes:
-
-- Runs blocks in order: `core_smoke -> timeout_front -> graphics_mid -> heavy_tail -> full_suite`.
-- Exits immediately if a block regresses (`python_ok`, `matlab_ok`, scalar overlap, parity contract, or regression gate).
-- Includes runtime regression guard using machine baseline block times with multiplier `NSTAT_PARITY_RUNTIME_MULTIPLIER` (default `2.5`).
-- Set `NSTAT_PARITY_RUNTIME_MULTIPLIER=0` to disable runtime regression checks.
-- Pass specific block names as args to run subset ladders, e.g.:
-  `tools/run_parity_ladder.sh core_smoke timeout_front`.
-- Ladder writes retry telemetry to `reports/parity_retry_summary.json` (block, attempt count, retry reason, timeout-topic list).
-- Retry behavior is controlled by `NSTAT_PARITY_RETRY_TIMEOUT_BLOCKS` and `NSTAT_PARITY_TIMEOUT_RETRY_BLOCKS`.
-- Set `NSTAT_MATLAB_TOPIC_MAX_ATTEMPTS=2` to retry per-topic MATLAB timeouts/crashes once before failing.
-- Set `NSTAT_PARITY_RETRY_RECOVERABLE_BLOCKS=1` and `NSTAT_PARITY_RECOVERABLE_RETRY_BLOCKS` to retry block failures caused by recoverable MATLAB failures (timeouts/crash signatures).
-- Preflight topic selection can be overridden with `NSTAT_PARITY_PREFLIGHT_STAGEB_TOPICS`.
-
-See `docs/parity_runbook.rst` for the exact locally validated parity command set.
-
-Use targeted blocks to debug delays locally before running remote CI:
-
-```bash
-# 1) Fast API/parity smoke
-python3 tools/debug_parity_blocks.py --blocks core_smoke \
-  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-
-# 2) Former timeout-prone front topics
-python3 tools/debug_parity_blocks.py --blocks timeout_front \
-  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-
-# 3) Graphics-sensitive middle topics
-python3 tools/debug_parity_blocks.py --blocks graphics_mid \
-  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-
-# 4) Heavy tail topics
-python3 tools/debug_parity_blocks.py --blocks heavy_tail \
-  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-
-# 5) Full gate-equivalent suite
-python3 tools/debug_parity_blocks.py --blocks full_suite \
-  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows -softwareopengl"
-```
-
-Summarize a parity report quickly:
-
-```bash
-python3 tools/summarize_parity_report.py reports/parity_block_full_suite.json
-```
-
-Recent local baseline on this machine (MATLAB R2025b, no figure windows, software OpenGL):
-
-- `core_smoke`: ~47s
-- `timeout_front`: ~122s
-- `graphics_mid`: ~291s
-- `heavy_tail`: ~385s
-- `full_suite` (25 topics): ~826s
-
-## CI
-
-- `.github/workflows/python-ci.yml` runs docs, notebook verification, offline standalone checks, and `pytest`.
-- `.github/workflows/matlab-parity-gate.yml` runs MATLAB/Python parity gate on self-hosted macOS runners with MATLAB installed.
-
-## Repo split inventory
-
-Snapshot MATLAB/Python help and example coverage before splitting `nSTAT` and `nSTAT-python`:
-
-```bash
-python3 tools/generate_repo_split_inventory.py
-```
-
-Outputs:
-- `reports/repo_split_inventory/summary.json`
-- `reports/repo_split_inventory/topic_coverage_matrix.json`
-- `reports/repo_split_inventory/split_readiness_gates.json`
diff --git a/RELEASE_CHECKLIST.md b/RELEASE_CHECKLIST.md
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,18 +1,25 @@
 API Reference
 =============
 
-.. code-block:: python
-
-   import nstat
-   print(nstat.__all__)
-
-Canonical modules include:
+Core modules:
 
 - ``nstat.signal``
 - ``nstat.spikes``
+- ``nstat.events``
+- ``nstat.history``
 - ``nstat.trial``
+- ``nstat.cif``
 - ``nstat.analysis``
 - ``nstat.fit``
-- ``nstat.cif``
 - ``nstat.decoding``
 - ``nstat.datasets``
+
+Compatibility adapters:
+
+- ``nstat.SignalObj``
+- ``nstat.nspikeTrain``
+- ``nstat.FitResult``
+- ``nstat.FitResSummary``
+- ``nstat.ConfigColl``
+- ``nstat.CovColl``
+- ``nstat.TrialConfig``
diff --git a/docs/help_topics.rst b/docs/help_topics.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,12 +1,9 @@
 nSTAT Python Documentation
 ==========================
 
-Standalone Python port of nSTAT with MATLAB-help topic coverage and executable notebooks.
+Minimal documentation for the standalone Python nSTAT core package.
 
 .. toctree::
    :maxdepth: 2
 
    api
-   help_topics
-   parity_runbook
-   repo_split_status