8. Parameters

The different command line interfaces, or CLIs, (ascidian_atlas, etc.) requires a parameter file (which is nothing but a python file) that contains specific parameters for the CLIs.

8.1. Prefixed parameters

See the prefixed parameters section of Astec documentation.

8.2. Embryo symmetry parameters

Embryo co-registration can be made efficiently by using embryo symmetry axis candidates, by first computing the distribution of the surface normals, and then extracting the maxima.

• direction_sample: Samples (vectors) that will be used to computed the direction distribution via kernel density estimation. In all cases, the used vectors are unit vectors derived from the vector joining the barycenters of a couple of cells.

  • 'contact-surface': cell couples are adjacent cells. Samples (ie vectors) are weighted by the contact surfaces of the adjacent cells. It comes to mimic G. Michelin approach to estimate the direction distribution

  • 'symmetric-cell': for each cell, a list of potential symmetric cells is build and sorted by decreasing likelihood. A neighborhood-based similarity (in [0,1]) is computed to estimate the likelihood. The first 'symmetric_cell_number' (ie the first 'symmetric_cell_number' cells that are candidate to be the symmetrical cells), hence there can be more than one sample per cell. Samples are weighted by the total cell surface times (1.0 - similarity)

• symmetric_cell_number: Number of cells used as candidates to be the symmetrical cell. 'symmetric_cell_number = 1' means there is only one candidate per cell.

• symmetric_cell_similarity: Method to compute the similarity between a cell and an other cell candidate to be the symmetrical of the first one. For the two cells to be compared, neighbors are paired and a difference measure is computed for every neighbor pair and summed up. The sum is then divided by the sum of the two cell surfaces, which ensures that the computed similarity is in [0, 1].

  • 'sorted-contact': the neighbors of the two cells to be compared are sorted in decreasing order (based on contact surfaces) and then paired. The difference measure is the difference of contact surfaces. This is exactly the distance used to name cells except that the pairing is done based on contact surface values except of cell names.

  • 'winged-contact': (unit) vectors joining a cell to its neighbors are used here. Let c and d be the cells to be compared, \(c(i)\) be the contact surface of a neighbor \(i\) of \(c\) and \(\mathbf{v}(i)\) the unit vector joining the barycenter of \(c\) to the one of \(i\). Let \(\mathbf{dc}\) be the unit vector joining the barycenter of \(c\) and \(d\). Vectors \(\mathbf{v}(j)\) of neighbors \(j\) of \(d\) are ‘symmetrised’ by \(\mathbf{v}'(j) = \mathbf{v}(j) - 2 (\mathbf{v}(j).\mathbf{dc}) \mathbf{dc}\) The difference measure is \(\|c(i)\mathbf{v}(i) - c(j)\mathbf{v}'(j)\|\) which is the contact surface difference if the two vectors \(\mathbf{v}(i)\) and \(\mathbf{v}'(j)\) are equal. Differences are computed for every couple \((i,j)\) and optimal pairing is done through scipy.optimize.linear_sum_assignment()

• distribution_sphere_radius: sphere radius to build the distribution support. The direction distribution is computed onto a discrete sphere, ie a sphere made of voxels. The larger the sphere, the more accurate the mode estimation, but the longer the computation.

  • radius = 10: 978 vectors, angle between neighboring vectors in [4.40, 10.58] degrees

  • radius = 15: 2262 vectors, angle between neighboring vectors in [2.98, 6.93] degrees

  • radius = 20: 4026 vectors, angle between neighboring vectors in [2.25, 5.16] degrees

  • radius = 25: 6366 vectors, angle between neighboring vectors in [1.73, 4.01] degrees

  • radius = 30: 9194 vectors, angle between neighboring vectors in [1.46, 3.40] degrees

  • radius = 35: 12542 vectors, angle between neighboring vectors in [1.26, 2.90] degrees

  • radius = 40: 16418 vectors, angle between neighboring vectors in [1.08, 2.53] degrees

• distribution_kernel_sigma: Sigma (standard deviation) to build the direction distribution (in radian). The distribution is built through a Gaussian kernel density estimation.

• direction_maxima_threshold: Threshold on the distribution value. Only maxima above this threshold are kept. Recall that the distribution values are normalize so that the maximum is 1.

• direction_maxima_number: Number of distribution maxima to be retained as symmetry axis candidates. None or negative number means all of them. Since the distribution is computed onto a sphere, both the surface normal and its opposite contribute to the distribution estimation. It comes out that each symmetry direction is represented by two (opposite) vectors, meaning that this parameter has to be even.

8.3. Diagnosis parameters

• Astec Diagnosis parameters

• 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]).

