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 +619 -0
- neuro_dot/DynamicFilter.py +297 -0
- neuro_dot/File_IO.py +1720 -0
- neuro_dot/Light_Modeling.py +232 -0
- neuro_dot/Matlab_Equivalent_Functions.py +33 -0
- neuro_dot/Reconstruction.py +168 -0
- neuro_dot/Spatial_Transforms.py +249 -0
- neuro_dot/Temporal_Transforms.py +605 -0
- neuro_dot/Visualizations.py +4380 -0
- neuro_dot/__init__.py +10 -0
- neurodot_py-1.4.1.dist-info/LICENSE +21 -0
- neurodot_py-1.4.1.dist-info/METADATA +44 -0
- neurodot_py-1.4.1.dist-info/RECORD +15 -0
- neurodot_py-1.4.1.dist-info/WHEEL +5 -0
- neurodot_py-1.4.1.dist-info/top_level.txt +1 -0
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
|
+
|