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.

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.
# The new "name" and "acronym" can be existing Allen Brain regions or a new (meaningful) one.
# Note that it is case sensitive.

[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.

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.1
########################################################################################

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 = "brain"  # brain or cord (eg. registration done in ABBA or abba_python)
midline = 5700  # midline Z coordinates (left/right limit) in microns
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...

Warning

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

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 hemisphere 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 chang 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

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.