8.4. Atlas parameters

• Diagnosis parameters (see section Diagnosis parameters)

• Embryo symmetry parameters (see section Embryo symmetry parameters)

• atlasFiles: list of atlas files. An atlas file is a property file that contains lineage, names, and contact surfaces for an embryo.

• referenceAtlas: reference atlas. Use for time alignment of atlases. If not provide, the first atlas of atlasFiles is used as reference. Warning, the reference atlas has to be in atlasFiles list also.

• outputDir: output directory where to write atlas-individualized output files, ie morphonet selection files or figure files.

• atlas_diagnosis: True or False. Performs some diagnosis when reading an additional property file into the atlases. Incrementing the verboseness (-v in the command line) may give more details.

• generate_figure: if True, generate python files (prefixed by figures_) that generate figures. Those files will be saved into the outputDir directory. generate_figure can be

  • a boolean value: if True, all figure files are generated; if False, none of them

  • a string: if 'all', all figure files are generated; else, only the specified figure file is generated (see below for the list)

  • a list of strings: if 'all' is in the list, all figure files are generated; else, only the specified figure files are generated (see below for the list)

  List of figures (see section Gallery):

  • 'cell-count-wrt-time': plot the number of cells wrt time point (ie image indices) without and with temporal registration wrt to the total cell count (allows to assess the temporal registration).

  • 'epidermis-cell-count-wrt-time': plot the number of epidermis cells wrt time point (ie image indices) without and with temporal registration wrt to the epidermis cell count (allows to assess the temporal registration).

  • 'name-composition-wrt-time': plot the number of names wrt time point (normalized time ie after temporal registration), and separate between names present in all embryos and others. It offers a means to visually assess the heterechronocity of divisions.

  • 'embryo-volume': plot the embryo volume (in voxel) without and with temporal registration (computed from cell number). The decreasing volume of embryos can be visually assessed, as well as the linear regression (for intra- and inter-embryo volume normalization)

  • 'neighbors-wrt-cell-number': plot the cell number in the cell neighborhood wrt the total cell number in the embryo

  • 'leftright-symmetry-axis': plot the error of the best symmetry axes (the closest to the one estimated with cell names), as well as its rank with respect to the distribution value. Warning: it may be long.

  • 'division-timeinterval': plot the length of the time interval where cell division occurs. For a given cell (defined by its name), the intra-embryo time interval is computed by comparing the division time for the left and the right side, the inter-embryo time interval is computed by substracting the smallest division time from the largest one. Times are normalized (see figure 'cell-count-wrt-time').

  • 'division-order':

  • 'cell-distance-along-branch': plot the cell-to-cell distance between successive along a branch (a cell without division) wrt the distance to the first cell. Cell neighborhoods are expressed with the neighbors of the first cell of the branch (thus it ignores divisions occurring in the cell neighborhood during the cell life)

  • 'cell-distance-histograms': plot cell-to-cell distance histograms. Warning: it may be long.

  • 'division-distance-histograms': plot division-to-division distance histograms.

  • 'distance-histograms': plot cell-to-cell distance histograms, as well as division-to-division distance histograms. Warning: it may be long.

  • 'division-dendrograms': draw a dendrogram per division where atlases are grouped with distance between divisions

• figurefile_suffix: suffix used to named the above python files as well as the generated figures.

• name_delay_from_division: Delay from the division to extract the neighborhooods used for atlas building, and thus for naming. 0 means right after the division. Negative values means that the delay is counted backwards from the end of the branch.

• confidence_delay_from_division: Delay from the division to extract the neighborhooods used for naming confidence. 0 means right after the division. Negative values means that the delay is counted backwards from the end of the branch.

• delay_from_division: set both name_delay_from_division and confidence_delay_from_division.

• add_symmetric_neighborhood: if True, add the symmetric neighborhood as additional exemplar. It means that left and right embryo hemisphere are considered together.

