15. Parameters

The different command line interfaces, or CLIs, (astec_fusion, astec_mars, etc.) requires a parameter file (which is nothing but a python file) that contains both information on the experiment (path to the experiment directory, on the sub-directory names – see section Data organisation parameters) as well as specific parameters for the CLIs.

15.1. Prefixed parameters

Some of the parameter sets are said to be prefixed, such as the two sets of pre-processing parameters for the astec_mars CLI (see section astec_mars parameters). Indeed, the pre-processing can be set differently for the seed input image and the membrane input image (eg see section astec_mars).

Prefixing parameters allows to either set all the parameters with the same name together or set them independently.

As exemplified in section Steps 1 and 4: input image pre-processing, the parameter file lines (where the variables are not prefixed)

intensity_transformation = 'normalization_to_u8'
intensity_enhancement = None

will set the corresponding pre-processing parameters for both the seed and the membrane image pre-processing. However, using prefixes, as in the lines

seed_intensity_transformation = 'Identity'
membrane_intensity_transformation = 'normalization_to_u8'
intensity_enhancement = None

allows to set them independently.

This mechanism is designed to simplify the parameter file, but may have undesired consequences. Indeed, using the basic variable names of the registration parameters (see section Registration parameters) for the astec_astec CLI will change all registration parameters included in the pre-processing parameters.

To check whether the parameters have been set correctly, one can either use the --print-param CLI option (see section Command line interfaces common options) beforehand, and/or to a posteriori check the used parameters in the log file.

15.2. Common parameters

first_time_point

first time point to be processed (astec_fusion, astec_astec or astec_postcorrection) or single time point to be processed (astec_mars or astec_manualcorrection).

last_time_point

last time point to be processed (astec_fusion, astec_astec or astec_postcorrection).

delta_time_point

interval between two time points to be processed. Set to 1 by default. Fragile.

delay_time_point

Delay to be added to the time points to build the file names. Fragile.

time_digits_for_filename

number of digits used to build the file names.

time_digits_for_cell_id

number of digits used to define unique cellule id. in lineage file. The unique id of cell \(c\) at time \(t\) is \(t \times 10^d + c\) where \(d\) is set by time_digits_for_cell_id.

default_image_suffix:

used for both the result and the temporary image data.

  • 'inr': Inrimage format, kept for historical reasons.

  • 'mha': MetaImage format, readable by Fiji.

  • 'tif': not advised, since the tiff format does not allow to keep the voxel size along the z direction (aka spacing), at least in a standardized way.

  • 'nii': Nifti format, compatible with Omero.

