add usage code to API, update mentions of hydra

docs/source/api.rst

@@ -1,15 +1,69 @@
+.. _lightning_pose_api:
+
 ##################
 Lightning Pose API
 ##################
 
 
-Training
-========
+Train function
+==============
 
 .. autofunction:: lightning_pose.train.train
 
-Inference
-=========
+To train a model using ``config.yaml`` and output to ``outputs/doc_model``:
+    .. code-block:: python
+
+        import os
+        from lightning_pose.train import train
+        from omegaconf import OmegaConf
+
+        cfg = OmegaConf.load("config.yaml")
+        os.chdir("outputs/doc_model")
+        train(cfg)
+
+To override settings before training:
+    .. code-block:: python
+
+        cfg = OmegaConf.load("config.yaml")
+        overrides = {
+            "training": {
+                "min_epochs": 5,
+                "max_epochs": 5
+            }
+        }
+        cfg = OmegaConf.merge(cfg, overrides)
+        train(cfg)
+
+Training returns a Model object, which is described next.
+
+Model class
+===========
+
+The ``Model`` class provides an easy-to-use interface to a lightning-pose
+model. It supports running inference and accessing model metadata.
+The set of supported Model operations will expand as we continue development.
+
+You create a model object using `Model.from_dir`:
+
+.. code-block:: python
+
+    from lightning_pose.model import Model
+
+    model = Model.from_dir("outputs/doc_model")
+
+Then, to predict on new data:
+
+.. code-block:: python
+
+    model.predict_on_video_file("path/to/video.mp4")
+
+or:
+
+.. code-block:: python
+
+    model.predict_on_label_csv("path/to/csv_file.csv")
+
+API Reference:
 
 .. autoclass:: lightning_pose.model.Model
     :members:

docs/source/developer_guide/add_a_loss.rst

@@ -198,7 +198,7 @@ from the ``data`` field) you can add those key-value pairs to the constructor in
 
 Step 4: update ``compute_metrics`` (optional)
 ---------------------------------------------
-The base training script ``scripts/train_hydra.py`` will automatically compute a set of metrics on
+Lightning pose will automatically compute a set of metrics on
 all labeled data and unlabeled videos upon training completion.
 To add your new metric to this operation, you must update
 :meth:`~lightning_pose.utils.scripts.compute_metrics`.

docs/source/developer_guide/add_a_model.rst

@@ -182,10 +182,6 @@ The field ``model.model_type`` is used to specify your model - the current suppo
 "regression", "heatmap", and "heatmap_mhcrnn".
 Add your new model name to this list.
 
-The basic training script can be found at ``scripts/train_hydra.py``.
-You do not need to update anything in this script to accommodate your new model, but this script
-uses several helper functions that we will update next.
-
 Step 2: update ``get_dataset``
 ------------------------------
 The first helper function you need to update is