• differentiate_other_half: if True, differentiate the cells of the symmetric half-embryo. If ‘False’, consider all the cells of the symmetric half-embryo as a single cell. This option has been introduced for test purpose. Please do not consider changing its default value (True)

• use_common_neighborhood: the same cell has different neighbors from an atlas to the other. If ‘True’ build and keep an unique common neighborhood (set of neighbors) for all atlases by keeping the closest ancestor for neighboring cells. Eg, if a division has occurred in some embryos and not in others, daughter cells will be somehow fused so that all neighborhoods only exhibit the parent cell. Please do not consider changing its default value (True).

• cell_normalization: Embryos/atlases have different volumes, and their volume decrease with time. To compare surfaces and/or volumes, a normalization is required. I can be chosen among:”

  • None: no normalization (for test purpose)

  • 'local': normalization by the cell surface. The normalization factor is then different from cell to cell within a embryo, and obviously for the two daughter cells resulting from a division

  • 'global': normalization by embryo volume. The normalization factor is for all the cells from the same time point within a embryo. It changes along time to compensate for the volume decrease.

8.5. ascidian_atlas parameters

These parameters are prefixed by atlas_.

• Atlas parameters (see section Atlas parameters)

• exclude_inner_surfaces: True or False. Exclude inner surfaces from the division-to-division distance calculation.

• division_diagnosis: True or False. Performs some diagnosis after building the division atlas. Incrementing the verboseness (‘-v’ in the command line) may give more details.

• division_permutation_proposal: it True, will propose some daughters switches in the atlases. For a given division, a global score is computed as the sum of all pairwise division similarity. A switch is proposed for an atlas if it allows to decrease this global score.

• dendrogram_cluster_distance: cluster distance used to build dendrograms. Dendrograms are used either for diagnosis purpose (if diagnosis_properties is set to True) or to generate figures (if generate_figure is set to True) See scipy.cluster.hierarchy.linkage documentation. Choices are:

  • 'single'

  • 'complete'

  • 'average'

  • 'weighted'

  • 'centroid'

  • 'median'

  • 'ward'

• write_selection: write morphonet selection file on disk.

8.6. Embryo registration parameters

• rotation_initialization: to coregister two embryos, a first 3D rotation is done that align vectors issued from the floating embryo (the embryo to be named) onto vectors issued from the reference embryo (an already named embryo)

  • 'sphere_wrt_z': an uniform sampling of 3D directions is done for the floating embryo (parameter ‘direction_sphere_radius’) while the ‘z’ direction is used for the reference embryo

  • 'sphere_wrt_symaxis': an uniform sampling of 3D directions is done for the floating embryo (parameter direction_sphere_radius) while one (out of two) vector defining the symmetry axis direction is used for the reference embryo (to be used for test purposes)

  • 'symaxis_wrt_symaxis': symmetry axis vector candidates are used for the floating embryo (embryo symmetry parameters, see section Embryo symmetry parameters) while one (out of the two) vector defining the symmetry axis (estimated from the cell name) is used for the reference embryo.

• direction_sphere_radius: to get an uniform sampling of the 3d directions in space (options 'sphere_wrt_z' and 'sphere_wrt_symaxis' of rotation_initialization), a discrete sphere is build and each point of the outer surface gives a sample. The larger the radius, the more vectors and the higher computational time.

  • radius = 2.0: 26 vectors, angle between neighboring vectors in [36.26, 60.0] degrees

  • radius = 2.3: 38 vectors, angle between neighboring vectors in [26.57, 54.74] degrees

  • radius = 2.5: 54 vectors, angle between neighboring vectors in [24.09, 43.09] degrees

  • radius = 2.9: 66 vectors, angle between neighboring vectors in [18.43, 43.09] degrees

  • radius = 3.0: 90 vectors, angle between neighboring vectors in [17.72, 43.09] degrees

  • radius = 3.5: 98 vectors, angle between neighboring vectors in [15.79, 32.51] degrees

  • radius = 3.7: 110 vectors, angle between neighboring vectors in [15.26, 32.51] degrees

  • radius = 3.8: 134 vectors, angle between neighboring vectors in [14.76, 29.50] degrees

  • radius = 4.0: 222 vectors, angle between neighboring vectors in [10.31, 22.57] degrees

  • radius = 5.0: 222 vectors, angle between neighboring vectors in [10.31, 22.57] degrees

