coord2region.coord2study#

Utilities for mapping coordinates to neuroimaging studies.

This module fetches, converts, and queries NiMARE-compatible datasets (e.g., Neurosynth, NeuroQuery, and NIDM-Pain) and assembles study metadata for coordinates of interest.

Attributes#

logger

Functions#

fetch_datasets(→ dict[str, nimare.dataset.Dataset])

Fetch and convert NiMARE datasets into Dataset objects.

load_deduplicated_dataset(→ nimare.dataset.Dataset | None)

Load a previously saved deduplicated dataset.

deduplicate_datasets(→ nimare.dataset.Dataset | None)

Create a deduplicated dataset across sources using PMIDs.

prepare_datasets(→ nimare.dataset.Dataset | None)

Load or create a deduplicated NiMARE dataset.

remove_duplicate_studies(→ list[dict[str, Any]])

Remove duplicate studies based on PMID.

search_studies(→ list[dict[str, Any]])

Search selected datasets for studies reporting an MNI coordinate.

get_studies_for_coordinate(→ list[dict[str, Any]])

Find studies reporting an MNI coordinate across all datasets.

Module Contents#

coord2region.coord2study.logger[source]#
coord2region.coord2study.fetch_datasets(data_dir: str, sources: list[str] | None = None) → dict[str, nimare.dataset.Dataset][source]#

Fetch and convert NiMARE datasets into Dataset objects.

Parameters:

  • data_dir (str) – Directory to store downloaded data.

  • sources (Optional[List[str]], optional) – List of dataset names to download. Valid entries include "neurosynth", "neuroquery" and "nidm_pain". If None (default), all available datasets are fetched.

Returns:

Dictionary of NiMARE Dataset objects indexed by dataset name.

Return type:

Dict[str, Dataset]

coord2region.coord2study.load_deduplicated_dataset(filepath: str) → nimare.dataset.Dataset | None[source]#

Load a previously saved deduplicated dataset.

Parameters:

filepath (str) – Path to the saved dataset file (.pkl.gz).

Returns:

The loaded Dataset object, or None if loading fails.

Return type:

Optional[Dataset]

coord2region.coord2study.deduplicate_datasets(datasets: dict[str, nimare.dataset.Dataset], save_dir: str | None = None) → nimare.dataset.Dataset | None[source]#

Create a deduplicated dataset across sources using PMIDs.

Duplicates are identified via PubMed IDs extracted from study identifiers. Datasets are merged sequentially using merge(), introduced in NiMARE 0.0.9. Older NiMARE versions without merge will return the first dataset unchanged.

Parameters:

  • datasets (Dict[str, Dataset]) – Dictionary of NiMARE Dataset objects to deduplicate.

  • save_dir (Optional[str], default=None) – Directory to save the deduplicated dataset (if provided).

Returns:

A deduplicated NiMARE Dataset combining all inputs, or None if no datasets were provided.

Return type:

Optional[Dataset]

coord2region.coord2study.prepare_datasets(data_dir: str | None = None, sources: list[str] | None = None) → nimare.dataset.Dataset | None[source]#

Load or create a deduplicated NiMARE dataset.

Parameters:

  • data_dir (str, optional) – Base directory for downloaded datasets and the merged cache. If None (default) the path ~/coord2region is used. Relative paths are interpreted relative to the user’s home directory so that passing "my_cache" stores data in ~/my_cache.

  • sources (Optional[List[str]], optional) – Dataset names to fetch if a cache needs to be built. See fetch_datasets() for valid entries. None (default) fetches all available datasets.

Returns:

The deduplicated NiMARE Dataset object, or None if preparation fails.

Return type:

Optional[Dataset]

coord2region.coord2study.remove_duplicate_studies(studies: list[dict[str, Any]]) → list[dict[str, Any]][source]#

Remove duplicate studies based on PMID.

Parameters:

studies (List[Dict[str, Any]]) – Study entries containing an "id" field with a PMID- prefix.

Returns:

Unique study entries keyed by PMID.

Return type:

List[Dict[str, Any]]

coord2region.coord2study.search_studies(datasets: dict[str, nimare.dataset.Dataset], coord: list[float] | tuple[float, float, float], radius: float = 0, sources: list[str] | None = None, email: str | None = None) → list[dict[str, Any]][source]#

Search selected datasets for studies reporting an MNI coordinate.

Parameters:

  • datasets (Dict[str, Dataset]) – NiMARE Dataset objects keyed by source name.

  • coord (Union[List[float], Tuple[float, float, float]]) – MNI coordinate [x, y, z].

  • radius (float, default=0) – Search radius in millimeters around the coordinate. 0 indicates an exact match.

  • sources (Optional[List[str]], optional) – Specific dataset names to query. None searches across all provided datasets.

  • email (Optional[str], optional) – Email address for Entrez (if abstract fetching is enabled).

Returns:

Deduplicated list of study metadata dictionaries.

Return type:

List[Dict[str, Any]]

coord2region.coord2study.get_studies_for_coordinate(datasets: dict[str, nimare.dataset.Dataset] | nimare.dataset.Dataset, coord: list[float] | tuple[float, float, float], radius: float = 0, email: str | None = None, sources: list[str] | None = None) → list[dict[str, Any]][source]#

Find studies reporting an MNI coordinate across all datasets.

This is a thin wrapper around search_studies() that searches every dataset in datasets. When a single deduplicated dataset is supplied, it is treated as a combined source.

Parameters:

  • datasets (Union[Dict[str, Dataset], Dataset]) – NiMARE Dataset objects keyed by source name, or a single deduplicated Dataset instance.

  • coord (Union[List[float], Tuple[float, float, float]]) – MNI coordinate [x, y, z].

  • radius (float, default=0) – Search radius in millimeters around the coordinate. 0 indicates an exact match.

  • email (Optional[str], optional) – Email address for Entrez (if abstract fetching is enabled).

  • sources (Optional[List[str]], optional) – Restrict the search to the specified dataset names when datasets is a mapping.