pycellin 0.5.0

Graph-based framework to manipulate and analyze cell lineages from cell tracking data

Pycellin

Pycellin is a graph-based Python framework to easily manipulate and extract information from cell tracking data, at the single-cell level. In pycellin, cell lineages are modeled intuitively by directed rooted trees. Graph nodes represent cells at a specific point in time and space, and graph edges represent the time and space displacement of the cells. Please note that while pycellin is built to support cell division events, it does not authorize cell merging events: a cell at a specific timepoint cannot have more than one parent.

Pycellin provides predefined properties related to cell morphology, cell motion and tracking that can be automatically added to enrich lineages. More predefined properties will be implemented in the future. The framework also facilitates the creation of new properties defined by the user to accommodate the wide variety of experiments and biological questions.

Pycellin can read from and write to:

• Cell Tracking Challenge text files,
• GEFF (Graph Exchange File Format,)
• trackpy DataFrames.
• TrackMate XMLs,

More tracking formats will progressively be supported.

Although pycellin was designed with bacteria / cell lineages in mind, it can be used with more diverse tracking data. The main requirement is that the data can be modeled by directed rooted trees, meaning no merging event.

Installation

Pycellin supports Python 3.10 and above. It is tested with Python 3.10 and 3.13 on the latest versions of Ubuntu, Windows and MacOS. Please let me know if you encounter any compatibility issue with a different combination.

It is recommended to install pycellin in a conda or mamba environment.

1. Check that conda/mamba is already installed by typing either conda or mamba in a terminal. If not, follow the installation instructions on Miniforge.

2. Create a Python environment dedicated to pycellin:

   conda create -n my_env_pycellin
   

3. Activate the environment:

   conda activate my_env_pycellin
   

4. Install pycellin via PyPI:

   pip install pycellin
   

   or if you want to install the optional test related dependencies use instead:

   pip install pycellin[test]
   

5. You're good to go!

Code Example

import pycellin

# Import data from an external tool, here TrackMate.
xml_path = "sample_data/Ecoli_growth_on_agar_pad.xml"
model = pycellin.load_TrackMate_XML(xml_path)

# Plot the cell lineages.
for lin in model.get_cell_lineages():
    plot(lin)

# Compute and plot the cell cycle lineages.
model.add_cycle_data()
for clin in model.get_cycle_lineages():
    plot(clin)

# Enrich your lineages with additional predefined properties.
model.add_pycellin_properties([
    "rod_length", 
    "rod_width",
    "cell_displacement", 
    "cell_speed", 
    "branch_mean_speed",
    "relative_age",
    "division_time", 
    "cycle_completeness",
    ])
model.update()

# Export the enriched data as dataframes...
cell_df = model.to_cell_dataframe()
link_df = model.to_link_dataframe()
cycle_df = model.to_cycle_dataframe()
lineage_df = model.to_lineage_dataframe()

# ... or export back to TrackMate...
pycellin.export_TrackMate_XML(
    model,
    "sample_data/Ecoli_growth_on_agar_pad_enriched.xml",
    units={
        "spatialunits": model.get_space_unit(),
        "temporalunits": model.get_time_unit(),
    },
    propagate_cycle_props=True,
)

# ... or to another file format.
pycellin.export_GEFF(
    model,
    "sample_data/Ecoli_growth_on_agar_pad_enriched.geff",
    time_axes=["POSITION_T"],
    space_axes=["cell_x", "cell_y", "cell_z"],
    variable_length_props=["ROI_coords"],
) 

Usage

Please note that the following notebooks are still a work in progress. There may be some mistakes in the code and some sections might move from one notebook to another.

Notebook	Description	Level	State
Getting started	The basics of pycellin, through examples	Beginner	WIP
Managing properties	How to add, compute and remove properties from a model	Beginner	WIP
Working with TrackMate data	How pycellin can work with TrackMate, through an example	Beginner	WIP
Creating a model from scratch	How to manually create a pycellin model, including its lineages	Advanced	Stub
Custom properties	How to create user-defined properties and augment a model with them	Advanced	WIP

Credits and references

• Laure Le Blanc for Escherichia coli growth on agar pad data (in sample_data directory)
• NetworkX for lineages modeling (Hagberg, Schult and Swart, 2008)
• TrackMate for the TrackMate data loader and exporter (Tinevez et al., 2017, Ershov et al., 2022)
• The Cell Tracking Challenge for the CTC data loader and exporter (Maška et al., 2023)
• trackpy for the trackpy data loader and exporter (Allan et al., 2024)