Skip to content

The configuration files#

There are three configuration files : altas_blacklist, atlas_fusion and a modality-specific file, that we'll call config in this document. The former two are related to the atlas you're using, the latter is what is used by cuisto to know what and how to compute and display things. There is a fourth, optional, file used to provide some information on a specific experiment, info.

The configuration files are in the TOML file format, that are basically text files formatted in a way that is easy to parse in Python. See here for a basic explanation of the syntax.

Most lines of each template file are commented to explain what each parameter do.

config.toml#

Click to see an example file
config_template.toml
########################################################################################
# Configuration file for cuisto package
# -----------------------------------------
# This is a TOML file. It maps a key to a value : `key = value`.
# Each key must exist and be filled. The keys' names can't be modified, except:
#   - entries in the [channels.names] section and its corresponding [channels.colors] section,
#   - entries in the [regions.metrics] section.                                                                                   
#
# It is strongly advised to NOT modify this template but rather copy it and modify the copy.
# Useful resources :
#   - the TOML specification : https://toml.io/en/
#   - matplotlib colors : https://matplotlib.org/stable/gallery/color/color_demo.html
#
# Configuration file part of the python cuisto package.
# version : 2.2
########################################################################################

object_type = "Cells"  # name of QuPath base classification (eg. without the ": subclass" part)
segmentation_tag = "cells"  # type of segmentation, matches directory name, used only in the full pipeline

[atlas]  # information related to the atlas used
name = "allen_mouse_10um"  # brainglobe-atlasapi atlas name
type = "abba"  # abba or brainglobe : registration done with regular ABBA (except allen_mouse_10um_java) or abba_python)
midline = 5700  # midline coordinates in microns (left/right limit, Z for abba, X for brainglobe) 
outline_structures = ["root", "CB", "MY", "P"]  # structures to show an outline of in heatmaps

[channels]  # information related to imaging channels
[channels.names]  # must contain all classifications derived from "object_type"
"marker+" = "Positive"  # classification name = name to display
"marker-" = "Negative"
[channels.colors]  # must have same keys as names' keys
"marker+" = "#96c896"  # classification name = matplotlib color (either #hex, color name or RGB list)
"marker-" = "#688ba6"

[hemispheres]  # information related to hemispheres
[hemispheres.names]
Left = "Left"  # Left = name to display
Right = "Right"  # Right = name to display
[hemispheres.colors]  # must have same keys as names' keys
Left = "#ff516e"  # Left = matplotlib color (either #hex, color name or RGB list)
Right = "#960010"  # Right = matplotlib color

[distributions]  # spatial distributions parameters
stereo = true  # use stereotaxic coordinates (Paxinos, only for brain)
ap_lim = [-8.0, 0.0]  # bins limits for anterio-posterior
ap_nbins = 75  # number of bins for anterio-posterior
dv_lim = [-1.0, 7.0]  # bins limits for dorso-ventral
dv_nbins = 50  # number of bins for dorso-ventral
ml_lim = [-5.0, 5.0]  # bins limits for medio-lateral
ml_nbins = 50  # number of bins for medio-lateral
hue = "channel"  # color curves with this parameter, must be "hemisphere" or "channel"
hue_filter = "Left"  # use only a subset of data. If hue=hemisphere : channel name, list of such or "all". If hue=channel : hemisphere name or "both".
common_norm = true  # use a global normalization for each hue (eg. the sum of areas under all curves is 1)
[distributions.display]
show_injection = false  # add a patch showing the extent of injection sites. Uses corresponding channel colors
cmap = "OrRd"  # matplotlib color map for heatmaps
cmap_nbins = 50  # number of bins for heatmaps
cmap_lim = [1, 50]  # color limits for heatmaps

[regions]  # distributions per regions parameters
base_measurement = "Count"  # the name of the measurement in QuPath to derive others from
hue = "channel"  # color bars with this parameter, must be "hemisphere" or "channel"
hue_filter = "Left"  # use only a subset of data. If hue=hemisphere : channel name, list of such or "all". If hue=channel : hemisphere name or "both".
hue_mirror = false  # plot two hue_filter in mirror instead of discarding the other
normalize_starter_cells = false  # normalize non-relative metrics by the number of starter cells
[regions.metrics]  # names of metrics. Do not change the keys !
"density µm^-2" = "density µm^-2"
"density mm^-2" = "density mm^-2"
"coverage index" = "coverage index"
"relative measurement" = "relative count"
"relative density" = "relative density"
[regions.display]
nregions = 18  # number of regions to display (sorted by max.)
orientation = "h"  # orientation of the bars ("h" or "v")
order = "max"  # order the regions by "ontology" or by "max". Set to "max" to provide a custom order
dodge = true  # enforce the bar not being stacked
log_scale = false  # use log. scale for metrics
[regions.display.metrics]  # name of metrics to display
"count" = "count"  # real_name = display_name, with real_name the "values" in [regions.metrics]
"density mm^-2" = "density (mm^-2)"

