nltools 0.6.0.dev2__tar.gz → 0.6.0.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nltools
-Version: 0.6.0.dev2
+Version: 0.6.0.dev3
 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.dev3}/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.dev3}/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.dev3}/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.dev3}/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(
             {

{nltools-0.6.0.dev2 → nltools-0.6.0.dev3}/nltools/tests/core/test_algorithms/test_procrustes.py

@@ -64,6 +64,19 @@ class TestAlign:
         with pytest.raises(TypeError):
             align(data, method="deterministic_srm", bogus_kwarg=1)
 
+    def test_default_n_features_is_the_smallest_subjects_voxel_count(self):
+        """Ragged subjects resolve `n_features=None` to the smallest voxel count.
+
+        The default read subject 0's voxel count, so a group whose first subject
+        was not the narrowest asked for more features than another subject had.
+        """
+        rng = np.random.default_rng(0)
+        data = [rng.standard_normal((20, n_voxels)) for n_voxels in (6, 4, 5)]
+
+        out = align(data, method="deterministic_srm", n_features=None)
+
+        assert out["common_model"].shape[1] == 4
+
     def test_isc_is_reported_for_a_single_aligned_unit(self):
         """One aligned unit is still a unit, not a scalar.
 

{nltools-0.6.0.dev2 → nltools-0.6.0.dev3}/nltools/tests/core/test_algorithms/test_signal.py

@@ -92,11 +92,19 @@ class TestMakeCosineBasis:
         """Cosine basis should return correct shape."""
         n_timepoints = 100
         basis = make_cosine_basis(
-            n_timepoints, sampling_freq=1, filter_length=128, drop=0
+            n_timepoints, sampling_interval=1, filter_length=128, drop=0
         )
         assert basis.shape[0] == n_timepoints
         assert basis.shape[1] >= 1
 
+    def test_second_argument_is_the_sampling_interval(self):
+        """100 TRs of 2 s under a 128 s filter give SPM's four bases less the constant."""
+        basis = make_cosine_basis(100, sampling_interval=2, filter_length=128)
+        assert basis.shape == (100, 3)
+
+        with pytest.raises(TypeError, match="sampling_freq"):
+            make_cosine_basis(100, sampling_freq=2, filter_length=128)
+
     def test_drop_removes_leading_columns(self):
         """drop=k removes the k lowest-frequency bases, keeping the remainder."""
         full = make_cosine_basis(128, 1, 32, drop=0)

{nltools-0.6.0.dev2 → nltools-0.6.0.dev3}/nltools/tests/datasets/test_datasets.py

@@ -175,6 +175,19 @@ class TestLoadHaxbyExample:
             # `.convolve()` always suffixes `_c0`
             assert f"{cond}_c0" in cols, f"missing condition {cond}_c0"
 
+    def test_shared_block_order_repeats_one_order_across_runs(self):
+        """`block_order='shared'` gives every run the same condition sequence."""
+        from nltools.datasets import load_haxby_example
+
+        shared, _ = load_haxby_example(n_runs=2, space="grid", block_order="shared")
+        assert shared[0].Y["condition"].to_list() == shared[1].Y["condition"].to_list()
+
+        independent, _ = load_haxby_example(n_runs=2, space="grid")
+        assert (
+            independent[0].Y["condition"].to_list()
+            != independent[1].Y["condition"].to_list()
+        )
+
     def test_reproducible_with_seed(self):
         import numpy as np
         from nltools.datasets import load_haxby_example

{nltools-0.6.0.dev2 → nltools-0.6.0.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nltools"
-version = "0.6.0.dev2"
+version = "0.6.0.dev3"
 requires-python = ">=3.11"
 description = "A Python package to analyze neuroimaging data"
 readme = "README.md"