Gzipped image files (with the additional extension '.gz' are also readable.

result_image_suffix:

used for the result image data.

result_lineage_suffix:

  • 'pkl': pickle file

  • 'xml': xml file

begin

same as first_time_point

end

same as last_time_point

delta

same as delta_time_point

raw_delay

same as delay_time_point

15.3. Data organisation parameters

DIR_LEFTCAM_STACKONE

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

DIR_LEFTCAM_STACKONE_CHANNEL_2

see section Fusion / input data

DIR_LEFTCAM_STACKONE_CHANNEL_3

see section Fusion / input data

DIR_LEFTCAM_STACKZERO

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

DIR_LEFTCAM_STACKZERO_CHANNEL_2

see section Fusion / input data

DIR_LEFTCAM_STACKZERO_CHANNEL_3

see section Fusion / input data

DIR_RAWDATA

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

DIR_RAWDATA_CHANNEL_2

see section Fusion / input data

DIR_RAWDATA_CHANNEL_3

see section Fusion / input data

DIR_RIGHTCAM_STACKONE

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

DIR_RIGHTCAM_STACKONE_CHANNEL_2

see section Fusion / input data

DIR_RIGHTCAM_STACKONE_CHANNEL_3

see section Fusion / input data

DIR_RIGHTCAM_STACKZERO

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

DIR_RIGHTCAM_STACKZERO_CHANNEL_2

see section Fusion / input data

DIR_RIGHTCAM_STACKZERO_CHANNEL_3

see section Fusion / input data

EN:

the so-called embryo name. All files will be named after this name. E.g. see section Fusion / output data and figure Listing 15.4.

EXP_FUSE:

String (str type) or list (list type) of strings. It indicates what are the fused images directories, of the form <PATH_EMBRYO>/FUSE/FUSE_<EXP_FUSE>.

EXP_FUSE = 'exp1'
EXP_FUSE = ['exp1', 'exp2']

are then both valid. Default value of EXP_FUSE is 'RELEASE'. See section Fusion / output data, see figure Listing 15.4.

EXP_FUSE_CHANNEL_2

see section Fusion / output data

EXP_FUSE_CHANNEL_3

see section Fusion / output data

PATH_EMBRYO:

path to the experiment. If not present, the current directory is used. See section Fusion / input data, see figures Listing 15.1, Listing 15.2, Listing 15.3, and Listing 15.4

acquisition_leftcam_image_prefix

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

acquisition_rightcam_image_prefix

see section Fusion / input data, see figures Listing 15.1, Listing 15.2, and Listing 15.3.

Listing 15.1 Typical organisation of mono-channel data.
 ``<PATH_EMBRYO>``/
 ├── ``<DIR_RAWDATA>``/
 │  ├── ``<DIR_LEFTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  ├── ``<acquisition_leftcam_image_prefix>001.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  ├── ``<acquisition_leftcam_image_prefix>001.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKONE>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  ├── ``<acquisition_leftcam_image_prefix>001.zip``
 │  │  └── ...
 │  └── ``<DIR_RIGHTCAM_STACKONE>``/
 │     ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │     ├── ``<acquisition_leftcam_image_prefix>001.zip``
 │     └── ...
 ...
Listing 15.2 Typical organisation of multi-channel data.
 ``<PATH_EMBRYO>``/
 ├── ``<DIR_RAWDATA>``/
 │  ├── ``<DIR_LEFTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKONE>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKONE>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKZERO_CHANNEL_2>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKZERO_CHANNEL_2>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKONE_CHANNEL_2>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  └── ``<DIR_RIGHTCAM_STACKONE_CHANNEL_2>``/
 │     ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │     └── ...
 ...
Listing 15.3 Alternative organisation of multi-channel data.mono-channel data.
 ``<PATH_EMBRYO>``/
 ├── ``<DIR_RAWDATA>``/
 │  ├── ``<DIR_LEFTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKONE>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  └── ``<DIR_RIGHTCAM_STACKONE>``/
 │     ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │     └── ...
 ├── ``<DIR_RAWDATA_CHANNEL_2>``/
 │  ├── ``<DIR_LEFTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_RIGHTCAM_STACKZERO>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  ├── ``<DIR_LEFTCAM_STACKONE>``/
 │  │  ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │  │  └── ...
 │  └── ``<DIR_RIGHTCAM_STACKONE>``/
 │     ├── ``<acquisition_leftcam_image_prefix>000.zip``
 │     └── ...
 ...
Listing 15.4 Typical organisation of fused images.
 ``<PATH_EMBRYO>``/
 ├── ``<DIR_RAWDATA>``/
 │  └── ...
 ├── ``<FUSE>``/
 │  └── ``FUSE_<EXP_FUSE>``/
 │     ├── ``<EN>_fuse_t000.<result_image_suffix>``
 │     ├── ``<EN>_fuse_t001.<result_image_suffix>``
 │     └── ...
 ...

15.4. Ace parameters

Ace stand for Automated Cell Extractor. [G[L]]ACE methods aim at detecting and enhancing membranes in a 3D images (see also section Membrane dedicated enhancement).

  1. Hessian-based detection of 2-D manifolds, computation of a center-membrane image.

  2. Thresholding of the center-membrane image to get a binary image.

  3. Reconstruction of a membrane images from the binary image through tensor voting.

sigma_membrane

this is the gaussian sigma that is used to compute image derivatives (in real units), for the Hessian-based detection of 2-D manifolds.

hard_thresholding

True or False. If set to True, a hard threshold (set by variable hard_threshold) is used instead of an automated threshold.

hard_threshold

manual

True or False. By default, this parameter is set to False. If failure, (meaning that thresholds are very bad, meaning that the binarized image is very bad), set this parameter to True and relaunch the computation on the test image. If the method fails again, “play” with the value of manual_sigma … and good luck.

manual_sigma

Axial histograms fitting initialization parameter for the computation of membrane image binarization axial thresholds (this parameter is used if manual is set to True). One may need to test different values of manual_sigma. We suggest to test values between 5 and 25 in case of initial failure. Good luck.

sensitivity

Membrane binarization parameter. Use larger values (smaller than or equal to 1.0) to increase the quantity of binarized membranes to be used for tensor voting.

sigma_TV

Parameter which defines the voting scale for membrane structures propagation by tensor voting method (real coordinates). This parameter should be set between \(3 \mu m\) (little cells) and \(4.5 \mu m\) (big gaps in the binarized membrane image).

sigma_LF:

Additional smoothing parameter for reconstructed image (in real coordinates). It seems that the default value = \(0.9 \mu m\) is ok for standard use.

sample:

Set the fraction (in [0, 1]) of the binarized membranes further used for tensor voting. It allows tensor voting computation speed optimisation (do not touch if not bewared): the more sample, the higher the cost.

sample_random_seed

Drawing a sample from the binarized membranes (see parameter sample) is a stochastic process. Setting this parameter to some int value allows to make this stochastic process reproducible.

ace_max_value

Maximal value for tensor voting output. After smoothing by sigma_LF, the values are casted into 1 or 2 bytes depending on this maximal value.

bounding_box_dilation

Dilation radius for the cell bounding boxes Used to compute local histograms

default_image_suffix

See also

Section Image preprocessing describes the overview of the so-called image reconstruction (ie how are build input images for segmentation).

Section Membrane dedicated enhancement gives some insights about membrane enhancement.

15.5. Morphosnake parameters

dilation_iterations

dilation of the cell bounding box for computation purpose.

iterations

maximal number of morphosnake iterations.

delta_voxel:

error on voxel count to define a stopping criteria.

energy
  • 'gradient': uses the same formula as in [MarquezNBA14], as in the historical astec version. But seems to be a poor choice.

  • 'image': uses directly the image as the energy image.

smoothing:

internal parameter for the morphosnake.

balloon:

internal parameter for the morphosnake.

processors: number of processors used for the morphosnake correction.

mimic_historical_astec:

True or False. If set to True, same implementation than the historical astec version. Kept for comparison purpose.

15.6. Preprocessing parameters

The input image may be pre-processed before being used as

  • either the membrane image (ie the height image) for watershed segmentation,

  • or the seed image (ie the image with which the regional minima are computed),

  • or the morphosnake image (ie the image with which the morphosnake energy is computed).

For more details, see section Image preprocessing.

  • Ace parameters: see section Ace parameters.

  • intensity_prenormalization: possible values are

    • 'identity'

    • 'normalization_to_u8'

    • 'normalization_to_u16'

    Performs a global robust normalization of the input image, prior to other pre-processing. The intensity value corresponding to the min percentile is set to 0, while the intensity value corresponding to the max percentile is set either to 255 (u8) or prenormalization_max_value (u16). In-between values are linearly interpolated. Should be left to ‘identity’ for integer-encoded images. It has been introduced for real-encoded images.

    It is governed by the variables:

    • prenormalization_max_percentile: Percentile of the image histogram used to determine the value to be set to 0 (prenormalization step).

    • prenormalization_min_percentile: Percentile of the image histogram used to determine the value to be set to maximal value (255 for u8, prenormalization_max_value for u16).

    • prenormalization_max_value: Maximal output value to be issued from the prenormalization step (only used for the intensity_prenormalization = 'normalization_to_u16' case).

  • intensity_transformation: set the (histogram based) intensity transformation of the original image (see section Histogram based image value transformation)

    • None: no intensity transformation of the original image is used to pre-process the input image.

    • 'identity': the input image is used without any transformation.

    • 'normalization_to_u8': the input image (usually encoded on 16 bits) is normalized onto 8 bits. The values corresponding to percentiles given by the variables normalization_min_percentile and normalization_max_percentile are mapped respectively on 0 and 255.

    • 'normalization_to_u16': the input image (usually encoded on 16 bits) is normalized onto 8 bits or 16 bits. The values corresponding to percentiles given by the variables normalization_min_percentile and normalization_max_percentile are mapped respectively on 0 and 255 for u8 or normalization_max_value for u16).

  • intensity_enhancement: set the membrane enhancement transformation of the original image (see section Membrane dedicated enhancement)

    • None: no membrane enhancement of the original image is used to pre-process the input image.

    • 'GACE': stands for Global Automated Cell Extractor. It tries to reconstructed a membrane image through a membrane detector, an automated thresholding and a tensor voting step. The automated thresholding is computed once for the whole image.

    • 'GLACE': stands for Grouped Local Automated Cell Extractor. It differs from one step from GACE: the threshold of extrema image is not computed globally (as in GACE), but one threshold is computed per cell of \(S^{\star}_{t-1} \circ \mathcal{T}_{t-1 \leftarrow t}\), from the extrema values of the cell bounding box. This can be used only with astec_astec (section astec_astec).

  • outer_contour_enhancement: allows to use a fake outer contour for better segmentation of cells adjacent to the background.

    • None: no contour images are used to pre-process the input image.

    • 'from_previous_segmentation': contour images are built from the previous segmented time point. Fragile. Kept for test purposes. Obviously, works only for propagated segmentation. This feature has been added for tests, but has not demonstrated yet any benefit.

    • 'from_contour_image': contours images named <EN>_contour_t<begin>.<image_suffix> are provided in a separate directory <PATH_EMBRYO>/CONTOUR/CONTOUR_<EXP_CONTOUR>/

  • reconstruction_images_combination:

    • 'addition'

    • 'maximum'

  • normalization_min_percentile Percentile of the image histogram used to determine the value to be set to 0 (normalization step).

  • normalization_max_percentile Percentile of the image histogram used to determine the value to be set to 255 or ‘normalization_max_value’ (normalization step)

  • normalization_max_value: Maximal output value to be issued from the normalization step (only used for the intensity_normalization = 'normalization_to_u16' case).

  • intensity_sigma: sigma (in real units) of the smoothing gaussian applied to the intensity-transformed image, prior its eventual combination with the other images (intensity enhancement, outer contours). Note that this variable can also be set by some watershed parameters (see section Watershed parameters and section A note on parameters).

  • Registration parameters (see section Registration parameters) prefixed by linear_registration_

  • Registration parameters (see section Registration parameters) prefixed by nonlinear_registration_

  • keep_reconstruction: True or False. If set to True, pre-processed images are kept in a RECONSTRUCTION/ directory.

    These pre-processed images may be re-used in case of manual correction (see section astec_manualcorrection), to extract seeds and to do a watershed based segmentation when a cell is to be split. Thus, to spare computation time, it is advised to keep them.

