nltools 0.6.0.dev2__tar.gz → 0.6.0.dev4__tar.gz

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/.gitignore

@@ -96,3 +96,6 @@ docs/tutorials/workflows/[0-9]*_*.md
 # page outputs docs_show replays (pages/). Deliberately not under .cache/, which
 # is zensical's and which `zensical build -c` wipes whole.
 /.tutorial-cache/
+
+# Local planning artifacts (specs, plans, SDD workspaces)
+.superpowers/

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nltools
-Version: 0.6.0.dev2
+Version: 0.6.0.dev4
 Summary: A Python package to analyze neuroimaging data
 Project-URL: Homepage, https://nltools.org
 Author-email: "Luke J. Chang" <luke.j.chang@dartmouth.edu>, Eshin Jolly <eshin.jolly@gmail.com>

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/nltools/algorithms/alignment/procrustes.py

@@ -151,8 +151,10 @@ def align(
         method (str): One of `'probabilistic_srm'`, `'deterministic_srm'`, or
             `'procrustes'`. Defaults to `'deterministic_srm'`.
         n_features (int | None): Number of features in the common space (SRM only).
-            None uses the number of voxels, and may not exceed any subject's
-            voxel count. Must be None for `'procrustes'`.
+            None uses the smallest subject's size along the aligned axis (voxels
+            for `axis=0`), the largest value every subject can support; an
+            explicit value may not exceed that size for any subject. Must be None
+            for `'procrustes'`.
         axis (int): Axis to align on: 0 aligns timepoints (ISC computed per voxel),
             1 aligns voxels (ISC computed per timepoint). Defaults to 0.
         n_iter (int): Number of `_SRM`/`_DetSRM` iterations; ignored by
