pycellin 0.3.5b3__tar.gz

pycellin-0.3.5b3/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2023 Institut Pasteur Paris, Laura Xénard
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

pycellin-0.3.5b3/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.2
+Name: pycellin
+Version: 0.3.5b3
+Summary: Graph-based framework to manipulate and analyze cell lineages from cell tracking data
+Author-email: Laura Xénard <laura.xenard@pasteur.fr>
+Project-URL: Documentation, https://Image-Analysis-Hub.github.io/pycellin/
+Project-URL: Examples, https://Image-Analysis-Hub.github.io/pycellin/notebooks/
+Project-URL: Issues, https://github.com/Image-Analysis-Hub/pycellin/issues
+Project-URL: Source, https://github.com/Image-Analysis-Hub/pycellin/
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: igraph>=0.9
+Requires-Dist: lxml>=5
+Requires-Dist: matplotlib>=3
+Requires-Dist: networkx>=3
+Requires-Dist: pandas>=2
+Requires-Dist: plotly>=5
+Requires-Dist: scikit-image>=0.19
+Requires-Dist: scipy>=1.15
+Requires-Dist: shapely>=2
+Provides-Extra: test
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-cov>=6.0; extra == "test"
+
+![Build](https://github.com/Image-Analysis-Hub/pycellin/actions/workflows/build.yml/badge.svg)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# 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 acyclic graphs (DAG). 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 features related to cell morphology, cell motion and tracking that can be automatically added to enrich lineages. More predefined features will be implemented in the future. The framework also facilitates the creation of new features defined by the user to accommodate the wide variety of experiments and biological questions.
+
+Pycellin can read from and write to TrackMate XML and Cell Tracking Challenge text file formats. More tracking formats will progressively be supported.
+
+While Pycellin has been designed with bacteria / cell lineages in mind, it could be used with more diverse tracking data provided the few conditions below are enforced:
+- the tracking data can be modeled by a DAG, meaning no merging event
+- time must flow homogeneously, i.e. all the edges of a lineage graph must represent the same elapsed time.
+
+
+## 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.
+
+You can install Pycellin from [PyPI](https://pypi.org/):
+
+```
+pip install pycellin
+```
+
+To install Pycellin with the optional test related dependencies:
+
+```
+pip install pycellin[test]
+```
+
+
+## Code Example
+
+```python
+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 features.
+model.add_pycellin_features([
+    "cell_length", 
+    "cell_width",
+    "cell_displacement", 
+    "cell_speed", 
+    "branch_mean_speed",
+    "relative_age",
+    "division_time", 
+    "division_rate",
+    "cell_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()
+```
+
+
+## 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](./notebooks/Getting%20started.ipynb)                                   | The basics of Pycellin, through examples                          | Beginner | WIP   |
+| [Managing features](./notebooks/Managing%20features.ipynb)                               | How to add, compute and remove features from a model              | Beginner | WIP   |
+| [Working with TrackMate data](./notebooks/Working%20with%20TrackMate%20data.ipynb)       | How Pycellin can work with TrackMate, through an example          | Beginner | WIP   |
+| [Creating a model from scratch](./notebooks/Creating%20a%20model%20from%20scratch.ipynb) | How to manually create a Pycellin model, including its lineages   | Advanced | Stub  |
+| [Custom features](./notebooks/Custom%20features.ipynb)                                   | How to create user-defined features and augment a model with them | Advanced | WIP   |
+
+
+## Credits
+
+- [NetworkX](https://networkx.org/) for lineages modeling ([Hagberg, Schult and Swart, 2008](http://conference.scipy.org.s3-website-us-east-1.amazonaws.com/proceedings/scipy2008/paper_2/))
+- [TrackMate](https://imagej.net/plugins/trackmate/) for the TrackMate data loader and exporter ([Tinevez et al., 2017](https://doi.org/10.1016/j.ymeth.2016.09.016), [Ershov et al., 2022](https://doi:10.1038/s41592-022-01507-1))
+- The [Cell Tracking Challenge](https://celltrackingchallenge.net/) for the CTC data loader and exporter ([Maška et al., 2023](https://doi.org/10.1038/s41592-023-01879-y))

pycellin-0.3.5b3/README.md

@@ -0,0 +1,91 @@
+![Build](https://github.com/Image-Analysis-Hub/pycellin/actions/workflows/build.yml/badge.svg)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# 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 acyclic graphs (DAG). 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 features related to cell morphology, cell motion and tracking that can be automatically added to enrich lineages. More predefined features will be implemented in the future. The framework also facilitates the creation of new features defined by the user to accommodate the wide variety of experiments and biological questions.
+
+Pycellin can read from and write to TrackMate XML and Cell Tracking Challenge text file formats. More tracking formats will progressively be supported.
+
+While Pycellin has been designed with bacteria / cell lineages in mind, it could be used with more diverse tracking data provided the few conditions below are enforced:
+- the tracking data can be modeled by a DAG, meaning no merging event
+- time must flow homogeneously, i.e. all the edges of a lineage graph must represent the same elapsed time.
+
+
+## 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.
+
+You can install Pycellin from [PyPI](https://pypi.org/):
+
+```
+pip install pycellin
+```
+
+To install Pycellin with the optional test related dependencies:
+
+```
+pip install pycellin[test]
+```
+
+
+## Code Example
+
+```python
+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 features.
+model.add_pycellin_features([
+    "cell_length", 
+    "cell_width",
+    "cell_displacement", 
+    "cell_speed", 
+    "branch_mean_speed",
+    "relative_age",
+    "division_time", 
+    "division_rate",
+    "cell_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()
+```
+
+
+## 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](./notebooks/Getting%20started.ipynb)                                   | The basics of Pycellin, through examples                          | Beginner | WIP   |
+| [Managing features](./notebooks/Managing%20features.ipynb)                               | How to add, compute and remove features from a model              | Beginner | WIP   |
+| [Working with TrackMate data](./notebooks/Working%20with%20TrackMate%20data.ipynb)       | How Pycellin can work with TrackMate, through an example          | Beginner | WIP   |
+| [Creating a model from scratch](./notebooks/Creating%20a%20model%20from%20scratch.ipynb) | How to manually create a Pycellin model, including its lineages   | Advanced | Stub  |
+| [Custom features](./notebooks/Custom%20features.ipynb)                                   | How to create user-defined features and augment a model with them | Advanced | WIP   |
+
+
+## Credits
+
+- [NetworkX](https://networkx.org/) for lineages modeling ([Hagberg, Schult and Swart, 2008](http://conference.scipy.org.s3-website-us-east-1.amazonaws.com/proceedings/scipy2008/paper_2/))
+- [TrackMate](https://imagej.net/plugins/trackmate/) for the TrackMate data loader and exporter ([Tinevez et al., 2017](https://doi.org/10.1016/j.ymeth.2016.09.016), [Ershov et al., 2022](https://doi:10.1038/s41592-022-01507-1))
+- The [Cell Tracking Challenge](https://celltrackingchallenge.net/) for the CTC data loader and exporter ([Maška et al., 2023](https://doi.org/10.1038/s41592-023-01879-y))

pycellin-0.3.5b3/pycellin/__init__.py

@@ -0,0 +1,66 @@
+from .classes.data import Data
+from .classes.lineage import CellLineage, CycleLineage
+from .classes.feature import FeaturesDeclaration, Feature
+from .classes.feature import (
+    frame_Feature,
+    cell_ID_Feature,
+    lineage_ID_Feature,
+    cell_coord_Feature,
+    link_coord_Feature,
+    lineage_coord_Feature,
+    cycle_ID_Feature,
+    cells_Feature,
+    cycle_length_Feature,
+    level_Feature,
+)
+from .classes.model import Model
+from .classes.feature_calculator import (
+    NodeLocalFeatureCalculator,
+    EdgeLocalFeatureCalculator,
+    LineageLocalFeatureCalculator,
+    NodeGlobalFeatureCalculator,
+    EdgeGlobalFeatureCalculator,
+    LineageGlobalFeatureCalculator,
+)
+
+from .io.cell_tracking_challenge.loader import load_CTC_file
+from .io.cell_tracking_challenge.exporter import export_CTC_file
+from .io.trackmate.loader import load_TrackMate_XML
+from .io.trackmate.exporter import export_TrackMate_XML
+
+from .graph.features.utils import (
+    get_pycellin_cell_lineage_features,
+    get_pycellin_cycle_lineage_features,
+)
+
+
+__all__ = [
+    "Data",
+    "CellLineage",
+    "CycleLineage",
+    "FeaturesDeclaration",
+    "Feature",
+    "frame_Feature",
+    "cell_ID_Feature",
+    "lineage_ID_Feature",
+    "cell_coord_Feature",
+    "link_coord_Feature",
+    "lineage_coord_Feature",
+    "cycle_ID_Feature",
+    "cells_Feature",
+    "cycle_length_Feature",
+    "level_Feature",
+    "Model",
+    "NodeLocalFeatureCalculator",
+    "EdgeLocalFeatureCalculator",
+    "LineageLocalFeatureCalculator",
+    "NodeGlobalFeatureCalculator",
+    "EdgeGlobalFeatureCalculator",
+    "LineageGlobalFeatureCalculator",
+    "load_CTC_file",
+    "export_CTC_file",
+    "load_TrackMate_XML",
+    "export_TrackMate_XML",
+    "get_pycellin_cell_lineage_features",
+    "get_pycellin_cycle_lineage_features",
+]

pycellin-0.3.5b3/pycellin/classes/__init__.py

@@ -0,0 +1,24 @@
+from .data import Data
+from .lineage import CellLineage, CycleLineage
+from .feature import FeaturesDeclaration, Feature
+from .feature import (
+    frame_Feature,
+    cell_ID_Feature,
+    lineage_ID_Feature,
+    cell_coord_Feature,
+    link_coord_Feature,
+    lineage_coord_Feature,
+    cycle_ID_Feature,
+    cells_Feature,
+    cycle_length_Feature,
+    level_Feature,
+)
+from .model import Model
+from .feature_calculator import (
+    NodeLocalFeatureCalculator,
+    EdgeLocalFeatureCalculator,
+    LineageLocalFeatureCalculator,
+    NodeGlobalFeatureCalculator,
+    EdgeGlobalFeatureCalculator,
+    LineageGlobalFeatureCalculator,
+)

pycellin-0.3.5b3/pycellin/classes/data.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import math
+from typing import Literal
+import warnings
+
+import networkx as nx
+
+from pycellin.classes.lineage import Lineage, CellLineage, CycleLineage
+
+
+class Data:
+    """
+    Class to store and manipulate cell lineages and cell cycle lineages.
+    """
+
+    def __init__(
+        self, data: dict[str, CellLineage], add_cycle_data: bool = False
+    ) -> None:
+        self.cell_data = data
+        if add_cycle_data:
+            self._compute_cycle_lineages()
+        else:
+            self.cycle_data = None
+
+    def __repr__(self) -> str:
+        return f"Data(cell_data={self.cell_data!r}, cycle_data={self.cycle_data!r})"
+
+    def __str__(self) -> str:
+        if self.cycle_data:
+            txt = f" and {self.number_of_lineages()} cycle lineages"
+        else:
+            txt = ""
+        return f"Data object with {self.number_of_lineages()} cell lineages{txt}."
+
+    def _add_cycle_lineages(self, lineage_IDs: list[int] | None = None) -> None:
+        """
+        Add the cell cycle lineages from the cell lineages.
+
+        Parameters
+        ----------
+        lineage_IDs : list[int], optional
+            The IDs of the lineages to compute the cycle lineages for,
+            by default None i.e. all lineages.
+        """
+        if lineage_IDs is None:
+            lineage_IDs = list(self.cell_data.keys())
+        self.cycle_data = {
+            lin_id: self._compute_cycle_lineage(lin_id) for lin_id in lineage_IDs
+        }
+
+    def _compute_cycle_lineage(self, lineage_ID: int) -> CycleLineage:
+        """
+        Compute and return the cycle lineage corresponding to a given cell lineage.
+
+        Parameters
+        ----------
+        lineage_ID : int
+            The ID of the cell lineage.
+
+        Returns
+        -------
+        CycleLineage
+            The cycle lineage corresponding to the cell lineage.
+        """
+        return CycleLineage(self.cell_data[lineage_ID])
+
+    def _freeze_lineage_data(self):
+        """
+        Freeze all cell lineages.
+
+        When a cell lineage is frozen, its structure cannot be modified:
+        nodes and edges cannot be added or removed. However, graph, node and edge
+        attributes can still be modified.
+        """
+        for lineage in self.cell_data.values():
+            if not nx.is_frozen(lineage):
+                nx.freeze(lineage)
+
+    def _unfreeze_lineage_data(self):
+        """
+        Unfreeze all cell lineages.
+        """
+        for lineage in self.cell_data.values():
+            Lineage.unfreeze(lineage)
+
+    def number_of_lineages(self) -> int:
+        """
+        Return the number of lineages in the data.
+
+        Returns
+        -------
+        int
+            The number of cell lineages in the data.
+
+        Raises
+        ------
+        Warning
+            If the number of cell lineages and cycle lineages do not match.
+        """
+        if self.cycle_data:
+            if len(self.cell_data) != len(self.cycle_data):
+                msg = (
+                    f"Number of cell lineages ({len(self.cell_data)}) "
+                    f"and cycle lineages ({len(self.cycle_data)}) do not match. "
+                    "An update of the model is required. "
+                )
+                warnings.warn(msg)
+        return len(self.cell_data)
+
+    def get_closest_cell(
+        self,
+        noi: int,
+        lineage: CellLineage,
+        radius: float = 0,
+        time_window: int = 0,
+        time_window_type: Literal["before", "after", "symetric"] = "symetric",
+        lineages_to_search: list[CellLineage] = None,
+        reference: Literal["center", "border"] = "center",
+    ) -> tuple[CellLineage, int]:
+        """
+        Find the closest cell to a given cell of a lineage.
+
+        Parameters
+        ----------
+        noi : int
+            Node of interest, the one for which to find the closest cell.
+        lineage : CellLineage
+            The lineage the node belongs to.
+        radius : float, optional
+            The maximum distance to consider, by default 0.
+            If 0, the whole space is considered.
+        time_window : int, optional
+            The time window to consider, by default 0 i.e. only the current frame.
+        time_window_type : Literal["before", "after", "symetric"], optional
+            The type of time window to consider, by default "symetric".
+        lineages_to_search : list[CellLineage], optional
+            The lineages to search in, by default None i.e. all lineages.
+        reference : Literal["center", "border"], optional
+            The reference point to consider for the distance, by default "center".
+
+        Returns
+        -------
+        tuple[int, CellLineage]
+            The node ID of the closest cell and the lineage it belongs to.
+        """
+        distances = self.get_closest_cells(
+            noi=noi,
+            lineage=lineage,
+            radius=radius,
+            time_window=time_window,
+            time_window_type=time_window_type,
+            lineages_to_search=lineages_to_search,
+            reference=reference,
+        )
+        return distances[0]
+
+    def get_closest_cells(
+        self,
+        noi: int,
+        lineage: CellLineage,
+        radius: float = 0,
+        time_window: int = 0,
+        time_window_type: Literal["before", "after", "symetric"] = "symetric",
+        lineages_to_search: list[CellLineage] = None,
+        reference: Literal["center", "border"] = "center",
+    ) -> list[tuple[int, CellLineage]]:
+        """
+        Find the closest cells to a given cell of a lineage.
+
+        Parameters
+        ----------
+        noi : int
+            Node of interest, the one for which to find the closest cell.
+        lineage : CellLineage
+            The lineage the node belongs to.
+        radius : float, optional
+            The maximum distance to consider, by default 0.
+            If 0, the whole space is considered.
+        time_window : int, optional
+            The time window to consider, by default 0 i.e. only the current frame.
+        time_window_type : Literal["before", "after", "symetric"], optional
+            The type of time window to consider, by default "symetric".
+        lineages_to_search : list[CellLineage], optional
+            The lineages to search in, by default None i.e. all lineages.
+        reference : Literal["center", "border"], optional
+            The reference point to consider for the distance, by default "center".
+
+        Returns
+        -------
+        tuple[int, CellLineage]
+            The node ID of the closest cells and the lineages it belongs to,
+            sorted by increasing distance.
+        """
+        # TODO: implement the reference parameter
+
+        # Identification of the frames to search in.
+        center_frame = lineage.nodes[noi]["frame"]
+        if time_window == 0:
+            frames_to_search = [center_frame]
+        else:
+            if time_window_type == "symetric":
+                frames_to_search = list(
+                    range(center_frame - time_window, center_frame + time_window + 1)
+                )
+            elif time_window_type == "before":
+                frames_to_search = list(
+                    range(center_frame - time_window, center_frame + 1)
+                )
+            elif time_window_type == "after":
+                frames_to_search = list(
+                    range(center_frame, center_frame + time_window + 1)
+                )
+            else:
+                raise ValueError(
+                    f"Unknown time window type: '{time_window_type}'."
+                    " Should be 'before', 'after' or 'symetric'."
+                )
+            frames_to_search.sort()
+
+        # Identification of nodes that are good candidates,
+        # i.e. nodes that are in the time window
+        # and in the lineages to search in.
+        if not lineages_to_search:
+            lineages_to_search = list(self.cell_data.values())
+        candidate_cells = {}
+        for lin in lineages_to_search:
+            nodes = [
+                node
+                for node, frame in lin.nodes(data="frame")
+                if frame in frames_to_search
+            ]
+            if nodes:
+                candidate_cells[lin] = nodes
+        # Need to remove the node itself from the candidates.
+        candidate_cells[lineage].remove(noi)
+
+        # Identification of the closest cell.
+        distances = []
+        for lin, nodes in candidate_cells.items():
+            for node in nodes:
+                distance = math.dist(
+                    lineage.nodes[noi]["location"], lin.nodes[node]["location"]
+                )
+                if radius == 0 or distance <= radius:
+                    distances.append((node, lin, distance))
+        distances.sort(key=lambda x: x[2])
+        return [(node, lin) for node, lin, _ in distances]
+
+    # def get_neighbouring_cells(
+    #     lineage: CellLineage,
+    #     node: int,
+    #     radius: float,
+    #     time_window: int | tuple[int, int],
+    # ) -> list[tuple[CellLineage, int]]:
+    #     """ """
+    #     # TODO: implement get_neighbouring_cells()
+    #     # Parameter to define sort order? By default closest to farthest
+    #     # Need to implement get_distance() between 2 nodes, not necessarily
+    #     # from the same lineage...
+    #     # To identify a node, need to have lineage_ID and cell_ID
+    #     pass