API Reference#

Welcome to the technical reference for Coord2Region.

While the CLI is great for quick recipes, the Python API is designed for experienced users. It allows you to integrate anatomical mapping, literature search, and AI summarization directly into your existing scripts, notebooks, and data processing pipelines.

Why use the Python API?#

  • Batch Processing: Loop through thousands of coordinates efficiently using the pipeline.

  • Custom Workflows: Use the AtlasFetcher to download atlases for your own use, even outside of Coord2Region.

  • AI Integration: Import llm to add semantic summaries to your own pandas DataFrames or analysis results.

Quick Access#

Most users will only need a few core components. Use this cheat sheet to find the right tool for your task:

Goal

Component

Run Everything

run_pipeline() The high-level orchestrator. It takes coordinates/regions and returns a complete result object with labels, studies, and summaries.

Map Coordinates

AtlasMapper The mathematical engine. Use this if you just want to know “What region is at (30, -20, 50)?” without triggering web requests.

Manage Data

AtlasFetcher Handles downloading, caching, and loading brain templates (Nilearn/MNE).

Query Literature

search_studies() Interface with Neurosynth and NeuroQuery to find studies near your coordinates.

Generate Summaries

generate_summary() Base function to send retrieved studies to an LLM (OpenAI, Gemini) and get back a human-readable summary.

Configure Settings

Coord2RegionConfig Manages API keys, output directories, and default parameters via YAML or environment variables.

The package is organized into logical sub-systems. You can browse the full tree in the left navigation sidebar, but here is a guide to what lives where:

  • `coord2region.pipeline`: The “glue” code that stitches modules together.

  • ``coord2region.fetching``: Data input. Handles interactions with nilearn and mne datasets.

  • `coord2region.ai_model_interface`: External APIs. Contains the logic for querying Neurosynth and NeuroQuery.

  • `coord2region.llm`: Generative AI. Functions for prompting OpenAI, Gemini, and Hugging Face models.

  • `coord2region.utils`: Low-level helpers for file I/O, validation, and logging.

Tip

Pro Tip: If you are looking for the exact arguments for the CLI, they map 1-to-1 with the arguments in Coord2RegionConfig.