nxr-convert 0.2.0__tar.gz

nxr_convert-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diellor Basha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nxr_convert-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: nxr-convert
+Version: 0.2.0
+Summary: Convert Brainstorm MEG/EEG protocols into nxr datastores (SQLite rows + Zarr v3 arrays) for the Cortical Flow desktop app.
+Keywords: brainstorm,meg,eeg,neuroimaging,zarr,cortical-flow
+Author: Diellor Basha
+Author-email: Diellor Basha <diellorbasha@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Dist: h5py>=3.16.0
+Requires-Dist: numpy>=2.5.2
+Requires-Dist: pymatreader>=1.2.3
+Requires-Dist: scipy>=1.18.0
+Requires-Dist: zarr>=3
+Requires-Dist: nibabel>=5.4.2 ; extra == 'atlas'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://corticalflow.app
+Project-URL: Documentation, https://corticalflow.app/docs
+Project-URL: Source, https://github.com/neurodynamics-xr/nxr-convert
+Provides-Extra: atlas
+Description-Content-Type: text/markdown
+
+# nxr-convert
+
+Converts a [Brainstorm](https://neuroimage.usc.edu/brainstorm/) protocol (MEG/EEG recordings, cortical surfaces, MRI
+volumes, head models, inverse kernels, source maps, fibres and connectomes) into an **nxr datastore**: a folder that the
+[Cortical Flow](https://corticalflow.app) desktop app opens.
+
+Version **0.2.0**, which writes **database schema 49**. Each dataset's `dataset.sqlite` carries the schema number as
+`PRAGMA user_version`. The app opens only databases with the version it was built for, and the converter opens only its
+own version and refuses any other. Use a converter release that matches your desktop app (0.2.x for Cortical Flow 0.2).
+
+## What it writes
+
+```
+<datastore>/
+  <dataset>/
+    dataset.sqlite          the dataset's database: one row per subject, surface, recording, kernel, …
+    <subject>.nxr.zarr/     one Zarr v3 store per subject; the bytes (positions, faces, timeseries, kernels …)
+```
+
+The rows are written first, and every `zarr.json` is then rewritten from the rows, so the store describes itself. A
+Brainstorm **condition** becomes a *session* of the subject. The protocol's default anatomy (`@default_subject`) becomes
+the dataset's **template** subject, and `Group_analysis` becomes its **group** subject.
+
+## Install
+
+Python 3.12 or newer. With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install git+https://github.com/neurodynamics-xr/nxr-convert
+```
+
+or with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install git+https://github.com/neurodynamics-xr/nxr-convert
+```
+
+Check the install:
+
+```bash
+nxr-convert --version        # nxr-convert 0.2.0 (database schema 49)
+```
+
+The `atlas` commands also need the `atlas` extra (`nibabel`), plus Node.js and the nxr-compute Node binding
+(`NXR_COMPUTE`). Install the extra with `uv tool install "nxr-convert[atlas] @ git+https://github.com/neurodynamics-xr/nxr-convert"`.
+The conversion commands below need neither.
+
+## Use with the Cortical Flow desktop app
+
+The desktop app's **Import** runs this converter. It looks for one in this order:
+
+1. `NXR_CONVERT_CMD`, an explicit command (for example `uv run --project /path/to/nxr-convert nxr-convert`);
+2. a development checkout of the app's monorepo, run through `uv`;
+3. `nxr-convert` on `PATH`;
+4. `~/.local/bin/nxr-convert` (`nxr-convert.exe` on Windows), where `uv tool install` and `pipx install` put it — found
+   even when the app was started from the Dock or Finder and did not inherit your shell's `PATH`.
+
+If none is found, the Import page shows a setup card. For an install elsewhere, set `NXR_CONVERT_CMD` to its full path.
+
+## Commands
+
+Every command prints its progress as JSON lines on stdout, one object per event keyed by `stage`. The app parses this
+output. A failure ends with a `{"stage": "error", "message": …}` line and exit status 1.
+
+### Datasets
+
+```bash
+nxr-convert dataset create <datastore> <name> [--source-tool brainstorm] [--source-protocol P] [--source-path S]
+nxr-convert dataset delete <datastore> <name>
+nxr-convert dataset recover <datastore>/<name>    # roll back unfinished writes, finish deletions, rewrite the store
+```
+
+`dataset create` makes `<datastore>/<name>/dataset.sqlite` from the schema. It also creates the datastore folder if
+it does not exist yet.
+
+### Reading a protocol
+
+```bash
+nxr-convert list <protocol>                       # its subjects and conditions, as JSON
+nxr-convert scan <protocol> [--prefer protocol.mat|sqlite|walk] [--out view.json] [--summary]
+```
+
+### Converting
+
+```bash
+# one whole subject as one composition: every session, MRI volumes, source maps, fibres, connectomes
+nxr-convert subject <protocol> --subject <name> --dataset <datastore>/<dataset>
+
+# one condition as a session of a subject (the subject is created if it is absent)
+nxr-convert convert <protocol> --subject <name> --condition <condition> --dataset <datastore>/<dataset> \
+    [--surface tess_*.mat] [--extra-surface tess_*.mat …] [--recording data_*.mat] [--channel-file F] \
+    [--no-gain] [--all-surfaces] [--include-imported] [--no-raw]
+
+# the protocol's default anatomy as the TEMPLATE subject, and its group results as the GROUP subject
+nxr-convert template <protocol> --dataset <datastore>/<dataset> [--surface tess_*.mat …]
+nxr-convert group    <protocol> --dataset <datastore>/<dataset>
+```
+
+`<protocol>` is the Brainstorm protocol folder, the one that holds `anat/` and `data/`.
+
+### Adding to or removing from a subject
+
+```bash
+nxr-convert surface --dataset D --subject S --file tess_*.mat [tess_*.mat …] [--bst-root <protocol>]
+nxr-convert mri     --dataset D --subject S --anat <protocol>/anat/<subject> [--only NAME …]
+nxr-convert inverse --dataset D --subject S --file results_*KERNEL*.mat --session C --bst-root <protocol> \
+    [--channels-id ID] [--surface-id ID] [--forward-id ID] [--name N] [--channel-file F]
+nxr-convert remove  --dataset D --subject S [--node <store path>]   # the subject, or one node of it
+```
+
+### The atlas (optional)
+
+```bash
+nxr-convert atlas default-subject <datastore>/<dataset> --templates <FreeSurfer subjects dir> […]
+nxr-convert atlas build  <datastore>/<dataset> --subject S [--replace] […]
+nxr-convert atlas reduce <datastore>/<dataset>
+nxr-convert atlas info   <datastore>/<dataset>
+```
+
+Run `nxr-convert <command> --help` for every flag.
+
+## One writer per dataset
+
+Each command that writes a dataset first takes its **writer lock**, `<datastore>/<dataset>/.writer.lock`. The lock is a
+small JSON file (`pid`, `host`, `program`, `started_utc`) created atomically. If another live process holds the lock
+(the desktop app, or a second conversion), the command is refused, and the error names the holder. A lock left by a
+process that has died on the same machine is taken over. A lock held by another host is never broken; remove it by hand
+if that host is gone. When the desktop app runs the converter during its own import, it already holds the lock and
+passes it on through `NXR_WRITER_LOCK_HELD`. The lock is advisory, so do not edit a dataset by other means while a
+conversion runs.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+```
+
+Tests that need a real Brainstorm protocol skip unless `NXR_TEST_PROTOCOL` points at one (Brainstorm's
+`TutorialAuditory`).
+
+This repository is a published snapshot. The converter is developed inside the Cortical Flow monorepo, and its
+database schema (`src/nxr_convert/model.sql`) is a copy of the app's schema.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nxr_convert-0.2.0/README.md

@@ -0,0 +1,147 @@
+# nxr-convert
+
+Converts a [Brainstorm](https://neuroimage.usc.edu/brainstorm/) protocol (MEG/EEG recordings, cortical surfaces, MRI
+volumes, head models, inverse kernels, source maps, fibres and connectomes) into an **nxr datastore**: a folder that the
+[Cortical Flow](https://corticalflow.app) desktop app opens.
+
+Version **0.2.0**, which writes **database schema 49**. Each dataset's `dataset.sqlite` carries the schema number as
+`PRAGMA user_version`. The app opens only databases with the version it was built for, and the converter opens only its
+own version and refuses any other. Use a converter release that matches your desktop app (0.2.x for Cortical Flow 0.2).
+
+## What it writes
+
+```
+<datastore>/
+  <dataset>/
+    dataset.sqlite          the dataset's database: one row per subject, surface, recording, kernel, …
+    <subject>.nxr.zarr/     one Zarr v3 store per subject; the bytes (positions, faces, timeseries, kernels …)
+```
+
+The rows are written first, and every `zarr.json` is then rewritten from the rows, so the store describes itself. A
+Brainstorm **condition** becomes a *session* of the subject. The protocol's default anatomy (`@default_subject`) becomes
+the dataset's **template** subject, and `Group_analysis` becomes its **group** subject.
+
+## Install
+
+Python 3.12 or newer. With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install git+https://github.com/neurodynamics-xr/nxr-convert
+```
+
+or with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install git+https://github.com/neurodynamics-xr/nxr-convert
+```
+
+Check the install:
+
+```bash
+nxr-convert --version        # nxr-convert 0.2.0 (database schema 49)
+```
+
+The `atlas` commands also need the `atlas` extra (`nibabel`), plus Node.js and the nxr-compute Node binding
+(`NXR_COMPUTE`). Install the extra with `uv tool install "nxr-convert[atlas] @ git+https://github.com/neurodynamics-xr/nxr-convert"`.
+The conversion commands below need neither.
+
+## Use with the Cortical Flow desktop app
+
+The desktop app's **Import** runs this converter. It looks for one in this order:
+
+1. `NXR_CONVERT_CMD`, an explicit command (for example `uv run --project /path/to/nxr-convert nxr-convert`);
+2. a development checkout of the app's monorepo, run through `uv`;
+3. `nxr-convert` on `PATH`;
+4. `~/.local/bin/nxr-convert` (`nxr-convert.exe` on Windows), where `uv tool install` and `pipx install` put it — found
+   even when the app was started from the Dock or Finder and did not inherit your shell's `PATH`.
+
+If none is found, the Import page shows a setup card. For an install elsewhere, set `NXR_CONVERT_CMD` to its full path.
+
+## Commands
+
+Every command prints its progress as JSON lines on stdout, one object per event keyed by `stage`. The app parses this
+output. A failure ends with a `{"stage": "error", "message": …}` line and exit status 1.
+
+### Datasets
+
+```bash
+nxr-convert dataset create <datastore> <name> [--source-tool brainstorm] [--source-protocol P] [--source-path S]
+nxr-convert dataset delete <datastore> <name>
+nxr-convert dataset recover <datastore>/<name>    # roll back unfinished writes, finish deletions, rewrite the store
+```
+
+`dataset create` makes `<datastore>/<name>/dataset.sqlite` from the schema. It also creates the datastore folder if
+it does not exist yet.
+
+### Reading a protocol
+
+```bash
+nxr-convert list <protocol>                       # its subjects and conditions, as JSON
+nxr-convert scan <protocol> [--prefer protocol.mat|sqlite|walk] [--out view.json] [--summary]
+```
+
+### Converting
+
+```bash
+# one whole subject as one composition: every session, MRI volumes, source maps, fibres, connectomes
+nxr-convert subject <protocol> --subject <name> --dataset <datastore>/<dataset>
+
+# one condition as a session of a subject (the subject is created if it is absent)
+nxr-convert convert <protocol> --subject <name> --condition <condition> --dataset <datastore>/<dataset> \
+    [--surface tess_*.mat] [--extra-surface tess_*.mat …] [--recording data_*.mat] [--channel-file F] \
+    [--no-gain] [--all-surfaces] [--include-imported] [--no-raw]
+
+# the protocol's default anatomy as the TEMPLATE subject, and its group results as the GROUP subject
+nxr-convert template <protocol> --dataset <datastore>/<dataset> [--surface tess_*.mat …]
+nxr-convert group    <protocol> --dataset <datastore>/<dataset>
+```
+
+`<protocol>` is the Brainstorm protocol folder, the one that holds `anat/` and `data/`.
+
+### Adding to or removing from a subject
+
+```bash
+nxr-convert surface --dataset D --subject S --file tess_*.mat [tess_*.mat …] [--bst-root <protocol>]
+nxr-convert mri     --dataset D --subject S --anat <protocol>/anat/<subject> [--only NAME …]
+nxr-convert inverse --dataset D --subject S --file results_*KERNEL*.mat --session C --bst-root <protocol> \
+    [--channels-id ID] [--surface-id ID] [--forward-id ID] [--name N] [--channel-file F]
+nxr-convert remove  --dataset D --subject S [--node <store path>]   # the subject, or one node of it
+```
+
+### The atlas (optional)
+
+```bash
+nxr-convert atlas default-subject <datastore>/<dataset> --templates <FreeSurfer subjects dir> […]
+nxr-convert atlas build  <datastore>/<dataset> --subject S [--replace] […]
+nxr-convert atlas reduce <datastore>/<dataset>
+nxr-convert atlas info   <datastore>/<dataset>
+```
+
+Run `nxr-convert <command> --help` for every flag.
+
+## One writer per dataset
+
+Each command that writes a dataset first takes its **writer lock**, `<datastore>/<dataset>/.writer.lock`. The lock is a
+small JSON file (`pid`, `host`, `program`, `started_utc`) created atomically. If another live process holds the lock
+(the desktop app, or a second conversion), the command is refused, and the error names the holder. A lock left by a
+process that has died on the same machine is taken over. A lock held by another host is never broken; remove it by hand
+if that host is gone. When the desktop app runs the converter during its own import, it already holds the lock and
+passes it on through `NXR_WRITER_LOCK_HELD`. The lock is advisory, so do not edit a dataset by other means while a
+conversion runs.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+```
+
+Tests that need a real Brainstorm protocol skip unless `NXR_TEST_PROTOCOL` points at one (Brainstorm's
+`TutorialAuditory`).
+
+This repository is a published snapshot. The converter is developed inside the Cortical Flow monorepo, and its
+database schema (`src/nxr_convert/model.sql`) is a copy of the app's schema.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

nxr_convert-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "nxr-convert"
+version = "0.2.0"
+description = "Convert Brainstorm MEG/EEG protocols into nxr datastores (SQLite rows + Zarr v3 arrays) for the Cortical Flow desktop app."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["brainstorm", "meg", "eeg", "neuroimaging", "zarr", "cortical-flow"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+authors = [
+    { name = "Diellor Basha", email = "diellorbasha@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "h5py>=3.16.0",
+    "numpy>=2.5.2",
+    "pymatreader>=1.2.3",
+    "scipy>=1.18.0",
+    "zarr>=3",
+]
+
+[project.urls]
+Homepage = "https://corticalflow.app"
+Documentation = "https://corticalflow.app/docs"
+Source = "https://github.com/neurodynamics-xr/nxr-convert"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[project.scripts]
+nxr-convert = "nxr_convert.cli:main"
+
+[project.optional-dependencies]
+atlas = [
+    "nibabel>=5.4.2",
+]

nxr_convert-0.2.0/src/nxr_convert/__init__.py

@@ -0,0 +1,7 @@
+"""nxr-convert — Brainstorm protocols into nxr datastores (the Cortical Flow desktop app's importer)."""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("nxr-convert")
+except PackageNotFoundError:  # run from a source tree that was never installed
+    __version__ = "0+unknown"

nxr_convert-0.2.0/src/nxr_convert/_zarr_compat.py

@@ -0,0 +1,44 @@
+"""Filesystem-compatibility shim for zarr-python's LocalStore.
+
+zarr >= 3.3 makes exclusive node creation atomic via a HARDLINK
+(``_safe_move``: ``os.link`` then ``unlink``) — which raises
+``OSError(EOPNOTSUPP/EPERM)`` on filesystems without hardlinks (exFAT is the
+live case: an external drive chosen as the datastore, 2026-08-13). Upstream
+has no fallback as of 3.3.0 (nor on main), so every write into such a
+datastore crashes on the FIRST node.
+
+The fallback below keeps the semantics that matter here: ``FileExistsError``
+when the destination exists (what ``os.link`` guaranteed), then a plain
+``os.replace``. The existence check is not atomic against a concurrent
+creator — acceptable by construction: nxr-convert is the datastore's SINGLE
+writer (the app's convert service refuses two subprocesses, and the CLI is
+one process).
+
+Imported for its side effect by ``store`` — every writer passes through it.
+"""
+from __future__ import annotations
+
+import errno
+import os
+from pathlib import Path
+
+import zarr.storage._local as _local
+
+_HARDLINK_ERRNOS = {errno.EOPNOTSUPP, errno.ENOTSUP, errno.EPERM, errno.EXDEV, 45}
+
+_orig_safe_move = _local._safe_move
+
+
+def _safe_move_with_fallback(src: Path, dst: Path) -> None:
+    try:
+        _orig_safe_move(src, dst)
+    except OSError as e:
+        if e.errno not in _HARDLINK_ERRNOS:
+            raise
+        if os.path.exists(dst):
+            os.unlink(src)
+            raise FileExistsError(str(dst)) from e
+        os.replace(src, dst)
+
+
+_local._safe_move = _safe_move_with_fallback

nxr_convert-0.2.0/src/nxr_convert/atlas/__init__.py

@@ -0,0 +1,14 @@
+"""The DYADIC ATLAS producer (D127–D137; ported from nsp's ``nsp/atlas``, D135).
+
+Measurements on the cortex — static maps (PET SUVR), MEG source activity, fibres — reduced onto a bookkeeping
+tree of the cortex (the app's surface ladder, bit-exact) and of time (frames of ``frame_s``, doubling), stored
+as MERGEABLE sums at the leaves only and rolled up by arithmetic (``code >> k``, ``frame >> m``).
+
+    nxr-convert atlas default-subject <dataset> --templates <dir>    the dataset's @default_subject (D127), one composition
+    nxr-convert atlas build <dataset> --subject S                    the subject-side rows + its atlas (D128/D129)
+    nxr-convert atlas reduce <dataset>                               the group sums, on the default subject (D130/D131)
+
+There is no atlas format: an atlas is measurement rows on tile partitions over plain arrays (``atlas_store``). Frames and
+the vector heat method run on nxr-compute's Node binding (``compute.mjs``; the addon the app pins). The newer
+DYNAMICS atlas of nsp (grid · placement · engine · spectrum …) is not ported (schema 49 §5).
+"""

nxr_convert-0.2.0/src/nxr_convert/atlas/atlas_store.py

@@ -0,0 +1,64 @@
+"""THE ATLAS AS ROWS (D129–D134): there is no atlas format. An atlas is MEASUREMENTS ON TILE PARTITIONS (D68), array-backed
+(D96) on plain arrays under the subject's ``atlas/`` folder — the folder holds only arrays, and what they are is the
+measurement rows that name them (``array_path``). The default atlas's DEFINITIONS (depth, frame, bands, Levi-Civita
+levels, trajectory, the gauge) are the ``atlas`` block of the default subject's tile SET (``params_json``).
+
+    <subject>/atlas/trees/<tree>/{codes, w}                  a tree's leaf codes (the partition's array) and leaf areas
+    <subject>/atlas/trees/<tree>/lc/L<k>/{centre,omega,adjacency}   explicit per level (path-dependent: not rows)
+    <subject>/atlas/spatial/<tree>/maps/<field>/{w,s1,s2,n,min,max}, grad/{…}, grad_lc/L<k>/{re,im}
+    <subject>/atlas/time/<recording>__<kernel>/samples, <tree>/{power,env,envmax | tensor/…, tensor_lc/…, trajectory/…}
+    <default subject>/atlas/spatial/group/maps/<kind>/…, per_subject/mean       the group sums (``reduce``)
+    <default subject>/atlas/time/<task>__<method>__<orientation>/group/…, per_subject/density
+
+Each array name maps to a MEASURE (``ATLAS_MEASURES``, the app's ``measurements.ts``), whose reduction says how it merges
+across members, leaves and frames (``MERGE``).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import numpy as np
+
+DEFAULT_SUBJECT = "@default_subject"
+DEFAULT_BANDS = [(1.0 * 2 ** b, 2.0 * 2 ** b) for b in range(6)]
+
+#: an atlas array (relative to its statistics group) → the app's measure (``atlas.ts`` / ``measurements.ts``)
+ATLAS_MEASURES = {
+    "w": "weight", "s1": "sum", "s2": "sum_square", "n": "count", "min": "min", "max": "max",
+    "power": "power_sum", "env": "envelope_sum", "envmax": "envelope_max", "samples": "count",
+    "grad/w": "gradient_weight", "grad/c1": "gradient_1", "grad/c2": "gradient_2", "grad/cn": "gradient_n",
+    "grad/c11": "gradient_11", "grad/c22": "gradient_22", "grad/c12": "gradient_12", "grad/mag": "gradient_magnitude",
+    "tensor/t11": "tensor_11", "tensor/t22": "tensor_22", "tensor/tnn": "tensor_nn", "tensor/t12r": "tensor_12_re",
+    "tensor/t12i": "tensor_12_im", "tensor/t1nr": "tensor_1n_re", "tensor/t1ni": "tensor_1n_im", "tensor/t2nr": "tensor_2n_re",
+    "tensor/t2ni": "tensor_2n_im", "tensor/total": "tensor_total",
+}
+#: how a measure merges (its reduction in the app's ``measure`` dictionary): sums add, extremes take the extreme
+MERGE = {m: ("max" if m in ("max", "envelope_max") else "min" if m == "min" else "sum") for m in ATLAS_MEASURES.values()}
+
+
+def merge_of(rel: str) -> str | None:
+    """How the array at ``rel`` (relative to its statistics group) merges — None for an explicit array."""
+    m = ATLAS_MEASURES.get(rel)
+    return MERGE[m] if m else None
+
+
+def default_subject(ds) -> dict | None:
+    """The dataset's DEFAULT SUBJECT (D127): the template named ``@default_subject``, else its template."""
+    return (ds.db.one("SELECT * FROM subject WHERE dataset_id = ? AND name = ? AND status = 'complete'", ds.id, DEFAULT_SUBJECT)
+            or ds.template())
+
+
+def definition(ds) -> dict[str, Any]:
+    """The dataset's default atlas DEFINITIONS — the ``atlas`` block of the default subject's tile set (``{}`` when none)."""
+    d = default_subject(ds)
+    if d is None:
+        return {}
+    row = ds.db.one("SELECT params_json FROM selection WHERE subject_id = ? AND type = 'set' AND member_of_id IS NULL AND "
+                    "json_extract(params_json, '$.atlas.default') = 1", d["id"])
+    return (json.loads(row["params_json"]) or {}).get("atlas", {}) if row and row["params_json"] else {}
+
+
+def put(sub, path: str, data, **_ignored) -> None:
+    """A plain atlas array at the subject's store path (laid out canonically, no attributes: the rows say what it is)."""
+    sub.write_array(path, np.ascontiguousarray(np.asarray(data)))

nxr_convert-0.2.0/src/nxr_convert/atlas/bad_segments.py

@@ -0,0 +1,21 @@
+"""THE SAMPLE MASK the atlas excludes: a recording's BAD SEGMENTS are a Selection (D143) — ``<rec>_bad_segments``, spans on
+its time Line, written by the converter from Brainstorm's extended events labelled ``bad*`` (``events.export_events``).
+Every sample inside a span carries no weight, so the atlas's sums — and the ``samples`` count per frame — are over good
+samples only, and stay mergeable."""
+from __future__ import annotations
+
+import numpy as np
+
+from .nxr_store import Recording, SubjectStore
+
+
+def sample_mask(store: SubjectStore, rec: Recording) -> tuple[np.ndarray, dict]:
+    """[n] bool, True = a good sample: outside every span of the recording's bad segments."""
+    start, stop = store.bad_spans(rec)
+    good = np.ones(rec.n_samples, bool)
+    i0 = np.clip(np.floor((start - rec.origin) * rec.sfreq).astype(np.int64), 0, rec.n_samples)
+    i1 = np.clip(np.ceil((stop - rec.origin) * rec.sfreq).astype(np.int64), 0, rec.n_samples)
+    for a, b in zip(i0, i1):
+        good[a:b] = False
+    return good, {"source": "selection" if len(start) else "none", "segments": int(len(start)),
+                  "bad_fraction": float(1 - good.mean()) if rec.n_samples else 0.0}

nxr_convert-0.2.0/src/nxr_convert/atlas/bands.py

@@ -0,0 +1,110 @@
+"""
+The filter bank of the tower of cycles — one complex analytic FIR per level, so chunked filtering is EXACT.
+
+A level L of the tower holds the band [1/P(L), 2/P(L)) Hz, P(L) = 86 400·2^L s (``band_hz``; nsp's dynamics-atlas
+``grid`` names the levels, and only these two lines of it are needed here — the dynamics atlas is not ported, D135). Its filter is the band's
+gain of the octave power partition (``scalars.band_gains``: cos/sin crossovers half an octave wide,
+squared gains summing to one across the bank), realised as a finite impulse response:
+
+  h_L[k], k = −H … H     the analytic (positive-frequency) gain, inverse-transformed, cut to ±H samples
+                         and tapered by a Hann window. H = ``cycles`` periods of the band's lowest
+                         passed frequency (its lower edge less the crossover), so the response is local
+                         in time at that band's own scale.
+
+Because h_L is finite, filtering a block padded by H on each side gives exactly the samples a whole-record
+filter would (overlap-save): the chunked engine and a whole-record pass agree to float rounding. The cut
+and the taper make the partition approximate (``partition_error`` measures it); the exactness is not.
+
+A sample within H of a record edge or of a bad sample is not clean for that band (``clean``).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import fft as sfft
+from scipy.signal import fftconvolve
+
+from .scalars import band_gains
+
+DAY_S = 86400.0                             # time level 0: one day (nsp's tower of cycles)
+
+
+def period_s(level: int) -> float:
+    """The period of a level-L cycle (s): 86 400·2^L."""
+    return DAY_S * 2.0 ** level
+
+
+def band_hz(level: int) -> tuple[float, float]:
+    """The octave band of level L: [1/P(L), 2/P(L)) Hz."""
+    lo = 1.0 / period_s(level)
+    return lo, 2.0 * lo
+
+
+CYCLES = 4.0
+CROSSOVER_OCT = 0.25                        # scalars.band_gains: half the crossover width, in octaves
+DEFAULT_LEVELS = tuple(range(-22, -15))     # −22 … −16: 0.76 – 97 Hz
+
+
+def levels_for(sfreq: float, f_min: float = 0.5, f_max: float | None = None) -> list[int]:
+    """The tower levels whose whole band (crossover included) lies in [f_min, min(f_max, Nyquist)]."""
+    top = min(f_max or math.inf, sfreq / 2.0)
+    out = []
+    for L in range(-40, 20):
+        lo, hi = band_hz(L)
+        if lo * 2 ** -CROSSOVER_OCT >= f_min and hi * 2 ** CROSSOVER_OCT <= top:
+            out.append(L)
+    return out
+
+
+@dataclass(frozen=True)
+class Filter:
+    level: int
+    band_hz: tuple[float, float]
+    half: int                     # H: the filter spans samples −H … H
+    h: np.ndarray                 # complex128 [2H + 1]
+
+
+def analytic_fir(level: int, sfreq: float, levels=DEFAULT_LEVELS, cycles: float = CYCLES) -> Filter:
+    """The complex analytic FIR of ``level`` in the power partition over ``levels``."""
+    levels = sorted(levels, reverse=True)            # ascending frequency (band_gains' order)
+    bands = [band_hz(L) for L in levels]
+    lo = band_hz(level)[0] * 2 ** -CROSSOVER_OCT
+    H = int(math.ceil(cycles / lo * sfreq))
+    n = 1 << int(math.ceil(math.log2(8 * (2 * H + 1))))
+    f = sfft.fftfreq(n, 1.0 / sfreq)
+    g = band_gains(np.abs(f), bands)[levels.index(level)] * 2.0 * (f > 0)
+    full = sfft.ifft(g)
+    k = np.arange(-H, H + 1)
+    h = full[k % n] * np.hanning(2 * H + 3)[1:-1]
+    return Filter(level, band_hz(level), H, h)
+
+
+def response(filt: Filter, freqs: np.ndarray, sfreq: float) -> np.ndarray:
+    """The realised complex gain of the FIR at ``freqs`` (Hz)."""
+    k = np.arange(-filt.half, filt.half + 1)
+    return np.exp(-2j * np.pi * np.outer(np.asarray(freqs) / sfreq, k)) @ filt.h
+
+
+def partition_error(filters: list[Filter], sfreq: float, n: int = 512) -> float:
+    """max |Σ |H_L(f)|²/4 − 1| over the bank's inner range (the analytic gain is 2 on positive frequencies)."""
+    lo = min(F.band_hz[0] for F in filters) * 2 ** CROSSOVER_OCT
+    hi = max(F.band_hz[1] for F in filters) * 2 ** -CROSSOVER_OCT
+    f = np.geomspace(lo, hi, n)
+    tot = sum(np.abs(response(F, f, sfreq)) ** 2 for F in filters) / 4.0
+    return float(np.max(np.abs(tot - 1.0)))
+
+
+def filter_block(x: np.ndarray, filt: Filter) -> np.ndarray:
+    """Filter a block padded by H samples on each side ([channels, T + 2H], zeros outside the record):
+    returns the T analytic samples of its interior (exact overlap-save)."""
+    return fftconvolve(np.asarray(x), filt.h[None, :], mode="valid", axes=-1)
+
+
+def clean(good: np.ndarray, half: int) -> np.ndarray:
+    """Samples whose ±H neighbourhood lies inside the record and holds no bad sample."""
+    bad = np.r_[np.ones(half, bool), ~np.asarray(good, bool), np.ones(half, bool)].astype(np.int64)
+    c = np.r_[0, np.cumsum(bad)]
+    w = 2 * half + 1
+    return (c[w:] - c[:-w]) == 0