fucciphase 0.0.1__py3-none-any.whl

fucciphase/utils/trackmate.py

@@ -0,0 +1,295 @@
+import re
+import xml.etree.ElementTree as et
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+# TrackMate XML tags
+MODEL = "Model"
+FEATURES = "FeatureDeclarations"
+SPOT_FEATURES = "SpotFeatures"
+ALL_SPOTS = "AllSpots"
+N_SPOTS = "nspots"
+ID = "ID"
+SUBTRACK_REGEX = r"Track_[0-9]+\.[a-z]+"
+
+
+# TODO test on very large trackmate files, since this is potentially a bottleneck here
+class TrackMateXML:
+    """Class to handle TrackMate xml files.
+
+    TrackMate xml files are structured as follows:
+        root
+        ├── Log
+        ├── Model
+        │   ├── FeatureDeclarations
+        │   ├── AllSpots
+        │   │   └── SpotsInFrame
+        │   │       └── Spot
+        │   ├── AllTracks
+        │   └── FilteredTracks
+        ├── Settings
+        ├── GUIState
+        └── DisplaySettings
+
+    This class allows reading in the tree and converting the spots to a
+    pandas dataframe. The features (columns) can also be updated and the
+    xml file be saved.
+
+    Attributes
+    ----------
+    nspots : int
+        Number of spots in the xml file.
+    features : Dict[str, type]
+        List of all features in the xml file, and whether they are integer features.
+    """
+
+    def __init__(self, xml_path: Union[str, Path]) -> None:
+        """Initialize the TrackMateXML object.
+
+        The xml file is parsed and the model and all spots are imported.
+
+        Parameters
+        ----------
+        xml_path : Union[str, Path]
+            Path to the xml file.
+        """
+        # parse tree
+        self._tree: et.ElementTree[et.Element[str]] = et.parse(xml_path)
+        self._root: et.Element | Any = self._tree.getroot()
+
+        # placeholders
+        self._model: Optional[et.Element] = None
+        self._allspots: Optional[et.Element] = None
+
+        self.nspots: int = 0  # number of spots
+        self.features: Dict[str, type] = {}  # features and their types
+        self.spot_features: List[str] = []  # list of spot features
+
+        # import model and all spots
+        self._import_data()
+
+    def _get_spot_features(self) -> None:
+        """Get the spot features from the tree."""
+        if self._allspots is not None:
+            spot_features: List[str] = []
+            for frame in self._allspots:
+                for spot in frame:
+                    spot_features.extend(spot.attrib.keys())
+                    break
+                break
+
+            self.spot_features = spot_features
+
+    def _get_features(self) -> None:
+        """Compare spot features and features declaration, keep the intersection and
+        register the dtypes in a public member.
+        """
+        if self._model is not None:
+            features = {}
+            for element in self._model:
+                if element.tag == FEATURES:
+                    for feature in element:
+                        if feature.tag == SPOT_FEATURES:
+                            for spot_feature in feature:
+                                # get feature name
+                                feature_name = spot_feature.attrib["feature"]
+
+                                # check if feature is integer
+                                is_integer = spot_feature.attrib["isint"] == "true"
+
+                                # add feature to dictionary
+                                features[feature_name] = int if is_integer else float
+
+            # get spot features
+            self._get_spot_features()
+
+            # keep only features that are in both spot features and features
+            features_key = set(features.keys())
+            features_to_keep = features_key - (features_key - set(self.spot_features))
+            self.features = {feature: features[feature] for feature in features_to_keep}
+
+    def _import_data(self) -> None:
+        """Import the model and all spots from the xml file.
+
+        Raises
+        ------
+        ValueError
+            If the xml file does not contain a "Model" tag.
+        ValueError
+            If the "Model" tag does not contain an "AllSpots" tag.
+        """
+        # get model
+        for element in self._root:
+            if element.tag == MODEL:
+                self._model = element
+
+        if self._model is None:
+            raise ValueError('"Model" tag not found in xml file.')
+
+        # get allspots
+        for element in self._model:
+            if element.tag == ALL_SPOTS:
+                self._allspots = element
+                self.nspots = int(element.attrib[N_SPOTS])
+
+        if self._allspots is None:
+            raise ValueError('"AllSpots" tag not found in xml file.')
+
+        # get feature declarations
+        self._get_features()
+
+    def _add_track_ids(self, df: pd.DataFrame) -> None:
+        # extract track IDs (if there are spots)
+        if len(df) > 0:
+            # some spots do not have tracks associated
+            track_ids = np.full_like(df[ID].values, -1)
+            if self._model is not None:
+                for element in self._model:
+                    if element.tag == "AllTracks":
+                        for track in element:
+                            track_id = int(track.attrib["TRACK_ID"])
+
+                            for edge in track:
+                                spot_source = edge.attrib["SPOT_SOURCE_ID"]
+                                spot_target = edge.attrib["SPOT_TARGET_ID"]
+
+                                # get row index of the source and target spots
+                                source_index = df[df[ID] == spot_source].index[0]
+                                target_index = df[df[ID] == spot_target].index[0]
+
+                                # update track IDs
+                                track_ids[source_index] = track_id
+                                track_ids[target_index] = track_id
+
+                # update dataframe
+                df["TRACK_ID"] = track_ids
+        else:
+            df["TRACK_ID"] = []
+
+        # add track id to the spot features (this avoids exporting it to the xml later)
+        self.spot_features.append("TRACK_ID")
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Export the spots as a pandas dataframe.
+
+        Returns
+        -------
+        pd.DataFrame
+            Dataframe containing the spots.
+        """
+        df = pd.DataFrame()
+
+        # loop over all frames and add spots to a dataframe
+        if self._allspots is not None:
+            spot_count = 0
+            for frame in self._allspots:
+                # only run on frames with spots
+                if len(frame) > 0:
+                    # for each spot in the frame
+                    for spot in frame:
+                        # if this is the first spot, initialize dataframe
+                        if spot_count == 0:
+                            df = pd.DataFrame(columns=spot.attrib.keys())
+
+                        # add the spot to the dataframe
+                        df.loc[spot_count] = spot.attrib
+                        spot_count += 1
+
+        # add tracks IDs
+        self._add_track_ids(df)
+
+        # fix type of TRACK_ID
+        self.features["TRACK_ID"] = int
+        # convert features to their declared types
+        return df.astype(self.features)
+
+    def update_features(self, df: pd.DataFrame) -> None:
+        """Update the xml tree with new features, where features are columns of the
+        dataset.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            Dataframe containing the new features.
+        """
+        # compare number of spots
+        if len(df) != self.nspots:
+            raise ValueError(
+                f"Number of spots in the dataframe ({len(df)}) does not match number "
+                f"of spots in xml file ({self.nspots})."
+            )
+
+        # check if ID column is in the dataframe
+        if ID not in df.columns:
+            raise ValueError(f"Column {ID} not found in dataframe.")
+
+        # new features
+        new_features = set(df.columns) - set(self.spot_features)
+
+        if self._allspots is not None:
+            # update features
+            for feature in new_features:
+                self.features[feature] = df[feature].dtype
+
+            # if there are spots and features
+            if len(df) > 0 and len(new_features) > 0:
+                # loop over the frames and spots
+                for frame in self._allspots:
+                    for spot in frame:
+                        # get ID
+                        spot_id = spot.attrib[ID]
+
+                        # get spot
+                        spot_df = df[df[ID] == spot_id]
+
+                        # add the new feature
+                        for feature in new_features:
+                            spot.attrib[feature] = str(spot_df[feature].values[0])
+
+    def save_xml(self, xml_path: Union[str, Path]) -> None:
+        """Save the xml file.
+
+        Parameters
+        ----------
+        xml_path : Union[str, Path]
+            Path to the xml file.
+        """
+        with open(xml_path, "wb") as f:
+            self._tree.write(f)
+
+    def get_full_tracks(
+        df: pd.DataFrame,
+        channels: List[str],
+        track_id_name: str = "UNIQUE_TRACK_ID",
+        spot_name: str = "name",
+        frame_name: str = "FRAME",
+        min_length: int = 40,
+    ) -> Tuple[List[pd.DataFrame], List[pd.DataFrame]]:
+        """Locate all tracks that may describe a full cycle.
+        Tracks need to be auto-named by TrackMate.
+        For example, Track_1a, Track_1aa, Track_1b etc.
+        This can be done in TrackMate by executing an action after the tracking.
+        In addition, tracks longer than a certain minimum length can be selected.
+        """
+        regex = "Track_[0-9]+.[a-z]+"
+        candidate_tracks: List[pd.DataFrame] = []
+        save_tracks: List[pd.DataFrame] = []
+        track_ids = df[track_id_name].unique()
+        for track_id in track_ids:
+            track = df[df[track_id_name] == track_id]
+            name = track[spot_name].iloc[0]
+            last_frame = track[frame_name].max()
+            # is the track a subtrack
+            match = re.match(regex, name)
+            # is there a subtrack
+            next_match = any(df[spot_name].str.match(name + "[a-z]+").unique())
+            if match is not None and last_frame < df[frame_name].max():
+                if next_match:
+                    save_tracks.append(track[[frame_name, *channels]])
+                else:
+                    if len(track) > min_length:
+                        candidate_tracks.append(track[[frame_name, *channels]])
+        return save_tracks, candidate_tracks

fucciphase-0.0.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: fucciphase
+Version: 0.0.1
+Summary: Cell cycle analysis plugin.
+Project-URL: homepage, https://github.com/nobias-ht/fucciphase
+Project-URL: repository, https://github.com/nobias-ht/fucciphase
+Author-email: Joran Deschamps <joran.deschamps@fht.org>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Requires-Dist: dtaidistance
+Requires-Dist: lineagetree<1.5.0
+Requires-Dist: matplotlib
+Requires-Dist: monotonic-derivative
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: svgwrite
+Provides-Extra: dev
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pdbpp; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: rich; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == 'doc'
+Provides-Extra: jupyter
+Requires-Dist: jupyter; extra == 'jupyter'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# fucciphase
+
+[![License](https://img.shields.io/pypi/l/fucciphase.svg?color=green)](https://github.com/Synthetic-Physiology-Lab/fucciphase/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/fucciphase.svg?color=green)](https://pypi.org/project/fucciphase)
+[![Python Version](https://img.shields.io/pypi/pyversions/fucciphase.svg?color=green)](https://python.org)
+[![CI](https://github.com/Synthetic-Physiology-Lab/fucciphase/actions/workflows/ci.yml/badge.svg)](https://github.com/Synthetic-Physiology-Lab/fucciphase/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Synthetic-Physiology-Lab/fucciphase/branch/main/graph/badge.svg)](https://codecov.io/gh/Synthetic-Physiology-Lab/fucciphase)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Synthetic-Physiology-Lab/fucciphase/main.svg)](https://results.pre-commit.ci/latest/github/Synthetic-Physiology-Lab/fucciphase/main)
+
+FUCCI cell cycle analysis plugin.
+Obtain cell cycle information from FUCCI fluorescence intensities.
+
+## Installation
+
+The best way to run fucciphase is to install it in a virtual conda environment.
+Make sure that git is installed and can be called from the command line.
+
+(SOON) To install from pip:
+
+```bash
+pip install fucciphase
+```
+
+If you wish to install it from source:
+    
+```bash
+git clone https://github.com/Synthetic-Physiology-Lab/fucciphase
+cd fucciphase
+pip install -e .
+```
+
+The installation should not take longer than a few seconds (depending on your internet connection).
+
+To use the notebooks, also install jupyter:
+    
+```bash
+pip install jupyter
+```
+
+## Usage
+
+Fucci phase currently supports loading a 
+[TrackMate](https://imagej.net/plugins/trackmate/) XML file:
+
+```python
+from fucciphase import process_trackmate
+from fucciphase.sensor import get_fuccisa_default_sensor
+
+trackmate_xml = "path/to/trackmate.xml"
+channel1 = "MEAN_INTENSITY_CH3"
+channel2 = "MEAN_INTENSITY_CH4"
+
+sensor = get_fuccisa_default_sensor()
+
+df = process_trackmate(trackmate_xml,
+                       channels=[channel1, channel2],
+		       sensor=sensor,
+                       thresholds=[0.1, 0.1])
+print(df)
+```
+
+The TrackMate XML is converted to a [Pandas](https://pandas.pydata.org/) DataFrame.
+Thus, in general data (e.g., stored in a CSV or XLSX file) that can be parsed into
+a DataFrame is supported.
+
+Have a look at the examples in the `example` folder to get more information!
+
+The runtime of the scripts depends on your datasize. 2D samples with a few hundred to a few thousand cells
+can be processed in a few minutes. Visualization in Napari can take a bit longer.
+Standard processing does not require a powerful computer.
+Make sure that you have sufficient RAM to load videos for visualization in Napari.
+
+## Development
+
+To develop fucciphase, clone the repository, install fucciphase in your environment
+and install the pre-commit hooks:
+
+```bash
+git clone https://github.com/Synthetic-Physiology-Lab/fucciphase
+cd fucciphase
+pip install -e ".[test, dev]"
+pre-commit install
+```
+
+If you want to build the documentation, replace the abovementioned pip install by:
+```bash
+pip install -e ".[test, dev, doc]"
+```
+
+## Cite us
+
+Di Sante, M., Pezzotti, M., Zimmermann, J., Enrico, A., Deschamps, J., Balmas, E.,
+Becca, S., Solito, S., Reali, A., Bertero, A., Jug, F. and Pasqualini, F.S., 2025.
+CALIPERS: Cell cycle-aware live imaging for phenotyping experiments and regeneration studies.
+bioRxiv, https://doi.org/10.1101/2024.12.19.629259 

fucciphase-0.0.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+fucciphase/__init__.py,sha256=8PA6UNaYjycfPpOg7e5ArP3k9Lj9H15Lmw-Mnd14azY,375
+fucciphase/fucci_phase.py,sha256=VgydHVN0nWzC6Eeh0LRaPHdScL2w7C5X7IhGSvyp4qw,6134
+fucciphase/io.py,sha256=ELcoxsPHzcg9tf48MaMNnuSMxe0Fd3Nc9LCWbQ6p4I8,1715
+fucciphase/phase.py,sha256=jy2l9LD81FTk6TIlyWyYPbVnwClGP9N4RrYyqtiMStg,17130
+fucciphase/plot.py,sha256=Obfv2VOHdDN4Az_JUErJ22ESAgHhdsBaavdsS0f6xZ4,18593
+fucciphase/py.typed,sha256=esB4cHc6c07uVkGtqf8at7ttEnprwRxwk8obY8Qumq4,187
+fucciphase/sensor.py,sha256=6-WEI8viI5fSVyKHnECmKYKaROW4tQaPaNW4hHYVAcA,14788
+fucciphase/tracking_utilities.py,sha256=IfKH2fyPo7fkW3PBvQrCz-UcfrdkOj7D-iLJabynvfw,2776
+fucciphase/napari/__init__.py,sha256=At9Shk6HfDf6obtQaM0yKG4NOZVO6YxD2-J1M2ZGm7w,198
+fucciphase/napari/tracks_to_napari.py,sha256=US9uAzGVJi5wAJ4CbUi9XztRFbrMRK7t0oJrQ40aDEg,4094
+fucciphase/utils/__init__.py,sha256=E4wk7ygjHQQ-8vj4VNHseMLE-PQ1bZK2gvDFaO5Z1eU,1011
+fucciphase/utils/checks.py,sha256=ZTe6cq11Y2e3suM3vECqCvvFxQTMOJqXMPS8gdCP7qc,651
+fucciphase/utils/dtw.py,sha256=MDJEJUT9oSz8Iu6SeWFSBhVgZmLnE3CXE_2cbEl6TE8,1682
+fucciphase/utils/normalize.py,sha256=eGytBDjmWcr1OY88McCJNcmy4zioM2DbtQConDoIVRw,6037
+fucciphase/utils/phase_fit.py,sha256=Ht_dEyuLYonv6is9qQ-Xd95pQR7IR-8C8mv0ckDcp4E,1743
+fucciphase/utils/simulator.py,sha256=7bmrO0IWUqsk4CyM-PlVpG2QTJxjTsY1h6buxmTs1iM,2322
+fucciphase/utils/track_postprocessing.py,sha256=cTe3OOCR4dxFBZwN7XdbzDbnsgouoJql8rv4WwvmbM8,14438
+fucciphase/utils/trackmate.py,sha256=dir4ayS1Fl-gtK8NTbP7t7CBLnrumC8LgPiCwxsBf-c,10666
+fucciphase-0.0.1.dist-info/METADATA,sha256=TL-dyIUGTeLdahG5YiQiWhq3i8o3esSpvujY47rLP14,4900
+fucciphase-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fucciphase-0.0.1.dist-info/licenses/LICENSE,sha256=pQGrOGpOTwikEzkZ8Zc9XLQwbaZ85TMJP-GaWCNZciw,1554
+fucciphase-0.0.1.dist-info/RECORD,,

fucciphase-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fucciphase-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Joran Deschamps
+Copyright (c) 2023, Julius Zimmermann (contributor)
+
+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.