[files]  # full path to information TOML files
blacklist = "../../atlas/atlas_blacklist.toml"
fusion = "../../atlas/atlas_fusion.toml"
outlines = "/data/atlases/allen_mouse_10um_outlines.h5"
infos = "../../configs/infos_template.toml"

This file is used to configure cuisto behavior. It specifies what to compute, how, and display parameters such as colors associated to each classifications, hemisphere names, distributions bins limits...

Keep in mind the QuPath requirements :

  • Only one object type, any number of markers (channels).
  • Annotations have a Name region name, and a Classification Hemisphere: region name where "Hemisphere" is either "Left" or "Right".
  • Annotations measurements are in the form object type: marker measurement name.
  • Detections have Classifications in the form object type: marker.
  • Detections have atlas coordinates as measurements called "Atlas_X", "Atlas_Y", "Atlas_Z". "Atlas_Y" always corresponds to the dorso-ventral axis. For ABBA atlas (eg. "Allen Brain Atlas V3p1" in ABBA used from Fiji), "Atlas_X" and "Atlas_Z" are the rostro-caudal and medio-lateral axis, respectively. For Brainglobe altases (eg. "allen_mouse_10um" or any other Brainglobe atlas in ABBA used from Python), "Atlas_X" and "Atlas_Z" are the medio-lateral and rostro-caudal axis, respectively.

Warning

When editing your config.toml file, you're allowed to modify the keys only in the [channels] section.

The template file is thoroughly commented to explain what each line does. Nevertheless, additional information for some of the parameters is provided below.

Tips

"marker" and "channel" are used interchangeably but in the configuration file, "channel" is used.

[atlas] section#

  • name corresponds to the exact name of the Brainglobe atlas that was used for registration (check the full list here). If the regular "Allen Brain Atlas V3p1" atlas was used in ABBA-Fiji, choose "allen_mouse_10um". It can be left empty to use cuisto with custom Annotations, in that case, atlas-related features will be disabled (see for instance the fusion configuration file).
  • type depends on the type of atlas used, see more information on this page.

[channels] section#

This configures channels names, eg. biological markers and detection channels. This is the only place you can change the keys.

  • [channels.names] maps the names of the markers in QuPath (marker) to a name displayed in the graphs.
  • [channels.colors] maps the names of the markers in QuPath (marker) to a color displayed in the graphs.

[hemispheres] section#

Same as the [channels] section, but the "Left" and "Right" keys are hardcoded an cannot be modified.

[distributions] and [regions] sections#

Those two sections configure how to compute and plot normalized spatial distributions (pdf) and metrics by regions derived from the base measurement in QuPath (typically count or cumulated length).
They rely on the concept of hue used in seaborn, the Python library used to plot the results. In most plots, there are two axes, 'X' and 'Y', that could be for instance 'Region names' and 'Object count'. A third dimension can be shown using different colors, or hue, that can either color data given their channel (or marker) or hemisphere.

  • hue may only be "channel" or "hemisphere".
  • hue_filter applies either to "channel" or "hemisphere", given hue :
    • if hue = "channel" : hue_filter can be a hemisphere name (as written in [hemispheres.names]) or "both" to use data pooled from both hemispheres. Only the selected data will be used.
    • if hue = "hemisphere" : hue_filter can be a channel name (as written in [channels.names]), "all" to use data pooled from all channels or a list of channel names. Only the selected data will be used.

[distributions] section#

  • common_norm : whether to use a global normalization for all hue. This results in the sum of the areas under each individual curves being equal to 1. Alternatively, each curve is normalized independently.

[regions] section#

  • base_measurement : matches exactly the name of the measurement in QuPath Annotations (measurement name above) from which metrics are derived.
  • [regions.metrics] : the keys cannot be changed, but the names that appear on the graph can. Given the units in which base_measurement is expressed, the derived metric (for instance base_measurement / area) can have different name and units.
  • nregions : only the regions with the highest metrics will be displayed.
  • order : "max" or "ontology". "ontology" requires an atlas, the regions are sorted given the ontology (for example the Allen brain sorts regions in the rostro-caudal direction). "max" sorts the regions by descending values. Choose the later to be able to override the order with the names_list argument of the cuisto.display.plot_regions() method.
