Datasets

Fetch matching public surfaces, maps, and parcellations for the plotting classes.

fetch_surfaces

fetch_surfaces(
    template: str = "fsaverage",
    *,
    surface: str = "inflated",
    density: str | None = None,
    data_dir: str | Path | None = None,
) -> _SurfacePaths

Fetch a standard left/right surface pair ready for a plotting constructor.

Parameters:

Name	Type	Description	Default
`template`	`str`	Surface template: "fsaverage", "fsLR", or "civet". This chooses actual data, not a declaration of registration with another image or subject.	`"fsaverage"`
`surface`	`str`	Geometry to select. All templates provide inflated and sphere surfaces. fsaverage also provides pial and white; fsLR provides midthickness; CIVET provides white and midthickness. fsLR and CIVET provide veryinflated, except fsLR at 4k/8k. Use anatomical geometry such as pial for a whole-brain background; sphere is registration geometry.	`"inflated"`
`density`	`str \| None`	Approximate vertices per hemisphere. None selects 10k for fsaverage, 32k for fsLR, or 41k for CIVET. Supported densities are fsaverage: 3k/10k/41k/164k; fsLR: 4k/8k/32k/164k; CIVET: 41k/164k. Density validation is delegated to neuromaps.	`None`
`data_dir`	`str \| Path \| None`	Persistent dataset directory. None uses ~/.cache/anatplot/neuromaps, outside the checkout. neuromaps downloads missing files and reuses existing files. The first call requires network access and fetches the template/density archive, including other geometries and auxiliary maps.	`None`

Returns:

Name	Type	Description
`surfaces`	`dict`	Display GIFTI paths under "left" and "right", plus "projection_surface", a (left, right) path tuple for anatomical contact localization. Pass the complete dictionary to SurfacePlot; VolumePlot uses only left and right. SurfacePlot uses projection_surface when adding contacts. Localization always prefers pial when the template provides it: fsaverage uses pial; fsLR/CIVET provide no pial and use midthickness. This choice is independent of display geometry. No geometry is changed.

Raises:

Type	Description
`ValueError`	If the template, surface, or density is unsupported. Download errors propagate from neuromaps; no substitute template is silently selected.

Notes

Data acquisition, integrity checks, extraction, and caching belong to neuromaps. No Workbench installation is needed to fetch and display these surfaces. Cite the template source and neuromaps when using downloaded data.

Examples:

from anatplot import SurfacePlot, datasets

surfaces = datasets.fetch_surfaces("fsLR", surface="inflated", density="32k")
plot = SurfacePlot(**surfaces)
fig = plot.to_figure()
fig.savefig("cortex.png")
plot.close()

fetch_sulcal_depth

fetch_sulcal_depth(
    template: str = "fsaverage",
    *,
    density: str | None = None,
    data_dir: str | Path | None = None,
) -> dict[str, NDArray[float64]]

Fetch sulcal-depth vertex arrays for a standard cortical template.

Parameters:

Name	Type	Description	Default
`template`	`str`	Surface template: "fsaverage", "fsLR", or "civet". Use the same template and density as fetch_surfaces to retain source vertex correspondence.	`"fsaverage"`
`density`	`str \| None`	Approximate vertices per hemisphere. None selects 10k for fsaverage, 32k for fsLR, or 41k for CIVET. Supported densities match fetch_surfaces; neuromaps validates the available choices.	`None`
`data_dir`	`str \| Path \| None`	Same template cache root as fetch_surfaces. None uses ~/.cache/anatplot/neuromaps. The first call downloads the template archive if needed; later surface and sulcal-depth requests reuse those files.	`None`

Returns:

Name	Type	Description
`values`	`dict[str, ndarray]`	Independent float64 arrays under "left" and "right", each with shape (n_vertices,) in the selected template's full hemisphere vertex order. Pass the dictionary directly to SurfacePlot.add_layer. Source values, signs, and units are retained without normalization or resampling.

Raises:

Type	Description
`ValueError`	If the template or density is unsupported, or a source array has the wrong vertex count. Download errors propagate from neuromaps.

Notes

These maps provide an anatomical display background. Fetching them does not establish correspondence with an arbitrary user surface. Cite the template source and neuromaps when using downloaded data.

available_parcellations

available_parcellations() -> dict[str, _ParcellationChoice]

Return the supported published surface parcellation combinations.

Returns:

