3. ascidian_embryo

ascidian_embryo can be used to assess the quality/coherency of a set of already named ascidian embryos (or atlases) as well to point out potential corrections. It assumes that the set (or mathematically speaking the vector) of valued surface contact of a named cell can be used as its signature.

ascidian_embryo can be used to

  • either, with a parameter file, assess the quality/coherency of a set of already named ascidian embryos (or atlases) as well to point out potential corrections; it assumes that the set (or mathematically speaking the vector) of valued surface contact of a named cell can be used as its signature;

  • or manipulate a property file (pkl or xml), in order to * convert an xml file into a pkl one (or conversely) * extract some features from a property file * compute cell fates from cell names * …

3.1. ascidian_embryo additional options

The following options are available (the updated list can be seen by ascidian_embryo -help):

-p | --parameters

parameter file

-e | --embryo-rep

path to the embryo data

-i | --input files ...

input files (pkl or xml) to be read

-o | --output files ...

output files (pkl or xml) to be read

-c | --compare files ...

files (pkl or xml) to be compared to those given by -i

-feature features ...

features to be extracted from the input files, that are to be written in the output files. Features have to be chosen in ‘lineage’, ‘h_min | volume | surface | sigma’, ‘label_in_time | barycenter | fate’, ‘all-cells | principal-value’, ‘name | contact | history | principal-vector’, ‘name-score | cell-compactness’ etc

-property features ...

same as -feature

--diagnosis

performs some test on the read properties

--diagnosis-minimal-volume DIAGNOSIS_MINIMAL_VOLUME

displays all cells with volume smaller than DIAGNOSIS_MINIMAL_VOLUME

--diagnosis-items DIAGNOSIS_ITEMS

minimal number of items to be displayed

-write-selection | --write-selection | -write-selections | --write-selections

write out morphonet selection files

-morphonet-directory | -mn-directory | -mn-dir

directory where to write morphonet files (created if required)

-morphonet-file-suffix | -mn-suffix

suffix to be added to morphonet file names

-morphonet-file-prefix | -mn-prefix

prefix to be added to morphonet file names

-name | --embryo-name

embryo key (name) for dictionary indexation

-tpf | --time-post-fertilization

default value for time after fertilization (minutes)’

-dt | --time-interval

default value for time interval (minutes)

-ref | -reference | --time-reference

reference embryo for time alignment/registratio and time post fertilization and time interval calculation

-ref-fate | -reference-fate | --time-reference-fate

fate for time alignment/registration. Ex: Epidermis

-ap | --compute-additional-property | --compute-additional-properties

add tissue fate, tissue fate color map, cell short name, and cell duration in the property file

-fate | --compute-fate

delete previous cell fate (if any) and recompute it, as well as a morphonet selection for cell colorization.

-name-map, --compute-name-map

compute name map for morphonet

--print-content | --print-keys

print keys of the input file(s) (read as dictionary)

3.2. Assess the quality of a set of named ascidian embryos

Each individual cell \(c^{R}_i\) (the cell \(c_i\) of atlas \(R\)) is represented by the vector of its contact surfaces \(c^{R}_i = \left( \begin{array}{c} s^{R}_{i,1} \\ \vdots \\ s^{R}_{i,j} \\ \vdots \end{array} \right)\).

From the cell-to-cell distance, a division-to-division similarity can be built, a division being represented by the couple of daughter cells (extracted at the distance delay_from_division from the division).

To enrich division exemplars, the symmetric division (of the other hemi-embryo) can be symmetrized (ie a7.0002_ will be changed in a7.0002*). This is governed by add_symmetric_neighborhood.

Thus, to assess the quality of a set of atlases, a typical parameter file may be

