nimare.dataset.Dataset

class Dataset(source, target='mni152_2mm', mask=None)[source]

Storage container for a coordinate- and/or image-based meta-analytic dataset/database.

Parameters
  • source (str) – JSON file containing dictionary with database information or the dict() object

  • target (str) – Desired coordinate space for coordinates. Names follow NIDM convention.

  • mask (str, Nifti1Image, or any nilearn Masker) – Mask(er) to use. If None, uses the target space image, with all non-zero voxels included in the mask.

Variables
  • ids (1D array_like) – A list of identifiers for all studies in the Dataset.

  • masker (nilearn.input_data.NiftiMasker or similar) – Masker object defining the space and location of the area of interest (e.g., ‘brain’).

  • space (str) – Standard space. Same as target parameter.

  • annotations (pandas.DataFrame) – DataFrame with labels describing studies in the dataset.

  • metadata (pandas.DataFrame) – DataFrame with metadata describing studies in the Dataset.

  • texts (pandas.DataFrame) – DataFrame with texts associated with studies in the Dataset.

  • images (pandas.DataFrame) – DataFrame with paths to statistical images for studies in the Dataset.

  • coordinates (pandas.DataFrame) – DataFrame with suprathreshold peak coordinates from studies in the Dataset.

get(dict_)[source]

Retrieve files and/or metadata from the current Dataset.

Parameters

dict_ (dict) – Dictionary specifying images or metadata to collect

Returns

results (dict) – A dictionary of lists of requested data.

get_images(ids=None, imtype=None)[source]

Get images of a certain type for a subset of studies in the dataset.

Parameters
  • ids (list, optional) – A list of IDs in the Dataset for which to find texts. Default is None, in which case all texts of requested type are returned.

  • imtype (str, optional) – Type of image to extract. Corresponds to column name in Dataset.images DataFrame. Default is None.

Returns

images (list) – List of images of requested type for selected IDs.

get_labels(ids=None)[source]

Extract list of labels for which studies in Dataset have annotations.

Parameters

ids (list, optional) – A list of IDs in the Dataset for which to find labels. Default is None, in which case all labels are returned.

Returns

labels (list) – List of labels for which there are annotations in the Dataset.

get_metadata(ids=None, field=None)[source]

Get metadata from Dataset.

Parameters
  • ids (list, optional) – A list of IDs in the Dataset for which to find texts. Default is None, in which case all texts of requested type are returned.

  • field (str, optional) – Metadata field to extract. Corresponds to column name in Dataset.metadata DataFrame. Default is None.

Returns

metadata (list) – List of values of requested type for selected IDs.

get_params(deep=True)[source]

Get parameters for this estimator.

Parameters

deep (boolean, optional) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params (mapping of string to any) – Parameter names mapped to their values.

get_studies_by_coordinate(xyz, r=20)[source]

Extract list of studies with at least one focus within radius r 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 (list) – A list of IDs from the Dataset with at least one focus within radius r of requested coordinates.

get_studies_by_label(labels=None, label_threshold=0.5)[source]

Extract list of studies with a given label.

Parameters
  • labels (list, optional) – List of labels to use to search Dataset. If a contrast has all of the labels above the threshold, it will be returned. Default is None.

  • label_threshold (float, optional) – Default is 0.5.

Returns

found_ids (list) – A list of IDs from the Dataset found by the search criteria.

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 (list) – A list of IDs from the Dataset with at least one focus in the mask.

get_texts(ids=None, text_type=None)[source]

Extract list of texts of a given type for selected IDs.

Parameters
  • ids (list, optional) – A list of IDs in the Dataset for which to find texts. Default is None, in which case all texts of requested type are returned.

  • text_type (str, optional) – Type of text to extract. Corresponds to column name in Dataset.texts DataFrame. Default is None.

Returns

texts (list) – List of texts of requested type for selected IDs.

classmethod load(filename, compressed=True)[source]

Load a pickled class instance from file.

Parameters
  • filename (str) – Name of file containing object.

  • compressed (bool, optional) – If True, the file is assumed to be compressed and gzip will be used to load it. Otherwise, it will assume that the file is not compressed. Default = True.

Returns

obj (class object) – Loaded class object.

save(filename, compress=True)[source]

Pickle the class instance to the provided file.

Parameters
  • filename (str) – File to which object will be saved.

  • compress (bool, optional) – If True, the file will be compressed with gzip. Otherwise, the uncompressed version will be saved. Default = True.

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.

Returns

self

slice(ids)[source]

Return a reduced dataset with only requested IDs.

Parameters

ids (array_like) – List of study IDs to include in new dataset

Returns

new_dset (nimare.dataset.Dataset) – Reduced Dataset containing only requested studies.

update_path(new_path)[source]

Update paths to images. Prepends new path to the relative path for files in Dataset.images.

Parameters

new_path (str) – Path to prepend to relative paths of files in Dataset.images.