@@ -235,7 +237,7 @@ def align(
     out = {}
     if method in ["deterministic_srm", "probabilistic_srm"]:
         if n_features is None:
-            n_features = int(data[0].shape[0])
+            n_features = int(min(x.shape[0] for x in data))
         if method == "deterministic_srm":
             srm = _DetSRM(
                 n_features=n_features, n_iter=n_iter, random_state=random_state

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/nltools/algorithms/signal.py

@@ -214,7 +214,9 @@ def upsample(
     return upsampled_df
 
 
-def make_cosine_basis(nsamples, sampling_freq, filter_length, unit_scale=True, drop=0):
+def make_cosine_basis(
+    nsamples, sampling_interval, filter_length, unit_scale=True, drop=0
+):
     """Create basis functions for a discrete cosine transform.
 
     Based on the implementation in ``spm_filter`` and ``spm_dctmtx`` because
@@ -224,11 +226,12 @@ def make_cosine_basis(nsamples, sampling_freq, filter_length, unit_scale=True, d
 
     Args:
         nsamples (int): Number of observations (e.g. TRs).
-        sampling_freq (float): Sampling *interval* in seconds (the TR), matching
-            SPM's `RT` — not a frequency, despite the name. The number of bases
-            is `trunc(2 * nsamples * sampling_freq / filter_length + 1)`, minus
-            the constant. `DesignMatrix.add_dct_basis` passes
-            `1 / DesignMatrix.sampling_freq` for this reason.
+        sampling_interval (float): Seconds between observations (the TR), SPM's
+            `RT`. The number of bases is
+            `trunc(2 * nsamples * sampling_interval / filter_length + 1)`, minus
+            the constant. `DesignMatrix` stores a sampling frequency, so
+            `DesignMatrix.add_dct_basis` inverts it and passes
+            `1 / DesignMatrix.sampling_freq`.
         filter_length (int): Filter length in seconds.
         unit_scale (bool): Scale the basis functions to the range [-1, 1]. Defaults to True.
         drop (int): Number of leading (slowest) bases to drop after the constant is
@@ -239,12 +242,13 @@ def make_cosine_basis(nsamples, sampling_freq, filter_length, unit_scale=True, d
         np.ndarray: Basis matrix of shape (nsamples, n_bases).
 
     Note:
-        The basis count follows `spm_dctmtx`'s `k = fix(2*(n*RT)/HParam + 1)`, so
-        100 TRs of 2 s with a 128 s filter give the same four bases SPM gives.
+        The basis count follows `spm_dctmtx`'s `k = fix(2*(n*RT)/HParam + 1)` less
+        the constant that `spm_filter` drops, so 100 TRs of 2 s under a 128 s
+        filter give three bases, the same three SPM uses.
     """
 
     # Figure out number of basis functions to create
-    order = int(np.trunc(2 * (nsamples * sampling_freq) / filter_length + 1))
+    order = int(np.trunc(2 * (nsamples * sampling_interval) / filter_length + 1))
 
     n = np.arange(nsamples)
 

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/nltools/data/designmatrix/regressors.py

@@ -427,7 +427,10 @@ def _add_dct_basis(
 
     # Create DCT basis matrix using stats function
     basis_mat = make_cosine_basis(
-        dm.shape[0], 1.0 / dm.sampling_freq, duration, drop=drop
+        dm.shape[0],
+        sampling_interval=1.0 / dm.sampling_freq,
+        filter_length=duration,
+        drop=drop,
     )
 
     # Generate column names (.nl_cosine_1, .nl_cosine_2, ...)

{nltools-0.6.0.dev2 → nltools-0.6.0.dev4}/nltools/data/simulator/haxby.py

@@ -186,7 +186,9 @@ def _simulate_run(dm, rois, n_voxels, rng):
     return data
 
 
-def load_haxby_example(n_runs=1, *, space="mni", random_state=42):
+def load_haxby_example(
+    n_runs=1, *, space="mni", block_order="independent", random_state=42
+):
     """Load a synthetic Haxby-like dataset on the MNI grid, entirely in-memory.
 
     The quickest way to try nltools: nothing is downloaded beyond the MNI
@@ -204,7 +206,10 @@ def load_haxby_example(n_runs=1, *, space="mni", random_state=42):
     fusiform cortex, and scrambled pictures in early visual cortex — with a 3%
     peak response against 1% white noise. A condition also drives its
     category-mates' spheres at a third of that, so the eight response patterns
-    carry an animate / man-made / scene / control similarity structure.
+    carry an animate / man-made / scene / control similarity structure. Each run
+    draws its own block order by default; pass `block_order='shared'` when the
+    runs have to line up TR by TR, as they do for intersubject correlation,
+    alignment and anything else that compares runs timepoint against timepoint.
 
     Args:
         n_runs (int): Number of runs to generate. Default 1.
@@ -213,6 +218,10 @@ def load_haxby_example(n_runs=1, *, space="mni", random_state=42):
             `extract_roi` work on the result. `'grid'` is a 10 x 10 x 5
             synthetic volume with random condition clusters, for tests that need
             construction in milliseconds and never plot.
+        block_order (str): How the condition order varies across runs.
+            `'independent'` (default) draws a fresh order per run; `'shared'`
+            draws one order and gives it to every run, so the runs are
+            comparable TR by TR. Noise differs per run either way.
         random_state (int | None): Seed for reproducible output. Default 42.
 
     Returns:
@@ -223,7 +232,8 @@ def load_haxby_example(n_runs=1, *, space="mni", random_state=42):
             `_c0` (HRF-convolved boxcars).
 
     Raises:
-        ValueError: If `space` is not `'mni'` or `'grid'`.
+        ValueError: If `space` is not `'mni'` or `'grid'`, or `block_order` is not
+            `'independent'` or `'shared'`.
 
     Examples:
         ```python
@@ -258,16 +268,31 @@ def load_haxby_example(n_runs=1, *, space="mni", random_state=42):
 
     if space not in ("mni", "grid"):
         raise ValueError(f"space must be 'mni' or 'grid', got {space!r}")
+    if block_order not in ("independent", "shared"):
+        raise ValueError(
+            f"block_order must be 'independent' or 'shared', got {block_order!r}"
+        )
 
     rng = np.random.default_rng(random_state)
     mask_img = _mask_image(space)
     n_voxels = int((np.asarray(mask_img.dataobj) > 0).sum())
     rois = _condition_rois(space, mask_img, rng)
 
+    # Drawn once so every run gets the same sequence; 'independent' draws inside
+    # the loop instead, leaving the default run's RNG stream untouched.
+    shared_order = (
+        list(rng.permutation(_HAXBY_CONDITIONS)) if block_order == "shared" else None
+    )
+
     brain_data_list = []
     design_matrix_list = []
     for run in range(n_runs):
-        dm, labels = _run_design(list(rng.permutation(_HAXBY_CONDITIONS)))
+        order = (
+            shared_order
+            if shared_order is not None
+            else list(rng.permutation(_HAXBY_CONDITIONS))
+        )
+        dm, labels = _run_design(order)
         data = _simulate_run(dm, rois, n_voxels, rng)
         labels_and_run = pl.DataFrame(
             {