atlasFiles = []
atlasFiles += ['/path_to_reference_embryos/Astec-pm1.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm3.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm4.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm5.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm7.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm8.pkl']
atlasFiles += ['/path_to_reference_embryos/Astec-pm9.pkl']
#
# how to select cells
#
add_symmetric_neighborhood = True
use_common_neighborhood = True
delay_from_division = 3
#
# how to extract/display information
#
atlas_diagnosis = True
division_diagnosis = True
division_permutation_proposal = True
generate_figure = True
figurefile_suffix = 'some_suffix'

  • atlas_diagnosis and division_diagnosis may be quite verbose. It may be adviced to set them to True when introducing a new atlas, but not when using a set of already curated atlases. Two kinds of diagnosis are conducted.

    • atlas_diagnosis

      • on each single atlas/reference file, the name and the contact properties are assessed.

      • on the population of division neighborhoods:

    • division_diagnosis

      • pairwise disagreements: for a given cell and every couple of reference embryos, the distance of the two divisions (one per reference) is compared to the distance of one division compared to the other being switched. If the later is prefered, it is denoted as a disagreement.

      • linkage/dendrogram analysis: it is checked whether adding the switched divisions to the set of divisions changes the largest value of cluster distance in a dendrogram. If yes, it also suggest that some divisions may be switched. Individualized morphonet selection files are written (if write_selection is set to True) in the outputDir directory.

  • division_permutation_proposal may propose to switch the daughter names of some divisions. It calculates whether a name switch result in a global score improvement, and, if so, proposes the switch. It is somehow computationally costly. Individualized morphonet selection files are written (if write_selection is set to True) in the outputDir directory.

  • generate_figure will generate python files (in the outputDir directory) that, when executed, generates some figures. It is somehow computationally costly.

Section Naming propagation parameters provides a view on all the parameters.

3.3. Examples of use

3.3.1. Computing cell fates

According that the input property file input.pkl contains the cell_name property, the cell fates, which can be derived from the names, will be added to the existing properties in the output property file output.pkl

$ ascidian_embryo -i input.pkl -o output.pkl -fate

3.3.2. Computing color map from cell names

According that the input property file contains the cell_name property, a cell name based color map name_map will be added to the existing properties in the output property file output.pkl

$ ascidian_embryo -i input.pkl -o output.pkl -name-map

3.3.3. Calibration of the time post fertilization (tpf) and time interval

The imaging protocol of the data used in Gallery used a time interval of 2 minutes between two successive acquisitions, while the time post fertilization (tpf) of the first acquisition (more precisely, of the acquisition of index 0) is of 4 hours (or 240 minutes) [Gui15].

However, the temporal alignment of the developing embryos, based on the cell count, demonstrates that the imaged embryos have different development speed (section 8.1.1 and figure 8.1).

For comparison purpose, time post fertilization (tpf) and time interval of acquired sequences can be uniformized within a set of acquired sequences by choosing one of them as reference.

The following command allows to set the default values of time post fertilization (tpf) and time interval (dt) in the property file (input file Astec-pm8-properties.xml and output file ref-Pm8.xml) for a reference embryo.

$ ascidian_embryo -i Astec-pm8-properties.xml -o ref-Pm8.xml -dt 2 -tpf 240 -name Phmamm8

Looking at the property file,

...
<embryo_name>'Phmamm8'</embryo_name>
<temporal_alignment>
  <Phmamm8>
    <default>[1.0, 0.0]</default>
  </Phmamm8>
</temporal_alignment>
<embryo_time_post_fertilization>
  <Phmamm8>'240'</Phmamm8>
</embryo_time_post_fertilization>
<embryo_time_interval>
  <Phmamm8>'2'</Phmamm8>
</embryo_time_interval>

some additional markups (or keys for dictionaries issued from pkl files) appears:

  • embryo_name: name to represent the embryo. Set by the -name option. If not present, the embryo will be named after the name of its property file.

  • temporal_alignment: gives the coefficient of the linear temporal alignment. Here, it is the same embryo, hence \([1.0, 0.0]\)

  • embryo_time_post_fertilization: The value have been set to 240 (minutes).

  • embryo_time_interval The value have been set to 2 (minutes).

The following command allows to calibrate the values of time post fertilization (tpf) and time interval (dt) in the property file (input file Phmamm-20-v1_properties.xml and output file cal-Pm10.xml) with respect to a reference embryo (here ref-Pm8.xml).

$ ascidian_embryo -i ../V2-PROPERTIES/Phmamm-20-v1_properties.xml -o cal-Pm10.xml \
  -ref ref-Pm8.xml -name Phmamm20

Looking at the property file,

...
<embryo_name>'Phmamm20'</embryo_name>
<temporal_alignment>
  <Phmamm20>
    <default>[1.0, 0.0]</default>
  </Phmamm20>
  <Phmamm8>
    <default>[1.119314391783472, -32.638231933749445]</default>
  </Phmamm8>
</temporal_alignment>
<embryo_time_post_fertilization>
  <Phmamm20>240</Phmamm20>
  <Phmamm8>174.72353613250112</Phmamm8>
