data mapping¶

one of the main features of yabplot is flexible data mapping. you can pass data as:

1. dictionaries (for partial data or specific regions).
2. arrays/lists (for mapping entire atlas vectors).

this tutorial demonstrates how to visualize statistical maps and ROI analysis results.

In [1]:

import yabplot as yab
import numpy as np
import pandas as pd

import yabplot as yab import numpy as np import pandas as pd

1. mapping dictionaries (partial data)¶

this is the safest way to plot data. you only need to provide values for the regions you care about. regions not in the dictionary will be hidden (colored with nan_color).

In [2]:

# define some specific values for subcortical regions
# notice how we can mix left and right hemisphere regions
roi_data = {
    'Left-Amygdala': 0.8,
    'Right-Amygdala': 0.75,
    'Left-Thalamus': 0.4,
    'Right-Thalamus': 0.45,
    'Left-Hippocampus': -0.5
}

ax = yab.plot_subcortical(
    data=roi_data,
    atlas='aseg',
    cmap='coolwarm',
    vminmax=[-1, 1],   # center the colormap at 0
    nan_alpha=0.1,     # make other regions almost invisible
)

# define some specific values for subcortical regions # notice how we can mix left and right hemisphere regions roi_data = { 'Left-Amygdala': 0.8, 'Right-Amygdala': 0.75, 'Left-Thalamus': 0.4, 'Right-Thalamus': 0.45, 'Left-Hippocampus': -0.5 } ax = yab.plot_subcortical( data=roi_data, atlas='aseg', cmap='coolwarm', vminmax=[-1, 1], # center the colormap at 0 nan_alpha=0.1, # make other regions almost invisible )

2. mapping arrays (full atlas)¶

if you have a vector of numbers (e.g., effect sizes for each region), you can pass it directly.

important: when using arrays, the order must match the atlas exactly. use get_atlas_regions to verify.

In [3]:

# get the list of regions for the schaefer 100 atlas
atlas_name = 'schaefer1000'
regions = yab.get_atlas_regions(atlas_name, 'cortical')

print(f"atlas '{atlas_name}' has {len(regions)} regions.")
print(f"first 3: {regions[:3]}")

# simulate some data
data_array = np.linspace(0, 1, len(regions)) 
# add some noise
data_array += np.random.normal(0, 0.1, len(regions))

# plot using the 'plasma' colormap
ax = yab.plot_cortical(
    data=data_array,
    atlas=atlas_name,
    cmap='plasma',
    views=['left_lateral', 'right_medial']
)

# get the list of regions for the schaefer 100 atlas atlas_name = 'schaefer1000' regions = yab.get_atlas_regions(atlas_name, 'cortical') print(f"atlas '{atlas_name}' has {len(regions)} regions.") print(f"first 3: {regions[:3]}") # simulate some data data_array = np.linspace(0, 1, len(regions)) # add some noise data_array += np.random.normal(0, 0.1, len(regions)) # plot using the 'plasma' colormap ax = yab.plot_cortical( data=data_array, atlas=atlas_name, cmap='plasma', views=['left_lateral', 'right_medial'] )

atlas 'schaefer1000' has 1000 regions.
first 3: ['7Networks_LH_Vis_1', '7Networks_LH_Vis_2', '7Networks_LH_Vis_3']

3. using pandas series¶

yabplot integrates well with pandas. if you have a dataframe of results, you can pass a series directly if the index matches region names.

In [4]:

# simulate a dataframe of tract statistics (e.g. fractional anisotropy)
tract_names = yab.get_atlas_regions('xtract_large', 'tracts')

# create a pandas series with names as index
df = pd.DataFrame({
    'fa_value': np.random.uniform(0.2, 0.8, len(tract_names))
}, index=tract_names)

print(df.head())

# pass the series directly
ax = yab.plot_tracts(
    data=df['fa_value'],
    atlas='xtract_large',
    cmap='magma',
    style='matte',
    bmesh='pial',
)

# simulate a dataframe of tract statistics (e.g. fractional anisotropy) tract_names = yab.get_atlas_regions('xtract_large', 'tracts') # create a pandas series with names as index df = pd.DataFrame({ 'fa_value': np.random.uniform(0.2, 0.8, len(tract_names)) }, index=tract_names) print(df.head()) # pass the series directly ax = yab.plot_tracts( data=df['fa_value'], atlas='xtract_large', cmap='magma', style='matte', bmesh='pial', )

      fa_value
AC    0.228494
AF_L  0.519530
AF_R  0.414318
AR_L  0.393668
AR_R  0.450084

In [ ]: