NeuroDOT-py 1.4.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.
neuro_dot/Analysis.py ADDED
@@ -0,0 +1,619 @@
1
+ # General imports
2
+ import numpy as np
3
+ import numpy.linalg as lna
4
+ import neuro_dot as ndot
5
+ from scipy import signal
6
+ from scipy.linalg import pinv
7
+ from scipy.stats import zscore as scipy_zscore
8
+ import plotly.io as pio
9
+ import plotly.graph_objects as go
10
+ import plotly.offline as po
11
+ from plotly.subplots import make_subplots
12
+
13
+
14
+
15
+
16
+
17
+ def plot_censoring(DM, keep, GVTD, th, info, Nt):
18
+ try:
19
+ import matplotlib.pyplot as plt
20
+ import matplotlib.gridspec as gridspec
21
+ except ImportError:
22
+ print("matplotlib not available – skipping censoring plot.")
23
+ return
24
+
25
+ # Normalise DM for display (optional, but often helps)
26
+ DM_min = DM.min()
27
+ DM_max = DM.max()
28
+ DM_norm = (DM - DM_min) / (DM_max - DM_min + 1e-12)
29
+
30
+ # Keep column: 1 for kept, 0 for censored
31
+ keep_col = keep.astype(float)
32
+
33
+ # Add keep as an extra column
34
+ combined = np.column_stack([DM_norm, keep_col]) # shape: (Nt, n_reg+1)
35
+
36
+ # --- Layout: tall DM on the left, two panels on the right ---
37
+ fig = plt.figure(figsize=(8, 5))
38
+ gs = gridspec.GridSpec(2, 2, width_ratios=[2, 1], height_ratios=[1, 1])
39
+
40
+ # Left: design matrix + keep, spanning both rows (0:2, 0)
41
+ ax_dm = fig.add_subplot(gs[:, 0])
42
+ # Show time on x-axis, regressors on y-axis => no transpose
43
+ im = ax_dm.imshow(combined, aspect='auto', cmap='gray',
44
+ extent=[0, Nt, combined.shape[1], 0],interpolation = 'nearest')
45
+ ax_dm.imshow(combined, aspect='auto', cmap='gray',interpolation='nearest')
46
+ ax_dm.set_xlabel('Regressors + keep')
47
+ ax_dm.set_ylabel('Time (samples)')
48
+ ax_dm.set_title('Design Matrix + keep')
49
+
50
+ # Top-right: GVTD time trace
51
+ ax_gvtd = fig.add_subplot(gs[0, 1])
52
+ ax_gvtd.plot(np.arange(Nt), GVTD, 'k')
53
+ ax_gvtd.axhline(th, color='r')
54
+ ax_gvtd.set_xlim([0, Nt])
55
+ ax_gvtd.set_ylabel('GVTD')
56
+ ax_gvtd.set_xlabel('Time (samples)')
57
+
58
+ # Bottom-right: GVTD histogram
59
+ ax_hist = fig.add_subplot(gs[1, 1])
60
+ ax_hist.hist(GVTD.ravel(), bins=100)
61
+ ylim = ax_hist.get_ylim()
62
+ ax_hist.plot([th, th], [0, ylim[1]], 'r')
63
+ ax_hist.set_xlabel('GVTD')
64
+ ax_hist.set_ylabel('Count')
65
+
66
+ plt.tight_layout()
67
+ plt.show()
68
+
69
+
70
+ def BlockAverage(data_in, pulse, dt, Tkeep = 0):
71
+ """
72
+ BLOCKAVERAGE Averages data by stimulus blocks.
73
+
74
+ data_out = BLOCKAVERAGE(data_in, pulse, dt) takes a data array "data_in"
75
+ and uses the pulse and dt information to cut that data timewise into
76
+ blocks of equal length (dt), which are then averaged together and
77
+ output as "data_out".
78
+
79
+ Tkeep is a temporal mask. Any time points with a zero in this vector is
80
+ set to NaN.
81
+ """
82
+ ## Parameters and Initialization.
83
+ dims = np.shape(data_in)
84
+ Nt = dims[-1]
85
+ NDtf = np.ndim(data_in) > 2
86
+ Nbl = len(pulse)
87
+
88
+ if Tkeep == 0:
89
+ Tkeep = np.ones(shape = (Nt, 1))==1
90
+
91
+ # Check to make sure that the block after the last synch point for this
92
+ if (dt + pulse[-1] - 1) > Nt:
93
+ Nbl = Nbl - 1
94
+
95
+ ## N-D Input (for 3-D or N-D voxel spaces).
96
+ if NDtf:
97
+ data_in = np.reshape(data_in, [], Nt)
98
+
99
+ ## Incorporate Tkeep
100
+ data_in[:, np.argwhere(Tkeep == False)] = np.nan
101
+
102
+ ## Cut data into blocks.
103
+ Nm = np.shape(data_in)[0]
104
+ blocks = np.zeros((Nm, dt, Nbl))
105
+
106
+ for p in range(0,len(pulse)):
107
+ pulse[p] = pulse[p] +1
108
+
109
+ for k in range(0, Nbl):
110
+ pulse_k = int(pulse[k])
111
+
112
+ if (pulse[k] + dt -1) <= Nt:
113
+ blocks[:, :, k] = data_in[:, pulse_k-1:pulse_k + dt-1] #Need to subtract 1 from both indices to account for 0 indexing in python
114
+ else:
115
+ dtb = (pulse_k-1) + dt - 1 - Nt+1
116
+ nans = np.empty(shape = (np.shape(data_in)[0], dtb)) # need multiple lines to create an array of nans in python
117
+ nans[:] = np.NaN
118
+ blocks[:, :, k] = np.concatenate((data_in[:, (pulse_k-1):Nt], nans), axis = 1) # need to subtract 1 from start index: pulse[k] due to zero indexing, also need to use Nt as final index to get correct size
119
+
120
+ ## Average blocks and return.
121
+ BA_out = np.nanmean(blocks, axis = 2)
122
+ BSTD_out = np.nanstd(blocks, axis = 2, ddof = 1)
123
+ nanmean_cols = np.nanmean(BA_out, axis = 1)
124
+ nanmean_matrix = np.ones(np.shape(BA_out))
125
+ for x in range(0, dt):
126
+ nanmean_matrix[:, x] = nanmean_cols
127
+ BA_out = BA_out - nanmean_matrix
128
+ BT_out = np.divide(BA_out, BSTD_out)
129
+ BT_out[np.argwhere(np.isinf(BT_out))] = 0
130
+
131
+ ## N-D Output.
132
+ if NDtf:
133
+ #create tuple containing the desired output shape for BA_out, BSTD_out and BT_out
134
+ #tuple contains first axis until second to last axis of data with dt appeneded to the end of it
135
+ newshape = tuple(np.append(np.array(dims[0:-1]), dt))
136
+ BA_out = np.reshape(BA_out, newshape)
137
+ BSTD_out = np.reshape(BSTD_out, newshape)
138
+ BT_out = np.reshape(BT_out, newshape)
139
+ newshape_blocks = tuple(np.append(np.array(dims[0:-1]), (dt, Nbl))) # create tuple for deisred output shape for blocks, different from previous newshape bc Nbl is also appended
140
+ blocks = np.reshape(blocks, newshape_blocks)
141
+
142
+
143
+ return BA_out, BSTD_out, BT_out, blocks
144
+
145
+
146
+ def CalcGVTD(data):
147
+ """
148
+ CalcGVTD calculates the Root Mean Square across measurements (log-mean light levels or voxels) of the temporal derivative.
149
+
150
+ The data is assumed to have measurements in the first and time in the last
151
+ dimension.
152
+
153
+ Any selection of measurement type or voxel index must be done
154
+ outside of this function.
155
+ """
156
+ # Double check data has correct dimensions
157
+ # Dsizes=size(data);
158
+ Dsizes = np.shape(data)
159
+ Ndim = len(Dsizes)
160
+ if Ndim > 2:
161
+ data = np.reshape(data, [], Dsizes[-1])
162
+
163
+ # 1st Temporal Derivative
164
+ Ddata = data - np.roll(data, np.array([0, -1]), np.array([0,-1]))
165
+
166
+ # RMS across measurements
167
+ GVTD = np.concatenate(([0], ndot.rms_py(Ddata[:,0:-1])), axis = 0)
168
+
169
+ return GVTD
170
+
171
+
172
+ def FindGoodMeas(data, info_in, bthresh = 0.075):
173
+
174
+ """
175
+ FINDGOODMEAS Performs "Good Measurements" analysis to return indices of measurements within a chosen threshold.
176
+
177
+ info_out = FINDGOODMEAS(data, info_in) takes a light-level array "data"
178
+ in the MEAS x TIME format, and calculates the std of each channel
179
+ as its noise level.
180
+
181
+ These are then thresholded by the default value of
182
+ 0.075 to create a logical array, and both are returned as MEAS x 1
183
+ columns of the "info.MEAS" table.
184
+
185
+ If pulse synch point information exists in "info.system.synchpts",
186
+ then FINDGOODMEAS will crop the data to the start and stop pulses.
187
+
188
+ info_out = FINDGOODMEAS(data, info_in, bthresh) allows the user to
189
+ specify a threshold value.
190
+
191
+ See Also: PLOTCAPGOODMEAS, PLOTHISTOGRAMSTD.
192
+ """
193
+ ## Parameters and Initialization.
194
+ # look for required info, FGM will not run if these fields are nonexistant
195
+ try:
196
+ info1 = info_in['system']['framerate']
197
+ except KeyError:
198
+ print('info_in["system"]["framerate"] does not exist and is required')
199
+ print('exiting FindGoodMeas')
200
+ return()
201
+ try:
202
+ info1 = info_in['pairs']
203
+ except KeyError:
204
+ print('info_in["pairs"] does not exist and is required')
205
+ print('exiting FindGoodMeas')
206
+ return()
207
+ info_out = info_in.copy() # create info_out
208
+ try:
209
+ GVwin
210
+ except NameError:
211
+ GVwin = 600
212
+ if not 'paradigm' in info_out:
213
+ info_out['paradigm'] = {}
214
+ if not bthresh in locals():
215
+ bthresh = 0.075 # Empirically derived threshold value.
216
+ dims = data.shape
217
+ Nt = dims[-1] # Assumes time is always the last dimension
218
+ NDtf = np.ndim(data) > 2
219
+ if GVwin > (Nt-1):
220
+ GVwin = (Nt-1)
221
+
222
+ # N-D Input.
223
+ if NDtf:
224
+ data = np.reshape(data, [], Nt)
225
+
226
+ # Crop data to synchpts if necessary.
227
+ keep = np.logical_and(info_in['pairs']['r2d'] < 20, info_in['pairs']['WL'] == 2)
228
+ foo = np.squeeze(data[keep,:])
229
+ foo = ndot.highpass(foo, 0.02, info_in['system']['framerate']) # bandpass filter, omega_hp = 0.02
230
+ foo = ndot.lowpass(foo, 1, info_in['system']['framerate']) # bandpass filter, omega_lp = 1
231
+ foo = foo - np.roll(foo, 1, 1)
232
+ foo[:,0] = 0
233
+ foob = ndot.rms_py(foo) # uses new rms that only takes one input, calculates rms for every column in rms_input and outputs row vector
234
+ NtGV = Nt - GVwin
235
+ NtGV_mat = np.ones((1,NtGV), dtype = np.int8)
236
+
237
+ if NtGV > 1: # sliding window to grab a meaningful set for 'quiet'
238
+ GVTD_win_means = np.zeros(NtGV, order = 'F')
239
+ i = 0
240
+ while i <= (NtGV - 1):
241
+ GVTD_win_means[i] = np.mean(foob[i:((i+1)+ GVwin - 1)])
242
+ i = i+1
243
+ t0 = np.where(GVTD_win_means == np.min(GVTD_win_means)) # find min and set t0 --> tF
244
+ tF = t0[0][0] + GVwin
245
+ STD = np.std(data[:, t0[0][0]:tF], 1, ddof= 1) # Calulate STD, make sure ddof param is set = 1 so that np.STD behaves the same as matlab STD
246
+ elif not 'synchpts' in info_out['paradigm']:
247
+ NsynchPts = len(info_out['paradigm']['synchpts'])
248
+ if NsynchPts > 2:
249
+ tF = info_out['paradigm']['synchpts'][-1]
250
+ t0 = info_out['paradigm']['synchpts'][0]
251
+ elif NsynchPts == 2:
252
+ tF = info_out['paradigm']['synchpts'][1]
253
+ t0 = info_out['paradigm']['synchpts'][0]
254
+ else:
255
+ tF = data.shape[1]
256
+ STD = np.std(data[:, t0:tF], 1, ddof=1) # Calculate STD.
257
+ else:
258
+ STD = np.std(data, 1, ddof=1)
259
+
260
+ # Populate in table of on-the-fly calculated stuff.
261
+ info_out['GVTDparams'] = {}
262
+ info_out['GVTDparams']['t0'] = t0[0][0]
263
+ info_out['GVTDparams']['tF'] = tF
264
+ if not 'MEAS' in info_out:
265
+ info_out['MEAS'] = {}
266
+ info_out['MEAS']['STD'] = STD
267
+ info_out['MEAS']['GI'] = np.zeros(np.shape(STD), dtype = np.uint8)
268
+ info_out['MEAS']['GI'][np.where(STD <= bthresh)] = 1
269
+ else:
270
+ info_out['MEAS']['STD'] = STD
271
+ info_out['MEAS']['GI'] = np.zeros(np.shape(STD), dtype = np.uint8)
272
+ info_out['MEAS']['GI'][np.where(STD <= bthresh)] = 1
273
+ if 'Clipped' in info_out['MEAS']:
274
+ info_out['MEAS']['GI'] = np.zeros(np.shape(STD), dtype = np.uint8)
275
+ info_out['MEAS']['GI'][np.where(info_out['MEAS']['GI'] and not info_out['MEAS']['Clipped'])] = 1
276
+
277
+ return info_out
278
+
279
+
280
+ def fisher_r2z(r):
281
+ """Apply Fisher R-to-Z (arctanh) transformation, clipping to avoid infinities."""
282
+ return np.arctanh(np.clip(r, -0.9999999, 0.9999999))
283
+
284
+
285
+ def GLM(data, hrf, info, params=None):
286
+ """
287
+ General Linear Model (GLM) based on a hemodynamic response function (HRF)
288
+ and stimulus times (info['paradigm']['synchpts']).
289
+
290
+ Parameters
291
+ ----------
292
+ data : ndarray, shape (voxels, time)
293
+ hrf : ndarray, 1-D HRF kernel
294
+ info : dict with keys like 'paradigm', 'GVTD_filt_rs', 'system', etc.
295
+ params : dict of options (see defaults below)
296
+
297
+ Returns
298
+ -------
299
+ b : ndarray (voxels, regressors) : beta map
300
+ e : ndarray (voxels, time) : residuals
301
+ DM : ndarray (time, regressors) : design matrix (after convolution)
302
+ EDM : ndarray (time, events) : experimental design matrix
303
+ keep : ndarray (bool) or None : timepoint mask (GVTD censoring)
304
+ r_sqrd : ndarray (voxels,) : R² per voxel
305
+ """
306
+
307
+ # ── Defaults ─────────────────────────────────────────────────────────────
308
+ if params is None:
309
+ params = {}
310
+
311
+ p = {
312
+ 'type': 'events',
313
+ 'GVTDreg': False,
314
+ 'Nuisance_Reg': False,
315
+ 'Nuisance_Regs': None,
316
+ 'GVTD_censor': False,
317
+ 'GVTD_censor_post_win': 0,
318
+ 'GVTD_censor_pre_win': 0,
319
+ 'GVTD_th': 1e-3,
320
+ 'DoFilter': False,
321
+ 'zscore': True,
322
+ 'zscoreData': False,
323
+ 'MakePlot': True,
324
+ }
325
+ p.update(params)
326
+
327
+ Nt = data.shape[1]
328
+ EL = p.get('event_length', 0)
329
+
330
+ paradigm = info['paradigm']
331
+ synchpts = paradigm['synchpts'] # 1-D array of sync point indices
332
+ synchtype = paradigm['synchtype'] # 1-D array of event type labels
333
+ Nevents = len(synchpts)
334
+
335
+ if 'events' in p:
336
+ events = np.unique(p['events'])
337
+ NuniqueEvents = len(events)
338
+ else:
339
+ NuniqueEvents = len(np.unique(synchtype))
340
+ events = np.arange(1, NuniqueEvents + 1)
341
+
342
+ # ── Filter parameters ─────────────────────────────────────────────────────
343
+ if p['DoFilter']:
344
+ flags = info.get('flags', {})
345
+
346
+ omega_hp = p.get('omega_hp',
347
+ flags.get('omega_hp', 0.02))
348
+
349
+ if 'omega_lp' in p:
350
+ omega_lp = p['omega_lp']
351
+ elif 'omega_lp1' in flags:
352
+ omega_lp = flags['omega_lp1']
353
+ elif flags.get('lowpass3') and 'omega_lp3' in flags:
354
+ omega_lp = flags['omega_lp3']
355
+ elif flags.get('lowpass2') and 'omega_lp2' in flags:
356
+ omega_lp = flags['omega_lp2']
357
+ elif flags.get('lowpass1') and 'omega_lp1' in flags:
358
+ omega_lp = flags['omega_lp1']
359
+ else:
360
+ omega_lp = 0.5
361
+
362
+ system = info.get('system', {})
363
+ fr = system.get('framerate', info.get('framerate', 1.0))
364
+
365
+ if omega_lp > fr / 2:
366
+ omega_lp = fr / 2
367
+ if omega_lp == fr / 2:
368
+ omega_lp *= 0.95
369
+
370
+ # ── GVTD ─────────────────────────────────────────────────────────────────
371
+ GVTD = None
372
+ if 'GVTD_filt_rs' in info:
373
+ GVTD = info['GVTD_filt_rs']
374
+ elif 'misc' in info and 'GVTD_filt_rs' in info['misc']:
375
+ GVTD = info['misc']['GVTD_filt_rs']
376
+ elif 'GVTD' in p:
377
+ GVTD = p['GVTD']
378
+
379
+ # ── Experimental Design Matrix (EDM) ──────────────────────────────────────
380
+ EDM = np.zeros((Nt, Nevents))
381
+ for j in range(Nevents - 1):
382
+ start = synchpts[j]
383
+ if EL:
384
+ end = min(synchpts[j] + EL, Nt) # inclusive start, exclusive end
385
+ else:
386
+ end = synchpts[j + 1] # up to (not including) next event
387
+ EDM[start:end, j] = 1
388
+
389
+ EDM[synchpts[-1]:, Nevents - 1] = 1
390
+
391
+ if p['type'] == 'events':
392
+ EDMu = np.zeros((Nt, NuniqueEvents))
393
+ for j, ev in enumerate(events):
394
+ pulse_key = f'Pulse_{int(ev)}'
395
+ pulse_indices = np.array(paradigm[pulse_key]).ravel().astype(int) - 1 # convert to 0-based
396
+ EDMu[:, j] = EDM[:, pulse_indices].sum(axis=1)
397
+ EDM = EDMu
398
+
399
+ # ── Convolve EDM with HRF ────────────────────────────────────────────────
400
+ hrf_col = hrf.ravel()
401
+ # conv2 in MATLAB pads in time; replicate with 1-D convolution per column
402
+ DM = np.column_stack([
403
+ np.convolve(EDM[:, col], hrf_col)[:Nt]
404
+ for col in range(EDM.shape[1])
405
+ ])
406
+
407
+ # ── Add nuisance regressors ───────────────────────────────────────────────
408
+ if p['GVTDreg'] and GVTD is not None:
409
+ DM = np.column_stack([DM, GVTD.ravel()])
410
+ if p['Nuisance_Reg'] and p['Nuisance_Regs'] is not None:
411
+ DM = np.column_stack([DM, p['Nuisance_Regs']])
412
+
413
+ # ── Standardise ───────────────────────────────────────────────────────────
414
+ if p['zscore']:
415
+ DM = scipy_zscore(DM, axis=0) # standardise each column
416
+ else:
417
+ DM = DM - DM.mean(axis=0) # mean-subtract each column
418
+
419
+ if p['zscoreData']:
420
+ data = scipy_zscore(data, axis=1)
421
+
422
+ # ── Filter DM ────────────────────────────────────────────────────────────
423
+ if p['DoFilter']:
424
+ # detrend_tts equivalent: linear detrend along time axis
425
+ DM = signal.detrend(DM, axis=0)
426
+
427
+ # Butterworth high-pass then low-pass (zero-phase via filtfilt)
428
+ sos_hp = signal.butter(4, omega_hp / (fr / 2), btype='high', output='sos')
429
+ sos_lp = signal.butter(4, omega_lp / (fr / 2), btype='low', output='sos')
430
+ DM = signal.sosfiltfilt(sos_hp, DM, axis=0)
431
+ DM = signal.sosfiltfilt(sos_lp, DM, axis=0)
432
+
433
+ # ── Add intercept ────────────────────────────────────────────────────────
434
+ DM = np.column_stack([np.ones(Nt), DM])
435
+
436
+ # ── GVTD censoring ───────────────────────────────────────────────────────
437
+ keep = None
438
+ if p['GVTD_censor'] and GVTD is not None:
439
+ keep = GVTD < p['GVTD_th']
440
+
441
+ if p['GVTD_censor_pre_win']:
442
+ keep0 = keep.copy()
443
+ for n in range(p['GVTD_censor_pre_win'], 0, -1):
444
+ keep = keep & np.roll(keep0, -n)
445
+
446
+ if p['GVTD_censor_post_win']:
447
+ keep0 = keep.copy()
448
+ for n in range(1, p['GVTD_censor_post_win'] + 1):
449
+ keep = keep & np.roll(keep0, n)
450
+
451
+ if p['MakePlot']:
452
+ ndot.plot_censoring(DM, keep, GVTD, p['GVTD_th'], info, Nt)
453
+
454
+ DM = DM[keep, :]
455
+ data = data[:, keep]
456
+
457
+ # ── Drop zero columns ────────────────────────────────────────────────────
458
+ col_norms = np.abs(DM).sum(axis=0)
459
+ is_zero = col_norms == 0
460
+ fix_idx = np.where(is_zero)[0] # original positions of zero cols
461
+ FixDM = is_zero.any()
462
+ if FixDM:
463
+ DM = DM[:, ~is_zero]
464
+
465
+ # ── GLM: beta map and residuals ──────────────────────────────────────────
466
+ # MATLAB: b = (pinv(DM'*DM) * DM' * data')'
467
+ # e = (data' - DM * b')'
468
+ DtD_inv = pinv(DM.T @ DM)
469
+ b = (DtD_inv @ DM.T @ data.T).T # (voxels, regressors)
470
+ e = (data.T - DM @ b.T).T # (voxels, time)
471
+
472
+ var_data = data.var(axis=1, ddof=0) * data.shape[1] # matches MATLAB var(...,1)*N
473
+ r_sqrd = 1.0 - (e ** 2).sum(axis=1) / var_data
474
+
475
+ # ── Re-insert zero-columns into beta map ─────────────────────────────────
476
+ if FixDM:
477
+ for idx in fix_idx:
478
+ idx = int(idx)
479
+ b = np.concatenate(
480
+ [b[:, :idx], np.zeros((b.shape[0], 1)), b[:, idx:]],
481
+ axis=1
482
+ )
483
+
484
+ return b, e, DM, EDM, keep, r_sqrd
485
+
486
+
487
+ def normalize_rows(data):
488
+ """
489
+ Normalize each row to zero mean and unit L2 norm (mimics MATLAB's normr).
490
+ This enables fast Pearson correlation via dot products.
491
+ """
492
+ norms = np.linalg.norm(data, axis=1, keepdims=True)
493
+ norms = np.where(norms == 0, 1.0, norms)
494
+ return data / norms
495
+
496
+
497
+ def normcND(data):
498
+ """
499
+ NORMCND returns a column-normed matrix. It is assumed that the matrix is 2D.
500
+ """
501
+ vecnorm = lna.norm(data, ord = 2, axis = 0)
502
+ data = data / vecnorm
503
+
504
+ return data
505
+
506
+
507
+ def normrND(data):
508
+ """
509
+ NORMRND returns a row-normed matrix. It is assumed that the matrix is 2D. Updated for broader compatability.
510
+ """
511
+ dataNorm = np.sqrt(np.sum(data**2))
512
+ data = data / dataNorm
513
+ data[np.argwhere(np.isfinite(data) == False)] = 0
514
+
515
+ return data
516
+
517
+
518
+ def parcel_based_fc(data, parcels, dim, params=None):
519
+ """
520
+ Calculate parcel-based functional connectivity between a volumetric dataset
521
+ and a set of volumetrically defined parcels.
522
+
523
+ Parameters
524
+ ----------
525
+ data : np.ndarray
526
+ Volumetric data. Time is assumed to be the last dimension.
527
+ Expected to already be preprocessed (demeaned + normalized).
528
+ If not 2D, data is reshaped to (n_voxels, n_timepoints).
529
+ parcels : np.ndarray
530
+ Volume of integers defining parcel locations (0 = background).
531
+ Must be in the same space as `data`.
532
+ dim : tuple or array-like
533
+ Spatial dimensions of the data volume (e.g. (x, y, z)).
534
+ params : dict, optional
535
+ Reserved for future use (e.g. custom masks).
536
+
537
+ Returns
538
+ -------
539
+ fc_maps : np.ndarray, shape (x, y, z, n_parcels)
540
+ Fisher-Z transformed seed correlation maps for each parcel.
541
+ fc_matrix : np.ndarray, shape (n_parcels, n_parcels)
542
+ Fisher-Z transformed parcel-to-parcel correlation matrix.
543
+ parcel_tt : np.ndarray, shape (n_timepoints, n_parcels)
544
+ Mean ROI timecourse for each parcel.
545
+ n_timepoints matches the time dimension of the input data
546
+ (i.e. the number of kept frames after any temporal masking applied
547
+ upstream, NOT the full original recording length).
548
+
549
+ Notes
550
+ -----
551
+ The correlation maps are computed in a single matrix multiply rather than
552
+ a per-parcel loop, making this significantly faster for large parcel sets.
553
+ Both `data` and the parcel seed timecourses are row-normalized before the
554
+ dot product so the result is equivalent to Pearson r.
555
+ """
556
+ if params is None:
557
+ params = {}
558
+ # --- Shape handling ---
559
+ dims = data.shape
560
+ n_t = dims[-1] # time is always the last dimension
561
+
562
+ if data.ndim > 2:
563
+ data = np.moveaxis(data, 0, -1)
564
+ n_t = data.shape[-1]
565
+ data = data.reshape(-1, n_t)
566
+
567
+ # --- Parcel setup ---
568
+ parcels_flat = parcels.ravel()
569
+ u_parcels = np.unique(parcels_flat[parcels_flat != 0])
570
+ n_parcels = len(u_parcels)
571
+
572
+ # --- Build parcel mean timecourses ---
573
+ parcel_tt = np.zeros((n_t, n_parcels))
574
+
575
+ if data.ndim > 2:
576
+ data = np.moveaxis(data, 0, -1)
577
+ n_t = data.shape[-1]
578
+ spatial_dims = data.shape[:3]
579
+ data = data.reshape(-1, n_t)
580
+ else:
581
+ n_t = data.shape[-1]
582
+ spatial_dims = tuple(dims[:3])
583
+
584
+ print(f"Calculating correlations for {n_parcels} parcels...")
585
+
586
+ for k, label in enumerate(u_parcels):
587
+ vol_mask = (parcels_flat == label) # boolean, shape (n_voxels,)
588
+ n_s = vol_mask.sum()
589
+ if n_s == 0:
590
+ continue
591
+ parcel_tt[:, k] = data[vol_mask, :].sum(axis=0) / n_s # mean over parcel voxels
592
+
593
+ # --- Vectorized correlation: all parcels in one matrix multiply ---
594
+
595
+ # Build parcel mean timecourses from already-normalized data
596
+ data_norm = ndot.normalize_rows(data) # normalize data rows first
597
+
598
+ parcel_tt = np.zeros((n_t, n_parcels))
599
+ for k, label in enumerate(u_parcels):
600
+ vol_mask = (parcels_flat == label)
601
+ n_s = vol_mask.sum()
602
+ if n_s == 0:
603
+ continue
604
+ parcel_tt[:, k] = data_norm[vol_mask, :].sum(axis=0) / n_s # mean of normalized rows
605
+
606
+ # Dot product directly — do NOT re-normalize parcel_tt
607
+ r_all = data_norm @ parcel_tt # (n_voxels, n_parcels)
608
+ fc_maps = ndot.fisher_r2z(r_all)
609
+
610
+ # --- Reshape fc_maps to volume ---
611
+ spatial_dims = parcels.shape
612
+
613
+ fc_maps = fc_maps.reshape(*spatial_dims, n_parcels)
614
+
615
+ # --- Parcel-to-parcel FC matrix ---
616
+ fc_matrix = ndot.fisher_r2z(np.corrcoef(parcel_tt.T))
617
+
618
+ return fc_maps, fc_matrix, parcel_tt
619
+