Rename diplomat tracking commands for clarity.

README.md

@@ -21,22 +21,7 @@ DIPLOMAT also includes a UI for performing tracking and several other tools for
 
 ## Installation
 
-To install DIPLOMAT with PIP right now, you can and install it with pip using one of the following commands below:
-```bash
-# For working with SLEAP projects:
-pip install diplomat-track[sleap]
-# For working with DeepLabCut projects:
-pip install diplomat-track[dlc]
-```
-To install DIPLOMAT with GUI elements and supervised tracking support, use one of the commands below:
-```bash
-# For using DIPLOMAT with SLEAP
-pip install diplomat-track[sleap, gui]
-# Again, replace sleap with dlc to install with DeepLabCut support.
-pip install diplomat-track[dlc, gui]
-```
-
-**NOTE:** DIPLOMAT also includes two environment configuration files for setting up DIPLOMAT with 
+DIPLOMAT also includes four environment configuration files for setting up DIPLOMAT with 
 [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), which can
 be installed on Windows, Linux, or MacOS using the [Miniforge](https://github.com/conda-forge/miniforge) installer.
 To create an environment using mamba, run one of these four commands:
@@ -60,7 +45,8 @@ mamba activate DIPLOMAT-DEEPLABCUT
 mamba activate DIPLOMAT-SLEAP
 ```
 
-For a more thorough explanation of the installation process, see the [documentation](https://diplomat.readthedocs.io/en/latest/installation.html).
+For a more thorough explanation of the installation process and alternative installation methods, see the 
+[documentation](https://diplomat.readthedocs.io/en/latest/installation.html).
 
 ## Usage
 
@@ -69,27 +55,33 @@ For a more thorough explanation of the installation process, see the [documentat
 To run DIPLOMAT on a video once it is installed, simply use DIPLOMAT's `unsupervised` and `supervised` commands to track a video:
 ```bash
 # Run DIPLOMAT with no UI...
-diplomat unsupervised -c path/to/config -v path/to/video
+diplomat track -c path/to/config -v path/to/video
 # Run DIPLOMAT with UI...
-diplomat supervised -c path/to/config -v path/to/video
+diplomat track_and_interact -c path/to/config -v path/to/video
 ```
 
 Multiple videos can be tracked by passing them as a list:
 ```bash
-diplomat unsupervised -c path/to/config -v [path/to/video1, path/to/video2, "path/to/video3"]
+diplomat track -c path/to/config -v [path/to/video1, path/to/video2, "path/to/video3"]
 ```
 
 Once tracking is done, DIPLOMAT can create labeled videos via it's `annotate` subcommand:
 ```bash
 diplomat annotate -c path/to/config -v path/to/video
 ```
 
+If you need to reopen the UI to make further major modifications, you can do so using the interact subcommand:
+```bash
+diplomat interact -s path/to/ui_state.dipui
+```
+This displays the full UI again for making further edits. Results are saved back to the same files.
+
 If you need to make minor modifications after tracking a video, you can do so using the tweak subcommand:
 ```bash
 diplomat tweak -c path/to/config -v path/to/video
 ```
-This will display a stripped down version of the supervised editing UI, allowing for minor tweaks to be made to the tracks, and then
-saved back to the same file.
+This will display a stripped down version of the interactive editing UI, allowing for minor tweaks to be made to the 
+tracks, and then saved back to the same file.
 
 For a list of additional ways DIPLOMAT can be used, see the [documentation](https://diplomat.readthedocs.io/en/latest/basic_usage.html).
 

diplomat/__init__.py

@@ -9,7 +9,7 @@
 from diplomat.predictor_ops import list_predictor_plugins, get_predictor_settings, test_predictor_plugin
 from diplomat.frontend_ops import list_all_frontends, list_loaded_frontends
 from diplomat.utils.video_splitter import split_videos
-from diplomat.core_ops import track, supervised, unsupervised, annotate, tweak, yaml, convert, restore
+from diplomat.core_ops import track_with, track, track_and_interact, annotate, tweak, yaml, convert, interact
 
 __all__ = [
     "list_predictor_plugins",
@@ -18,14 +18,14 @@
     "list_all_frontends",
     "list_loaded_frontends",
     "split_videos",
+    "track_with",
+    "track_and_interact",
     "track",
-    "supervised",
-    "unsupervised",
     "annotate",
     "tweak",
     "yaml",
     "convert",
-    "restore"
+    "interact"
 ]
 
 

diplomat/_cli_runner.py

@@ -16,15 +16,15 @@ def get_static_cli_tree() -> dict:
             "test": diplomat.test_predictor_plugin,
             "list_settings": diplomat.get_predictor_settings
         },
+        "track_with": diplomat.track_with,
+        "track_and_interact": diplomat.track_and_interact,
         "track": diplomat.track,
-        "supervised": diplomat.supervised,
-        "unsupervised": diplomat.unsupervised,
         "annotate": diplomat.annotate,
         "split_videos": diplomat.split_videos,
         "tweak": diplomat.tweak,
         "yaml": diplomat.yaml,
         "convert": diplomat.convert,
-        "restore": diplomat.restore,
+        "interact": diplomat.interact,
         "frontends": {
             "__description": "Contains subcommands for listing available frontends and inspecting the functions "
                              "each frontend supports.",

diplomat/core_ops.py

@@ -166,7 +166,7 @@ def yaml(
 
 @allow_arbitrary_flags
 @typecaster_function
-def track(
+def track_with(
     config: Union[List[PathLike], PathLike],
     videos: Optional[Union[List[PathLike], PathLike]] = None,
     frame_stores: Optional[Union[List[PathLike], PathLike]] = None,
@@ -178,6 +178,7 @@ def track(
 ):
     """
     Run DIPLOMAT tracking on videos and/or frame stores. Automatically select a frontend based on the passed arguments.
+    Allows for selecting a specific tracker, or predictor.
 
     :param config: The path to the configuration file for the project. The format of this argument will depend on the frontend.
     :param videos: A single path or list of paths to video files to run analysis on.
@@ -243,7 +244,7 @@ def track(
 
 @allow_arbitrary_flags
 @typecaster_function
-def unsupervised(
+def track(
     config: Union[List[PathLike], PathLike],
     videos: Optional[Union[List[PathLike], PathLike]] = None,
     frame_stores: Optional[Union[List[PathLike], PathLike]] = None,
@@ -253,24 +254,28 @@ def unsupervised(
     **extra_args
 ):
     """
-    Run diplomat in unsupervised mode on the specified config and videos or frame stores. An alias for
-    DIPLOMAT track with the SegmentedFramePassEngine predictor.
+    Run diplomat in a non-interactive tracking mode on the specified config and videos or frame stores. An alias for
+    DIPLOMAT track_with with the SegmentedFramePassEngine predictor. The interactive UI can be restored later using
+    diplomat interact function or cli command.
 
-    :param config: The path to the configuration file for the project. The format of this argument will depend on the frontend.
+    :param config: The path to the configuration file for the project. The format of this argument will depend on the
+                   frontend.
     :param videos: A single path or list of paths to video files to run analysis on.
     :param frame_stores: A single path or list of paths to frame store files to run analysis on.
     :param num_outputs: An integer, the number of bodies to track in the video. Defaults to 1.
-    :param settings: An optional dictionary, listing the settings to use for the SegmentedFramePassEngine predictor plugin.
-                     If not specified, the frontend will determine the settings in a frontend specific manner. To see the settings the
-                     SegmentedFramePassEngine supports, use the "diplomat predictors list_settings -p SegmentedFramePassEngine" command
-                     or "diplomat.get_predictor_settings('SegmentedFramePassEngine')". To get more information about how a frontend gets
-                     settings if not passed, set the help_extra parameter to True to print additional settings for the selected
-                     frontend instead of running tracking.
-    :param help_extra: Boolean, if set to true print extra settings for the automatically selected frontend instead of running tracking.
-    :param extra_args: Any additional arguments (if the CLI, flags starting with '--') are passed to the automatically selected frontend.
-                       To see valid values, run track with extra_help flag set to true.
+    :param settings: An optional dictionary, listing the settings to use for the SegmentedFramePassEngine predictor
+                     plugin. If not specified, the frontend will determine the settings in a frontend specific manner.
+                     To see the settings the SegmentedFramePassEngine supports, use the
+                     "diplomat predictors list_settings -p SegmentedFramePassEngine" command
+                     or "diplomat.get_predictor_settings('SegmentedFramePassEngine')". To get more information about
+                     how a frontend gets settings if not passed, set the help_extra parameter to True to print
+                     additional settings for the selected frontend instead of running tracking.
+    :param help_extra: Boolean, if set to true print extra settings for the automatically selected frontend instead of
+                       running tracking.
+    :param extra_args: Any additional arguments (if the CLI, flags starting with '--') are passed to the automatically
+                       selected frontend. To see valid values, run track with extra_help flag set to true.
     """
-    track(
+    track_with(
         config=config,
         videos=videos,
         frame_stores=frame_stores,
@@ -284,7 +289,7 @@ def unsupervised(
 
 @allow_arbitrary_flags
 @typecaster_function
-def supervised(
+def track_and_interact(
     config: Union[List[PathLike], PathLike],
     videos: Optional[Union[List[PathLike], PathLike]] = None,
     frame_stores: Optional[Union[List[PathLike], PathLike]] = None,
@@ -294,8 +299,8 @@ def supervised(
     **extra_args
 ):
     """
-    Run diplomat in supervised mode on the specified config and videos or frame stores. An alias for
-    DIPLOMAT track with the SupervisedSegmentedFramePassEngine predictor.
+    Run diplomat in interactive tracking mode on the specified config and videos or frame stores. An alias for
+    DIPLOMAT track_with with the SupervisedSegmentedFramePassEngine predictor.
 
     :param config: The path to the configuration file for the project. The format of this argument will depend on the frontend.
     :param videos: A single path or list of paths to video files to run analysis on.
@@ -311,7 +316,7 @@ def supervised(
     :param extra_args: Any additional arguments (if the CLI, flags starting with '--') are passed to the automatically selected frontend.
                        To see valid values, run track with extra_help flag set to true.
     """
-    track(
+    track_with(
         config=config,
         videos=videos,
         frame_stores=frame_stores,
@@ -375,8 +380,9 @@ def tweak(
     **extra_args
 ):
     """
-    Make modifications to DIPLOMAT produced tracking results created for a video using a limited version supervised
-    labeling UI. Allows for touching up and fixing any minor issues that may arise after tracking and saving results.
+    Make modifications to DIPLOMAT produced tracking results created for a video using a limited version of the
+    interactive labeling UI. Allows for touching up and fixing any minor issues that may arise after tracking and
+    saving results.
 
     :param config: The path to the configuration file for the project. The format of this argument will depend on the
                    frontend.
@@ -464,12 +470,13 @@ def convert(
 
 
 @typecaster_function
-def restore(
+def interact(
     state: Union[List[PathLike], PathLike]
 ):
     """
-    Restore the state of the diplomat UI from a .dipui file. Allows for reloading the UI when diplomat crashes.
-    Settings and backend will be restored automatically based on the settings and info passed during the first run.
+    Open diplomat's interactive UI from a .dipui file. Allows for reloading the UI when diplomat crashes, or for
+    further editing. Settings and backend will be restored automatically based on the settings and info passed during
+    the first run.
 
     :param state: A path or list of paths to the ui states to restore. Files should be of ".dipui" format.
     """

diplomat/frontends/csv/tweak_results.py

@@ -19,7 +19,7 @@ def tweak_videos(
     **kwargs
 ):
     """
-    Make minor modifications and tweaks to arbitrary csv files using DIPLOMAT's supervised UI.
+    Make minor modifications and tweaks to arbitrary csv files using DIPLOMAT's light interactive UI.
 
     :param config: The path (or list of paths) to the csv file(s) to edit.
     :param videos: Paths to video file(s) corresponding to the provided csv files.

diplomat/frontends/deeplabcut/tweak_results.py

@@ -19,7 +19,8 @@ def tweak_videos(
     video_type: str = "",
 ):
     """
-    Make minor modifications and tweaks to tracked results produced by DEEPLABCUT (or DIPLOMAT) using the supervised UI.
+    Make minor modifications and tweaks to tracked results produced by DEEPLABCUT (or DIPLOMAT) using the interactive
+    UI.
 
     :param config: The path to the config.yaml file for the project.
     :param videos: A single video or list of videos to tweak, passed in order to modify.

diplomat/frontends/sleap/tweak_results_sleap.py

@@ -26,7 +26,7 @@ def tweak_videos(
     **kwargs
 ):
     """
-    Make minor modifications and tweaks to sleap results (stored in .slp files) using DIPLOMAT's supervised UI.
+    Make minor modifications and tweaks to sleap results (stored in .slp files) using DIPLOMAT's interactive UI.
 
     :param config: The path (or list of paths) to the sleap model(s) used for inference, each as either as a folder or zip file.
     :param videos: Paths to the sleap label files, or .slp files, to make minor modifications to, NOT the video files.

diplomat/predictors/supervised_sfpe/supervised_segmented_frame_pass_engine.py

@@ -114,7 +114,7 @@ def frames(self, frames):
 
 class SupervisedSegmentedFramePassEngine(SegmentedFramePassEngine):
     """
-    The supervised version of the :plugin:`~diplomat.predictors.SegmentedFramePassEngine` predictor.
+    The supervised (aka interactive) version of the :plugin:`~diplomat.predictors.SegmentedFramePassEngine` predictor.
     Provides a GUI for modifying results at the end of the tracking process.
     """
 

diplomat/utils/tweak_ui.py

@@ -1,5 +1,5 @@
 """
-Contains utilities for loading user tracks into a lighter version of the supervised UI to allow for minor modifications
+Contains utilities for loading user tracks into a lighter version of the interactive UI to allow for minor modifications
 to user saved tracking data.
 """
 
@@ -246,7 +246,7 @@ def tweak(
         make_app: bool = True
     ):
         """
-        Load a lighter version of the supervised UI to allow for minor modifications to user saved tracking data.
+        Load a lighter version of the interactive UI to allow for minor modifications to user saved tracking data.
 
         :param parent: The parent wx widget of the UI. Can be None, indicating no parent widget, or an independent window.
         :param video_path: The path to the video to display in the editor.

diplomat/wx_gui/__init__.py

@@ -3,5 +3,5 @@
 controls for video playback, pose editing, plotting, etc. Used by the
 :plugin:`~diplomat.predictors.SupervisedSegmentedFramePassEngine` predictor,
 :plugin:`~diplomat.predictors.SupervisedFramePassEngine` predictor,
-:cli:`diplomat tweak` command, :cli:`diplomat supervised` command, and :cli:`diplomat restore` command.
+:cli:`diplomat tweak` command, :cli:`diplomat track_and_interact` command, and :cli:`diplomat interact` command.
 """

diplomat/wx_gui/fpe_editor.py

@@ -1,5 +1,5 @@
 """
-Includes DIPLOMAT's main GUI editor window. Displayed when a supervised run is performed or restored.
+Includes DIPLOMAT's main GUI editor window. Displayed when an interactive run is performed or restored.
 The GUI allows for editing and rerunning tracking on the fly by the user.
 """
 

docs/README.md

@@ -0,0 +1,59 @@
+# DIPLOMAT Documentation
+
+This folder contains documentation for DIPLOMAT. These are automatically built using Github actions/read the docs when
+pushing to the main branch of diplomat, but can also be built locally. 
+
+DIPLOMAT uses [Sphinx](https://www.sphinx-doc.org/en/master/) for handling documentation. All the docs can be found in
+the `source` folder. Sphinx uses restructured text (`.rst`) for handling documentation. 
+The index of the documentation is `source/index.rst`, so if you add a file to DIPLOMAT's documentation, make sure to
+include it in the index file under its table of contents (under the `toctree` element). 
+
+Configuration of Sphinx is found under `source/conf.py`. DIPLOMAT uses some custom styling (`source/_static/css`), and
+also includes a custom extension for properly documenting and building links for the API, CLI, and Plugins. This
+extension can be found under `source/ext/plugin_docgen.py`. The extension adds custom types and links to Sphinx, so
+that CLI commands, and plugins can be linked to easily in documentation and doc strings in the code. 
+Some examples are shown below:
+```rst
+To link to a plugin, use the plugin prefix like :plugin:`~diplomat.predictors.FastPlotterArgmax`, 
+:plugin:`~diplomat.frontends.SLEAPFrontend`, or :plugin:`~diplomat.predictors.fpe.frame_pass.MITViterbi`.
+
+To link to a CLI commands, use the cli prefix, like :cli:`diplomat track`, or :cli:`diplomat frontends list loaded`.
+```
+
+The extension also comes with custom templates, which are a mix of restructured text and python f-strings for 
+dynamically injecting info from the extension. These are found in `source/_templates`, and exclude the custom class
+and custom module templates (which are just standard sphinx/jinja templates).
+
+## Building Documentation Locally
+
+To build documentation on your local machine, you'll need to create a python environment for docs and activate it. 
+This can be done using venv as below. (You can also use other environments, such as conda or mamba environments)
+
+```bash
+# On unix
+python -m venv venv
+source venv/bin/activate
+# On windows (cmd)
+python -m venv venv
+cd venv/Scripts
+Activate.bat
+cd ../..
+```
+
+Once a virtual environment is activated, you can install the documentation dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+And build the documentation (as html) use the following command:
+
+```bash
+make html
+```
+
+Now you can navigate to [build/html/index.html](build/html/index.html) relative to this folder, to preview the 
+locally built docs in your browser.
+
+DIPLOMAT's documentation can be built into many formats (epub, pdf, latex, man pages, etc). 
+To see all the other formats DIPLOMAT's docs can build to, simply run the command `make help`.