cache¶
Disk-based caching infrastructure for expensive computations.
This module provides a general-purpose caching system for nltools, designed to be reused across various computationally expensive operations like searchlight neighborhoods, ISC, and SRM.
Example
from nltools.data.braindata.cache import CacheManager, hash_mask import nibabel as nib
Hash a mask for cache key generation¶
mask = nib.load(“mask.nii.gz”) mask_hash = hash_mask(mask)
Use cache manager for searchlight neighborhoods¶
cache = CacheManager(“searchlight”) if not cache.exists(f"{mask_hash}_10mm"): ... # Compute expensive operation ... result = compute_something() ... cache.save(f"{mask_hash}_10mm", data=result) else: ... result = cache.load(f"{mask_hash}_10mm")[“data”]
Classes:
| Name | Description |
|---|---|
CacheManager | Manages disk-based caching for expensive computations. |
Methods:
| Name | Description |
|---|---|
clear_cache | Clear the nltools cache. |
get_cache_dir | Get the nltools cache directory. |
hash_mask | Compute a stable hash for a NIfTI mask image. |
Classes¶
CacheManager¶
CacheManager(category: str = 'general')Manages disk-based caching for expensive computations.
CacheManager provides a simple key-value interface for caching numpy arrays to disk. It organizes cached files by category (e.g., “searchlight”, “isc”) in separate subdirectories.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category | str | Category name for organizing cached files (e.g., “searchlight”) | ‘general’ |
Example
cache = CacheManager(“searchlight”)
Check if something is cached¶
if cache.exists(“mykey”): ... data = cache.load(“mykey”) ... else: ... result = expensive_computation() ... cache.save(“mykey”, adjacency=result, metadata=metadata) ... data = {“adjacency”: result, “metadata”: metadata}
Attributes:
| Name | Type | Description |
|---|---|---|
cache_dir | ||
category |
Methods:
| Name | Description |
|---|---|
clear | Clear all cached files in this category. |
delete | Delete a cached file. |
exists | Check if a cache key exists. |
get_path | Get the file path for a cache key. |
list_keys | List all cached keys in this category. |
load | Load cached data. |
save | Save arrays to cache. |
Methods¶
clear¶
clear() -> intClear all cached files in this category.
Returns:
| Type | Description |
|---|---|
int | Number of files deleted |
delete¶
delete(key: str, ext: str = '.npz') -> boolDelete a cached file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Cache key | required |
ext | str | File extension | ‘.npz’ |
Returns:
| Type | Description |
|---|---|
bool | True if file was deleted, False if it didn’t exist |
exists¶
exists(key: str, ext: str = '.npz') -> boolCheck if a cache key exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Cache key | required |
ext | str | File extension (default: “.npz”) | ‘.npz’ |
Returns:
| Type | Description |
|---|---|
bool | True if cached file exists |
get_path¶
get_path(key: str, ext: str = '.npz') -> PathGet the file path for a cache key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Cache key | required |
ext | str | File extension (default: “.npz”) | ‘.npz’ |
Returns:
| Type | Description |
|---|---|
Path | Path to the cache file |
list_keys¶
list_keys(ext: str = '.npz') -> list[str]List all cached keys in this category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ext | str | File extension to match | ‘.npz’ |
Returns:
| Type | Description |
|---|---|
list [ str ] | List of cache keys (without extension) |
load¶
load(key: str) -> dict | NoneLoad cached data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Cache key | required |
Returns:
| Type | Description |
|---|---|
dict | None | Dictionary of cached arrays, or None if not cached |
save¶
save(key: str, compressed: bool = True, **arrays: bool) -> PathSave arrays to cache.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key | str | Cache key | required |
compressed | bool | If True, use compressed npz format (smaller but slower) | True |
**arrays | Named arrays to cache | {} |
Returns:
| Type | Description |
|---|---|
Path | Path to saved cache file |
Methods¶
clear_cache¶
clear_cache(category: str | None = None) -> intClear the nltools cache.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category | str | None | If provided, only clear this category. Otherwise clear all. | None |
Returns:
| Type | Description |
|---|---|
int | Number of files deleted |
get_cache_dir¶
get_cache_dir() -> PathGet the nltools cache directory.
Returns ~/.nltools/cache, creating it if necessary.
Returns:
| Type | Description |
|---|---|
Path | Path to cache directory |
hash_mask¶
hash_mask(mask_img: Nifti1Image) -> strCompute a stable hash for a NIfTI mask image.
The hash is based on the mask’s shape, affine transformation, and the actual voxel positions. This ensures that masks with the same shape but different voxel locations (or different affines) produce different hashes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mask_img | Nifti1Image | NIfTI image to hash (typically a binary mask) | required |
Returns:
| Type | Description |
|---|---|
str | 16-character hexadecimal hash string |
Example
import nibabel as nib mask = nib.load(“mask.nii.gz”) hash_mask(mask) ‘a1b2c3d4e5f60789’