basty (Automated Behavioral Analysis of Asleep Fruit Fly) is a software designed to analyze behavioral correlates of sleep in Drosophila Melanogaster. The software consists of an end-to-end & multi-stage pipeline and a couple of useful scripts for behavioral analysis. basty is specifically designed for unique challenges related to the characteristics of sleep, so can deal with hard-to-detect behaviors exhibited rarely during long sleep cycles. It allows both unsupervised and semi-supervised analysis and is able to map the animal tracking data to given behavioral categories with limited supervision (basty does not require a large labeled data set!). basty also offers an extensive set of pre-processing procedures, and therefore, can directly operate on noisy pose estimation data (e.g., DeepLabCut [1]). Similar to many other behavior mapping pipelines, basty starts by computing a meaningful high-dimensional spatio-temporal representation from the filtered and imputed pose estimation data. Utilizing high-dimensional time-series representations, our software can detect sleep epochs, micro-activities (e.g., postural adjustment and short-duration grooming behaviors), and macro-activities (e.g., feeding and walking). Then, basty performs high-performance behavior mapping and allows a fine-grained categorization of the micro-activities by generating behavior embeddings and using a novel nearest neighbor-based prediction scheme.
You can either clone the repository and crate a new virtual environment using poetry as decribed below in Quickstart, or simply use pip install basty.
- Clone the repository, and change current directory to
basty/.
git clone https://github.com/bo1929/basty.git
cd basty- Create a new virtual environment with Python version 3.9 with using any version management tool, such as
condaandpyenv.- You can use following
condacommands.
conda create -n basty python=3.9.0 conda activate basty
- Alternatively,
pyenvsets a local application-specific Python version by writing the version name to a file called.python-version, and automatically switches to that version when you are in the directory.
pyenv local 3.9.0 - You can use following
- Use poetry to install dependencies in the
basty/directory, and spawn a new shell.
poetry install
poetry shell- Then, after creating your configuration files, initialize a project using the below command.
For a detailed description of the main configuration file (
main_cfg.yaml), see Configuration Files.
python init_project.py --main-cfg-path /path/to/main_cfg.yaml- Extract spatio-temporally meaningful features.
python extract_features.py --main-cfg-path /path/to/main_cfg.yaml --compute-all- Detect sleep epochs, micro-activity and macro-activity bouts by running the following command.
python outline_experiments.py --main-cfg-path /path/to/main_cfg.yaml --outline-all- Generate behavioral embedding space(s). At this step, you have different options (e.g., unsupervised or semi-supervised dimensionality reduction). For a detailed description and some tips, please see Practical Guide. Assuming labeled data is available for semi-supervised behavior mapping, the following command generates semi-supervised pair embeddings.
python map_behaviors.py --main-cfg-path /path/to/main_cfg.yaml --compute-semisupervised-pair-embeddings- Finally, you can map your unlabeled tracking data to defined behavior categories (with some sensible default parameters), and export predictions to a
.csvfile.
python predict_behavioral_categories.py --main-cfg-path /path/to/main_cfg.yaml \
--num-neighbors 15 --neighbor-weights distance --neighbor-weights-norm log_count \
--activation standard --voting soft
python export_behavior_predictions.py --main-cfg-path /path/to/main_cfg.yaml- [1] Mathis, Alexander, et al. "DeepLabCut: markerless pose estimation of user-defined body parts with deep learning." Nature neuroscience 21.9 (2018): 1281-1289.