Merge pull request #6 from paninski-lab/slp-converter

Slp converter

.gitignore

@@ -135,3 +135,6 @@ data/ibl-pupil/outputs/
 data/mirror-mouse/outputs/
 
 *.pdf
+/eks/timing.py
+/scripts/plotting.py
+/scripts/plotting2.py

README.md

@@ -1,5 +1,16 @@
 # EKS
-This repo contains code to run an Ensemble Kalman Smoother (EKS) for improving pose estimation outputs. 
+This repo contains code to run an Ensemble Kalman Smoother (EKS) for improving pose estimation outputs.
+
+The EKS uses a Kalman filter to ensemble and smooth pose estimation outputs as a post-processing
+step after multiple model predictions have been generated, resulting in a more robust output:
+
+![](assets/crim13_singlecam.gif)
+
+In this gif, there are five models (in red) on which EKS is run to generate the EKS
+output (in green). As can be seen, the EKS output improves tracking by ensembling and smoothing the
+individual model outputs, which can often diverge considerably for difficult frames.
+
+---
 
 ## Installation
 
@@ -46,6 +57,8 @@ If you wish to install the developer version of the package, run installation li
 pip install -e ".[dev]"
 ```
 
+For more information on individual modules and their usage, see [Requirements](docs/requirements.md)
+
 ### Method 2: pip
 
 You can also install the `eks` package using the Python Package Index (PyPI):
@@ -55,10 +68,20 @@ python3 -m pip install ensemble-kalman-smoother
 Note that you will not have access to the example data or example scripts with the pip install 
 option.
 
+### Note: Using GPU for fast parallel-scan
+As of now, EKS singlecam features a jitted parallel scan implementation for quickly optimizing the
+smoothing parameter (notably for larger datasets of 10,000+ frames). In order to utilize parallel scan,
+you will need to have a cuda environment with jax enabled. Further instructions can be found in the [jax
+docs](https://jax.readthedocs.io/en/latest/installation.html).
+-------------------------------
+
 ## Example scripts
 
 We provide several example datasets and fitting scripts to illustrate use of the package. See
-[Command-Line Arguments](docs/command-line_arguments.md) for more information on arguments.
+[Command-Line Arguments](docs/command-line_arguments.md) for more information on arguments, 
+including optional flags and defaults. We recommend starting with the first of four scripts outlined
+below, `singlecam_example.py`, following along with the [Singlecam Overview](docs/singlecam_overview.md)
+if a deeper understanding of EKS is desired.
 
 ### Single-camera datasets
 The `singlecam_example.py` script demonstrates how to run the EKS code for standard single-camera
@@ -68,8 +91,12 @@ our example.
 To run the EKS on the example data, execute the following command from inside this repo:
 
 ```console 
-python scripts/singlecam_example.py --input-dir ./data/ibl-pupil --data-type lp --bodypart-list pupil_top_r  pupil_bottom_r pupil_left_r pupil_right_r
+python scripts/singlecam_example.py --input-dir ./data/ibl-pupil
 ```
+
+The singlecam script is currently the most up-to-date script with the greatest number of feature
+implementations, including fast smoothing parameter auto-tuning using GPU-driven parallelization.
+[Here](docs/singlecam_overview.md) is a detailed overview of the workflow.
 
 ### Multi-camera datasets
 The `multicam_example.py` script demonstrates how to run the EKS code for multi-camera
@@ -82,7 +109,7 @@ for a two-view video of a mouse with cameras named `top` and `bot`.
 To run the EKS on the example data provided, execute the following command from inside this repo:
 
 ```console 
-python scripts/multicam_example.py --input-dir ./data/mirror-mouse --data-type lp --bodypart-list paw1LH paw2LF paw3RF paw4RH --camera-names top bot
+python scripts/multicam_example.py --input-dir ./data/mirror-mouse --bodypart-list paw1LH paw2LF paw3RF paw4RH --camera-names top bot
 ```
 
 ### IBL pupil dataset
@@ -91,7 +118,7 @@ model predictions.
 To run this script on the example data provided, execute the following command from inside this repo:
 
 ```console 
-python scripts/pupil_example.py --input-dir ./data/ibl-pupil
+python scripts/ibl_pupil_example.py --input-dir ./data/ibl-pupil
 ```
 
 ### IBL paw dataset (multiple asynchronous views)
@@ -101,12 +128,16 @@ the two cameras.
 To run this script on the example data provided, execute the following command from inside this repo:
 
 ```console 