</embryo_time_post_fertilization>
<embryo_time_interval>
  <Phmamm20>2</Phmamm20>
  <Phmamm8>2.238628783566944</Phmamm8>
</embryo_time_interval>
...
<embryo_temporal_reference>'Phmamm8'</embryo_temporal_reference>
<embryo_temporal_reference_fate>'default'</embryo_temporal_reference_fate>

the same additional markups (or keys for dictionaries issued from pkl files) than for the reference embryo appears:

  • embryo_name: name to represent the embryo. Set by the -name option. If not present, the embryo will be named after the name of its property file.

  • temporal_alignment: gives the coefficient of the linear temporal alignment. Here, it is with respect to either the same embryo, hence \([1.0, 0.0]\), or the reference embryo (named Phmamm8) \([1.12, -32.64]\).

    Some details

    Coefficients \([\hat{a},\hat{b}]\) are the ones that optimize \(\min_{a,b} \sum_n \left( a t_f(n) + b - t_r(n)\right)^2\) where \(n\) is a cell count, \(t_f(n)\) is the acquisition time (aacquisition index) where the floating embryo has \(n\) cellswhile \(t_r(n)\) is the acquisition time where the reference embryo has \(n\) cells.

    Thus, we have here \(t_{8} = 1.12 * t_{20} - 32.64\) where \(t_{8}\) and \(t_{20}\) are respectively the acquisition times (integer values, then) of Phmamm8 and Phmamm20, Phmamm8 being the reference embryo. The value of 1.12 indicates that the development of Phmamm20 is faster than the one of Phmamm8, which is coherent since Phmamm20 has been imaged at \(20^{o}C\) and Phmamm8 at \(18^{o}C\).

  • embryo_time_post_fertilization: The calibrated value with respect to itself have been set to the default, ie 240 (minutes), while the calibrated value with respect to the reference Phmamm8 is 174.72.

  • embryo_time_interval The calibrated value with respect to itself have been set to the default, ie 2 (minutes), while The calibrated value with respect to the reference Phmamm8 is 2.24.

    Some details

    embryo_time_post_fertilization, \(tpf\), and embryo_time_interval, \(dt\), allowed to express the time \(\tau\): (in real units, here in minutes) from the acquisition indices \(t\): since the fertilization with \(\tau = dt * t + tpf\).

    Given that the acquisition indices \(t_f\) of a floating embryo are linked to the ones \(t_r\) of a reference embryo by \(t_r = a t_f + b\) one have \(\tau = dt_r * t_r + tpf_r = (dt_r * a) * t_f + (dt_r * b + tpf_r)\). Hence, the values of both the embryo_time_interval and the embryo_time_post_fertilization of the floating embryo in the reference embryo time \(\tau\) are respectively \(dt_r * a\) and \(dt_r * b + tpf_r\).

By default, the temporal alignment of the developing embryos is based on the total cell count. However, for some embryos (ie the ones treated by U0126, that have a pertubed development), this total cell count is not representative of the developmental speed. Since U0126 is not perturbing the epidermis cell, the temporal alignment can be done with the count of epidermis cells only (section 8.1.1 and figure 8.3).

To compute both the time post fertilization (tpf) and the time interval, this can be achieved by adding -ref-fate Epidermis to the command line (note the capital E).

$ ascidian_embryo -i ../V2-PROPERTIES/U0126-Pm1 -o cal-U0126-Pm1 \
  -ref ref-Pm8.xml -name Phmamm20 -ref-fate Epidermis

Note

The default behavior of the ascidian suite is to name the embryo after its property file (hence the file name Astec-pm8-properties.xml corresponds to an embryo named Astec-pm8-properties). This is how are named the embryos in the figures of Section 8. Using the option -name Phmamm8 allows to set the embryo name whatever the file name.

3.3.4. Writing morphonet files

Some properties can be exported in Morphonet format for use and/or display in this visualisation tool [LLC+19].

Using the option -write-morphonet will write all possible morphonet properties:

$ ascidian_embryo -i input.pkl -write-morphonet

Some of these properties can be computed on the fly. Eg

$ ascidian_embryo -i input.pkl -name-map -write-morphonet

will compute the cell name based colormap and write it out as a morphonet file. If one wants also to add to the input.pkl file, the command should be

$ ascidian_embryo -i input.pkl -o input.pkl -name-map -write-morphonet

Morphonet file outputs can be tuned with the options -morphonet-directory, -morphonet-file-suffix, and -morphonet-file-prefix.