15.7. Registration parameters

  • compute_registration: True or False.

  • pyramid_highest_level: Registration is performed within a hierarchical scheme, ie an image pyramid is built, with the image dimensions decreasing from one pyramid level to the next (divided by 2). The registration starts at the highest pyramid level (the smallest image so the pyramid) and ends at the lowest level. 0 is the lowest level, ie the original image itself. To go from level ‘l’ to level ‘l+1’, each image dimension is divided by 2, meaning the size of a 3D image is divided by 8. Level 1 is defined by the first value of form ‘\(2^n\)’ immediately inferior to the image dimension, or the image dimension divided by 2 if it is already of form ‘\(2^n\)’. Setting this variable to 6 means that registration starts with images whose dimensions are 1/64th of the original image.

  • pyramid_lowest_level: Lowest level of the pyramid image for registration. Setting it to 0 means that the lowest level is with the image itself. Setting it to 1, 2 or even 3 allows to gain substantial computational time. See pyramid_highest_level description.

  • gaussian_pyramid: True or False. If True the image at one pyramid level is smoothed by a Gaussian kernel before building the image at the next level.

  • transformation_type Possible values are 'translation', 'rigid', 'similitude', 'affine' or 'vectorfield'.

  • elastic_sigma: Gaussian sigma to regularize the deformation, only for ‘vectorfield’ transformation. At each registration iteration, a residual deformation is computed. It is smoothed (regularized) by a gaussian of fluid_sigma parameter, then compounded with the previously found transformation, and the resulting deformation is finally smoothed (regularized) by a gaussian of elastic_sigma parameter.

  • transformation_estimation_type: Possible values are 'wlts', 'lts', 'wls', or 'ls'.

    • 'wlts': weighted least trimmed squares

    • 'lts': least trimmed squares

    • 'wls': weighted least squares

    • 'ls': least squares

  • lts_fraction: Fraction of pairings retained to compute the transformation, only for robust estimation scheme ('wlts' or 'lts'). Has obviously to be larger than 0.5.

  • fluid_sigma: Gaussian sigma to regularize the deformation update, only for ‘vectorfield’ transformation. See elastic_sigma description.

  • normalization: True or False. If True, the images to be registered are normalized on 1 byte for computational purposes. This variable is kept for historical reasons. Do not change it.

