coord2region.utils.file_handler#

Utilities for managing atlas files.

This module handles downloading, caching, and loading atlas files used by the mapping utilities. It provides helpers for retrieving label information and packing volumetric atlas outputs.

Attributes#

logger

Classes#

AtlasFileHandler

Handle file operations for atlas fetching.

Functions#

`save_as_pdf`(→ None)	Save pipeline results to a PDF file or directory.
`save_as_csv`(→ None)	Save pipeline results to a CSV file.
`save_batch_folder`(→ None)	Save results as a directory with individual JSON files and images.

Module Contents#

coord2region.utils.file_handler.logger[source]#

class coord2region.utils.file_handler.AtlasFileHandler(data_dir: str | None = None, subjects_dir: str | None = None)[source]#

Handle file operations for atlas fetching.

Parameters:

data_dir (str or None, optional) – Base directory for downloaded atlas files. Defaults to ~/coord2region. Relative paths are interpreted relative to the user’s home directory.
subjects_dir (str or None, optional) – FreeSurfer SUBJECTS_DIR. If None, the value is inferred from mne.get_config().

data_dir[source]#

Base directory where atlas files and other outputs are stored.

Type:: str

cached_data_dir[source]#

Directory for cached datasets.

Type:: str

generated_images_dir[source]#

Directory for generated images.

Type:: str

results_dir[source]#

Directory for exported results.

Type:: str

subjects_dir[source]#

Path to the FreeSurfer subjects directory.

Type:: str or None

nilearn_data[source]#

Directory for caching Nilearn datasets.

Type:: str

mne_data_dir[source]#

Directory registered with MNE for dataset downloads.

Type:: str

Examples

>>> handler = AtlasFileHandler()  
>>> handler.data_dir  
'/home/user/coord2region'

data_dir = ''[source]#

cached_data_dir[source]#

generated_images_dir[source]#

results_dir[source]#

nilearn_data[source]#

mne_data_dir = ''[source]#

subjects_dir[source]#

save(obj, filename: str)[source]#

Save an object to the data directory using pickle.

Parameters:

obj (Any) – The object to serialize.
filename (str) – Name of the file to save the object to.

Raises:

ValueError – If the data directory is not writable.
Exception – If there is an error during saving.

Examples

>>> handler = AtlasFileHandler()
>>> handler.save({'a': 1}, 'example.pkl')  

load(filename: str)[source]#

Load an object from the data directory.

Parameters:: filename (str) – Name of the file to load the object from.
Returns:: The loaded object, or None if the file does not exist.
Return type:: object or None
Raises:: Exception – If there is an error during loading.

Examples

>>> handler = AtlasFileHandler()
>>> handler.load('missing.pkl')  
None

fetch_from_local(atlas_file: str, atlas_dir: str, labels: str | list)[source]#

Load an atlas from a local file.

Parameters:

atlas_file (str) – The name of the atlas file.
atlas_dir (str) – Directory where the atlas file is located.
labels (str or list) – Labels file or a list of label names.

Returns:

Dictionary containing the atlas data.

Return type:

dict

Raises:

FileNotFoundError – If the atlas or labels file is not found.
Exception – If there is an error during loading.

Examples

>>> handler = AtlasFileHandler()
>>> handler.fetch_from_local('atlas.nii.gz', '.', ['A', 'B'])  
{'vol': array(...), 'hdr': array(...), 'labels': ['A', 'B']}

fetch_from_url(atlas_url: str, **kwargs)[source]#

Download an atlas from a URL.

Parameters:

atlas_url (str) – The URL of the atlas file.
**kwargs – Additional arguments for the download.

Returns:

Local path to the downloaded (and possibly decompressed) file.

Return type:

str

Raises:

RuntimeError – If the download fails.
ValueError – If the data directory is not writable.
Exception – If there is an error during downloading.

Examples

>>> handler = AtlasFileHandler()
>>> handler.fetch_from_url('http://example.com/atlas.nii.gz')  
'/path/to/atlas.nii.gz'

coord2region.utils.file_handler.save_as_pdf(results: Sequence[Any], path: str) → None[source]#: Save pipeline results to a PDF file or directory.

coord2region.utils.file_handler.save_as_csv(results: Sequence[Any], path: str) → None[source]#: Save pipeline results to a CSV file.

coord2region.utils.file_handler.save_batch_folder(results: Sequence[Any], path: str) → None[source]#: Save results as a directory with individual JSON files and images.