Config File Guide

If you're using the command line to run MesoNet, you will generate a configuration file containing various parameters that can be adjusted to customize your MesoNet analysis.

Testing config file

When you are testing a MesoNet model, MesoNet will output a config file called mesonet_test_config.yaml to your chosen output folder. Here's a guide to the parameters you can change in that file:

atlas (default: False): Set to True to just predict the cortical landmarks on your brain images, and not segment your brain images by region. Upon running mesonet.predict_dlc(config_file), MesoNet will output your brain images labelled with these landmarks as well as a file with the coordinates of these landmarks. Set to False to carry out the full brain image segmentation workflow.

config (default: dlc/config.yaml): The location (within the MesoNet repository) of a DeepLabCut config file that references the landmark alignment model that we provide with MesoNet. Don't change this unless you have your own DeepLabCut model for identifying cortical landmarks that you would like to use instead.

git_repo_base (automatically determined): The automatically determined location of your MesoNet git repository, which is necessary to access the U-Net and DLC models that we provide. Do not change this path manually unless you're moving the git repository around after creating this config file (the repository will automatically be located each time you generate this config file).

input_file (no default): The full path to the folder containing your input brain images. This must be specified as an argument to mesonet.config_project when you create this config file, but you can change the path here at any time.

mat_save (default: True): Choose whether or not to export each predicted cortical region, each region's centrepoint, and the overall region of the brain to a .mat file (True = output .mat files, False = don't output .mat files).

model (default: models/unet_bundary.hdf5): The location (within the MesoNet repository) of a U-Net model to be used for finding the boundaries of the brain region (as the default model does), or (if you have a specially trained model for this purpose) segmenting the entire brain into regions without the need for atlas alignment. Only choose another model if you have another model that you would like to use for segmenting the brain.

num_images (automatically determined from input_file): The number of brain images in the folder. Only change this if you add or remove images from the folder after generating this config file but before starting your analysis (in particular, it's not a good idea to change this number after running mesonet.predict_regions(config_file) as it can cause the code to break).

output_file (no default): The full path to the folder to which you'd like to save all of the outputs of your MesoNet analyses. This must be specified as an argument to mesonet.config_project when you create this config file, but you can change the path here at any time.

sensory_match (default: False): If True, MesoNet will attempt to align your brain images using peaks of sensory activation on sensory maps that you provide in a folder named sensory inside your input images folder. If you do not have such images, keep this value as False.

sensory_path (no default): The full path to the folder containing the functional images optionally used for further aligning each input brain image. Ensure that this folder contains one folder for each input brain image, with three sensory images from that particular brain in each subfolder.

mask_generate: (default = True): If mask_generate is True, running the function predict_regions will only generate U-Net based masks without an atlas-to-brain alignment.

threshold (default: 0.0001): Adjusts the sensitivity of the algorithm used to define individual brain regions from the brain atlas. NOTE: Changing this number may significantly change the quality of the brain region predictions; only change it if your brain images are not being segmented properly! In general, increasing this number causes each brain region contour to be smaller (less like the brain atlas); decreasing this number causes each brain region contour to be larger (more like the brain atlas).

olfactory_check: If True, draws olfactory bulb contours on the brain image.

use_unet: Choose whether or not to identify the borders of the cortex using a U-Net model.

use_dlc: Choose whether or not to try and register the atlas and brain image using a DeepLabCut model.

atlas_to_brain_align: If True, registers the atlas to each brain image. If False, registers each brain image to the atlas.

plot_landmarks: If True, plots DeepLabCut landmarks (large circles) and original alignment landmarks (small circles) on final brain image.

align_once: if True, carries out all alignments based on the alignment of the first atlas and brain. This can save time if you have many frames of the same brain with a fixed camera position.

original_label: if True, uses a brain region labeling approach that attempts to automatically sort brain regions in a consistent order (left to right by hemisphere, then top to bottom for vertically aligned regions). This approach may be more flexible if you're using a custom brain atlas (i.e. not one in which region is filled with a unique number).

use_voxelmorph: Choose whether or not to apply a local deformation registration for image registration, 
using a voxelmorph model.


exist_transform: if True, uses an existing voxelmorph transformation field for all data instead of predicting
 a new transformation.


voxelmorph_model: the name of a .h5 model located in the models folder of the git repository for MesoNet,
 generated using voxelmorph and containing weights for a voxelmorph local deformation model.


template_path: the path to a template atlas (.npy or .mat) to which the brain image will be aligned in
 voxelmorph.


flow_path: the path to a voxelmorph transformation field that will be used to transform all data instead of 
predicting a new transformation if exist_transform is True.


coords_input_file: The path to a file with DeepLabCut coordinates based on which a DeepLabCut transformation
 should be carried out.


atlas_label_list: A list of aligned atlases in which each brain region is filled with a unique numeric label.
 This allows for consistent identification of brain regions across images. If original_label is True, this is an 
empty list.

model: The location (within the MesoNet repository) of a U-Net model to be used for finding the boundaries of the brain region (as the default model does), or (if you have a specially trained model for this purpose) segmenting the entire brain into regions without the need for atlas alignment. Only choose another model if you have another model that you would like to use for segmenting the brain.

git_repo_base (automatically determined): The automatically determined location of your MesoNet git repository, which is necessary to access the U-Net and DLC models that we provide and is the default save location for the U-Net models that you train. Do not change this path manually unless you're moving the git repository around after creating this config file (the repository will automatically be located each time you generate this config file).

region_labels: If True, MesoNet will attempt to label each brain region according to the Allen Institute's Mouse Brain Atlas. Otherwise, MesoNet will label each region with a number. Please note that this feature is experimental!

landmark_arr: The default number and order of landmarks to be used for the full alignment of a standard brain atlas to a brain image. Change what is contained in this list to change the landmarks used. When the default DeepLabCut model with nine landmarks, the landmarks are:

• 0: Anterolateral tip of the left parietal bone.
• 1: Left frontal pole.
• 2: Posterior tip of the left retrosplenial region.
• 3: Cross point between the median line and the line which connects the left and right frontal pole.
• 4: Bregma (centre point of cortex)
• 5: Anterior tip of the interparietal bone.
• 6: Anterolateral tip of the right parietal bone.
• 7: Right frontal pole.
• 8: Posterior tip of the right retrosplenial region.

align_once: If True, aligns all brains based on the alignment for the first brain. This can save time if all brain images in a sequence of images are of the same animal and have the same orientation and zoom.

original_label: if True, uses a brain region labelling approach that attempts to automatically sort brain
regions in a consistent order (left to right by hemisphere, then top to bottom for vertically aligned regions). This
approach may be more flexible if you're using a custom brain atlas (i.e. not one in which region is filled with a
unique number).

