Regions#

How modewise describes channels, selects regions and summarises them. The design works for any atlas, and for any modality: an fMRI parcel, an EEG electrode and an fNIRS optode are all channels.

Describing channels#

Each channel has:

a name, which is what the data’s labels refer to
a region: an open vocabulary, as the atlas states it (PFCm, lAMY, frontopolar). Atlases share almost no region names, so there is no fixed list.
a hemisphere: left, right, or none. Midline structures such as the vermis, the brainstem and EEG Cz have none.
tags: open key–value pairs, so several region definitions can sit side by side. Examples: yeo17 = DefaultB, yeo7 = Default, lobe = frontal, tcp_network = striatum.

Atlas label files#

`format`	Reads	Gives
`tsv`	a tab-separated table with a header: `name` (required), plus optional `region` and `hemisphere` columns. `index` and `color` columns are ignored; every other column becomes a tag. This covers BIDS `dseg.tsv`.	whatever the columns say
`schaefer`	Schaefer and Yan (homotopic) labels such as `17Networks_LH_DefaultB_PFCm_1`, one per line or as a column of a lookup table (the `_info.txt` and LUT files both work)	hemisphere, a `yeo7`/`yeo17` tag, and the region where the label has one (somatomotor parcels often have only a network)
`tian`	Tian subcortex labels such as `NAc-shell-rh`, one per line	region and hemisphere
`names`	one name per line	name only

A dataset spec lists tables in channel order and concatenates them, for example cortex, then subcortex, then cerebellum (see docs/datasets.md). In Python, use modewise.read_channels(path, format), ChannelTable.from_records([...]), and + to concatenate.

Selecting#

The select step keeps the channels that match any of its rules. Within a rule, every field given must match:

[[step]]
id = "roi"
op = "select"
input = { data = "modes", channels = "channels" }
params = { rules = [
  { region = "PFCv" },
  { region = "PFCm", hemisphere = "left" },
  { region = "*AMY*" },                      # lAMY, mAMY: * matches any text
  { tags = { yeo17 = "Limbic*" } },
] }

A rule that names a hemisphere leaves out midline channels. A rule on a region or tag leaves out channels that lack that description. An empty rule ({}) selects every channel.

select works on series, decompositions, instantaneous attributes, time–frequency maps, epochs, functional connectivity (rows and columns), loadings and channel tables. The output has the same kind as the input.

In Python, ChannelTable.select returns the names a set of rules keeps:

import modewise

table = modewise.ChannelTable.from_records([
    {"name": "PFCm_L", "region": "PFCm", "hemisphere": "left", "tags": {"yeo17": "DefaultA"}},
    {"name": "PFCm_R", "region": "PFCm", "hemisphere": "right", "tags": {"yeo17": "DefaultA"}},
    {"name": "lAMY-lh", "region": "lAMY", "hemisphere": "left"},
    {"name": "V1_L", "region": "Striate", "hemisphere": "left", "tags": {"yeo17": "VisCent"}},
])
print(table.select([{"region": "*AMY*"}, {"tags": {"yeo17": "Default*"}, "hemisphere": "left"}]))
# ['PFCm_L', 'lAMY-lh']

Selecting before or after decomposition#

Both orders are supported; where select sits in the pipeline decides which:

Decompose all channels, then select (mvmd → select). Modes are fitted to the whole brain, so they are the same whichever regions you study.
Select, then decompose (select → mvmd). Modes are fitted to the selected regions only.

For slow bands the order changes little. On one ds005237 run with the MVMD settings of examples/tcp/thesis.toml (K = 10), decomposing 434 channels and decomposing 17 selected channels gave centre frequencies within about 0.02 Hz, and matching modes of the selected regions correlated at a median of 0.99–1.00 up to 0.2 Hz (0.86–0.89 between 0.30 and 0.46 Hz). Prefer whole-brain-first when results from different region sets must be comparable.

Summarising regions#

The region_average step averages channels within each group:

`by`	Groups by	Example output labels
`region`	region name	`PFCm`, `lAMY`
`hemisphere`	left and right	`left`, `right`
`tag` (with `tag = "yeo17"`)	a tag	`DefaultB`, `LimbicA`

split_hemispheres = true keeps the sides apart (PFCm_left, PFCm_right). Channels without the grouping description are left out.

Signals, modes, time–frequency maps and epochs: the mean over the group’s channels. This is the “mean” strategy of nilearn’s labels masker and of the TCP parcellation.
Functional connectivity: group × group matrices, each the mean over all pairs of distinct channels, one from each group. The diagonal gives within-group connectivity; the rest gives between-group connectivity. Pearson r is averaged as Fisher z, and the result is reported as z (see docs/connectivity.md). Fisher z and PLV are averaged as they are. Pairs with NaN are skipped.
Instantaneous attributes: not averaged, because a mean of instantaneous frequencies across channels has no clear meaning.

Averaging signals and then computing connectivity is not the same as computing connectivity and then averaging it. The first gives the coupling of region-mean signals; the second gives the mean coupling between the regions’ channels. Choose by the question.

Statistical contrasts#

Comparing regions or groups statistically (Welch t, permutation tests, FDR, the network-based statistic) belongs to S8.

ds005237#

examples/tcp/channels.tsv describes the 434 parcellated channels of the Transdiagnostic Connectome Project:

Channels	Atlas
0–399	homotopic Schaefer 400 with Yeo 17 networks (Yan et al. 2023, NeuroImage 273:120010): left 0–199, right 200–399
400–431	Tian subcortex, scale II (right hemisphere first)
432–433	cerebellum, left then right (Buckner atlas)

The layout comes from the TCP data descriptor (Scientific Data, 2025), and the names and order from the TCP processing repository’s label files. examples/tcp/make_channels.py rebuilds the table. It reads the pickled name list with pickletools, so nothing from the download is executed.