Repository: funkelab/motile_tracker (language: python)

Issue:
Update README.md



Discussion / hints:

Fix patch:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..fc75743
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,53 @@
+name: Docs build
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install conda dependencies
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: '3.10'
+          environment-file: conda_config.yml
+          channel-priority: true
+      - name: Install pip dependencies
+        shell: bash -el {0}  # this is necessary to activate the conda env
+        run: |
+          pip install ".[dev]"
+      - name: Build docs
+        shell: bash -el {0}
+        run: |
+          cd docs/
+          make html
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  # Deploy the artifact to GitHub pages.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/LICENSE b/LICENSE
index 32ce61b..bccbb86 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,5 +1,5 @@
 
-Copyright (c) 2023, Caroline Malin-Mayor
+Copyright (c) 2023, Howard Hughes Medical Institute
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
diff --git a/README.md b/README.md
index 8475cee..8ed99dd 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,30 @@
-# motile-plugin
+# Motile Napari Plugin
 
-[![License BSD-3](https://img.shields.io/pypi/l/motile-plugin.svg?color=green)](https://github.com/cmalinmayor/motile-plugin/raw/main/LICENSE)
-[![PyPI](https://img.shields.io/pypi/v/motile-plugin.svg?color=green)](https://pypi.org/project/motile-plugin)
-[![Python Version](https://img.shields.io/pypi/pyversions/motile-plugin.svg?color=green)](https://python.org)
-[![tests](https://github.com/cmalinmayor/motile-plugin/workflows/tests/badge.svg)](https://github.com/cmalinmayor/motile-plugin/actions)
-[![codecov](https://codecov.io/gh/cmalinmayor/motile-plugin/branch/main/graph/badge.svg)](https://codecov.io/gh/cmalinmayor/motile-plugin)
+[![tests](https://github.com/funkelab/motile-napari-plugin/workflows/tests/badge.svg)](https://github.com/funkelab/motile-napari-plugin/actions)
+[![codecov](https://codecov.io/gh/funkelab/motile-napari-plugin/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/motile-napari-plugin)
 [![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/motile-plugin)](https://napari-hub.org/plugins/motile-plugin)
 
-Tracking with Motile and the Graph layer
+A plugin for tracking with [motile](https://github.com/funkelab/motile) in napari. 
+Motile is a library that makes it easy to solve tracking problems using optimization 
+by framing the task as an Integer Linear Program (ILP).
+See the motile [documentation](https://funkelab.github.io/motile) 
+for more details on the concepts and method.
 
 ----------------------------------
 
-This [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.
-
-<!--
-Don't miss the full getting started guide to set up your new package:
-https://github.com/napari/cookiecutter-napari-plugin#getting-started
-
-and review the napari docs for plugin developers:
-https://napari.org/stable/plugins/index.html
--->
-
 ## Installation
 
-You can install `motile-plugin` via [pip]:
-
-    pip install motile-plugin
-
-
-
-To install latest development version :
-
-    pip install git+https://github.com/cmalinmayor/motile-plugin.git
+This plugin depends on [motile](https://github.com/funkelab/motile), which in 
+turn depends on gurobi and ilpy. These dependencies must be installed with 
+conda before installing the plugin with pip.
 
-
-## Contributing
-
-Contributions are very welcome. Tests can be run with [tox], please ensure
-the coverage at least stays the same before you submit a pull request.
-
-## License
-
-Distributed under the terms of the [BSD-3] license,
-"motile-plugin" is free and open source software
+    conda create -n motile-plugin python>=3.10
+    conda activate motile-plugin
+    conda install -c conda-forge -c funkelab -c gurobi ilpy
+    pip install git+https://github.com/funkelab/motile-napari-plugin.git
 
 ## Issues
 
-If you encounter any problems, please [file an issue] along with a detailed description.
-
-[napari]: https://github.com/napari/napari
-[Cookiecutter]: https://github.com/audreyr/cookiecutter
-[@napari]: https://github.com/napari
-[MIT]: http://opensource.org/licenses/MIT
-[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
-[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
-[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
-[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
-[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
-[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin
-
-[file an issue]: https://github.com/cmalinmayor/motile-plugin/issues
-
-[napari]: https://github.com/napari/napari
-[tox]: https://tox.readthedocs.io/en/latest/
-[pip]: https://pypi.org/project/pip/
-[PyPI]: https://pypi.org/
+If you encounter any problems, please 
+[file an issue](https://github.com/funkelab/motile-napari-plugin/issues) 
+along with a detailed description.
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..7d50994
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,16 @@
+project = 'Motile Plugin'
+copyright = '2024, Howard Hughes Medical Institute'
+author = 'Caroline Malin-Mayor'
+
+extensions = ['sphinx.ext.autodoc', 'myst_parser', 'autoapi.extension', 'sphinx_rtd_theme']
+autoapi_dirs = ['../../src/motile_plugin']
+
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+# html_static_path = ['_static']
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
new file mode 100644
index 0000000..485fd48
--- /dev/null
+++ b/docs/source/getting_started.rst
@@ -0,0 +1,61 @@
+Getting started with the motile plugin
+======================================
+
+Installation
+------------
+This plugin depends on ``ilpy``, which must be installed via conda.::
+
+    conda create -n motile-plugin python>=3.10
+    conda activate motile-plugin
+    conda install -c conda-forge -c funkelab -c gurobi ilpy
+    pip install git+https://github.com/funkelab/motile-napari-plugin.git
+
+If this is successful, you can then run ``napari`` from your command line, and
+the motile plugin should be visible in the "Plugins" drop down menu.
+Clicking this should open the motile widget on the right of the viewer.
+
+Input data
+----------
+The motile plugin takes as input expects a Labels layer with time as the
+first dimension followed by the spatial dimensions (no channels).
+You can load an example 2D HeLa Dataset from the `Cell Tracking Challenge`_ 
+in "Files" -> "Sample Data".
+
+In the future, we could also support Points layers as input - please react to 
+`Issue #30`_ if this is important to your use case. While source images are 
+nice to qualitatively evaluate results, they are not necessary to run tracking. 
+
+Running tracking
+----------------
+The motile plugin by default opens to the "Run Editor" view. In this section,
+you can pick a name for your run, select an input Labels layer, set
+hyperparameters, and start a motile run. Hovering over the title of each
+element in the widget will make a tooltip appear describing the purpose
+of the element. When you are ready, click the "Run" button to start tracking.
+
+Viewing run results
+-------------------
+Clicking the "Run" button will automatically take you to the "Run Viewer".
+Here you will see:
+
+- the solver status
+- a graph of the solver gap (an optimization value that should approach zero)
+- the hyperparameters of the run
+- a button to save the whole run (for persistent viewing in the plugin)
+- a button to export just the tracks as a CSV
+- a button to return to the Run Editor
+
+Once the solver completes, you will also see a segmentation and a tracks layer
+in the napari viewer. These are the tracking results.
+
+A list of "Tracking Runs" will also appear at the bottom of the 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. 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 Run" button.
+
+
+.. _Issue #30: https://github.com/funkelab/motile-napari-plugin/issues/30
+.. _Cell Tracking Challenge: https://celltrackingchallenge.net/
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..a768964
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,12 @@
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 3
+
+   getting_started
+
+Indices and tables
+==================
+
+* :ref:`search`
diff --git a/setup.cfg b/setup.cfg
index 7e9dcbf..b84773f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,10 +1,10 @@
 [metadata]
 name = motile-plugin
 version = attr: motile_plugin.__version__
-description = Tracking with Motile and the Graph layer
+description = Tracking with motile
 long_description = file: README.md
 long_description_content_type = text/markdown
-url = https://github.com/cmalinmayor/motile-plugin
+url = https://github.com/funkelab/motile-napari-plugin
 author = Caroline Malin-Mayor
 author_email = malinmayorc@janelia.hhmi.org
 license = BSD-3-Clause
@@ -18,19 +18,19 @@ classifiers =
     Programming Language :: Python
     Programming Language :: Python :: 3
     Programming Language :: Python :: 3 :: Only
-    Programming Language :: Python :: 3.8
-    Programming Language :: Python :: 3.9
     Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
     Topic :: Scientific/Engineering :: Image Processing
 project_urls =
-    Bug Tracker = https://github.com/cmalinmayor/motile-plugin/issues
-    Documentation = https://github.com/cmalinmayor/motile-plugin#README.md
-    Source Code = https://github.com/cmalinmayor/motile-plugin
-    User Support = https://github.com/cmalinmayor/motile-plugin/issues
+    Bug Tracker = https://github.com/funkelab/motile-napari-plugin/issues
+    Documentation = https://github.com/funkelab/motile-napari-plugin#README.md
+    Source Code = https://github.com/funkelab/motile-napari-plugin
+    User Support = https://github.com/funkelab/motile-napari-plugin/issues
 
 [options]
 packages = find:
 install_requires =
+    napari
     numpy
     magicgui
     qtpy
@@ -43,7 +43,7 @@ install_requires =
     pyqtgraph
     lxml_html_clean  # only to deal with napari dependencies being broken
 
-python_requires = >=3.8
+python_requires = >=3.10
 include_package_data = True
 package_dir =
     =src
@@ -65,6 +65,10 @@ testing =
     napari
     pyqt5
 
+docs =
+    sphinx
+    sphinx-autoapi
+    sphinx_rtd_theme
 
 [options.package_data]
 * = *.yaml
diff --git a/src/motile_plugin/_graph_layer_utils.py b/src/motile_plugin/_graph_layer_utils.py
deleted file mode 100644
index bd2c8bf..0000000
--- a/src/motile_plugin/_graph_layer_utils.py
+++ /dev/null
@@ -1,33 +0,0 @@
-from napari.layers import Graph
-from napari_graph import UndirectedGraph
-
-
-def get_location(node_data, loc_keys=("z", "y", "x")):
-    return [node_data[k] for k in loc_keys]
-
-
-def to_napari_graph_layer(graph, name, loc_keys=("t", "z", "y", "x")):
-    """A function to convert a networkx graph into a Napari Graph layer"""
-    nx_id_to_napari_id = {}
-    napari_id_to_nx_id = {}
-    napari_id = 0
-    for nx_id in graph.nodes:
-        nx_id_to_napari_id[nx_id] = napari_id
-        napari_id_to_nx_id[napari_id] = nx_id
-        napari_id += 1
-    num_nodes = napari_id
-
-    edges = [
-        [nx_id_to_napari_id[s], nx_id_to_napari_id[t]]
-        for s, t in graph.edges()
-    ]
-    coords = [
-        get_location(
-            graph.nodes[napari_id_to_nx_id[nap_id]], loc_keys=loc_keys
-        )
-        for nap_id in range(num_nodes)
-    ]
-    ndim = len(loc_keys)
-    napari_graph = UndirectedGraph(edges=edges, coords=coords, ndim=ndim)
-    graph_layer = Graph(data=napari_graph, name=name)
-    return graph_layer


Test patch:
diff --git a/.github/workflows/test_and_deploy.yml b/.github/workflows/test_and_deploy.yml
index 1693cb4..9da6ba8 100644
--- a/.github/workflows/test_and_deploy.yml
+++ b/.github/workflows/test_and_deploy.yml
@@ -66,7 +66,7 @@ jobs:
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          slug: funkelab/motile_napari_plugin
+          slug: funkelab/motile-napari-plugin
 
   deploy:
     # this will run when you have tagged a commit, starting with "v*"