nimare.dataset.Dataset
- class Dataset(source, target='mni152_2mm', mask=None)[source]
Bases:
NiMAREBaseStorage container for a coordinate- and/or image-based meta-analytic dataset/database.
Changed in version 0.0.9:
[ENH] Add merge method to Dataset class
Changed in version 0.0.8:
[FIX] Set
nimare.dataset.Dataset.basepathinupdate_path()using absolute path.
- Parameters:
source (
strordict) – JSON file containing dictionary with database information or the dict() objecttarget (
str, optional) – Desired coordinate space for coordinates. Names follow NIDM convention. Default is ‘mni152_2mm’ (MNI space with 2x2x2 voxels). This parameter has no impact on images.mask (
str,Nifti1Image,NiftiMaskeror similar, or None, optional) – Mask(er) to use. If None, uses the target space image, with all non-zero voxels included in the mask.
- Variables:
space (
str) – Standard space. Same astargetparameter.
Notes
Images loaded into a Dataset are assumed to be in the same space. If images have different resolutions or affines from the Dataset’s masker, then they will be resampled automatically, at the point where they’re used, by
Dataset.masker.Methods
copy()Create a copy of the Dataset.
get(dict_[, drop_invalid])Retrieve files and/or metadata from the current Dataset.
get_images([ids, imtype])Get images of a certain type for a subset of studies in the dataset.
get_labels([ids])Extract list of labels for which studies in Dataset have annotations.
get_metadata([ids, field])Get metadata from Dataset.
get_params([deep])Get parameters for this estimator.
get_studies_by_coordinate(xyz[, r])Extract list of studies with at least one focus within radius of requested coordinates.
get_studies_by_label([labels, label_threshold])Extract list of studies with a given label.
get_studies_by_mask(mask)Extract list of studies with at least one coordinate in mask.
get_texts([ids, text_type])Extract list of texts of a given type for selected IDs.
load(filename[, compressed])Load a pickled class instance from file.
merge(right)Merge two Datasets.
save(filename[, compress])Pickle the class instance to the provided file.
set_params(**params)Set the parameters of this estimator.
slice(ids)Create a new dataset with only requested IDs.
update_path(new_path)Update paths to images.
Properties
Labels describing studies in the dataset.
Coordinates in the dataset.
1D array of identifiers in Dataset.
Images in the dataset.
Masker object.
Metadata describing studies in the dataset.
Texts in the dataset.
- property annotations
Labels describing studies in the dataset.
Each study/experiment has its own row. Columns correspond to individual labels (e.g., ‘emotion’), and may be prefixed with a feature group including two underscores (e.g., ‘Neurosynth_TFIDF__emotion’).
- Type:
- property coordinates
Coordinates in the dataset.
Changed in version 0.0.10: The coordinates attribute no longer includes the associated matrix indices (columns ‘i’, ‘j’, and ‘k’). These columns are calculated as needed.
Each study has one row for each peak. Columns include [‘x’, ‘y’, ‘z’] (peak locations in mm) and ‘space’ (Dataset’s space).
- Type:
- get(dict_, drop_invalid=True)[source]
Retrieve files and/or metadata from the current Dataset.
- Parameters:
dict (
dict) – Dictionary specifying images or metadata to collect. Keys should be variables to be used as keys for results dictionary. Values should be tuples with two values: type (e.g., ‘image’ or ‘metadata’) and specific field corresponding to column of type-specific DataFrame (e.g., ‘z’ or ‘sample_sizes’).drop_invalid (
bool, optional) – Whether to automatically ignore any studies without the required data or not. Default is False.
- Returns:
results – A dictionary of lists of requested data. Keys correspond to the keys in
dict_.- Return type:
Examples
>>> dset.get({'z_maps': ('image', 'z'), 'sample_sizes': ('metadata', 'sample_sizes')}) >>> dset.get({'coordinates': ('coordinates', None)})
- get_images(ids=None, imtype=None)[source]
Get images of a certain type for a subset of studies in the dataset.
- Parameters:
- Returns:
images – List of images of requested type for selected IDs.
- Return type:
- get_metadata(ids=None, field=None)[source]
Get metadata from Dataset.
- Parameters:
- Returns:
metadata – List of values of requested type for selected IDs.
- Return type:
- get_studies_by_coordinate(xyz, r=20)[source]
Extract list of studies with at least one focus within radius of requested coordinates.
- Parameters:
xyz ((X x 3) array_like) – List of coordinates against which to find studies.
r (
float, optional) – Radius (in mm) within which to find studies. Default is 20mm.
- Returns:
found_ids – A list of IDs from the Dataset with at least one focus within radius r of requested coordinates.
- Return type:
- get_studies_by_label(labels=None, label_threshold=0.001)[source]
Extract list of studies with a given label.
Changed in version 0.0.10: Fix bug in which all IDs were returned when a label wasn’t present in the Dataset.
Changed in version 0.0.9: Default value for label_threshold changed to 0.001.
- Parameters:
- Returns:
found_ids – A list of IDs from the Dataset found by the search criteria.
- Return type:
- get_studies_by_mask(mask)[source]
Extract list of studies with at least one coordinate in mask.
- Parameters:
mask (img_like) – Mask across which to search for coordinates.
- Returns:
found_ids – A list of IDs from the Dataset with at least one focus in the mask.
- Return type:
- get_texts(ids=None, text_type=None)[source]
Extract list of texts of a given type for selected IDs.
- Parameters:
- Returns:
texts – List of texts of requested type for selected IDs.
- Return type:
- property ids
1D array of identifiers in Dataset.
The associated setter for this property is private, as
Dataset.idsis immutable.- Type:
- property images
Images in the dataset.
Each image type has its own column (e.g., ‘z’) with absolute paths to files and each study has its own row. Additionally, relative paths to image files are stored in columns with the suffix ‘__relative’ (e.g., ‘z__relative’).
Warning
Images are assumed to be in the same space, although they may have different resolutions and affines. Images will be resampled as needed at the point where they are used, via
Dataset.masker.- Type:
- classmethod load(filename, compressed=True)[source]
Load a pickled class instance from file.
- Parameters:
- Returns:
obj – Loaded class object.
- Return type:
class object
- property masker
Masker object.
Defines the space and location of the area of interest (e.g., ‘brain’).
- Type:
nilearn.input_data.NiftiMaskeror similar
- property metadata
Metadata describing studies in the dataset.
Each metadata field has its own column (e.g., ‘sample_sizes’) and each study has its own row.
- Type:
- set_params(**params)[source]
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as pipelines). The latter have parameters of the form
<component>__<parameter>so that it’s possible to update each component of a nested object.- Return type:
self
- slice(ids)[source]
Create a new dataset with only requested IDs.
- Parameters:
ids (array_like) – List of study IDs to include in new dataset
- Returns:
new_dset – Reduced Dataset containing only requested studies.
- Return type:
- property texts
Texts in the dataset.
Each text type has its own column (e.g., ‘abstract’) and each study has its own row.
- Type:
Examples using nimare.dataset.Dataset
Run a coordinate-based meta-analysis (CBMA) workflow