@@ -217,8 +213,8 @@ Finally, there is helper function :meth:`~lightning_pose.utils.predictions.get_m
 is used to seamlessly load model parameters from checkpoint files.
 Again, there are various ``if/else`` statements where your model should be incorporated.
 
-Step 6: optional and miscellaneous additons
--------------------------------------------
+Step 6: optional and miscellaneous additions
+--------------------------------------------
 
 If you find yourself needing to write a new DALI dataloader to support your model training, you might also need to update the :class:`~lightning_pose.utils.predictions.PredictionHandler` class.
 

docs/source/user_guide/config_file.rst

@@ -95,7 +95,8 @@ See the :ref:`FAQs <faq_oom>` for more information on memory management.
   If the value is a float between 0 and 1 then it is interpreted as the fraction of total train frames.
   If the value is an integer greater than 1 then it is interpreted as the number of total train frames.
 
-.. _config_num_gpus:
+    .. _config_num_gpus:
+
 * ``training.num_gpus`` (*int, default: 1*): the number of GPUs for
   :ref:`multi-GPU training <multi_gpu_training>`
 
@@ -245,15 +246,14 @@ Evaluation
 
 The following parameters are used for general evaluation.
 
-* ``eval.predict_vids_after_training`` (*bool, default: true*): if true, after training (when using
-  scripts/train_hydra.py) run inference with the best model on all videos located in
-  ``eval.test_videos_directory`` (see below)
+* ``eval.predict_vids_after_training`` (*bool, default: true*): if true, after training run
+  inference on all videos located in ``eval.test_videos_directory`` (see below)
 
 * ``eval.test_videos_directory`` (*str, default: null*): absolute path to a video directory
-  containing videos for prediction; used in scripts/train_hydra.py and scripts/predict_new_vids.py
+  containing videos for post-training prediction.
 
 * ``eval.save_vids_after_training`` (*bool, default: false*): save out an mp4 file with predictions
-  overlaid after running inference; used in scripts/train_hydra.py and scripts/predict_new_vids.py
+  overlaid after running post-training prediction.
 
 * ``eval.colormap`` (*str, default: cool*): colormap options for labeled videos; options include
   sequential colormaps (viridis, plasma, magma, inferno, cool, etc) and diverging colormaps (RdBu,
@@ -262,11 +262,10 @@ The following parameters are used for general evaluation.
 * ``eval.confidence_thresh_for_vid`` (*float, default: 0.9*): predictions with confidence below this
   value will not be plotted in the labeled videos
 
-* ``eval.hydra_paths`` (*list, default: []*): absolute paths to hydra output folders for use with
-  scripts/predict_new_vids.py (see :ref:`inference <inference>` docs) and
-  scripts/create_fiftyone_dataset.py (see :ref:`FiftyOne <fiftyone>` docs)
-
 * ``eval.fiftyone.dataset_name`` (*str, default: test*): name of the FiftyOne dataset
 
 * ``eval.fiftyone.model_display_names`` (*list, default: [test_model]*): shorthand name for each of
   the models specified in ``hydra_paths``
+
+* ``eval.hydra_paths`` (*list, default: []*): absolute paths to model directories, only for use with
+  scripts/create_fiftyone_dataset.py (see :ref:`FiftyOne <fiftyone>` docs).

docs/source/user_guide/evaluation.streamlit.rst

@@ -13,13 +13,10 @@ Run the following command from inside the ``lightning-pose/lightning_pose/apps``
 
 .. code-block:: console
 
-    streamlit run labeled_frame_diagnostics.py -- --model_dir <ABOLUTE_PATH_TO_HYDRA_OUTPUTS_DIRECTORY>
+    streamlit run labeled_frame_diagnostics.py -- --model_dir <ABSOLUTE_PATH_TO_OUTPUT_DIRECTORY>
 
-The only argument needed is ``--model_dir``, which tells the app where to find models and their predictions. ``<ABOLUTE_PATH_TO_HYDRA_OUTPUTS_DIRECTORY>`` should contain hydra subfolders of the type ``YYYY-MM-DD/HH-MM-SS``.
-
-.. note:
-
-    The lightning-pose output folder for a single model is typically ``/path/to/lightning-pose/outputs/YYYY-MM-DD/HH-MM-SS``, where the last folder contains prediction csv files.
+The only argument needed is ``--model_dir``, which tells the app where to find model directories.
+It should contain model directories of the type ``YYYY-MM-DD/HH-MM-SS``.
 
 The app shows:
 

docs/source/user_guide/inference.rst

@@ -4,15 +4,12 @@
 Inference
 #########
 
-Since version 1.7.0, installing lightning-pose also installs the ``litpose`` command.
+Since version 1.7.0, installing lightning-pose also installs ``litpose``,
+a command-line tool built on top of the :ref:`lightning_pose_api`.
 The command ``litpose predict`` is used to run model inference on new data.
 
-The command-line tool is a wrapper around our python library.
-If you wish to interface directly with the python library,
-see the source code at ``lightning_pose/cli/main.py`` for a usage example.
-
-Inference on new videos using the command-line
-==============================================
+Inference on new videos
+=======================
 
 The model_dir argument is the path to the model outputted by ``litpose train``.
 
@@ -44,8 +41,8 @@ For the full list of options:
   :ref:`FAQs<faq_video_formats>`.
 
 
-Inference on new images using the command-line
-==============================================
+Inference on new images
+=======================
 
 Lightning pose also supports inference on images, as well 
 as computing pixel error against new labeled images. This is useful

docs/source/user_guide/training.rst

@@ -4,9 +4,6 @@
 Training
 ########
 
-Preparation
-===========
-
 If this is your first time training a model, you'll need to:
 
 #. Organize your data (per the document in :ref:`directory_structure`)
@@ -15,7 +12,7 @@ If this is your first time training a model, you'll need to:
 After that, you are ready to train a model.
 
 Create a valid config file
---------------------------
+==========================
 
 Copy the default config (`config_default.yaml`_)
 to a local file and modify the ``data`` section to point to your own dataset. For example:
@@ -42,15 +39,11 @@ to a local file and modify the ``data`` section to point to your own dataset. Fo
 Sections other than ``data`` have reasonable defaults for getting started,
 but can be modified as well. For the full reference of fields, see :ref:`config_file`.
 
-Training a model using the command-line
-=======================================
-
-Since version 1.7.0, installing lightning-pose also installs the ``litpose`` command.
-The command ``litpose train`` is used to train new models.
+Train a model
+=============
 
-The command-line tool is a wrapper around our python library.
-If you wish to interface directly with the python library,
-see the source code at ``lightning_pose/cli/main.py`` for a usage example.
+Since version 1.7.0, installing lightning-pose also installs ``litpose``,
+a command-line tool built on top of the :ref:`lightning_pose_api`.
 
 To train a model, just point ``litpose train`` at your config file:
 
@@ -125,14 +118,10 @@ sample dataset. Clone the repository and run the train command pointed at our sa
 Tensorboard
 ===========
 
-The outputs of the training script, namely the model checkpoints and tensorboard logs,
-will be saved in the ``lightning-pose/outputs/YYYY-MM-DD/HH-MM-SS/tb_logs`` directory by default.
-(Note: this behavior can be changed by updating ``hydra.run.dir`` in the config file to an
-absolute path of your choosing.)
+Training metrics such as losses are logged in ``model_dir/tb_logs``.
+To view the logged losses via tensorboard, run:
 
-To view the logged losses with tensorboard in your browser, in the command line, run:
-
-.. code-block:: console
+.. code-block:: shell
 
     tensorboard --logdir outputs/YYYY-MM-DD/
 
@@ -189,15 +178,9 @@ The following are important metrics for the semi-supervised models:
 Model directory structure
 =========================
 
-If you train a model using our script ``lightning-pose/scripts/train_hydra.py``,
-a directory will be created with the following structure.
-The default is to save models in a directory called ``outputs`` inside the Lightning Pose
-directory; to change this, update the config fields ``hydra.run.dir`` and ``hydra.sweep.dir``
-with absolute paths of your choosing.
-
 .. code-block::
 
-    /path/to/models/YYYY-MM-DD/HH-MM-SS/
+    /path/to/model/YYYY-MM-DD/HH-MM-SS/
       ├── tb_logs/
       ├── video_preds/
       │   └── labeled_videos/

docs/source/user_guide_advanced/multi_gpu_training.rst

@@ -57,8 +57,8 @@ Execution model
     The implementation spawns ``num_gpus - 1`` processes of the same command originally executed,
     repeating all of the command's execution per process.
     Thus it is advised to only run multi-GPU training in a dedicated training script
-    (``scripts/train_hydra.py``). If you use lightning-pose as part of a custom script and don't
-    want your entire script to run once per GPU, your script should run ``scripts/train_hydra.py``
+    (``litpose train``). If you use lightning-pose as part of a custom script and don't
+    want your entire script to run once per GPU, your script should run ``litpose train``
     rather than directly calling the ``train`` method.
 
 Tensorboard metric calculation
@@ -75,4 +75,4 @@ GPUs. For example, if you want to train on only the first two GPUs on your machi
 
 .. code-block:: bash
 
-    CUDA_VISIBLE_DEVICES=0,1 python scripts/train_hydra.py
+    CUDA_VISIBLE_DEVICES=0,1 litpose train config.yaml