15.8. Seed edition parameters

  • seed_edition_dir:

  • seed_edition_file: if run with '-k', temporary files, including the computed seeds are kept into a temporary directory, and can be corrected in several rounds

    seed_edition_file = [['seeds_to_be_fused_001.txt', 'seeds_to_be_created_001.txt'], \
                     ['seeds_to_be_fused_002.txt', 'seeds_to_be_created_002.txt'],
                     ...
                     ['seeds_to_be_fused_00X.txt', 'seeds_to_be_created_00X.txt']]
    

    Each line of a seeds_to_be_fused_00x.txt file contains the labels to be fused, e.g. “10 4 2 24”. A same label can be found in several lines, meaning that all the labels of these lines will be fused. Each line of seeds_to_be_created_00x.txt contains the coordinates of a seed to be added.

15.9. Watershed parameters

  • seed_sigma: gaussian sigma for smoothing of initial image for seed extraction (real coordinates). This is a short-cut to change the value of intensity_sigma of the pre-processing parameters used to get the seed image (see section Preprocessing parameters).

  • seed_hmin: \(h\) value for the extraction of the \(h\)-minima,

  • seed_high_threshold: regional minima thresholding.

  • membrane_sigma: gaussian sigma for smoothing of reconstructed image for image regularization prior to segmentation (real coordinates). This is a short-cut to change the value of intensity_sigma of the pre-processing parameters used to get the membrane image (see section Preprocessing parameters).

15.10. Diagnosis parameters

These parameters are prefixed by diagnosis_.

  • minimal_volume: for diagnosis on cell volume. Threshold on cell volume. Snapshot cells that have a volume below this threshold are displayed.

  • maximal_volume_variation: for diagnosis on cell volume. Threshold on volume variation along branches. Branches that have a volume variation above this threshold are displayed. The volume variation along a branch is calculated as \(100 * \frac{\max_{t} v(c_t) - \min_{t} v(c_t)}{\mathrm{med}_t v(c_t)}\) where \(v(c_t)\) is the volume of the cell \(c_t\) and \(\mathrm{med}\) is the median value.

  • maximal_volume_derivative: for diagnosis on cell volume. Threshold on volume derivative along branches. Time points along branches that have a volume derivative above this threshold are displayed. The volume derivative along a branch is calculated as \(100 * \frac{v(c_{t+1}) - v(c_{t})}{v(c_{t})}\) where \(t\) denotes the successive acquisition time points.

  • items: if strictly positif, number minimal of items (ie cells) to be displayed in diagnosis.

  • minimal_length: for diagnosis on lineage. Threshold on branch length. Branches that have a length below this threshold are displayed.

  • maximal_contact_distance: for diagnosis on cell contact surface. Threshold on cell contact surface distance along branches. Time points along branches that have a cell contact surface distance above this threshold are displayed (recall that the distance is in [0, 1]).

