Deprecate motile run

docs/source/getting_started.rst

@@ -95,18 +95,17 @@ You can :doc:`view the results <tree_view>` using the synchronized napari layers
 if you select the new labels/points layer as input: our next major feature to add
 is incorporating the detection and linking corrections into the optimization task in a more principled manner.
 
-Each ``Tracking Run`` will be stored in the ``Tracks List`` widget.
+Each ``Tracking Run`` will be stored in the ``Results List`` widget.
 These are the runs that are stored in memory - if you run tracking multiple
 times with different inputs or parameters, you can click back and forth
-between the results here. Here you can also save any runs that you want to store for later,
-or export the tracks to `geff`_ or csv, optionally including the (relabeled) segmentation.
+between the results here.
 If your input was a Labels layer, the ``node_id`` will be determined by segmentation label id. If your original segmentation
 repeated labels across time, the application will relabel them all to be unique, and
 the new label id will be used as the node id.
 If your input was a Points layer, the ``node_id`` is simply the index of the
 node in the list of points.
 Deleting runs you do not want to keep viewing is a good idea, since these are stored in memory.
-Runs that were saved in previous sessions do not appear here until you load them from disk with the ``Load Tracks`` button.
+Tracks that were saved in previous sessions do not appear here until you load them from disk with the ``Load`` button.
 The tracking results can also be visualized as a lineage tree.
 You can open the lineage tree widget via ``Plugins`` > ``Motile Tracker`` > ``Widget - Lineage View``.
 For more details, go to the :doc:`Tree View <tree_view>` documentation.
@@ -116,6 +115,75 @@ Displaying feature measurements
 If you are tracking with a segmentation layer, you can select size and shape features to measure in the ``Features`` widget.
 Once selected, the measurements for these features will appear in the ``Lineage View`` (select ``Plot`` > ``Feature`` to display them), and in the ``Table`` widget.
 
+.. _save-load-vs-import-export:
+
+Saving and loading vs. importing and exporting
+**********************************************
+The ``Results List`` widget offers two different ways of getting tracks in and out
+of the application, and it is worth understanding which one you want.
+
+**Saving and loading** is for continuing your own work. The application controls the
+format, so it can make and enforce assumptions about it: tracks are always written
+as a `geff`_ store, with the metadata and attributes the application needs already
+in place. Anything you save can be loaded back into a later session and picked up
+exactly where you left off, including run-specific extras like the motile solver
+parameters. Use this while you are still working on a dataset.
+
+**Importing and exporting** is for exchanging tracks with other tools. Here the
+application cannot assume much about the format, so it supports more of them (`geff`_
+and CSV) and asks you to fill in the gaps - which column means what, how the data is
+scaled, where the segmentation lives. An export is a snapshot for another tool to read,
+not a session you can resume, and importing tracks from elsewhere requires the
+column mapping step described in :doc:`Importing externally generated tracks <view_external_tracks>`.
+
+In short: save/load round-trips within the application, import/export crosses the
+boundary to other tools.
+
+Saving tracks
+-------------
+Above the results list are a ``Save directory`` field, with a ``Browse`` button, and a
+``Save filename`` field. Together these are the path that the save (floppy disk) button
+beside a set of tracks writes to; the ``.geff`` suffix is added for you and shown as a
+fixed label beside the filename. The directory starts out as an application-owned
+location (the same place the sample data is downloaded to) and the filename follows
+whichever tracks you have selected, so in the common case you can simply click save.
+
+Both fields are editable, and your edits last for the rest of the session - so if you
+point the directory somewhere else once, subsequent saves go there too. Once you have
+typed your own filename it stops following the selection, so selecting different tracks
+will not overwrite what you typed. Because names in the results list are not required to
+be unique, always check the filename before saving if you have several similarly named
+sets of tracks.
+
+Saving writes to exactly the path shown; there is no timestamped subdirectory. If
+something already exists at that path you will be asked to confirm before it is
+replaced. Note that saving a set of tracks over an existing geff store replaces the
+tracks but leaves any other files in the store alone.
+
+Loading tracks
+--------------
+The dropdown menu at the bottom of the widget selects what to load, and the ``Load``
+button starts it:
+
+- ``Tracks (geff)`` - load tracks previously saved from this application. Select the
+  ``.geff`` store itself.
+- ``Motile Run`` - load a saved motile run, which restores the solver parameters into
+  the ``Run Editor`` along with the tracks. Select the ``.geff`` store the run was
+  saved to. Runs saved by older versions, which used a timestamped directory
+  containing the tracks and a separate parameters file, can still be loaded.
+- ``External tracks from CSV`` and ``External tracks from geff`` - import tracks that
+  were generated elsewhere. These open the import dialog, where you map columns to
+  attributes and optionally provide a segmentation; see
+  :doc:`Importing externally generated tracks <view_external_tracks>`.
+
+Exporting tracks
+----------------
+The export button beside a set of tracks in the results list opens the export dialog,
+where you choose ``GEFF``
+or ``CSV`` and pick the location, optionally including the (relabeled) segmentation as
+zarr or tiff. You can also export a subset of tracks from the Groups tab. Exported tracks are meant to be read by other tools: to continue working
+on them here later, save them instead.
+
 .. _Issue #48: https://github.com/funkelab/motile_tracker/issues/48
 .. _Cell Tracking Challenge: https://celltrackingchallenge.net/
 .. _Fabrèges et al (2024): https://www.science.org/doi/10.1126/science.adh1145

docs/source/view_external_tracks.rst

@@ -1,15 +1,25 @@
-Viewing Externally Generated Tracks
-===================================
+Importing Externally Generated Tracks
+=====================================
 
 Usage Overview
 **************
 
 It is also possible to view tracks that were not created from the motile widget using
-the synchronized Lineage View and napari layers. To do so, navigate to the ``Tracks List`` tab and
+the synchronized Lineage View and napari layers. Bringing them in is an *import* rather
+than a load: because the application cannot assume anything about how another tool
+wrote the data, you have to describe its layout as part of importing it. See
+:ref:`save-load-vs-import-export` for how this differs from loading tracks you saved
+here yourself.
+
+To import, navigate to the ``Results List`` tab and
 select ``External tracks from CSV`` or ``External tracks from geff`` in the dropdown menu at the bottom of the widgets, and click ``Load``.
 A pop up menu will allow you to select a CSV file or geff zarr folder and map its columns to the required default attributes and optional additional attributes.
 You may also provide the accompanying segmentation and specify scaling information.
 
+Once imported, tracks appear in the results list like any other set of tracks, and can
+be edited and then saved in the application's own format so that later sessions can load
+them back without repeating the column mapping.
+
 The following columns have to be selected:
 
 - time: representing the position of the object in the time dimension.

pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
 
 dependencies =[
     "napari>=0.6.2,<0.8.0",
-    "funtracks>=2,<3",
+    "funtracks>=2.0.3,<3",
     "appdirs>=1,<2",
     "numpy>=2,<3",
     "magicgui>=0.10.1",
@@ -109,7 +109,11 @@ addopts = "--ignore=tests/benchmarks"
 # that pointing pytest at the tests/benchmarks directory discovers them.
 python_files = ["test_*.py", "bench_*.py"]
 filterwarnings = [
-    "error::DeprecationWarning:funtracks",
+    # Temporarily disabled: motile_tracker still converts to the deprecated
+    # SolutionTracks when emitting tracks, because the views/actions require
+    # track IDs. Re-add when we refactor to operate on Tracks directly, ahead
+    # of the next major funtracks release.
+    # "error::DeprecationWarning:funtracks",
 ]
 
 [tool.setuptools_scm]