indi-net-extract 0.1.0.dev0__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.
- indi_net_extract-0.1.0.dev0.dist-info/METADATA +158 -0
- indi_net_extract-0.1.0.dev0.dist-info/RECORD +18 -0
- indi_net_extract-0.1.0.dev0.dist-info/WHEEL +5 -0
- indi_net_extract-0.1.0.dev0.dist-info/licenses/LICENSE +30 -0
- indi_net_extract-0.1.0.dev0.dist-info/licenses/THIRD_PARTY_NOTICES.md +30 -0
- indi_net_extract-0.1.0.dev0.dist-info/top_level.txt +1 -0
- indinetextract/__init__.py +13 -0
- indinetextract/_algorithms/__init__.py +1 -0
- indinetextract/_algorithms/dual_regression.py +148 -0
- indinetextract/_algorithms/gig_ica.py +412 -0
- indinetextract/_io.py +302 -0
- indinetextract/_types.py +114 -0
- indinetextract/_validation.py +124 -0
- indinetextract/_version.py +1 -0
- indinetextract/batch.py +218 -0
- indinetextract/evaluation.py +129 -0
- indinetextract/extraction.py +326 -0
- indinetextract/postprocessing.py +391 -0
|
@@ -0,0 +1,412 @@
|
|
|
1
|
+
# Copyright (c) 2012 Yuhui DU and Yong FAN
|
|
2
|
+
# All rights reserved.
|
|
3
|
+
#
|
|
4
|
+
# Redistribution and use in source or any other forms, with or without
|
|
5
|
+
# modification, are permitted provided that the following conditions are met:
|
|
6
|
+
#
|
|
7
|
+
# * Redistributions of source code must retain the above copyright notice,
|
|
8
|
+
# this list of conditions and the following disclaimer.
|
|
9
|
+
# * Redistributions in any other form must reproduce the above copyright notice,
|
|
10
|
+
# this list of conditions and the following disclaimer in the documentation
|
|
11
|
+
# and/or other materials provided with the distribution.
|
|
12
|
+
# * Neither the names of the copyright holders nor the names of future
|
|
13
|
+
# contributors may be used to endorse or promote products derived from this
|
|
14
|
+
# software without specific prior written permission.
|
|
15
|
+
#
|
|
16
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
17
|
+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
18
|
+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
19
|
+
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
20
|
+
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
21
|
+
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
22
|
+
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
23
|
+
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
24
|
+
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
25
|
+
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
26
|
+
# POSSIBILITY OF SUCH DAMAGE.
|
|
27
|
+
"""NumPy/SciPy translation of the locked official classic GIG-ICA core.
|
|
28
|
+
|
|
29
|
+
Source: GIFT ``icatb_gigicar.m``, SHA256 given by SOURCE_SHA256 below.
|
|
30
|
+
Inputs are data [time, voxel] and reference [component, voxel]. Outputs are
|
|
31
|
+
components [voxel, component] and timecourses [time, component], both float64.
|
|
32
|
+
The Python solver calls no MATLAB process or MATLAB Engine.
|
|
33
|
+
|
|
34
|
+
The official threshold/fallback, sample-standard-deviation convention, and
|
|
35
|
+
iteration control flow are retained, including its final-candidate assignment.
|
|
36
|
+
This is a translation requiring independent validation, not author software.
|
|
37
|
+
"""
|
|
38
|
+
from __future__ import annotations
|
|
39
|
+
|
|
40
|
+
from dataclasses import dataclass, field
|
|
41
|
+
import time
|
|
42
|
+
from typing import Callable
|
|
43
|
+
|
|
44
|
+
import numpy as np
|
|
45
|
+
from scipy import linalg
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
SOURCE_SHA256 = '6a0bbf665524d0122686ce6416d06350cb21d71f90460c282aa539f76803773c'
|
|
49
|
+
SOURCE_NAME = 'GIFT icatb_gigicar.m'
|
|
50
|
+
GAUSSIAN_EXPECTATION = 0.3745672075
|
|
51
|
+
FIRST_THRESHOLD = float(np.finfo(np.float64).eps)
|
|
52
|
+
FALLBACK_THRESHOLD = 0.02
|
|
53
|
+
UNIT_SD_TOLERANCE = 1e-2
|
|
54
|
+
MAX_ATTEMPTS = 100
|
|
55
|
+
WEIGHT_CHANGE_SQUARED_TOLERANCE = 1e-5
|
|
56
|
+
Callback = Callable[[dict], None] | None
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _emit(callback: Callback, stage: str, **values) -> None:
|
|
60
|
+
if callback is not None:
|
|
61
|
+
callback(dict(stage=stage, **values))
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _nege(values: np.ndarray) -> float:
|
|
65
|
+
# Preserve the literal author expression. A stable alternative would be a
|
|
66
|
+
# separately validated numerical change, not silently substituted here.
|
|
67
|
+
with np.errstate(over='raise', invalid='raise'):
|
|
68
|
+
expectation = float(np.mean(np.log(np.cosh(values))))
|
|
69
|
+
return (expectation - GAUSSIAN_EXPECTATION) ** 2
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class WhitenedData:
|
|
74
|
+
y: np.ndarray
|
|
75
|
+
threshold: float
|
|
76
|
+
eigenvalues: np.ndarray
|
|
77
|
+
metadata: dict
|
|
78
|
+
pinv_cache: dict = field(default_factory=dict, repr=False)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@dataclass
|
|
82
|
+
class PreparedData:
|
|
83
|
+
centered: np.ndarray
|
|
84
|
+
spatial_means: np.ndarray
|
|
85
|
+
eigenvalues: np.ndarray
|
|
86
|
+
eigenvectors: np.ndarray
|
|
87
|
+
metadata: dict
|
|
88
|
+
whitened_cache: dict = field(default_factory=dict, repr=False)
|
|
89
|
+
|
|
90
|
+
def clear_cache(self) -> None:
|
|
91
|
+
"""Release cached whitened maps and SVD factors, retaining input prep."""
|
|
92
|
+
self.whitened_cache.clear()
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def prepare(data, *, eigen_driver: str = 'evd', callback: Callback = None) -> PreparedData:
|
|
96
|
+
"""Copy to float64, spatially demean each timepoint, then diagonalize XX'/V.
|
|
97
|
+
|
|
98
|
+
The caller's float32 memmap or ndarray is never modified. Negative
|
|
99
|
+
eigenvalues are not clipped; whiten() implements the author's exact rule.
|
|
100
|
+
"""
|
|
101
|
+
started = time.perf_counter()
|
|
102
|
+
if np.iscomplexobj(data):
|
|
103
|
+
raise ValueError('data must be real-valued')
|
|
104
|
+
x = np.array(data, dtype=np.float64, order='C', copy=True)
|
|
105
|
+
if x.ndim != 2 or min(x.shape) < 2 or not np.isfinite(x).all():
|
|
106
|
+
raise ValueError('data must be a finite real [time, voxel] matrix')
|
|
107
|
+
_emit(callback, 'spatial_demean', shape=list(x.shape))
|
|
108
|
+
spatial_means = x.mean(axis=1)
|
|
109
|
+
x -= spatial_means[:, None]
|
|
110
|
+
covariance = (x @ x.T) / x.shape[1]
|
|
111
|
+
_emit(callback, 'covariance_eigh_start', driver=eigen_driver)
|
|
112
|
+
eigenvalues, eigenvectors = linalg.eigh(
|
|
113
|
+
covariance, lower=False, overwrite_a=True, check_finite=False,
|
|
114
|
+
driver=eigen_driver)
|
|
115
|
+
metadata = dict(
|
|
116
|
+
n_timepoints=x.shape[0], n_voxels=x.shape[1], dtype='float64',
|
|
117
|
+
eigen_driver=eigen_driver, covariance_divisor=x.shape[1],
|
|
118
|
+
negative_eigenvalue_count=int(np.sum(eigenvalues < 0)),
|
|
119
|
+
smallest_eigenvalues=eigenvalues[:min(16, len(eigenvalues))].tolist(),
|
|
120
|
+
largest_eigenvalue=float(eigenvalues[-1]),
|
|
121
|
+
elapsed_seconds=time.perf_counter() - started)
|
|
122
|
+
_emit(callback, 'covariance_eigh_complete', **metadata)
|
|
123
|
+
return PreparedData(x, spatial_means, eigenvalues, eigenvectors, metadata)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def whiten(prepared: PreparedData, threshold: float, *, callback: Callback = None,
|
|
127
|
+
cache: bool = True) -> WhitenedData:
|
|
128
|
+
"""Apply the original absolute eigenvalue cutoff and conditional Y/SD(Y)."""
|
|
129
|
+
threshold = float(threshold)
|
|
130
|
+
if threshold in prepared.whitened_cache:
|
|
131
|
+
return prepared.whitened_cache[threshold]
|
|
132
|
+
if not np.isfinite(threshold) or threshold < 0:
|
|
133
|
+
raise ValueError('threshold must be finite and nonnegative')
|
|
134
|
+
# Source removes negative eigenvalues, sorts the rest, then uses > thr.
|
|
135
|
+
# For nonnegative thr the resulting retained set equals this mask.
|
|
136
|
+
selected = np.flatnonzero((prepared.eigenvalues >= 0)
|
|
137
|
+
& (np.abs(prepared.eigenvalues) > threshold))[::-1]
|
|
138
|
+
if selected.size == 0:
|
|
139
|
+
raise ValueError('The official eigenvalue rule retained no dimensions')
|
|
140
|
+
values = np.abs(prepared.eigenvalues[selected])
|
|
141
|
+
whitener = prepared.eigenvectors[:, selected].T / np.sqrt(values)[:, None]
|
|
142
|
+
_emit(callback, 'whitening_start', threshold=threshold, rank=int(selected.size))
|
|
143
|
+
y = whitener @ prepared.centered
|
|
144
|
+
row_sd_before = y.std(axis=1, ddof=1)
|
|
145
|
+
rescaled = threshold < 1e-10 and selected.size < prepared.centered.shape[0]
|
|
146
|
+
if rescaled:
|
|
147
|
+
if np.any(row_sd_before <= 0) or not np.isfinite(row_sd_before).all():
|
|
148
|
+
raise FloatingPointError('Whitened dimension has invalid sample SD')
|
|
149
|
+
y /= row_sd_before[:, None]
|
|
150
|
+
if not np.isfinite(y).all():
|
|
151
|
+
raise FloatingPointError('Whitening produced nonfinite values')
|
|
152
|
+
row_sd_after = y.std(axis=1, ddof=1)
|
|
153
|
+
metadata = dict(
|
|
154
|
+
threshold=threshold, rank=int(selected.size),
|
|
155
|
+
retained_eigenvalue_min=float(values[-1]),
|
|
156
|
+
retained_eigenvalue_max=float(values[0]),
|
|
157
|
+
retained_smallest_eigenvalues=values[-min(16, len(values)):].tolist(),
|
|
158
|
+
conditional_sample_sd_rescaling=bool(rescaled), sample_sd_ddof=1,
|
|
159
|
+
row_sd_before_min=float(row_sd_before.min()),
|
|
160
|
+
row_sd_before_max=float(row_sd_before.max()),
|
|
161
|
+
row_sd_after_min=float(row_sd_after.min()),
|
|
162
|
+
row_sd_after_max=float(row_sd_after.max()),
|
|
163
|
+
max_abs_row_mean=float(np.max(np.abs(y.mean(axis=1)))))
|
|
164
|
+
result = WhitenedData(y, threshold, values, metadata)
|
|
165
|
+
if cache:
|
|
166
|
+
prepared.whitened_cache[threshold] = result
|
|
167
|
+
_emit(callback, 'whitening_complete', **metadata)
|
|
168
|
+
return result
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _svd_coefficients(y, references, cache, callback):
|
|
172
|
+
factors = cache.get('svd') if cache is not None else None
|
|
173
|
+
if factors is None:
|
|
174
|
+
_emit(callback, 'pinv_svd_start', shape=list(y.shape))
|
|
175
|
+
u, singular, vh = linalg.svd(y, full_matrices=False,
|
|
176
|
+
check_finite=False, lapack_driver='gesdd')
|
|
177
|
+
# MATLAB pinv: tol=max(size(Y))*eps(norm(Y)); norm(Y) is its largest
|
|
178
|
+
# singular value, and eps(x) is the local floating-point spacing.
|
|
179
|
+
tolerance = float(max(y.shape) * np.spacing(singular[0]))
|
|
180
|
+
keep = singular > tolerance
|
|
181
|
+
if not keep.any():
|
|
182
|
+
raise FloatingPointError('MATLAB pinv tolerance retained no singular values')
|
|
183
|
+
factors = (u, singular, vh, keep, tolerance)
|
|
184
|
+
if cache is not None:
|
|
185
|
+
cache['svd'] = factors
|
|
186
|
+
_emit(callback, 'pinv_svd_complete', retained_rank=int(keep.sum()),
|
|
187
|
+
matlab_absolute_tolerance=tolerance)
|
|
188
|
+
u, singular, vh, keep, tolerance = factors
|
|
189
|
+
# pinv(Y).T @ R.T = U @ diag(1/s) @ Vh @ R.T. This computes its action
|
|
190
|
+
# on only K reference vectors, never materializing the V-by-time pinv.
|
|
191
|
+
projected = vh[keep] @ references.T
|
|
192
|
+
coefficients = (u[:, keep] / singular[keep]) @ projected
|
|
193
|
+
return coefficients, dict(
|
|
194
|
+
requested_method='svd', resolved_method='svd',
|
|
195
|
+
matlab_absolute_tolerance=tolerance, retained_rank=int(keep.sum()),
|
|
196
|
+
largest_singular_value=float(singular[0]),
|
|
197
|
+
smallest_retained_singular_value=float(singular[keep][-1]))
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def matlab_pinv_coefficients(y, references, *, pinv_method='svd', cache=None,
|
|
201
|
+
callback: Callback = None):
|
|
202
|
+
"""Return pinv(Y).T @ R.T and diagnostics, using MATLAB's cutoff.
|
|
203
|
+
|
|
204
|
+
The optional Gram route solves (Y Y')c=Y R'. It is equivalent when Y has
|
|
205
|
+
full row rank and no singular values are discarded. Since forming a Gram
|
|
206
|
+
matrix squares its condition number, ill-conditioned cases use SVD instead.
|
|
207
|
+
"""
|
|
208
|
+
if np.iscomplexobj(y) or np.iscomplexobj(references):
|
|
209
|
+
raise ValueError('Y and reference must be real-valued')
|
|
210
|
+
y = np.asarray(y, dtype=np.float64)
|
|
211
|
+
references = np.asarray(references, dtype=np.float64)
|
|
212
|
+
if (y.ndim != 2 or references.ndim != 2 or y.shape[1] != references.shape[1]
|
|
213
|
+
or not np.isfinite(y).all() or not np.isfinite(references).all()):
|
|
214
|
+
raise ValueError('Expected finite Y [dimension, voxel] and R [component, voxel]')
|
|
215
|
+
if pinv_method == 'svd':
|
|
216
|
+
return _svd_coefficients(y, references, cache, callback)
|
|
217
|
+
if pinv_method != 'gram':
|
|
218
|
+
raise ValueError('pinv_method must be svd or gram')
|
|
219
|
+
factors = cache.get('gram') if cache is not None else None
|
|
220
|
+
if factors is None:
|
|
221
|
+
gram = y @ y.T
|
|
222
|
+
eigenvalues = linalg.eigvalsh(gram, check_finite=False, driver='evd')
|
|
223
|
+
condition = (float(eigenvalues[-1] / eigenvalues[0])
|
|
224
|
+
if eigenvalues[0] > 0 else float('inf'))
|
|
225
|
+
largest_singular = float(np.sqrt(max(0., eigenvalues[-1])))
|
|
226
|
+
tolerance = float(max(y.shape) * np.spacing(largest_singular))
|
|
227
|
+
full_rank = bool(eigenvalues[0] > tolerance ** 2)
|
|
228
|
+
factors = (gram, condition, full_rank, tolerance, largest_singular,
|
|
229
|
+
float(np.sqrt(max(0., eigenvalues[0]))))
|
|
230
|
+
if cache is not None:
|
|
231
|
+
cache['gram'] = factors
|
|
232
|
+
gram, condition, full_rank, tolerance, largest_singular, smallest = factors
|
|
233
|
+
if not full_rank or condition > 1e6:
|
|
234
|
+
result, metadata = _svd_coefficients(y, references, cache, callback)
|
|
235
|
+
metadata.update(requested_method='gram', gram_condition_number=condition,
|
|
236
|
+
fallback_reason='Gram not demonstrably well-conditioned and full row rank')
|
|
237
|
+
return result, metadata
|
|
238
|
+
result = linalg.solve(gram, y @ references.T, assume_a='pos', check_finite=False)
|
|
239
|
+
return result, dict(requested_method='gram', resolved_method='gram',
|
|
240
|
+
gram_condition_number=condition,
|
|
241
|
+
matlab_absolute_tolerance=tolerance, retained_rank=y.shape[0],
|
|
242
|
+
largest_singular_value=largest_singular,
|
|
243
|
+
smallest_retained_singular_value=smallest)
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def _fit_components(y, normalized_reference, reference_s, callback):
|
|
247
|
+
n_voxels = y.shape[1]
|
|
248
|
+
sim_gradient = (y @ normalized_reference.T) / n_voxels
|
|
249
|
+
weights = np.empty((y.shape[0], normalized_reference.shape[0]), dtype=np.float64)
|
|
250
|
+
records = []
|
|
251
|
+
for k, reference in enumerate(normalized_reference):
|
|
252
|
+
_emit(callback, 'component_start', component=k + 1)
|
|
253
|
+
wc = reference_s[:, k].copy()
|
|
254
|
+
y1 = wc @ y
|
|
255
|
+
initial_similarity = float((y1 @ reference) / n_voxels)
|
|
256
|
+
initial_negentropy = _nege(y1)
|
|
257
|
+
c = np.tan(initial_similarity * np.pi / 2) / initial_negentropy
|
|
258
|
+
objective = float(.5 * (2 / np.pi) * np.arctan(c * initial_negentropy)
|
|
259
|
+
+ .5 * initial_similarity)
|
|
260
|
+
accepted_counter = 1
|
|
261
|
+
accepted_proposals = 0
|
|
262
|
+
step = 1.
|
|
263
|
+
last_accepted = False
|
|
264
|
+
stop_reason = 'attempt_limit'
|
|
265
|
+
for attempt in range(1, MAX_ATTEMPTS + 1):
|
|
266
|
+
with np.errstate(over='raise', invalid='raise'):
|
|
267
|
+
expectation = float(np.mean(np.log(np.cosh(y1))))
|
|
268
|
+
negama = expectation - GAUSSIAN_EXPECTATION
|
|
269
|
+
jy1 = negama ** 2
|
|
270
|
+
derivative = (2 / np.pi) * c / (1 + (c * jy1) ** 2)
|
|
271
|
+
eygy = (y @ np.tanh(y1)) / n_voxels
|
|
272
|
+
gradient = .5 * derivative * 2 * negama * eygy + .5 * sim_gradient[:, k]
|
|
273
|
+
gradient_norm = float(np.sqrt(gradient @ gradient))
|
|
274
|
+
if gradient_norm == 0 or not np.isfinite(gradient_norm):
|
|
275
|
+
raise FloatingPointError('Official GIG update has zero/nonfinite gradient')
|
|
276
|
+
direction = gradient / gradient_norm
|
|
277
|
+
wx = wc + step * direction
|
|
278
|
+
wx /= np.linalg.norm(wx)
|
|
279
|
+
y3 = wx @ y
|
|
280
|
+
proposed_objective = float(.5 * (2 / np.pi) * np.arctan(c * _nege(y3))
|
|
281
|
+
+ .5 * ((y3 @ reference) / n_voxels))
|
|
282
|
+
change = proposed_objective - objective
|
|
283
|
+
armijo_threshold = step * .02 * float(gradient @ direction)
|
|
284
|
+
last_accepted = bool(change >= armijo_threshold)
|
|
285
|
+
if not last_accepted:
|
|
286
|
+
step /= 2
|
|
287
|
+
continue
|
|
288
|
+
accepted_proposals += 1
|
|
289
|
+
change_squared = float((wc - wx) @ (wc - wx))
|
|
290
|
+
if change_squared < WEIGHT_CHANGE_SQUARED_TOLERANCE:
|
|
291
|
+
stop_reason = 'weight_change_squared'
|
|
292
|
+
break
|
|
293
|
+
if accepted_counter == MAX_ATTEMPTS:
|
|
294
|
+
stop_reason = 'accepted_counter_limit'
|
|
295
|
+
break
|
|
296
|
+
objective = proposed_objective
|
|
297
|
+
y1 = y3
|
|
298
|
+
wc = wx
|
|
299
|
+
accepted_counter += 1
|
|
300
|
+
# Important source behavior: even a last rejected candidate is stored.
|
|
301
|
+
# Do not silently return wc, add orthogonalization, or flip its sign.
|
|
302
|
+
weights[:, k] = wx
|
|
303
|
+
record = dict(component=k + 1, attempts=attempt,
|
|
304
|
+
accepted_proposals=accepted_proposals,
|
|
305
|
+
source_accepted_counter=accepted_counter,
|
|
306
|
+
stop_reason=stop_reason, final_candidate_accepted=last_accepted,
|
|
307
|
+
final_step=step, initial_similarity=initial_similarity,
|
|
308
|
+
initial_negentropy=initial_negentropy,
|
|
309
|
+
initial_c=float(c), final_candidate_objective=proposed_objective)
|
|
310
|
+
records.append(record)
|
|
311
|
+
_emit(callback, 'component_complete', **record)
|
|
312
|
+
return weights, records
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
def fit_at_threshold(prepared: PreparedData, reference, threshold: float, *,
|
|
316
|
+
pinv_method='svd', callback: Callback = None):
|
|
317
|
+
"""Run one original threshold attempt; intended also for stagewise tests."""
|
|
318
|
+
started = time.perf_counter()
|
|
319
|
+
if np.iscomplexobj(reference):
|
|
320
|
+
raise ValueError('reference must be real-valued')
|
|
321
|
+
reference = np.asarray(reference, dtype=np.float64)
|
|
322
|
+
if (reference.ndim != 2 or reference.shape[0] < 1
|
|
323
|
+
or reference.shape[1] != prepared.centered.shape[1]
|
|
324
|
+
or not np.isfinite(reference).all()):
|
|
325
|
+
raise ValueError('reference must be finite [component, voxel] on the data grid')
|
|
326
|
+
centered_reference = reference - reference.mean(axis=1, keepdims=True)
|
|
327
|
+
reference_sd = centered_reference.std(axis=1, ddof=1)
|
|
328
|
+
if np.any(reference_sd <= 0):
|
|
329
|
+
raise ValueError('Each reference requires positive spatial sample SD')
|
|
330
|
+
normalized_reference = centered_reference / reference_sd[:, None]
|
|
331
|
+
whitened = whiten(prepared, threshold, callback=callback)
|
|
332
|
+
coefficients, pinv_metadata = matlab_pinv_coefficients(
|
|
333
|
+
whitened.y, normalized_reference, pinv_method=pinv_method,
|
|
334
|
+
cache=whitened.pinv_cache, callback=callback)
|
|
335
|
+
norms = np.sqrt(np.sum(coefficients ** 2, axis=0))
|
|
336
|
+
if np.any(norms == 0) or not np.isfinite(norms).all():
|
|
337
|
+
raise FloatingPointError('A reference has zero/nonfinite projection in whitened data')
|
|
338
|
+
coefficients /= norms
|
|
339
|
+
weights, component_records = _fit_components(
|
|
340
|
+
whitened.y, normalized_reference, coefficients, callback)
|
|
341
|
+
components = (weights.T @ whitened.y).T
|
|
342
|
+
# Restore spatial means in bounded row blocks, matching FmriMatr+meanDat
|
|
343
|
+
# without allocating another full time-by-voxel array.
|
|
344
|
+
timecourses = np.empty((prepared.centered.shape[0], reference.shape[0]), dtype=np.float64)
|
|
345
|
+
for start in range(0, len(timecourses), 128):
|
|
346
|
+
stop = min(start + 128, len(timecourses))
|
|
347
|
+
block = prepared.centered[start:stop] + prepared.spatial_means[start:stop, None]
|
|
348
|
+
block /= prepared.centered.shape[1]
|
|
349
|
+
timecourses[start:stop] = block @ components
|
|
350
|
+
if not np.isfinite(components).all() or not np.isfinite(timecourses).all():
|
|
351
|
+
raise FloatingPointError('GIG produced nonfinite output')
|
|
352
|
+
component_sd = components.std(axis=0, ddof=1)
|
|
353
|
+
sd_error = float(np.linalg.norm(1 - component_sd))
|
|
354
|
+
metadata = dict(
|
|
355
|
+
whitening=whitened.metadata, pinv=pinv_metadata,
|
|
356
|
+
threshold=float(threshold), rank=whitened.metadata['rank'],
|
|
357
|
+
n_components=reference.shape[0], sample_sd_ddof=1,
|
|
358
|
+
max_iteration_attempts=MAX_ATTEMPTS,
|
|
359
|
+
weight_change_squared_tolerance=WEIGHT_CHANGE_SQUARED_TOLERANCE,
|
|
360
|
+
gaussian_expectation=GAUSSIAN_EXPECTATION,
|
|
361
|
+
objective_weights=[.5, .5], reference_normalization='spatial_mean_and_sample_SD',
|
|
362
|
+
component_sample_sd=component_sd.tolist(), unit_sd_error=sd_error,
|
|
363
|
+
unit_sd_passed=bool(sd_error <= UNIT_SD_TOLERANCE),
|
|
364
|
+
component_optimization=component_records,
|
|
365
|
+
elapsed_seconds=time.perf_counter() - started,
|
|
366
|
+
matrix_product_scalars_applied_after_reduction=True)
|
|
367
|
+
_emit(callback, 'threshold_complete', threshold=float(threshold),
|
|
368
|
+
rank=whitened.metadata['rank'], unit_sd_error=sd_error)
|
|
369
|
+
return dict(components=components, timecourses=timecourses, metadata=metadata)
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
def fit_prepared(prepared: PreparedData, reference, *, pinv_method='svd',
|
|
373
|
+
callback: Callback = None):
|
|
374
|
+
"""Use the original eps(double), then 0.02 fallback based on output SD."""
|
|
375
|
+
attempts = []
|
|
376
|
+
for threshold in (FIRST_THRESHOLD, FALLBACK_THRESHOLD):
|
|
377
|
+
_emit(callback, 'threshold_start', threshold=threshold)
|
|
378
|
+
result = fit_at_threshold(prepared, reference, threshold,
|
|
379
|
+
pinv_method=pinv_method, callback=callback)
|
|
380
|
+
attempts.append(result['metadata'])
|
|
381
|
+
if result['metadata']['unit_sd_error'] <= UNIT_SD_TOLERANCE:
|
|
382
|
+
break
|
|
383
|
+
if threshold == FIRST_THRESHOLD:
|
|
384
|
+
_emit(callback, 'unit_sd_fallback', next_threshold=FALLBACK_THRESHOLD)
|
|
385
|
+
# As in the source, the second attempt is returned even if SD tolerance
|
|
386
|
+
# still fails. Its diagnostic remains explicit; there is no extra retry.
|
|
387
|
+
result['metadata'] = dict(
|
|
388
|
+
implementation='independent_numpy_scipy_classic_GIG_ICA_translation',
|
|
389
|
+
source_name=SOURCE_NAME, source_sha256=SOURCE_SHA256,
|
|
390
|
+
preparation=prepared.metadata, threshold_attempts=attempts,
|
|
391
|
+
selected_threshold=threshold, fallback_used=len(attempts) > 1,
|
|
392
|
+
pinv_method=pinv_method, final_unit_sd_passed=result['metadata']['unit_sd_passed'],
|
|
393
|
+
input_modified=False, output_dtype='float64', matlab_invoked=False,
|
|
394
|
+
independent_component_optimization=True,
|
|
395
|
+
joint_orthogonality_constraint_added=False,
|
|
396
|
+
**result['metadata'])
|
|
397
|
+
return result
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def fit_gig_ica(data, reference, *, pinv_method='svd', eigen_driver='evd',
|
|
401
|
+
callback: Callback = None):
|
|
402
|
+
"""Fit classic GIG-ICA with no external MATLAB dependency.
|
|
403
|
+
|
|
404
|
+
``callback`` receives one JSON-compatible dictionary for each stage or
|
|
405
|
+
component. The default SVD route is the faithful reference implementation;
|
|
406
|
+
the optional Gram route must be independently compared before production.
|
|
407
|
+
"""
|
|
408
|
+
started = time.perf_counter()
|
|
409
|
+
prepared = prepare(data, eigen_driver=eigen_driver, callback=callback)
|
|
410
|
+
result = fit_prepared(prepared, reference, pinv_method=pinv_method, callback=callback)
|
|
411
|
+
result['metadata']['total_elapsed_seconds'] = time.perf_counter() - started
|
|
412
|
+
return result
|