braincoder 0.7.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,186 @@
1
+ """Calibration metrics for grid posteriors (e.g. from ``get_stimulus_pdf``).
2
+
3
+ All functions take a posterior DataFrame — rows = trials, columns = grid
4
+ stimuli — and the true stimulus of every trial. Rows are renormalised to sum
5
+ to one (discrete masses over the grid), so both the trapezoid-normalised 1-D
6
+ densities and the max-normalised multi-dimensional output of
7
+ ``get_stimulus_pdf`` can be passed directly.
8
+
9
+ A calibrated posterior gives
10
+
11
+ * randomised PIT values ~ Uniform(0, 1) (1-D only; SD ≈ 0.289, slightly less
12
+ on a coarse discrete grid), U-shaped = overconfident, ∩-shaped =
13
+ underconfident;
14
+ * randomised HPD levels of the truth ~ Uniform(0, 1), i.e. the q-HDI
15
+ contains the truth on a fraction q of trials (any dimensionality);
16
+ * a log score that is not below that of a flat posterior.
17
+
18
+ Randomisation (a uniform draw within the probability mass of the true grid
19
+ cell) makes the statistics exactly uniform for a calibrated discrete
20
+ posterior instead of biased by ties and grid coarseness.
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import numpy as np
25
+ import pandas as pd
26
+
27
+ __all__ = ['posterior_grid', 'marginalize', 'true_stimulus_index', 'log_score',
28
+ 'pit', 'hpd_level', 'hdi_coverage', 'calibration_summary',
29
+ 'plot_calibration']
30
+
31
+
32
+ def _rng(rng):
33
+ if isinstance(rng, np.random.Generator):
34
+ return rng
35
+ return np.random.default_rng(rng)
36
+
37
+
38
+ def posterior_grid(pdf, grid=None):
39
+ """(P, grid): row-normalised masses (n_trials, n_stimuli) and the grid.
40
+
41
+ ``grid`` is taken from the columns (numeric Index or MultiIndex) unless
42
+ passed explicitly (needed when ``get_stimulus_pdf`` was called on a
43
+ multi-dimensional grid without ``include_multidimensional_stimulus_index``).
44
+ """
45
+ P = np.asarray(pdf, dtype=np.float64)
46
+ P = np.clip(np.nan_to_num(P), 0, None)
47
+ P = P / P.sum(1, keepdims=True)
48
+ if grid is None:
49
+ cols = pdf.columns
50
+ if isinstance(cols, pd.MultiIndex):
51
+ grid = np.array([np.asarray(c, dtype=float) for c in cols.to_flat_index()])
52
+ elif isinstance(cols, pd.RangeIndex) or cols.dtype == object:
53
+ raise ValueError('Cannot infer the stimulus grid from the columns; '
54
+ 'pass grid=')
55
+ else:
56
+ grid = np.asarray(cols, dtype=float)[:, None]
57
+ grid = np.asarray(grid, dtype=float)
58
+ if grid.ndim == 1:
59
+ grid = grid[:, None]
60
+ if len(grid) != P.shape[1]:
61
+ raise ValueError('grid length does not match the number of columns')
62
+ return P, grid
63
+
64
+
65
+ def marginalize(pdf, dimension, grid=None):
66
+ """Marginal posterior over one stimulus dimension (int or level name)."""
67
+ P, grid = posterior_grid(pdf, grid)
68
+ if not isinstance(dimension, (int, np.integer)):
69
+ dimension = list(pdf.columns.names).index(dimension)
70
+ vals, inv = np.unique(grid[:, dimension], return_inverse=True)
71
+ M = np.zeros((len(P), len(vals)))
72
+ np.add.at(M.T, inv, P.T)
73
+ name = None
74
+ if isinstance(pdf.columns, pd.MultiIndex):
75
+ name = pdf.columns.names[dimension]
76
+ return pd.DataFrame(M, index=pdf.index, columns=pd.Index(vals, name=name))
77
+
78
+
79
+ def true_stimulus_index(true_stimulus, grid):
80
+ """Index of the nearest grid point for every true stimulus."""
81
+ t = np.asarray(true_stimulus, dtype=float)
82
+ if t.ndim == 1:
83
+ if grid.shape[1] != 1:
84
+ raise ValueError('true_stimulus must be (n_trials, n_dims) for a '
85
+ 'multi-dimensional grid')
86
+ t = t[:, None]
87
+ d2 = ((t[:, None, :] - grid[None, :, :]) ** 2).sum(-1)
88
+ return d2.argmin(1)
89
+
90
+
91
+ def log_score(pdf, true_stimulus, grid=None, relative_to_uniform=True):
92
+ """Per-trial log posterior mass of the true grid cell.
93
+
94
+ With ``relative_to_uniform`` (default) ``log(1/n_stimuli)`` is subtracted,
95
+ so 0 = as good as a flat posterior and > 0 = informative and calibrated
96
+ enough to beat it.
97
+ """
98
+ P, grid = posterior_grid(pdf, grid)
99
+ ti = true_stimulus_index(true_stimulus, grid)
100
+ ls = np.log(np.clip(P[np.arange(len(P)), ti], 1e-300, None))
101
+ if relative_to_uniform:
102
+ ls = ls + np.log(P.shape[1])
103
+ return ls
104
+
105
+
106
+ def pit(pdf, true_stimulus, grid=None, rng=0):
107
+ """Randomised probability integral transform (1-D posteriors).
108
+
109
+ F(s* − 1) + U · p(s*), U ~ U(0, 1). For a multi-dimensional posterior,
110
+ first :func:`marginalize` it.
111
+ """
112
+ P, grid = posterior_grid(pdf, grid)
113
+ if grid.shape[1] != 1:
114
+ raise ValueError('PIT needs a 1-D posterior; marginalize() first')
115
+ order = np.argsort(grid[:, 0])
116
+ P, grid = P[:, order], grid[order]
117
+ ti = true_stimulus_index(true_stimulus, grid)
118
+ cdf = np.cumsum(P, 1)
119
+ below = np.where(ti > 0, cdf[np.arange(len(P)), np.maximum(ti - 1, 0)], 0.)
120
+ u = _rng(rng).uniform(size=len(P))
121
+ return below + u * P[np.arange(len(P)), ti]
122
+
123
+
124
+ def hpd_level(pdf, true_stimulus, grid=None, rng=0):
125
+ """Randomised level of the smallest HDI that contains the truth.
126
+
127
+ h = P(p(s) > p(s*)) + U · P(p(s) = p(s*)). The q-HDI covers the truth
128
+ iff h < q. Works for any dimensionality.
129
+ """
130
+ P, grid = posterior_grid(pdf, grid)
131
+ ti = true_stimulus_index(true_stimulus, grid)
132
+ pt = P[np.arange(len(P)), ti][:, None]
133
+ above = (P * (P > pt)).sum(1)
134
+ tie = (P * (P == pt)).sum(1)
135
+ u = _rng(rng).uniform(size=len(P))
136
+ return above + u * tie
137
+
138
+
139
+ def hdi_coverage(pdf, true_stimulus, levels=(0.5, 0.95), grid=None, rng=0):
140
+ """Fraction of trials whose q-HDI contains the truth, for each q."""
141
+ h = hpd_level(pdf, true_stimulus, grid=grid, rng=rng)
142
+ return pd.Series({q: float(np.mean(h < q)) for q in levels}, name='coverage')
143
+
144
+
145
+ def calibration_summary(pdf, true_stimulus, grid=None, levels=(0.5, 0.95), rng=0):
146
+ """One-row summary: log score vs uniform, HDI coverage, PIT SD (1-D),
147
+ posterior mean r / MAE / posterior SD (1-D)."""
148
+ P, g = posterior_grid(pdf, grid)
149
+ out = {'n_trials': len(P),
150
+ 'log_score': float(np.mean(log_score(pdf, true_stimulus, grid=grid)))}
151
+ for q, c in hdi_coverage(pdf, true_stimulus, levels=levels, grid=grid, rng=rng).items():
152
+ out[f'coverage_{q:g}'] = c
153
+ if g.shape[1] == 1:
154
+ p = pit(pdf, true_stimulus, grid=grid, rng=rng)
155
+ out['pit_sd'] = float(np.std(p))
156
+ out['pit_tails_5pct'] = float(np.mean((p < .025) | (p > .975)))
157
+ t = np.asarray(true_stimulus, dtype=float).ravel()
158
+ mean = P @ g[:, 0]
159
+ out['posterior_sd'] = float(np.mean(np.sqrt(np.clip(P @ g[:, 0] ** 2 - mean ** 2, 0, None))))
160
+ out['r_posterior_mean'] = float(np.corrcoef(mean, t)[0, 1]) if np.std(mean) > 0 else np.nan
161
+ out['mae_posterior_mean'] = float(np.mean(np.abs(mean - t)))
162
+ return pd.Series(out)
163
+
164
+
165
+ def plot_calibration(pdf, true_stimulus, grid=None, rng=0, axes=None, label=None,
166
+ levels=np.linspace(0.05, 0.95, 19)):
167
+ """Two-panel diagnostic: coverage vs nominal HDI level, and PIT histogram
168
+ (1-D) or HPD-level histogram (multi-D). Returns the axes."""
169
+ import matplotlib.pyplot as plt
170
+ if axes is None:
171
+ _, axes = plt.subplots(1, 2, figsize=(7, 3))
172
+ P, g = posterior_grid(pdf, grid)
173
+ h = hpd_level(pdf, true_stimulus, grid=grid, rng=rng)
174
+ cov = [np.mean(h < q) for q in levels]
175
+ axes[0].plot([0, 1], [0, 1], color='0.6', lw=1, ls='--')
176
+ axes[0].plot(levels, cov, marker='o', ms=3, label=label)
177
+ axes[0].set(xlabel='Nominal HDI level', ylabel='Empirical coverage',
178
+ xlim=(0, 1), ylim=(0, 1))
179
+ if g.shape[1] == 1:
180
+ vals, xlabel = pit(pdf, true_stimulus, grid=grid, rng=rng), 'Randomised PIT'
181
+ else:
182
+ vals, xlabel = h, 'Randomised HPD level of truth'
183
+ axes[1].hist(vals, bins=np.linspace(0, 1, 11), density=True, alpha=.6, label=label)
184
+ axes[1].axhline(1, color='0.6', lw=1, ls='--')
185
+ axes[1].set(xlabel=xlabel, ylabel='Density', xlim=(0, 1))
186
+ return axes
@@ -0,0 +1,141 @@
1
+ """Cortical surface helpers for the GP-prior workflow.
2
+
3
+ Two thin wrappers:
4
+
5
+ * ``load_freesurfer_surface`` — read an ``lh.white``/``rh.white`` style
6
+ surface as ``(vertices, faces)`` numpy arrays via nibabel.
7
+ * ``geodesic_distance_matrix`` — compute a pairwise distance matrix
8
+ on a triangular mesh by running Dijkstra on the mesh graph with
9
+ edge weights set to Euclidean edge lengths.
10
+
11
+ Neither pycortex nor a full Laplace-Beltrami implementation is needed.
12
+ The mesh-edge Dijkstra approximation biases distances slightly high
13
+ (paths are constrained to follow edges instead of cutting across
14
+ triangles, typically a 10-20% overestimate). For our use — an RBF
15
+ kernel ``exp(-d^2 / 2l^2)`` whose lengthscale is fit empirically from
16
+ the data — this bias gets absorbed into the fitted lengthscale and is
17
+ invisible to the prior.
18
+ """
19
+
20
+ import os
21
+
22
+ import numpy as np
23
+
24
+
25
+ def load_freesurfer_surface(subject, hemi, surface='white', subjects_dir=None):
26
+ """Load a FreeSurfer surface as ``(vertices, faces)`` numpy arrays.
27
+
28
+ Parameters
29
+ ----------
30
+ subject : str
31
+ FreeSurfer subject ID (the directory name under ``$SUBJECTS_DIR``).
32
+ hemi : {'lh', 'rh'}
33
+ surface : str
34
+ Surface name. ``'white'``, ``'pial'``, ``'midgray'`` etc.
35
+ subjects_dir : str, optional
36
+ Defaults to ``$SUBJECTS_DIR``.
37
+ """
38
+ import nibabel as nib # optional dependency
39
+
40
+ if hemi not in ('lh', 'rh'):
41
+ raise ValueError(f"hemi must be 'lh' or 'rh', got {hemi!r}")
42
+ if subjects_dir is None:
43
+ subjects_dir = os.environ.get('SUBJECTS_DIR')
44
+ if subjects_dir is None:
45
+ raise ValueError(
46
+ "subjects_dir not given and SUBJECTS_DIR not set")
47
+
48
+ path = os.path.join(subjects_dir, subject, 'surf', f'{hemi}.{surface}')
49
+ vertices, faces = nib.freesurfer.read_geometry(path)
50
+ return (np.asarray(vertices, dtype=np.float32),
51
+ np.asarray(faces, dtype=np.int64))
52
+
53
+
54
+ def _build_edge_graph(vertices, faces):
55
+ """Build a sparse symmetric weighted-adjacency graph from a mesh.
56
+
57
+ Each undirected mesh edge becomes one entry per direction with
58
+ weight = Euclidean length. Interior edges are shared by two
59
+ triangles, so we deduplicate by sorted (i, j) before building the
60
+ sparse matrix — otherwise coo→csr would sum duplicate entries and
61
+ double the edge weights.
62
+ """
63
+ from scipy.sparse import csr_matrix
64
+
65
+ n_v = len(vertices)
66
+ e = np.concatenate([
67
+ faces[:, [0, 1]],
68
+ faces[:, [1, 2]],
69
+ faces[:, [0, 2]],
70
+ ], axis=0)
71
+ e = np.sort(e, axis=1)
72
+ e = np.unique(e, axis=0)
73
+ diff = vertices[e[:, 0]] - vertices[e[:, 1]]
74
+ w = np.sqrt((diff ** 2).sum(axis=1)).astype(np.float64)
75
+ rows = np.concatenate([e[:, 0], e[:, 1]])
76
+ cols = np.concatenate([e[:, 1], e[:, 0]])
77
+ data = np.concatenate([w, w])
78
+ return csr_matrix((data, (rows, cols)), shape=(n_v, n_v))
79
+
80
+
81
+ def geodesic_distance_matrix(vertices, faces, source_indices=None,
82
+ progressbar=True, dtype=np.float32):
83
+ """Pairwise mesh-graph (Dijkstra) distance matrix.
84
+
85
+ Approximates geodesic distance by the shortest path along mesh
86
+ edges. Lightweight (scipy only) and sufficient for an RBF-kernel
87
+ GP prior where the lengthscale is fit empirically.
88
+
89
+ Parameters
90
+ ----------
91
+ vertices : array (n_v, 3)
92
+ faces : int array (n_f, 3)
93
+ source_indices : array of int, optional
94
+ Indices into ``vertices`` defining the ROI. If given, returns
95
+ ``(k, k)`` pairwise distances among these vertices. If ``None``,
96
+ the full ``(n_v, n_v)`` matrix is returned (expensive).
97
+ progressbar : bool
98
+ Show a tqdm bar while iterating Dijkstra batches.
99
+ dtype : numpy dtype
100
+ Output dtype. ``float32`` saves half the memory and is plenty
101
+ accurate for distances in mm.
102
+
103
+ Returns
104
+ -------
105
+ D : array (k, k)
106
+ Symmetric pairwise distances in the same units as ``vertices``
107
+ (millimeters for FreeSurfer surfaces), with zero diagonal.
108
+ """
109
+ from scipy.sparse.csgraph import dijkstra
110
+
111
+ vertices = np.asarray(vertices, dtype=np.float64)
112
+ faces = np.asarray(faces, dtype=np.int64)
113
+
114
+ if source_indices is None:
115
+ source_indices = np.arange(len(vertices))
116
+ source_indices = np.asarray(source_indices, dtype=int).ravel()
117
+ n = len(source_indices)
118
+
119
+ graph = _build_edge_graph(vertices, faces)
120
+
121
+ # Multi-source Dijkstra is fast; chunk to keep peak memory bounded
122
+ # for big ROIs. ``indices`` returns one row of distances per source.
123
+ chunk_size = 64
124
+ chunks = range(0, n, chunk_size)
125
+ if progressbar:
126
+ from tqdm.auto import tqdm
127
+ chunks = tqdm(chunks, desc='Mesh Dijkstra')
128
+
129
+ D = np.zeros((n, n), dtype=dtype)
130
+ for start in chunks:
131
+ end = min(start + chunk_size, n)
132
+ srcs = source_indices[start:end]
133
+ # rows: (len(srcs), n_v) — distance from each src to every vertex
134
+ rows = dijkstra(graph, indices=srcs, directed=False)
135
+ D[start:end, :] = rows[:, source_indices].astype(dtype)
136
+
137
+ # Dijkstra on a symmetric graph is already symmetric, but float
138
+ # round-trip can leave tiny asymmetries. Symmetrize defensively.
139
+ D = 0.5 * (D + D.T)
140
+ np.fill_diagonal(D, 0.0)
141
+ return D
@@ -0,0 +1,252 @@
1
+ from importlib.resources import files
2
+ import numpy as np
3
+ import pandas as pd
4
+ from scipy import ndimage
5
+ from nilearn.surface import load_surf_data
6
+
7
+ def load_szinte2024(resize_factor=1., best_voxels=None):
8
+ data = {}
9
+
10
+ base = files(__package__) / '../data/szinte2024'
11
+
12
+ with (base / 'dm_gazecenter.npz').open('rb') as f:
13
+ data['stimulus'] = np.load(f)['arr_0'].astype(np.float32)
14
+
15
+ with (base / 'grid_coordinates.tsv').open('rb') as f:
16
+ data['grid_coordinates'] = pd.read_csv(f, sep='\t').astype(np.float32)
17
+
18
+ with (base / 'gauss_parameters.tsv').open('rb') as f:
19
+ prf_pars = pd.read_csv(f, index_col='source', sep='\t').astype(np.float32)
20
+
21
+ if resize_factor != 1.:
22
+ data['stimulus'] = np.array([ndimage.zoom(d, 1./resize_factor) for d in data['stimulus']]).astype(np.float32)
23
+
24
+ tmp_x = data['grid_coordinates'].set_index(pd.MultiIndex.from_frame(data['grid_coordinates']))['x']
25
+ tmp_y = data['grid_coordinates'].set_index(pd.MultiIndex.from_frame(data['grid_coordinates']))['y']
26
+
27
+ new_x = ndimage.zoom(tmp_x.unstack('y'), 1./resize_factor)
28
+ new_y = ndimage.zoom(tmp_y.unstack('y'), 1./resize_factor)
29
+
30
+ data['grid_coordinates'] = pd.DataFrame({'x': new_x.ravel(), 'y': new_y.ravel()[::-1]}).astype(np.float32)
31
+
32
+ with (base / 'mask-v1_bold.tsv.gz').open('rb') as f:
33
+ data['v1_timeseries'] = pd.read_csv(f, sep='\t', index_col='time', compression='gzip').astype(np.float32)
34
+
35
+ data['v1_timeseries'].columns = data['v1_timeseries'].columns.astype(int)
36
+ data['tr'] = 1.317025
37
+
38
+ if best_voxels:
39
+ best_voxels = prf_pars['r2'].sort_values(ascending=False).iloc[:best_voxels].index
40
+ data['v1_timeseries'] = data['v1_timeseries'].loc[:, best_voxels]
41
+ prf_pars = prf_pars.loc[best_voxels]
42
+
43
+ data['prf_pars'] = prf_pars
44
+ data['r2'] = prf_pars['r2']
45
+ data['prf_pars'].drop('r2', axis=1, inplace=True)
46
+
47
+ return data
48
+
49
+ import os
50
+ import pathlib
51
+ import requests
52
+ import zipfile
53
+ import shutil
54
+ from tqdm import tqdm
55
+
56
+ FIGSHARE_URL = "https://figshare.com/ndownloader/files/26577941"
57
+ DATA_DIR = pathlib.Path.home() / ".braincoder" / "data"
58
+ ZIP_PATH = DATA_DIR / "fmri_teaching_materials.zip"
59
+
60
+ def ensure_directory_exists(directory):
61
+ """Create directory if it doesn't exist."""
62
+ directory.mkdir(parents=True, exist_ok=True)
63
+
64
+ def download_file(url, save_path):
65
+ """Download a file from a URL with a progress bar."""
66
+ response = requests.get(url, stream=True)
67
+ response.raise_for_status() # Raise error if download fails
68
+
69
+ total_size = int(response.headers.get("content-length", 0))
70
+ block_size = 1024 # 1 KB
71
+ progress_bar = tqdm(total=total_size, unit="B", unit_scale=True, desc="Downloading")
72
+
73
+ with open(save_path, "wb") as f:
74
+ for data in response.iter_content(block_size):
75
+ progress_bar.update(len(data))
76
+ f.write(data)
77
+
78
+ progress_bar.close()
79
+
80
+ def extract_zip(zip_path, extract_to):
81
+ """Extracts the given zip file."""
82
+ with zipfile.ZipFile(zip_path, "r") as zip_ref:
83
+ zip_ref.extractall(extract_to)
84
+
85
+ def load_vanes2019(raw_files=False, downsample_stimulus=5.):
86
+ """
87
+ Ensures the fMRI van Es 2019 dataset is available in ~/.braincoder/data.
88
+ Downloads and extracts it if necessary.
89
+ Returns the path to the dataset.
90
+ """
91
+ ensure_directory_exists(DATA_DIR)
92
+ dataset_folder = DATA_DIR / "prf_vanes2019"
93
+
94
+ if not dataset_folder.exists() or not any(dataset_folder.iterdir()):
95
+ print(f"Dataset missing or incomplete in {dataset_folder}, redownloading...")
96
+ if dataset_folder.exists():
97
+ shutil.rmtree(dataset_folder) # Remove partial data
98
+ download_file(FIGSHARE_URL, ZIP_PATH)
99
+ print("\nDownload complete, extracting...")
100
+ extract_zip(ZIP_PATH, dataset_folder)
101
+ print("\nExtraction complete, cleaning up...")
102
+ ZIP_PATH.unlink() # Remove zip file after extraction
103
+
104
+ data_lh = load_surf_data(dataset_folder / "sub-02_task-prf_space-59k_hemi-L_run-median_desc-bold.func.gii")
105
+ data_rh = load_surf_data(dataset_folder / "sub-02_task-prf_space-59k_hemi-R_run-median_desc-bold.func.gii")
106
+
107
+ if raw_files:
108
+ # Return a list with all files in dataset_folder:
109
+ return list(dataset_folder.iterdir())
110
+
111
+ data = {}
112
+ data['ts'] = pd.concat((pd.DataFrame(data_lh, index=pd.Index(np.arange(len(data_lh)), name='vertex')),
113
+ pd.DataFrame(data_rh, index=pd.Index(np.arange(len(data_rh)), name='vertex'))), keys=['L', 'R'], names=['hemisphere'], axis=0).T
114
+
115
+ # Convert ts to percent signal change:
116
+ data['ts'] = (data['ts'] - data['ts'].mean()) / data['ts'].mean() * 100
117
+
118
+ data['stimulus'] = zoom(io.loadmat(dataset_folder / "vis_design.mat")['stim'], (1./downsample_stimulus, 1./downsample_stimulus, 1)).astype(np.float32)
119
+ data['stimulus'] = np.clip(np.moveaxis(np.moveaxis(data['stimulus'], -1, 0), -1, 1) / 255., 0, 1)
120
+
121
+ # Calculate the degree per pixel scaling factors
122
+ width_pixels, height_pixels = data['stimulus'].shape[1:]
123
+ width_degrees = 20
124
+ dx = width_degrees / width_pixels
125
+ dy = dx
126
+ height_degrees = height_pixels * dy
127
+
128
+ x_degrees = np.linspace(-width_degrees / 2 + dx / 2, width_degrees / 2 - dx / 2, width_pixels)
129
+ y_degrees = np.linspace(-height_degrees / 2 + dy / 2, height_degrees / 2 - dy / 2, height_pixels)
130
+
131
+ x_mesh, y_mesh = np.meshgrid(x_degrees, y_degrees)
132
+
133
+ data['grid_coordinates'] = pd.DataFrame({'x': x_mesh.ravel(), 'y': y_mesh.ravel()}).astype(np.float32)
134
+ data['tr'] = 1.5
135
+
136
+ return data
137
+
138
+
139
+ # Numerosity demo bundle (sub-13 from the Prat-Carrabin et al. 2025
140
+ # numerosity fMRI dataset). The release URL is overridable for local
141
+ # testing via the env var BRAINCODER_NPC_DEMO_URL — point that at a
142
+ # file:// or http(s):// resource.
143
+ # Article: https://doi.org/10.6084/m9.figshare.32358570 (Prat-Carrabin et al.
144
+ # 2025 numerosity NPC extract, sub-13).
145
+ NPC_DEMO_DEFAULT_URL = "https://ndownloader.figshare.com/files/64795824"
146
+
147
+
148
+ def load_pratcarrabin2025_npc(force_redownload=False):
149
+ """Download and load the numerosity demo bundle.
150
+
151
+ A small (~4 MB) extract from the numerosity fMRI dataset accompanying
152
+ Prat-Carrabin et al. (2025, *Distributed range adaptation in human
153
+ parietal encoding of numbers*, bioRxiv 10.1101/2025.09.25.675916),
154
+ built from one subject (highest mean NPCr CV-R² with model 15). The
155
+ bundle is structured so the encoding-pipeline example notebooks
156
+ (``examples/01_decoding_pipeline``) can run end-to-end without any
157
+ local BIDS dataset on disk.
158
+
159
+ Returns
160
+ -------
161
+ dict with keys::
162
+
163
+ manifest — provenance dict (subject id, hemisphere, ...)
164
+ r2_wholebrain — nibabel Nifti1Image, whole-brain
165
+ within-sample R² (use for the mixture-
166
+ model voxel selection)
167
+ cv_r2_wholebrain — nibabel Nifti1Image, whole-brain CV-R²
168
+ (for generalisation reporting)
169
+ brain_mask — nibabel Nifti1Image, EPI brain mask (T1w)
170
+ data — pd.DataFrame (n_trials × n_vox), NPCr betas
171
+ paradigm — pd.DataFrame (n_trials × {session, run,
172
+ trial_nr, n, range}); ``n`` is the
173
+ presented numerosity, ``range`` ∈
174
+ {'narrow', 'wide'}
175
+ voxel_coords_mm — pd.DataFrame (n_vox × {x, y, z}), T1w mm
176
+ voxel_to_vertex — pd.DataFrame (n_vox × {vertex,
177
+ distance_mm}) — nearest patch vertex per
178
+ voxel
179
+ r2 — pd.Series, NPCr within-sample R² per voxel
180
+ cv_r2 — pd.Series, NPCr CV-R² per voxel
181
+ surface_vertices — (n_patch_vertices × 3) float32 array
182
+ surface_faces — (n_patch_faces × 3) int32 array
183
+ hemisphere — 'L' or 'R'
184
+ """
185
+ url = os.environ.get('BRAINCODER_NPC_DEMO_URL', NPC_DEMO_DEFAULT_URL)
186
+ dataset_folder = DATA_DIR / 'pratcarrabin2025_npc'
187
+ zip_path = DATA_DIR / 'pratcarrabin2025_npc.zip'
188
+
189
+ ensure_directory_exists(DATA_DIR)
190
+ if force_redownload and dataset_folder.exists():
191
+ shutil.rmtree(dataset_folder)
192
+
193
+ if not dataset_folder.exists() or not any(dataset_folder.iterdir()):
194
+ if url.startswith('file://') or os.path.isabs(url):
195
+ # Local-file shortcut for development.
196
+ src = url.removeprefix('file://')
197
+ print(f'Copying demo bundle from {src} …')
198
+ shutil.copy(src, zip_path)
199
+ else:
200
+ print(f'Downloading demo bundle from {url} …')
201
+ download_file(url, zip_path)
202
+ ensure_directory_exists(dataset_folder)
203
+ extract_zip(zip_path, dataset_folder)
204
+ zip_path.unlink()
205
+
206
+ import json
207
+ import nibabel as nib
208
+
209
+ manifest = json.loads((dataset_folder / 'manifest.json').read_text())
210
+
211
+ r2_wholebrain = nib.load(dataset_folder / 'r2_wholebrain.nii.gz')
212
+ cv_r2_wholebrain = nib.load(dataset_folder / 'cv_r2_wholebrain.nii.gz')
213
+ brain_mask = nib.load(dataset_folder / 'brain_mask.nii.gz')
214
+
215
+ npcr = dataset_folder / 'npcr'
216
+ data = pd.read_csv(npcr / 'single_trial_betas.tsv.gz',
217
+ sep='\t', index_col='trial', compression='gzip')
218
+ data.columns = data.columns.astype(int)
219
+ data.columns.name = 'voxel'
220
+ data = data.astype(np.float32)
221
+
222
+ paradigm = pd.read_csv(npcr / 'paradigm.tsv', sep='\t')
223
+
224
+ voxel_coords_mm = pd.read_csv(npcr / 'voxel_coords_mm.tsv',
225
+ sep='\t', index_col='voxel')
226
+ voxel_to_vertex = pd.read_csv(npcr / 'voxel_to_vertex.tsv',
227
+ sep='\t', index_col='voxel')
228
+ r2 = pd.read_csv(npcr / 'r2.tsv', sep='\t',
229
+ index_col='voxel')['r2']
230
+ cv_r2 = pd.read_csv(npcr / 'cv_r2.tsv', sep='\t',
231
+ index_col='voxel')['cv_r2']
232
+
233
+ with np.load(dataset_folder / 'surface_patch.npz', allow_pickle=False) as npz:
234
+ surface_vertices = npz['vertices'].astype(np.float32)
235
+ surface_faces = npz['faces'].astype(np.int32)
236
+ hemi = str(npz['hemi'])
237
+
238
+ return {
239
+ 'manifest': manifest,
240
+ 'r2_wholebrain': r2_wholebrain,
241
+ 'cv_r2_wholebrain': cv_r2_wholebrain,
242
+ 'brain_mask': brain_mask,
243
+ 'data': data,
244
+ 'paradigm': paradigm,
245
+ 'voxel_coords_mm': voxel_coords_mm,
246
+ 'voxel_to_vertex': voxel_to_vertex,
247
+ 'r2': r2,
248
+ 'cv_r2': cv_r2,
249
+ 'surface_vertices': surface_vertices,
250
+ 'surface_faces': surface_faces,
251
+ 'hemisphere': hemi,
252
+ }
@@ -0,0 +1,63 @@
1
+ import pandas as pd
2
+ import numpy as np
3
+ from keras import ops
4
+
5
+ def format_paradigm(paradigm):
6
+ if paradigm is None:
7
+ return None
8
+
9
+ if isinstance(paradigm, pd.DataFrame):
10
+ return paradigm
11
+
12
+ if isinstance(paradigm, pd.Series):
13
+ return paradigm.to_frame()
14
+
15
+ if paradigm.ndim == 1:
16
+ paradigm = paradigm[:, np.newaxis]
17
+ elif paradigm.ndim > 2:
18
+ paradigm = paradigm.reshape((paradigm.shape[0], -1))
19
+
20
+ return pd.DataFrame(paradigm, index=pd.Index(range(len(paradigm)), name='time'),
21
+ columns=pd.Index(range(paradigm.shape[1]), name='stimulus dimension')).astype(np.float32)
22
+
23
+ def format_parameters(parameters, parameter_labels=None):
24
+
25
+ if isinstance(parameters, pd.DataFrame):
26
+ return parameters.astype(np.float32)
27
+
28
+ if parameters is None:
29
+ return None
30
+
31
+ if parameter_labels is None:
32
+ parameter_labels = [
33
+ f'par{i+1}' for i in range(parameters.shape[1])]
34
+
35
+ if type(parameter_labels) is list:
36
+ parameter_labels = pd.Index(parameter_labels, name='parameter')
37
+
38
+ return pd.DataFrame(parameters,
39
+ columns=parameter_labels,
40
+ index=pd.Index(range(len(parameters)), name='source')).astype(np.float32)
41
+
42
+ def format_weights(weights):
43
+ if weights is not None:
44
+ if isinstance(weights, pd.DataFrame):
45
+ return weights
46
+ else:
47
+ return pd.DataFrame(weights,
48
+ index=pd.Index(
49
+ range(1, len(weights) + 1), name='population'),
50
+ columns=pd.Index(np.arange(weights.shape[1]), name='unit')).astype(np.float32)
51
+
52
+ def format_data(data):
53
+
54
+ if isinstance(data, pd.DataFrame):
55
+ return data
56
+
57
+ if not isinstance(data, np.ndarray):
58
+ data = ops.convert_to_numpy(data)
59
+
60
+ return pd.DataFrame(data,
61
+ index=pd.Index(
62
+ np.arange(len(data)), name='time'),
63
+ columns=pd.Index(range(data.shape[1]), name='unit')).astype(np.float32)