-
Notifications
You must be signed in to change notification settings - Fork 3
Function Reference
The following is the documentation for the functions that are accessible through MesoNet's command line interface.
mesonet.gui_start(gui_type='test', git_repo='', config_file='')
Starts the MesoNet gui.
Parameters:
gui_type (string): Default is 'test'. If 'test', opens the GUI for applying existing U-Net and DeepLabCut models to register and segment a set of brain images. If 'train', opens the GUI for training a new U-Net model (for automatically identifying the borders of the cortex in a brain image) and DeepLabCut model (for automatically identifying cortical landmarks for brain atlas - brain registration).
git_repo (string): Default is ''. If not '', the directory path supplied here will be used as the path to the MesoNet git repository. This can be useful to pre-define if your computer takes a while to find the repository automatically (this may occur on Unix systems).
config_file (string, not functional): Default is ''. If not '', the GUI will autofill based on information from the config file at the supplied file path. Note that this feature is still under construction.
mesonet.config_project(input_dir, output_dir, mode, model_name='unet.hdf5', config='dlc/config.yaml',
atlas=False, sensory_match=False, sensory_path='sensory', mat_save=True, use_unet=True,
atlas_to_brain_align=True, olfactory_check=True, plot_landmarks=True, align_once=True,
threshold=0.0001, model='models/unet_bundary.hdf5',
region_labels=False, steps_per_epoch=300, epochs=60)
Generates a config file (mesonet_train_config.yaml or mesonet_test_config.yaml, depending on whether you are applying an existing model or training a new one).
Parameters:
input_dir: The directory containing the input brain images.
output_dir: The directory containing the output files
.
mode: If 'train', generates a config file for training; if 'test', generates a config file for applying
the model.
model_name: (optional) Set a new name for the unet model to be trained. Default is 'unet.hdf5'
.
config: Select the config file for the DeepLabCut model to be used for landmark estimation.
atlas: Set to True to just predict the four 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.
sensory_match: 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: If sensory_match is True, this should be set to the path to a folder containing sensory maps
for each brain image. For each brain, put your sensory maps in a folder with the same name as the brain image (0, 1,
2, ...).
mat_save: Choose whether or not to export each predicted cortical region, each region's centre point, and the
overall region of the brain to a .mat file (True = output .mat files, False = don't output .mat files).
mask_generate: If mask_generate is True, running the function predict_regions will only generate U-Net based masks without an atlas-to-brain alignment.
threshold: 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 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).
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.
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!
steps_per_epoch: During U-Net training, the number of steps that the model will take per epoch. Defaults to
300 steps per epoch.
epochs: During U-Net training, the number of epochs for which the model will run. Defaults to 60 epochs (set
l ower for online learning, e.g. if augmenting existing model).
This function returns config_file: The path to the config_file. If you run this function as config_file = config_project(...) then
you can directly get the config file path to be used later.
mesonet.predict_regions(config_file)
Segments brain regions using a U-net model, based on parameters supplied in a .yaml configuration file.
Parameters:
Please see the Config File Guide for a full list of parameters that can be supplied in the .yaml configuration file.
mesonet.predict_dlc(config_file)
Predicts the locations of cortical landmarks on the brain, then uses these cortical landmarks (and, optionally, the U-net model) to register a standard brain atlas to the brain image (or brain image to atlas).
Parameters:
Please see the Config File Guide for a full list of parameters that can be supplied in the .yaml configuration file.