Click for a more readable parameters explanation

object_type : name of QuPath base classification (eg. without the ": subclass" part) segmentation_tag : type of segmentation, matches directory name, used only in the full pipeline

atlas

Information related to the atlas used

name : brainglobe-atlasapi atlas name
type : "brain" or "cord" (eg. registration done in ABBA or abba_python). This will determine whether to flip Left/Right when determining detections hemisphere based on their coordinates. Also adapts the axes in the 2D heatmaps.
midline : midline Z coordinates (left/right limit) in microns to determine detections hemisphere based on their coordinates.
outline_structures : structures to show an outline of in heatmaps

channels

Information related to imaging channels

names

Must contain all classifications derived from "object_type" you want to process. In the form subclassification name = name to display on the plots

"marker+" : classification name = name to display
"marker-" : add any number of sub-classification

colors

Must have same keys as "names" keys, in the form subclassification name = color, with color specified as a matplotlib named color, an RGB list or an hex code.

"marker+" : classification name = matplotlib color
"marker-" : must have the same entries as "names".

hemispheres

Information related to hemispheres, same structure as channels

names

Left : Left = name to display
Right : Right = name to display

colors

Must have same keys as names' keys

Left : ff516e" # Left = matplotlib color (either #hex, color name or RGB list)
Right : 960010" # Right = matplotlib color

distributions

Spatial distributions parameters

stereo : use stereotaxic coordinates (as in Paxinos, only for mouse brain CCFv3)
ap_lim : bins limits for anterio-posterior in mm
ap_nbins : number of bins for anterio-posterior
dv_lim : bins limits for dorso-ventral in mm
dv_nbins : number of bins for dorso-ventral
ml_lim : bins limits for medio-lateral in mm
ml_nbins : number of bins for medio-lateral
hue : color curves with this parameter, must be "hemisphere" or "channel"
hue_filter : use only a subset of data

  • If hue=hemisphere : it should be a channel name, a list of such or "all"
  • If hue=channel : it should be a hemisphere name or "both"

common_norm : use a global normalization (eg. the sum of areas under all curves is 1). Otherwise, normalize each hue individually

display

Display parameters

show_injection : add a patch showing the extent of injection sites. Uses corresponding channel colors. Requires the information TOML configuration file set up cmap : matplotlib color map for 2D heatmaps cmap_nbins : number of bins for 2D heatmaps cmap_lim : color limits for 2D heatmaps

regions

Distributions per regions parameters

base_measurement : the name of the measurement in QuPath to derive others from. Usually "Count" or "Length µm"
hue : color bars with this parameter, must be "hemisphere" or "channel"
hue_filter : use only a subset of data

  • If hue=hemisphere : it should be a channel name, a list of such or "all"
  • If hue=channel : it should be a hemisphere name or "both"

hue_mirror : plot two hue_filter in mirror instead of discarding the others. For example, if hue=channel and hue_filter="both", plots the two hemispheres in mirror.
normalize_starter_cells : normalize non-relative metrics by the number of starter cells

metrics

Names of metrics. The keys are used internally in cuisto as is so should NOT be modified. The values will only change etheir names in the ouput file

"density µm^-2" : relevant name
"density mm^-2" : relevant name
"coverage index" : relevant name
"relative measurement" : relevant name
"relative density" : relevant name

display

nregions : number of regions to display (sorted by max.)
orientation : orientation of the bars ("h" or "v")
order : order the regions by "ontology" or by "max". Set to "max" to provide a custom order
dodge : enforce the bar not being stacked
log_scale : use log. scale for metrics

metrics
name of metrics to display

"count" : real_name = display_name, with real_name the "values" in [regions.metrics] "density mm^-2"

files

Full path to information TOML files and atlas outlines for 2D heatmaps.

blacklist
fusion
outlines
infos

You can check supplementary configuration file examples in the resources folder, that are the ones used in the examples.

atlas_blacklist.toml#

Click to see an example file
atlas_blacklist.toml
# TOML file to list Allen brain regions to ignore during analysis.
# 
# It is used to blacklist regions and all descendants regions ("WITH_CHILD").
# Objects belonging to those regions and their descendants will be discarded.
# And you can specify an exact region where to remove objects ("EXACT"),
# descendants won't be affected.
# Use it to remove noise in CBX, ventricual systems and fiber tracts.
# Regions are referenced by their exact acronym.
#
# Syntax :
#   [WITH_CHILDS]
#   members = ["CBX", "fiber tracts", "VS"]
#
#   [EXACT]
#   members = ["CB"]