exist_transform: if True, uses an existing voxelmorph transformation field for all data instead of predicting
a new transformation.


voxelmorph_model: the name of a .h5 model located in the models folder of the git repository for MesoNet,
generated using voxelmorph and containing weights for a voxelmorph local deformation model.


template_path: the path to a template atlas (.npy or .mat( to which the brain image will be aligned in
 voxelmorph.


flow_path: the path to a voxelmorph transformation field that will be used to transform all data instead of
predicting a new transformation if exist_transform is True.


atlas_label_list: A list of aligned atlases in which each brain region is filled with a unique numeric label.
 This allows for consistent identification of brain regions across images. If original_label is True, this is an
 empty list.


model: The location (within the MesoNet repository) of a U-net model to be used for finding the boundaries of the brain region (as the default model does), or (if you have a specially trained model for this purpose) 
segmenting the entire brain into regions without the need for atlas alignment. Only choose another model if you have
 another model that you would like to use for segmenting the brain.


region_labels: If True, MesoNet will attempt to label each brain region according to the Allen Institute's
Mouse Brain Atlas. Otherwise, MesoNet will label each region with a number. Please note that this feature is 
experimental!

Training config file

When you are training a MesoNet model, MesoNet will output a config file called mesonet_train_config.yaml to your output folder. Here's a guide to the parameters you can change in that file:

git_repo_base (automatically determined): The automatically determined location of your MesoNet git repository, which is necessary to access the U-Net and DLC models that we provide and is the default save location for the U-Net models that you train. Do not change this path manually unless you're moving the git repository around after creating this config file (the repository will automatically be located each time you generate this config file).

epochs (default: 60): The number of epochs for which the model will be trained. You may wish to reduce this number if you're updating an existing model.

input_file (no default): The full path to the folder containing your input brain images and corresponding binary masks delineating the borders of the brain region for each image. The brain images themselves must be in a subfolder of input_file called images; the masks must be in a subfolder called label. This must be specified as an argument to mesonet.config_project when you create this config file, but you can change the path here at any time.

log_folder (no default): The folder to which logging data should be output (and where this config file will be saved).

model_name (default: my_unet.hdf5): The name for the model that you are going to train (must include .hdf5 extension!)

steps_per_epoch (default: 300): The number of steps per training epoch. Influences the pace at which the model is trained.

epochs: During U-Net training, the number of epochs for which the model will run. Defaults to 60 epochs (set lower for online learning, e.g. if augmenting existing model).

bodyparts (default: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I']): The names and numbers of landmarks (bodyparts in DeepLabCut) to label in the DeepLabCut model.

rotation_range, width_shift_range, height_shift_range, shear_range, zoom_range, horizontal_flip, fill_mode: 
Keras image augmentation parameters for U-Net model training. See the Keras documentation for
 full documentation.