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.
@@ -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