Ensembling and kalman smoothing for pose estimation
Project description
EKS
This repo contains code to run an Ensemble Kalman Smoother (EKS) for improving pose estimation outputs.
Installation
We offer two methods for installing the eks
package:
- Method 1,
github+conda
: this is the preferred installation method and will give you access to example scripts and data - Method 2,
pip
: this option is intended for non-interactive environments, such as remote servers.
For both installation methods we recommend using conda to create a new environment in which this package and its dependencies will be installed:
conda create --name eks python=3.10
Activate the new environment:
conda activate eks
Make sure you are in the activated environment during the Lightning Pose installation.
Method 1: github+conda
First you'll have to install the git
package in order to access the code on github.
Follow the directions here
for your specific OS.
Then, in the command line, navigate to where you'd like to install the eks
package and move
into that directory:
git clone https://github.com/colehurwitz/eks
cd eks
To make the package modules visible to the python interpreter, locally run pip
install from inside the main eks
directory:
pip install -e .
If you wish to install the developer version of the package, run installation like this:
pip install -e ".[dev]"
Method 2: pip
You can also install the eks
package using the Python Package Index (PyPI):
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.
Example scripts
We provide several example datasets and fitting scripts to illustrate use of the package. See Command-Line Arguments for more information on arguments.
Single-camera datasets
The singlecam_example.py
script demonstrates how to run the EKS code for standard single-camera
setups.
Any of the provided datasets are compatible with this script; below we'll use data/ibl-pupil
as
our example.
To run the EKS on the example data, execute the following command from inside this repo:
python scripts/singlecam_example.py --csv-dir ./data/ibl-pupil --bodypart-list pupil_top_r pupil_bottom_r pupil_left_r pupil_right_r
Multi-camera datasets
The multicam_example.py
script demonstrates how to run the EKS code for multi-camera
setups where the pose predictions for a given model are all stored in a single csv file.
For example, if there is a body part names nose_tip
and three cameras named
top
, bottom
, and side
, then the csv file should have columns named
nose_tip_top
, nose_tip_bottom
, and nose_tip_side
.
We provide example data in the data/mirror-mouse
directory inside this repo,
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:
python scripts/multicam_example.py --csv-dir ./data/mirror-mouse --bodypart-list paw1LH paw2LF paw3RF paw4RH --camera-names top bot
IBL pupil dataset
The pupil_example.py
script requires a csv-dir
which contains lightning-pose or DLC
model predictions.
To run this script on the example data provided, execute the following command from inside this repo:
python scripts/pupil_example.py --csv-dir ./data/ibl-pupil
IBL paw dataset (multiple asynchronous views)
The multiview_paw_example.py
script requires a csv-dir
which contains lightning-pose
or DLC model predictions for the left and right camera views, as well as timestamp files to align
the two cameras.
To run this script on the example data provided, execute the following command from inside this repo:
python scripts/multiview_paw_example.py --csv-dir ./data/ibl-paw
Authors
Cole Hurwitz
Matt Whiteway
Keemin Lee
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ensemble-kalman-smoother-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 99d227a215e318cb019bb28a0109874594e2585e7544868e7bf75fb9799a63ee |
|
MD5 | ea8521f93a32cbf44dce41fb47dc0ca9 |
|
BLAKE2b-256 | 7ba3fe551eb575119dfc34f4231e3e813a61052ebd5ba1e90530a6657b39d350 |
Hashes for ensemble_kalman_smoother-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a03679d9f673153bcf325903885ef6370c773d47852eabb1af40fefa6227c182 |
|
MD5 | 9b3435d62384db340dbbb9708ab7cc8e |
|
BLAKE2b-256 | 020def33eb70a06cc54fd94ae1222dbf2ed2ebf70581225ec3ccde2160c6f636 |