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.
- braincoder/__init__.py +27 -0
- braincoder/barstimuli.py +569 -0
- braincoder/data/szinte2024/dm_gazecenter.npz +0 -0
- braincoder/data/szinte2024/gauss_parameters.tsv +2366 -0
- braincoder/data/szinte2024/grid_coordinates.tsv +3601 -0
- braincoder/data/szinte2024/mask-v1_bold.tsv.gz +0 -0
- braincoder/hrf.py +272 -0
- braincoder/models/__init__.py +21 -0
- braincoder/models/base.py +1004 -0
- braincoder/models/linear.py +100 -0
- braincoder/models/prf_1d.py +369 -0
- braincoder/models/prf_2d.py +824 -0
- braincoder/noise.py +614 -0
- braincoder/optimize/__init__.py +22 -0
- braincoder/optimize/bayesian_fitter.py +467 -0
- braincoder/optimize/gp_prior.py +361 -0
- braincoder/optimize/parameter_fitter.py +666 -0
- braincoder/optimize/residual_fitter.py +563 -0
- braincoder/optimize/stimulus_fitter.py +656 -0
- braincoder/optimize/weight_fitter.py +112 -0
- braincoder/stimuli.py +224 -0
- braincoder/utils/__init__.py +4 -0
- braincoder/utils/backend.py +533 -0
- braincoder/utils/calibration.py +186 -0
- braincoder/utils/cortex.py +141 -0
- braincoder/utils/data.py +252 -0
- braincoder/utils/formatting.py +63 -0
- braincoder/utils/math.py +131 -0
- braincoder/utils/mcmc.py +114 -0
- braincoder/utils/stats.py +267 -0
- braincoder/utils/visualize.py +26 -0
- braincoder-0.7.1.dist-info/METADATA +136 -0
- braincoder-0.7.1.dist-info/RECORD +36 -0
- braincoder-0.7.1.dist-info/WHEEL +5 -0
- braincoder-0.7.1.dist-info/licenses/LICENSE +22 -0
- braincoder-0.7.1.dist-info/top_level.txt +1 -0
|
@@ -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
|
braincoder/utils/data.py
ADDED
|
@@ -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)
|