15.11. astec_fusion parameters

  • acquisition_orientation: 'left' or 'right'. Gives the rotation (with respect to the Y axis) of the left camera frame of stack #0 to be aligned with the the left camera frame of stack #1.

    • 'right': +90 degrees

    • 'left': -90 degrees

    See also 'acquisition_mirrors'. Since it should depend on the apparatus, this parameter should not change for all acquisitions performed by the same microscope. See section Important parameters in the parameter file.

  • acquisition_mirrors: True or False. If False, the right camera images are mirrored to make them similar to left camera images. To determine the configuration (acquisition_orientation, acquisition_mirrors) (ie ('left', False), ('left', True), ('right', False), or ('right', True)), it is advised to perform the fusion for only one time point (by setting 'begin' and 'end' at the same value) with a large 'target_resolution', for each of those 4 choices, xzsection_extraction being set to True (or some adequate value).

    See also 'acquisition_orientation'. Since it should depend on the apparatus, this parameter should not change for all acquisitions performed by the same microscope. See section Important parameters in the parameter file.

  • acquisition_resolution: voxel size of acquired images e.g.

    raw_resolution = (.195, .195, 1.)
    

    see section Important parameters in the parameter file.

  • acquisition_stack0_leftcamera_z_stacking: 'direct' or 'inverse'. Defines where are the high contrasted XZ-sections of the left camera image of stack0.

    • 'direct': small z are well contrasted (close to the camera), while large z are fuzzy. It is useful for direction-dependent weighting schemes.

    • 'inverse': the other way around.

    Changing ‘direct’ to ‘inverse’ (or the other way) implies to change acquisition_orientation as well. Setting xzsection_extraction to True (or some adequate value) allows to verify whether acquisition_stack0_leftcamera_z_stacking is set to the right value.

  • acquisition_stack1_leftcamera_z_stacking: same as acquisition_stack0_leftcamera_z_stacking for stack #1.

  • acquisition_leftcamera_z_stacking: allows to set both acquisition_stack0_leftcamera_z_stacking and acquisition_stack1_leftcamera_z_stacking. See section Important parameters in the parameter file.

  • acquisition_slit_line_correction: True or False. Slit lines are Y lines that appear brighter or darker in the acquisition, which may cause artifacts in the reconstructed (ie fused) image, which, in turn, may impair further segmentation steps. See section Fusion method overview.

  • target_resolution: Voxel size of the reconstructed image after fusion of the four views. e.g.

    target_resolution = 0.3
    

    See section Fusion / output data.

  • fusion_strategy: Possible values are ‘direct-fusion’ and ‘hierarchical-fusion’.

    • 'direct-fusion': each acquisition is linearly co-registered with the first acquisition (stack #0, left camera). The transformation is computed in two steps:

      • with parameters prefixed by fusion_preregistration_ (by default deactivated).

      • with parameters prefixed by fusion_registration_ (by default 'affine' transformation).

      Then weights and images are transformed thanks to the computed transformations. Finally a weighted linear combination gives the result.

    • 'hierarchical-fusion': from the couple (left camera, right camera), each stack is reconstructed following the same scheme than the direct fusion but with only 2 images. (thus with the registration parameters prefixed by fusion_preregistration_ and fusion_registration_). Then stack #1 is co-registered with stack #0 in two steps:

      • with parameters prefixed by fusion_stack_preregistration_ (by default 'affine' transformation).

      • with parameters prefixed by fusion_stack_registration_ (by default 'vectorfield' transformation).

      Images and weights associated with stack#1 are then transformed. Finally a weighted linear combination gives the result.

    See section Step 5 parameters: image co-registration.

  • acquisition_cropping: True or False. If set to True, the acquisitions stacks are cropped before fusion along the X and Y directions. Maximum Intensity Projection (MIP) images are automatically thresholded (Otsu algorithm) to determine the bounding box of the object of interest. Margins are then added to the bounding box. See section Step 3 parameters: raw data cropping.

  • acquisition_z_cropping: True or False. If set to True, the acquisitions stacks are cropped before fusion along the Z direction. Margins are then added to the bounding box.

  • acquisition_cropping_margin_x_0: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘left’ X direction.

  • acquisition_cropping_margin_x_1: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘right’ X direction.

  • acquisition_cropping_margin_y_0: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘left’ Y direction.

  • acquisition_cropping_margin_y_1: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘right’ Y direction.

  • acquisition_cropping_margin_z_0: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘left’ Z direction.

  • acquisition_cropping_margin_z_1: Added margin of the bounding box computed for the cropping of the raw acquisition image in ‘right’ Z direction.

  • acquisition_cropping_margin_x: allows to set both acquisition_cropping_margin_x_0 and acquisition_cropping_margin_x_1

  • acquisition_cropping_margin_y: allows to set both acquisition_cropping_margin_y_0 and acquisition_cropping_margin_y_1

  • acquisition_cropping_margin_z: allows to set both acquisition_cropping_margin_z_0 and acquisition_cropping_margin_z_1

  • acquisition_cropping_margin: allows to set the six margin variables.

  • acquisition_cropping_opening: Active when acquisition_cropping is set to True. Perform an opening (mathematical morphology) on the thresholded MIP image. It may be useful if some structures are connected to the desired one (0 means no opening, else specify the structuring element size).

  • raw_crop same as acquisition_cropping

  • Registration parameters (see section Registration parameters) prefixed by fusion_preregistration_. First registration step of the co-registration of each of the four acquisitions for the 'direct-fusion' scheme (see fusion_strategy), or of the left and right camera acquisitions to reconstruct a stack for the 'hierarchical-fusion' scheme. By default deactivated.

  • Registration parameters (see section Registration parameters) prefixed by fusion_registration_. Second registration step of the co-registration of each of the four acquisitions for the 'direct-fusion' scheme (see fusion_strategy), or of the left and right camera acquisitions to reconstruct a stack for the 'hierarchical-fusion' scheme. By default an affine transformation is sought.

  • Registration parameters (see section Registration parameters) prefixed by fusion_stack_preregistration_. First registration step of the co-registration of the two stacks reconstructed with left and right cameras for the 'hierarchical-fusion' scheme (see fusion_strategy). By default an affine transformation is sought.

  • Registration parameters (see section Registration parameters) prefixed by fusion_stack_registration_ Second registration step of the co-registration of the two stacks reconstructed with left and right cameras for the 'hierarchical-fusion' scheme (see fusion_strategy). By default an non-linear transformation is sought.

  • xzsection_extraction: False, True, an integer or a list of integers.

    • True: extracts the XZ-section at the middle of the volume

    • one integer: extracts the XZ-section for the given Y value

    • a list of integers: extracts the XZ-sections for all given Y values

    Note

    Setting the Y value(s) of the extracted XY sections allows to choose a convenient section for the fusion assessment.

    If not False, XZ-sections XZ-sections of the co-registered acquisitions, as well as the weighting function images, are stored in the directory <PATH_EMBRYO>/FUSE/FUSE_<EXP_FUSE>/XZSECTION_<xxxx> where <xxxx> is the time point index. It provides a direct and efficient means to check whether the parameters acquisition_orientation, acquisition_mirrors, or acquisition_stack[0,1]_leftcamera_z_stacking are correctly set. If the value is an integer or a list of integers, it indicates the indices of XZ-sections to be extracted See section Stacks non-linear co-registration

  • fusion_cropping: True or False. If True, the fusion image is cropped along the X and Y directions. Maximum Intensity Projection (MIP) images are automatically thresholded (Otsu algorithm) to determine the bounding box of the object of interest. Margins are then added to the bounding box. See section Step 7: fused data cropping

  • fusion_z_cropping: True or False. If True, the fusion image is also cropped along the Z direction. Margins are then added to the bounding box.

  • fusion_cropping_margin_x_0: Added margin of the bounding box computed for the cropping of the fusion image in ‘left’ X direction.

  • fusion_cropping_margin_x_1 Added margin of the bounding box computed for the cropping of the fusion image in ‘right’ X direction.

  • fusion_cropping_margin_y_0 Added margin of the bounding box computed for the cropping of the fusion image in ‘left’ Y direction.

  • fusion_cropping_margin_y_1 Added margin of the bounding box computed for the cropping of the fusion image in ‘right’ Y direction.

  • fusion_cropping_margin_z_0 Added margin of the bounding box computed for the cropping of the fusion image in ‘left’ Z direction.

  • fusion_cropping_margin_z_1 Added margin of the bounding box computed for the cropping of the fusion image in ‘right’ Z direction.

  • fusion_cropping_margin_x: allows to set both fusion_cropping_margin_x_0 and fusion_cropping_margin_x_1

  • fusion_cropping_margin_y: allows to set both fusion_cropping_margin_y_0 and fusion_cropping_margin_y_1

  • fusion_cropping_margin_z: allows to set both fusion_cropping_margin_z_0 and fusion_cropping_margin_z_1

  • fusion_cropping_margin: allows to set the six margin variables.

  • fusion_weighting: Possible values are ‘uniform’, ‘ramp’, ‘corner’, or ‘guignard’. Allows to set the weighting function used to compute the weighted linear combination of the 4 co-registered acquisitions (for all channels to be processed).

    • 'uniform': uniform (or constant) weighting, it comes to the average of the resampled co-registered stacks

    • 'ramp': the weights are linearly increasing or decreasing along the Z axis

    • 'corner': the weights are constant in a corner portion of the stack, defined by two diagonals in the XZ-section

    • 'guignard': original historical weighting function, described in Leo Guignard’s Phd thesis [Gui15], that puts more weight to sections close to the camera and take also account the traversed material.

    Setting the variable xzsection_extraction to True (or some adequate value) allows to see the weights used for the extracted XZ sections. See section Stacks non-linear co-registration.

  • fusion_weighting_channel_1: set the weighting function for the weighted sum of the registered acquisition stacks for the first channel (in case of multi-channel acquisition).

  • fusion_weighting_channel_2: set the weighting function for the weighted sum of the registered acquisition stacks for the second channel (in case of multi-channel acquisition).

  • fusion_weighting_channel_3: set the weighting function for the weighted sum of the registered acquisition stacks for the third channel (in case of multi-channel acquisition).

The following parameters are kept for backward compatibility:

  • fusion_crop same as fusion_cropping

  • fusion_margin_x_0 same as fusion_cropping_margin_x_0

  • fusion_margin_x_1 same as fusion_cropping_margin_x_1

  • fusion_margin_y_0 same as fusion_cropping_margin_y_0

  • fusion_margin_y_1 same as fusion_cropping_margin_y_1

  • fusion_xzsection_extraction same as xzsection_extraction

  • raw_crop same as acquisition_cropping

  • raw_margin_x_0 same as acquisition_cropping_margin_x_0

  • raw_margin_x_1 same as acquisition_cropping_margin_x_1

  • raw_margin_y_0 same as acquisition_cropping_margin_y_0

  • raw_margin_y_1 same as acquisition_cropping_margin_y_1

  • raw_mirrors same as acquisition_mirrors

  • raw_ori same as acquisition_orientation

  • raw_resolution same as acquisition_resolution

  • begin: first time point of the series to be processed. See section Important parameters in the parameter file.

  • delta

  • end: last time point of the series to be processed. When testing or tuning parameters, it is advised not to processed the whole series, but only one or a few time points. See section Important parameters in the parameter file.

  • fusion_weighting

  • fusion_weighting_channel_1

  • fusion_weighting_channel_2

  • fusion_weighting_channel_3

  • raw_delay

15.12. astec_intraregistration parameters

These parameters are prefixed by intra_registration_.

  • Registration parameters (see section Step 5 parameters: image co-registration)

  • reference_index: defines the still image after transformation compositions it will only translated, except if reference_transformation_file or reference_transformation_angles are set. See section Step 3: template building.

  • reference_transformation_file: resampling transformation to be applied to the reference image (and to the whole serie) after transformation compositions. See section Step 3: template building.

  • reference_transformation_angles: list of rotations wrt the X, Y,or Z axis that defines the resampling transformation.

    reference_transformation_angles = 'X 30 Y 50'
    

    represents a rotation of 30 degree around the X axis followed by a rotation of 50 degrees around the Y axis.

    Beware: rotation composition depends on the order, so 'X 30 Y 50' is not equivalent to 'Y 50 X 30'.

  • template_type Possible values are ‘FUSION’, ‘SEGMENTATION’, or ‘POST-SEGMENTATION’ The template is built so that the useful information of all resampled images fits into it. Useful information can be issued from either the fused sequence, the segmentation sequence or the post-segmentation sequence.

  • template_threshold Giving a threshold with the template_type, only points above the threshold are considered to be included in the template after resampling, this allows to reduce the template. According the background value is either 0 or 1 in both the segmentation and the post-segmentation sequences, setting this threshold to 2 for these sequences allows to keep the entire embryo in the resampled/reconstructed sequence.

  • margin In addition, a margin can be given for a more comfortable visualization. By default, it is 0 when only fusion images are used, and 10 if either segmentation or post-segmentation images are also used.

  • resolution gives the resulting (isotropic) voxel size (as the ‘target_resolution’ gives the voxel size of the fused images). However, for visualization purposes, it may be indicated to have a larger voxel size (hence the 0.6 instead of 0.3)

  • rebuild_template: True or False. If set to True, force to recompute the template as well as the transformations from existing co-registrations (that are not re-computed). It is useful when a first intra-registration has been done with only the fusion images: a second intra-registration with the segmentation images as template can be done without recomputing the co-registrations.

  • sigma_segmentation_images Sigma to smooth (post-)segmentation images when resampling.

  • resample_fusion_images Possible values are True or False

  • resample_reconstruction_images Possible values are True or False

  • resample_segmentation_images Possible values are True or False

  • resample_post_segmentation_images Possible values are True or False

  • movie_fusion_images Possible values are True or False. To build 2D+t movies from the resampled fusion images.

  • movie_segmentation_images Possible values are True or False. To build 2D+t movies from the resampled segmentation images.

  • movie_post_segmentation_images Possible values are True or False. To build 2D+t movies from the resampled post-segmentation images.

  • xy_movie_fusion_images List of XY-sections used to build the 2D+t movies eg xy_movie_fusion_images = [100, 200]

  • xz_movie_fusion_images List of XZ-sections used to build the 2D+t movies eg xz_movie_fusion_images = [100, 200]

  • yz_movie_fusion_images List of YZ-sections used to build the 2D+t movies eg yz_movie_fusion_images = [100, 200]

  • xy_movie_segmentation_images

  • xz_movie_segmentation_images

  • yz_movie_segmentation_images

  • xy_movie_post_segmentation_images

  • xz_movie_post_segmentation_images

  • yz_movie_post_segmentation_images

  • maximum_fusion_images Possible values are True or False. Build a maximum image from the resampled series. It may be useful to define a cropping valid area for the whole sequence.

  • maximum_segmentation_images

  • maximum_post_segmentation_images

15.13. astec_mars parameters

These parameters are prefixed by mars_.

  • first_time_point: first time point to be segmented by the mars method. Overrides the value of the begin variable.

  • last_time_point: last time point to be segmented by the mars method.

  • Watershed parameters (see section Watershed parameters)

  • Seed edition parameters (see section Seed edition parameters)

  • Preprocessing parameters (see section Preprocessing parameters) prefixed by seed_

  • Preprocessing parameters (see section Preprocessing parameters) prefixed by membrane_

15.14. astec_manualcorrection parameters

  • Diagnosis parameters (see section Diagnosis parameters)

  • Astec parameters (see section astec_astec parameters)

  • first_time_point: first time point to be corrected. Overrides the value of the begin variable.

  • last_time_point: last time point to be corrected.

  • input_image: defines the input file names (to be used when correcting other files than the astec_mars output file.

  • output_image: defines the output file names (to be used when correcting other files than the astec_mars output file.

  • manualcorrection_dir: path to directory where to find the mapping file.

  • manualcorrection_file: path to mapping file for manual correction of a segmentation (ie label) image. See above the syntax of this file.

    • 1 line per label association

    • background label has value 1

    • the character # denotes commented lines

    Example of mapping_file:

    # a line beginning by '#' is ignored (comment)
    
    # lines with only numbers concern changes for the first time point of the time series
    # or the only time point when correcting the segmentation of the first time point
    # - one single number: label of the cell to be divided at the first time point
    # - several numbers: labels of the cells to be fused
    # Hence
    
    8
    # means that cell of label 8 have to be splitted
    
    9 2 7
    # means that cells of label 9, 7, and 2 have to be fused
    
    30 1
    # means that cell of label 30 have to be fused with the background (of label 1)
    
    # lines beginning by 'timevalue:' concern changes for the given time point
    # - 'timevalue:' + one single number: label of the cell to be splitted
    # - 'timevalue:' + several numbers: labels of the cells to be fused
    # Note there is no space between the time point and ':'
    
    8: 7
    # means that cell of label 7 of time point 8 have to be splitted
    
    10: 14 12 6
    # means that cells of label 14, 12 and 6 of time point 10 have to be fused
    
    # lines beginning by 'timevalue-timevalue:' concern changes for the given time point range
    # - 'timevalue-timevalue:' + several numbers: labels of the cells to be fused
    
    10-12: 14 16
    # means that cells of label 14 and 16 of time point 10 have to be fused
    # their offspring will be fused until time point 12
    
  • use_new_labels: True or False. If set to True, try to use new labels when encountering a division to be made. Divisions will be pursued with the same two (new) parameters whenever possible.

15.15. astec_astec parameters

These parameters are prefixed by astec_.

  • Watershed parameters (see section Watershed parameters)

  • Preprocessing parameters (see section Preprocessing parameters) prefixed by seed_

  • Preprocessing parameters (see section Preprocessing parameters) prefixed by membrane_

  • Preprocessing parameters (see section Preprocessing parameters) prefixed by morphosnake_

  • Morphosnake parameters (see section Morphosnake parameters)

  • propagation_strategy:

    • 'seeds_from_previous_segmentation'

    • 'seeds_selection_without_correction'

  • previous_seg_method: how to build the seeds \(S^e_{t-1 \leftarrow t}\) for the computation of \(\tilde{S}_{t}\)

    • 'deform_then_erode': \(S^{\star}_{t-1}\) is transformed towards \(I_t\) frame through \(\mathcal{T}_{t-1 \leftarrow t}\), and then the cells and the background are eroded.

    • 'erode_then_deform': historical method. The cells and the background of \(S^{\star}_{t-1}\) are eroded, and then transformed towards \(I_t\) frame through \(\mathcal{T}_{t-1 \leftarrow t}\).

  • previous_seg_erosion_cell_iterations: set the cell erosion size for \(S^e_{t-1 \leftarrow t}\) computation.

  • previous_seg_erosion_background_iterations: set the background erosion size for \(S^e_{t-1 \leftarrow t}\) computation.

  • previous_seg_erosion_cell_min_size: size threshold. Cells whose size is below this threshold will be discarded seeds in \(S^e_{t-1 \leftarrow t}\)

  • watershed_seed_hmin_min_value: set the \(h_{min}\) value of the \([h_{min}, h_{max}]\) interval.

  • watershed_seed_hmin_max_value: set the \(h_{max}\) value of the \([h_{min}, h_{max}]\) interval.

  • watershed_seed_hmin_delta_value set the \(\delta h\) to go from one \(h\) to the next in the \([h_{min}, h_{max}]\) interval.

  • background_seed_from_hmin: True or False. Build the background seed at time point \(t\) by cell propagation.

  • background_seed_from_previous: True or False. Build the background seed at time point \(t\) by using the background seed from \(S^e_{t-1 \leftarrow t}\). Fragile.

  • seed_selection_tau: Set the \(\tau\) value for division decision (seed selection step).

  • minimum_volume_unseeded_cell: Volume threshold for cells without found seeds in the seed selection step. Cells with volume (in \(\tilde{S}_t\)) whose size is below this threshold and for which no seed was found are discarded.

  • volume_ratio_tolerance: Ratio threshold to decide whether there is a volume decrease (due to the background) for morphosnake correction.

  • volume_ratio_threshold: Ratio threshold to decide whether there is a large volume decrease for segmentation consistency checking.

  • volume_minimal_value: Size threshold for seed correction step. For a given cell at time point \(t-1\), if the corresponding cell(s) at time point \(t\) has(ve) volume below this threshold, they are discarded (and the cell at time point \(t-1\) has no lineage.

  • morphosnake_correction: True or False.

  • outer_correction_radius_opening

15.16. astec_postcorrection parameters

These parameters are prefixed by postcorrection_.

  • volume_minimal_value branch ending with leaf cell below this value are candidate for deletion. Expressed in voxel unit.

  • lifespan_minimal_value

  • test_early_division

  • test_volume_correlation

  • correlation_threshold

  • test_postponing_division

  • postponing_correlation_threshold

  • postponing_minimal_length

  • postponing_window_length

  • lineage_diagnosis performs a kind of diagnosis on the lineage before and after the post-correction.