# Tunacell’s data model¶

tunacell’s top level data structure matches input files scaffold. Raw data is stored in Cell instances connected through a tree structure arising from cell divisions.

## Top level structures: Experiment and Container¶

tunacell’s top level structure is Experiment and handles the experiment. We refer to the API documentation for details about attributes and methods. In particular, it stores the list of container files that allows to open/read such containers.

These are stored under Container instances, which label is set by file name. Such objects gets two major attributes: cells and trees. The former is the list of Cell instances imported from raw data file, the latter is the list of reconstructed trees formed by dividing cells, stored as Colony instances.

## Low-level structures: Cell and Colony¶

These classes are derived from the treelib package Node and Tree classes respectively.

Raw data is stored under the data attribute of Cell instances.

Methods are defined at the Container level to retrieve objects corresponding to an identifier. More importantly there is an iterator over colonies that can be used when parsing data for statistical analysis.

## Tree decomposition: Lineage¶

For studying dynamics over times larger than one or few cell cycles, it is necessary to build timeseries of observables over sequences of more than one cells.

We use features from the treelib package to decompose trees in independent lineages. A lineage is a sequence $${c_i}_i$$ of cells related through successive divisions: cell $$c_i$$ is a daughter of cell :mathc_{i-1}, and the mother of cell $$c_{i+1}$$.

One way to decompose a tree in lineages is to build the sets of lineages from root to all leaves. Such decomposition implies that some cells may belong to more than one lineage. Using such decomposition require some statistical weighting procedure.

To avoid such weighting procedure, we used a decomposition in independent lineages. Such decomposition ensures that each cell is counted once and only once. More specifically our method to decompose a tree in independent lineages is to traverse the tree starting from the root and choosing randomly one daughter cell at each division until a leaf is reached, repeatidly.

A lineage is defined as a Lineage instance. Such object gets method to build the corresponding timeseries for a given observable.