generate_custom_parcel_approach

neurocaps.utils.generate_custom_parcel_approach(filepath_or_df, maps_path, column_map, hemisphere_map=None, background_label='Background', metadata=None)

Generate a “Custom” Parcellation Approach From a Tabular Metadata File.

Constructs the nested dictionary for the “Custom” parcel_approach by reading a tabular file containing metadata about the parcellation.

Parameters:

• filepath_or_df (pd.Dataframe or str) – Path to the parcellation description file (e.g., “Schaefer_400.tsv”). Supports files with the following extension: “.csv”, “.tsv”, “.txt”, “.xlsx”. Can also be a pandas Dataframe.

• maps_path (str) – Path to the corresponding NIfTI parcellation file (e.g., “Schaefer_400.nii.gz”).

• column_map (dict[Literal["nodes", "regions", "hemispheres"], str]) –

  A dictionary mapping keys to column names in the metadata file. The following keys are valid:

  • ”nodes” (Required): Column name for the ROI labels/names.

  • ”regions” (Optional): Column name for the network/region names.

  • ”hemispheres” (Optional): Column name for hemisphere labels.

  Note

  If a “regions” key is provided in column_map, then the “regions” subkey will be created. Additionally, for lateralization, a “hemispheres” key must be provided in column_map. If the “regions” key is not provided, then the output custom parcellation dictionary will only contain the “maps” and “nodes” subkeys.

• hemisphere_map (dict[Literal["lh", "rh"], list[str]] or None, default=None) –

  A dictionary mapping hemisphere values in the metadata column to “lh” and “rh” (e.g. {“lh”: [“Left”, “L”, “l”, “LH”], “rh”: [“Right”, “R”, “r”, “RH”]]}).

  Important

  An error will be raised for cases where a region/network is partially lateralized (where not all nodes in the network are lateralized). Note that the lateralization information is only used in a specific case in CAP.caps2plot when visual_scope is set to “nodes” and the add_custom_node_labels kwarg is True.

• background_label (str or None, default=”Background”) –

  The label name for the background ROI to be excluded (e.g. “background”, “Unknown”, etc).

  Important

  Will be used to only check the first row in the metadata file. Since it is assumed that the first label, typically the 0 index is the background. This label will be removed and the first non-background label is assigned as the 0 index in the “regions” sub-dictionary, which will shift the remaining labels backwards. Note that the mapping of regions/networks corresponds to the indices in the “nodes” list not its label ID.

• metadata (dict[str, Any] or None, default=None) – Metadata information to add to the “metadata” key if not None.

Returns:

dict[Literal[“Custom”], CustomParcelApproach] – A dictionary representing the “Custom” parcellation approach.

See also

CustomParcelApproach

The type definition for the Custom parcellation approach. (See CustomParcelApproach Documentation)

ParcelApproach

Type definition representing the structure of the Schaefer, AAL, and Custom parcellation approaches. (See ParcelApproach Documentation)

Note

Dataframe Structure: The following is an example dataframe containing the metadata of the parcellation. The specific column names for the columns containing the labels (nodes), networks (regions), and hemisphere are to be mapped using column_map. Note that the column names do not have to be named “labels”, “networks”, and “hemispheres”. In this case, the map would be {"nodes": "labels", "regions": "networks", "hemispheres": "hemisphere}.

The labels for the hemispheres can be mapped using hemisphere_map. In this case, the map would be {"lh": ["L"], "rh": [R, "rh"]}.

labels	networks	hemisphere	…
SalVentAttn_TempOccPar	VAN	L	…
SalVentAttn_FrOperIns	VAN	R	…
Limbic_OFC	Limbic	rh	…
…	…	…	…

Excel Files: Pandas requires an optional dependency (openpyxl) to be installed for Excel files (“.xlsx”).