bootstrap¶
Bootstrap functions extracted from BrainData methods.
Methods:
| Name | Description |
|---|---|
bootstrap | Bootstrap statistics with CPU parallelization or GPU acceleration. |
convert_bootstrap_results_to_brain_data | Convert bootstrap results dictionary to BrainData format. |
Methods¶
bootstrap¶
bootstrap(bd, stat, *, n_samples = 5000, save_boots = False, percentiles = (2.5, 97.5), X_test = None, device = 'cpu', max_gpu_memory_gb = None, tail = 2, n_jobs = -1, random_state = None, progress_bar = False)Bootstrap statistics with CPU parallelization or GPU acceleration.
Supports simple aggregation statistics and fitted model statistics (Ridge).
Note: the CPU path pre-generates all resample indices and collects every
per-sample result, so peak memory grows with n_samples (it is not a
streaming/online accumulator).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bd | BrainData instance. | required | |
stat | (str) Statistic to bootstrap. Options: Simple stats (‘mean’, ‘median’, ‘std’, ‘sum’, ‘min’, ‘max’) or Model stats (‘weights’ requires fitted Ridge model, ‘predict’ requires fitted Ridge model + X_test). | required | |
n_samples | (int) Number of bootstrap iterations. Default: 5000 | 5000 | |
save_boots | (bool) If True, store all bootstrap samples (memory intensive). Default: False | False | |
percentiles | (tuple) Percentiles for confidence intervals. Default: (2.5, 97.5) | (2.5, 97.5) | |
X_test | (np.ndarray, optional) Test features for ‘predict’ bootstrap. Required if stat=‘predict’ | None | |
device | (str) Compute device for Ridge bootstrap: ‘cpu’ (default), ‘gpu’ (PyTorch on CUDA/MPS if available), or ‘auto’ (use a GPU if present, else CPU). Ignored for simple stats. Default: ‘cpu’ | ‘cpu’ | |
max_gpu_memory_gb | (float, optional) Explicit GPU memory budget in GB when device is ‘gpu’ or ‘auto’. None (default) measures the device. | None | |
tail | 2 | ‘two’ (two-tailed, default) or 1 | |
n_jobs | (int) Number of CPU cores for parallelization. Default: -1 (all CPUs). | -1 | |
random_state | (int, optional) Random seed for reproducibility | None | |
progress_bar | (bool) If True, show a progress bar. Default: False | False |
Returns:
| Type | Description |
|---|---|
BrainData or dict: - For simple stats (with save_boots=False): Returns BrainData with bootstrap mean - For model stats: Returns dict with keys: ‘mean’, ‘std’, ‘Z’, ‘p’, ‘ci_lower’, ‘ci_upper’ (all BrainData objects) - If save_boots=True: Returns a dict (even for simple stats) with an added ‘samples’ key holding all samples as a raw ndarray |
Examples:
>>> # Simple aggregation
>>> boot = brain.bootstrap(stat='mean', n_samples=1000)
>>> assert isinstance(boot, BrainData)>>> # Ridge weights bootstrap (CPU)
>>> brain.fit(X=dm, model='ridge', alpha=1.0)
>>> boot = brain.bootstrap(stat='weights', n_samples=1000)
>>> assert 'mean' in boot
>>> assert isinstance(boot['mean'], BrainData)>>> # Ridge weights bootstrap (GPU accelerated)
>>> brain.fit(X=dm, model='ridge', alpha=1.0)
>>> boot = brain.bootstrap(stat='weights', n_samples=1000, device='gpu')
>>> assert 'mean' in boot
>>> assert isinstance(boot['mean'], BrainData)>>> # Ridge predict bootstrap
>>> brain.fit(X=dm, model='ridge', alpha=1.0)
>>> boot = brain.bootstrap(stat='predict', X_test=X_new, n_samples=1000)
>>> assert 'mean' in boot
>>> assert isinstance(boot['mean'], BrainData)Note
This method replaces the removed summarize_bootstrap() function.
New API:
Option 1: Use BrainData.bootstrap() for generating bootstrap samples¶
boot = brain.bootstrap(stat=‘mean’, n_samples=1000, save_boots=False)
Returns BrainData with bootstrap mean¶
To get Z and p, use stat=‘weights’ or ‘predict’ which returns dict¶
Option 2: For existing bootstrap samples (BrainData with multiple images),¶
use OnlineBootstrapStats directly:¶
from nltools.algorithms.inference.bootstrap import OnlineBootstrapStats stats = OnlineBootstrapStats(shape=(brain.shape[1],), save_samples=False) for sample in bootstrap_samples: # Iterate over samples ... stats.update(sample.data) result = stats.get_results()
Returns: {‘mean’: array, ‘std’: array, ‘Z’: array, ‘p’: array,¶
‘ci_lower’: array, ‘ci_upper’: array}¶
Convert to BrainData if needed:¶
mean_brain = shallow_copy(brain) mean_brain.data = result[‘mean’]
convert_bootstrap_results_to_brain_data¶
convert_bootstrap_results_to_brain_data(bd, result, save_boots = False, return_dict = False)Convert bootstrap results dictionary to BrainData format.
Helper method to convert numpy arrays from bootstrap functions into BrainData objects or dicts of BrainData objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bd | BrainData instance. | required | |
result | (dict) Result dictionary from bootstrap function with keys: ‘mean’, ‘std’, ‘Z’, ‘p’, ‘ci_lower’, ‘ci_upper’, and optionally ‘samples’ | required | |
save_boots | (bool) If True, include ‘samples’ key in output | False | |
return_dict | (bool) If True, always return dict even for simple stats. If False, return BrainData for simple stats (when save_boots=False) | False |
Returns:
| Type | Description |
|---|---|
| BrainData or dict: - If return_dict=False and save_boots=False: Returns BrainData with mean - Otherwise: Returns dict with BrainData objects for each statistic. The optional ‘samples’ entry (when save_boots=True) is a raw ndarray, not a BrainData. |