From 2a403c219c1050c7296ac0b4f158e2e4a6dd0b3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jord=C3=A3o=20Bragantini?= Date: Mon, 8 Jul 2024 10:32:05 -0700 Subject: [PATCH] updated docs and renamed to_napari to to_tracks_layer (#125) --- README.md | 4 ++-- docs/source/api.rst | 8 ++++++++ docs/source/configuration.rst | 2 ++ docs/source/getting_started.rst | 23 +++++++++++++++++++++-- docs/source/optimizing.rst | 20 +++++++++++++++----- docs/source/quickstart.rst | 4 ++-- setup.cfg | 2 +- ultrack/core/_test/test_tracker.py | 4 ++-- ultrack/core/tracker.py | 2 +- 9 files changed, 54 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 4d2cbfa..f068d82 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ To avoid conflicts between different packages, we recommend using conda to creat ```bash conda create --name tracking -c conda-forge python=3.10 pyqt conda activate tracking -pip install git+https://github.com/royerlab/ultrack +pip install ultrack ``` ## Usage @@ -68,7 +68,7 @@ if __name__ == "__main__": tracker.track(foreground=foreground, edges=contours) # Visualize results in napari - tracks, graph = tracker.to_napari() + tracks, graph = tracker.to_tracks_layer() napari.view_tracks(tracks[["track_id", "t", "z", "y", "x"]], graph=graph) napari.run() ``` diff --git a/docs/source/api.rst b/docs/source/api.rst index 88f4df7..e7e8eaa 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -66,6 +66,8 @@ Array utilities .. automodule:: ultrack.utils.array :members: +.. _api_imgproc: + ========================== Image processing utilities ========================== @@ -77,6 +79,8 @@ Image processing utilities .. automodule:: ultrack.imgproc.sam :members: +.. _api_flow: + ---- Flow ---- @@ -84,6 +88,8 @@ Flow .. automodule:: ultrack.imgproc.flow :members: +.. _api_tracks: + ================ Tracks utilities ================ @@ -92,6 +98,8 @@ Tracks utilities :imported-members: :members: +.. _api_export: + ========= Exporting ========= diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index d908e6f..60ade3a 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -32,4 +32,6 @@ The configurations are documented below, the parameters are ordered by importanc --------------- +.. _tracking_config: + .. autopydantic_model:: ultrack.config.TrackingConfig diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 4395b62..56aabaa 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -43,17 +43,36 @@ Solving ``````` The solving step is responsible for solving the tracking problem by finding the best segmentation and trajectory for each cell. The parameters for this step are harder to interpret, as they are related to the optimization problem. The most important ones are: + - ``config.tracking_config.appear_weight``: The penalization for a cell to appear, which means to start a new lineage; - ``config.tracking_config.division_weight``: The penalization for a cell to divide, breaking a single tracklet into two; - ``config.tracking_config.disappear_weight``: The penalization for a cell to disappear, which means to end a lineage; These weights are negative or zero, as they try to balance the cost of including new lineages in the final solution. The connections (links) between segmentation hypotheses are positive and measure the quality of the tracks, so only lineages with a total linking weight higher than the penalizations are included in the final solution. At the same time, our optimization problem is finding the combination of connections that maximize the sum of weights of all lineages. +See the :ref:`tracking configuration description ` for more information and :doc:`optimizing` for details on how to select these parameters. + + Exporting ````````` Once the above steps have been applied, the tracking solutions are recorded in the database and they can be exported to a format of your choice, them being, ``to_networkx``, ``to_trackmate``, ``to_tracks_layer``, ``tracks_to_zarr`` and others. +See the :ref:`export API reference ` for all available options and their parameters. + +Example of exporting solutions to napari tracks layer: + +.. code-block:: python + + # ... tracking computation + + # Exporting to napari format using `Tracker` class + tracks, graph = tracker.to_tracks_layer() + + # Exporting using config file + tracks, graph = to_tracks_layer(config) + + Post-processing ``````````````` @@ -67,7 +86,7 @@ Other functionalities can be found in ``ultrack.utils`` or ``ultrack.imgproc``, - ``tracks_properties``: Which returns compute statistics from the tracks, segmentation masks and images. -For additional information, please refer to the :doc:`API reference `. +For additional information, please refer to the :ref:`tracks post-processing API reference `. Image processing ```````````````` @@ -76,4 +95,4 @@ Despite being presented here last, ultrack's image processing module provides au Most of them are available in ``ultrack.imgproc`` , ``ultrack.utils.array`` and ``ultrack.utils.cuda`` modules. -Refer to the :doc:`API reference ` for more information. +Refer to the :ref:`image processing API reference ` for more information. diff --git a/docs/source/optimizing.rst b/docs/source/optimizing.rst index e40dd86..17a1dbb 100644 --- a/docs/source/optimizing.rst +++ b/docs/source/optimizing.rst @@ -5,6 +5,7 @@ Once you have a working ultrack pipeline, the next step is optimizing the tracki Here we describe our guidelines for optimizing the tracking performance and up to what point you can expect to improve the tracking performance. It will be divided into a few sections: + - Pre-processing: How to make tracking easier by pre-processing the data; - Input verification: Guidelines to check if you have good `labels` or `foreground` and `contours` maps; - Hard constraints: Parameters must be adjusted so the hypotheses include the correct solution; @@ -13,15 +14,24 @@ It will be divided into a few sections: Pre-processing `````````````` -The first question to ask yourself is, are your frames correctly aligned? -If not, we recommend aligning them, we provide the ``ultrack.imgproc.register_timelapse`` to align translations, see :doc:`API reference `. +Registration +^^^^^^^^^^^^ + +Before tracking, the first question to ask yourself is, are your frames correctly aligned? + +If not, we recommend aligning them. To do that, we provide the ``ultrack.imgproc.register_timelapse`` to align translations, see the :ref:`registration API `. + +If the movement is more complex, with cells moving in different directions, we recommend using the ``flow`` functionalities to align individual segments with distinct transforms, see the :doc:`flow tutorial `. +See the :ref:`flow estimation API ` for more information. -If your cells are very dynamic and there are considerable movements in different directions, we recommend using the ``flow`` functionalities to align individual segments with their own transforms, see the :doc:`flow tutorial `. +Deep learning +^^^^^^^^^^^^^ -Some deep learning models are sensitive to the contrast of your data, we recommend adjusting the contrast and removing background applying them. +Some deep learning models are sensitive to the contrast of your data, we recommend adjusting the contrast and removing background before applying them to improve their predictions. +See the :ref:`image processing utilities API ` for more information. Input verification -````````````````` +`````````````````` At this point, we assume you already have a ``labels`` image or a ``foreground`` and ``contours`` maps; diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 889881b..fca6f4f 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -40,7 +40,7 @@ The following example demonstrates how to use ``ultrack`` to track cells using i tracker.track(foreground=foreground, contours=contours) # Visualize the results - tracks, graph = tracker.to_napari() + tracks, graph = tracker.to_tracks_layer() napari.view_tracks(tracks[["track_id", "t", "y", "x"]], graph=graph) napari.run() @@ -70,6 +70,6 @@ If you already have segmentation labels, you can provide them directly to the tr tracker.track(labels=labels) # Visualize the results - tracks, graph = tracker.to_napari() + tracks, graph = tracker.to_tracks_layer() napari.view_tracks(tracks[["track_id", "t", "y", "x"]], graph=graph) napari.run() diff --git a/setup.cfg b/setup.cfg index 4447775..f18f82a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -47,7 +47,7 @@ install_requires = pydot >= 2.0.0 [options.extras_require] -testing = +test = pytest >=7.3.1,<8.0.0 pre-commit >=3.2.2,<4.0.0 pytest-qt >=4.2.0,<5.0.0 diff --git a/ultrack/core/_test/test_tracker.py b/ultrack/core/_test/test_tracker.py index 3e1a2e6..fc52b11 100644 --- a/ultrack/core/_test/test_tracker.py +++ b/ultrack/core/_test/test_tracker.py @@ -135,8 +135,8 @@ def test_outputs( tracker.link() tracker.solve() - # test to_napari (and indirectly to_pandas) - df_tracker, graph_tracker = tracker.to_napari() + # test to_tracks_layer (and indirectly to_pandas) + df_tracker, graph_tracker = tracker.to_tracks_layer() df_original, graph_original = to_tracks_layer(config_instance) assert df_tracker.equals(df_original) diff --git a/ultrack/core/tracker.py b/ultrack/core/tracker.py index d3b0370..f3d21a3 100644 --- a/ultrack/core/tracker.py +++ b/ultrack/core/tracker.py @@ -144,7 +144,7 @@ def to_ctc(self, *args, **kwargs) -> None: to_ctc(config=self.config, *args, **kwargs) @functools.wraps(to_tracks_layer) - def to_napari(self, *args, **kwargs) -> Tuple[pd.DataFrame, Dict]: + def to_tracks_layer(self, *args, **kwargs) -> Tuple[pd.DataFrame, Dict]: self._assert_solved() tracks_df, graph = to_tracks_layer(self.config, *args, **kwargs) return tracks_df, graph