Name	Type	Description
`choices`	`dict`	Keys are names accepted by fetch_parcellation. Each value contains templates mapped to density tuples, the default (template, density), selectable n_regions and networks, provider, and original citation. Empty option tuples mean the corresponding parameter must remain None. The returned dictionary can be edited without changing package defaults.

Notes

This lists existing provider files, not combinations generated by resampling. Calling this function performs no downloads.

fetch_parcellation

fetch_parcellation(
    name: str,
    *,
    template: str | None = None,
    density: str | None = None,
    n_regions: int | None = None,
    networks: int | None = None,
    data_dir: str | Path | None = None,
) -> _Parcellation

Fetch a published surface parcellation and its original label tables.

Parameters:

Name	Type	Description	Default
`name`	`(schaefer, glasser, desikan, destrieux, yeo)`	Schaefer 2018, HCP-MMP1.0, Desikan-Killiany, Destrieux 2009, or Yeo 2011.	`"schaefer"`
`template`	`str \| None`	Surface space. None selects fsLR for Schaefer/Glasser, fsaverage for the others. Consult available_parcellations for supported combinations.	`None`
`density`	`str \| None`	Vertices per hemisphere, approximately. None follows fetch_surfaces: 32k for fsLR and 10k for fsaverage. No registration or resampling occurs.	`None`
`n_regions`	`int \| None`	Schaefer: 100 to 1000 in steps of 100 (default 100); Glasser: 360; Yeo: 7 or 17 networks (default 7). Desikan/Destrieux have fixed schemes and require None. This selects published data, not runtime subdivision.	`None`
`networks`	`int \| None`	Schaefer network ordering: 7 or 17, default 7. Leave None for other parcellations; for Yeo select the network count through n_regions.	`None`
`data_dir`	`str \| Path \| None`	Provider cache root. None uses ~/.cache/anatplot/parcellations. Provider downloads are explicit on first use and cached for subsequent calls.	`None`

Returns:

Name	Type	Description
`parcellation`	`dict`	"left" and "right" contain integer arrays in the requested vertex order. "labels" maps each hemisphere to {ID: {name, color}}, where color is source RGBA in [0, 1]. Original IDs are retained, including hemisphere- local FreeSurfer IDs; interpret each array with its own label table. Zero is background/medial wall and should be masked for add_parcellation. "name", "template", "density", "n_regions", and "networks" describe the selected variant. "source" records the data provider, source paths, file SHA256 hashes, and original paper citation. Direct OSF downloads also record their archive URL, archive SHA256, and fixed manifest URL; TemplateFlow downloads record the provider package version.

Raises:

Type	Description
`ValueError`	If a requested combination is unavailable, before any download starts, or a provider file has a vertex count inconsistent with the selection.

Notes

Pooch retrieves the same public OSF archives listed by netneurotools, without importing that package. TemplateFlow supplies the other atlases. No Workbench or FreeSurfer installation is required. Format reading restores CIFTI BrainModel vertex indices without transforming coordinates. Existing provider versions may themselves have been resampled upstream; cite the source and inspect maps. Surface CIFTI files can contain zero voxel spacings in their NIfTI header. Their vertex labels do not use these fields; NiBabel may report this header diagnostic during loading. Source files are unchanged. Desikan 164k is excluded because its published files contain vertex IDs absent from their label tables. Array length cannot establish registration with an arbitrary user surface.

fetch_dmn_map_fslr32k

fetch_dmn_map_fslr32k(
    *, data_dir: str | Path | None = None
) -> tuple[NDArray[float64], NDArray[float64]]

Fetch the Neurosynth default-mode association map on fsLR 32k.

Parameters:

Name	Type	Description	Default
`data_dir`	`str \| Path \| None`	Persistent cache directory. None uses Pooch's platform cache for anatplot. Downloads use fixed upstream revisions and SHA256 checks.	`None`

Returns:

Name	Type	Description
`maps`	`tuple[ndarray, ndarray]`	Left and right float arrays, each of shape (32492,), in fsLR 32k vertex order. Zero denotes absent association and can be masked to retain the anatomical background.

Notes

This is a meta-analytic association map, not subject-level activation. Neurosynth provides the underlying map (Yarkoni et al., 2011, doi:10.1038/nmeth.1635); surfplot distributes its neuromaps projection to fsLR 32k. Fetching these attributed data files does not require surfplot or BrainSpace. No registration or surface transformation occurs here.