updated docs and renamed to_napari to to_tracks_layer (#125)

royerlab · Jul 8, 2024 · 2a403c2 · 2a403c2
1 parent 299b26c
commit 2a403c2
Show file tree

Hide file tree

Showing 9 changed files with 54 additions and 15 deletions.
diff --git 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
@@ -66,6 +66,8 @@ Array utilities
 .. automodule:: ultrack.utils.array
     :members:
 
+.. _api_imgproc:
+
 ==========================
 Image processing utilities
 ==========================
@@ -77,13 +79,17 @@ Image processing utilities
 .. automodule:: ultrack.imgproc.sam
     :members:
 
+.. _api_flow:
+
 ----
 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
@@ -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
@@ -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 <tracking_config>` 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 <api_export>` 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 <api>`.
+For additional information, please refer to the :ref:`tracks post-processing API reference <api_tracks>`.
 
 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 <api>` for more information.
+Refer to the :ref:`image processing API reference <api_imgproc>` for more information.
diff --git 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 <api>`.
+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 <api_imgproc>`.
+
+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 <examples>`.
+See the :ref:`flow estimation API <api_flow>` 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 <examples>`.
+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 <api_imgproc>` 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
@@ -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
@@ -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
@@ -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
@@ -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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,4 +32,6 @@ The configurations are documented below, the parameters are ordered by importanc

		---------------

		.. _tracking_config:

		.. autopydantic_model:: ultrack.config.TrackingConfig