-python scripts/multiview_paw_example.py --input-dir ./data/ibl-paw
+python scripts/ibl_paw_multiview_example.py --input-dir ./data/ibl-paw
 ```
 
-### Authors 
+### Authors
+
 Cole Hurwitz
 
+Keemin Lee
+
+Amol Pasarkar
+
 Matt Whiteway
 
-Keemin Lee

docs/command-line_arguments.md

@@ -12,11 +12,15 @@ The script is run as a python executable. Arguments are parsed using the `argpar
 [Python module](https://docs.python.org/3/library/argparse.html), as seen in each of
 the example scripts.
 
-Arguments fall into two categories:
-## File I/O Arguments
-These arguments dictate the file directories for reading and writing data, and are present in all example scripts.
-- `--csv-dir <csv_directory>` String specifying read-in directory containing CSV files used as input data.
+Arguments are either general or script-specific.
+## General Arguments
+These arguments are present in all example scripts.
+- `--input-dir <input_data_directory>` String specifying read-in directory containing data.
 - `--save-dir <save_directory>` String specifying write-to directory (csv-dir by default).
+- `--save-filename <save_filename>` String specifying output file name ({'smoother_type}_{last_keypoint_smooth_param}' by default).
+- `--data-type <data_type>` String specifying input data file type. Accepts DeepLabCut (dlc), Lightning Pose (lp), and SLEAP (slp) file types. LP by default.
+- `--s-frames <s-frame_int> or <list of tuples (e.g. [(1, 300), (1000, None)]` Specifies frames to be considered for smoothing. If the input is an integer, selects that many frames starting from frame 1.
+Selects the first 10,000 frames by default.
 
 ## Script-specific Arguments
 These arguments are specific to the example script (e.g. `eks/singleview_smoother.py`) being used, which is
@@ -29,16 +33,16 @@ smoother-dependent. The following are the arguments found in the provided exampl
 - `--camera-names <camera_1> <camera_2> ...` List of camera views.
 - `--s <smooth_param>` Float specifying the extent of smoothing to be done. Smoothing increases as param **decreases** (range 0.01-20, 0.01 by default)
 - `--quantile_keep_pca <min_variance%>` Float specifying the percentage of points kept for multi-view PCA. Selectivity increases as param increases (range 0-100, 25 by default)
-### [IBL Pupil](../scripts/pupil_example.py)
+### [IBL Pupil](../scripts/ibl_pupil_example.py)
 - `--diameter-s <smooth_param>` Float specifying the extent of smoothing to be done for diameter. Smoothing increases as param **increases** (range 0-1 exclusive, 0.9999 by default)
 - `--com-s <smooth_param>` Float specifying the extent of smoothing to be done for center of mass. Smoothing increases as param **increases** (range 0-1 exclusive, 0.999 by default)
-### [IBL Paw (multiple asynchronous view)](../scripts/multiview_paw_example.py)
+### [IBL Paw (multiple asynchronous view)](../scripts/ibl_paw_multiview_example.py)
 - `--s <smooth_param>` Float specifying the extent of smoothing to be done. Smoothing increases as param **decreases** (range 0.01-20, 0.01 by default)
 - `--quantile_keep_pca <min_variance%>` Float specifying the percentage of points kept for multi-view PCA. Selectivity increases as param increases (range 0-100, 25 by default)
 
 The following table summarizes the script-specific arguments featured in each of the example scripts.
 
-| Argument\Script       | [Single-Camera](../scripts/singlecam_example.py) | [Multi-Camera](../scripts/multicam_example.py) | [IBL Pupil](../scripts/pupil_example.py) | [IBL Paw](../scripts/multiview_paw_example.py) |
+| Argument\Script       | [Single-Camera](../scripts/singlecam_example.py) | [Multi-Camera](../scripts/multicam_example.py) | [IBL Pupil](../scripts/ibl_pupil_example.py) | [IBL Paw](../scripts/ibl_paw_multiview_example.py) |
 |-----------------------|---------------|--------------|-----------|---------------------|
 | `--bodypart-list`     | ✓             | ✓            |           |                     |
 | `--camera-names`      |               | ✓            |           |                     |