[WITH_CHILDS]
members = ["CBX", "fiber tracts", "VS"]

[EXACT]
members = ["CB"]

This file is used to filter out specified regions and objects belonging to them.

  • The atlas regions present in the members keys will be ignored. Objects whose parents are in here will be ignored as well.
  • In the [WITH_CHILDS] section, regions and objects belonging to those regions and all descending regions (child regions, as per the altas hierarchy) will be removed.
  • In the [EXACT] section, only regions and objects belonging to those exact regions are removed. Descendants regions are not taken into account.

atlas_fusion.toml#

Click to see an example file
atlas_blacklist.toml
# TOML file to determine which brain regions should be merged together.
# Regions are referenced by their exact acronym.
# The syntax should be the following :
# 
#   [MY]
#   name = "Medulla"  # new or existing full name
#   acronym = "MY"  # new or existing acronym
#   members = ["MY-mot", "MY-sat"]  # existing Allen Brain acronyms that should belong to the new region
#
# Then, regions labelled "MY-mot" and "MY-sat" will be labelled "MY" and will join regions already labelled "MY".
# What's in [] does not matter but must be unique and is used to group each blocks.
# The new "name" and "acronym" can be existing Allen Brain regions or a new (meaningful) one.
# Notes :
# - It is case sensitive.
# - If a Brainglobe atlas is specified in the configuration file, by default, cuisto will remove any
# non-leaf regions (eg. any regions that have child region in the atlas ontology) *before* the merging
# defined here. This means that if members are non-leaf regions, they will be discarded before the merge
# and NOT be included in the new custom region.

[PHY]
name = "Perihypoglossal nuclei"
acronym = "PHY"
members = ["NR", "PRP"]

[NTS]
name = "Nucleus of the solitary tract"
acronym = "NTS"
members = ["ts", "NTSce", "NTSco", "NTSge", "NTSl", "NTSm"]

[AMB]
name = "Nucleus ambiguus"
acronym = "AMB"
members = ["AMBd", "AMBv"]

[MY]
name = "Medulla undertermined"
acronym = "MYu"
members = ["MY-mot", "MY-sat"]

[IRN]
name = "Intermediate reticular nucleus"
acronym = "IRN"
members = ["IRN", "LIN"]

This file is used to group regions together, to customize the atlas hierarchy. It is particularly useful to group smalls brain regions that are impossible to register precisely. Keys name, acronym and members should belong to a [section].

  • [section] is just for organizing, the name does not matter but should be unique.
  • name should be a human-readable name for your new region.
  • acronym is how the region will be refered to. It can be a new acronym, or an existing one.
  • members is a list of acronyms of atlas regions that should be part of the new one.

Note that the fusion will happen after filtering out the data. By default, when using an atlas, cuisto will remove any annotations that are not leaf regions, eg. only regions without children will be kept for analysis. This is because in most of the atlases, leaf regions pave all the image : parent regions exist merely to group leaf regions in coarser ensemble. Merging regions happens after this filter, thus, even if the new regions have names that are not in the original atlas ontology, they will be kept.

info.toml#

Click to see an example file
info_template.toml
# TOML file to specify experimental settings of each animals.
# Syntax should be :
#   [animalid0]  # animal ID
#   slice_thickness = 30  # slice thickness in microns
#   slice_spacing = 60  # spacing between two slices in microns
#   [animalid0.marker-name]  # [{Animal id}.{segmented channel name}]
#   starter_cells = 190  # number of starter cells
#   injection_site = [x, y, z]  # approx. injection site in CCFv3 coordinates
#
# --------------------------------------------------------------------------
[animalid0]
slice_thickness = 30
slice_spacing = 60
[animalid0."marker+"]
starter_cells = 150
injection_site = [ 10.8937328, 6.18522070, 6.841855301 ]
[animalid0."marker-"]
starter_cells = 175
injection_site = [ 10.7498512, 6.21545461, 6.815487203 ]
# --------------------------------------------------------------------------
[animalid1-SC]
slice_thickness = 30
slice_spacing = 120
[animalid1-SC.EGFP]
starter_cells = 250
injection_site = [ 10.9468211, 6.3479642, 6.0061113 ]
[animalid1-SC.DsRed]
starter_cells = 275
injection_site = [ 10.9154874, 6.2954872, 8.1587125 ]
# --------------------------------------------------------------------------

This file is used to specify injection sites for each animal and each channel, to display it in distributions.