• 'z_rotation_angle_increment': increment (in degrees) between two successive angles when enumerating rotations along the z or the symmetry axis

• transformation_filename: file name to save or to read the transformations between the embryos. Useful when parsing name choice parameters (for test purposes then).

• pair_ratio_for_residual: the optimal transformation between two embryos is the one giving the smallest residual value. The residual value of a transformation is the sum of the smallest distances between paired points. This parameter gives the ratio of points to be retained (default value issued from G. Michelin’s thesis [Mic16]).

• processors: number of processors for parallelization

8.7. ascidian_atlas_init_naming parameters

• Embryo registration parameters (see section Embryo registration parameters)

• Atlas parameters (see section Atlas parameters)

• generate_figure: see section Atlas parameters. Additional figure file generations are available (see section Gallery):

  • 'atlas-naming-register-leave-one-out-wrt-atlases': plot leave-one-out results when naming one atlas out the atlasFiles with all combination of the other atlases (from combinations of 1 atlas to combinations of N-1 atlases). Results are plotted wrt the number of atlases used for naming. Setting 'transformation_filename' (see section Embryo registration parameters) allows to keep/reuse computed embryo-to-embryo transformations. Warning: it may be long (embryo-to-embryo transformation calculation and quality estimation).

  • 'atlas-naming-register-leave-one-out-wrt-cells' plot leave-one-out results when naming one atlas out the atlasFiles with all the other atlases (for a series of cell counts). Results are plotted wrt cell count. Setting 'transformation_filename' (see section Embryo registration parameters) allows to keep/reuse computed embryo-to-embryo transformations. Warning: it may be long (embryo-to-embryo transformation calculation).

• inputFile: Input property file to be named. Must contain lineage, volumes and contact surfaces

• outputFile: Output property file.

• cell_number Cell number of the developmental stade to be named

• check_duplicate: True or False. After naming, check whether some names are duplicated, and, if yes, remove them

• check_volume: True or False. After naming, check whether the named cell volume is coherent with its mother/daughters volumes. May be set to False for the 64- or 112-stages where the cells are assumed to be the same among embryos.

• testFile: input property file to be tested (must include cell names). If given, inputFile is ignored.

8.8. ascidian_atlas_naming parameters

These parameters are prefixed by naming_.

• ascidian_atlas parameters (see section ascidian_atlas parameters).

• inputFile: input property file to be named. Must contain lineage and contact surfaces as well as some input names (one time point should be entirely named).

• outputFile: output property file.

• selection_method: decision method to name the daughters after a division. Distances are computed between the couple of daugthers to be named as well as the couple of switched daughters and all the atlas divisions.

  • 'mean': choose the couple of names that yield the minimal average distance over all the atlases.

  • ‘minimum’: choose the couple of names that yield a minimal distance. It comes to name after the closest atlas (for this division).

  • 'sum': same as mean.

  • 'majority': for each choice, order the distances in increasing order then compute the cumulated sum over the n first elements (so the first is the minimum distance, and the last one is the average over all atlases). Counts then the number of times when a choice is better than the switched one, and choose the name couple with majority choices.

• confidence_atlases_nmin: minimum number of atlases required to assess naming confidence. If there is not enough atlases in the database for the aimed division, naming is not assessed.

• confidence_atlases_percentage: percentage of atlases (for a given division) used to assess naming confidence. If the percentage is less than ‘confidence_atlases_nmin’, ‘confidence_atlases_nmin’ atlases are used.

• testFile: input property file to be tested (must include cell names), for instance for

  leave-one-out test. 64-cells time point is searched, cell names at other time points are deleted and the embryo is entirely renamed from this given time point. Comparison between new names and actual ones are reported. If given, inputFile is ignored.

• test_diagnosis: if True, some diagnosis are conducted on the property file to be tested.

• generate_figure: see section Atlas parameters. Additional figure file generations are available (see section Gallery):

  • 'atlas-naming-distance': plot the average (division-to-division) distances used to name after a division

• atlas_naming_distance_mintime: First time point to be considered when drawing the figure 'atlas-naming-distance'

• atlas_naming_distance_maxtime: Last time point to be considered when drawing the figure 'atlas-naming-distance'