This project is part of the Larva Tagger Project, aiming to monitor the behavior of Drosophila Larvae in video recordings. This repository contains the code for the autimated hyperparameter optimization of the Larva Tagger. Currently, three Larva Taggers are supported:
- MWT (Multi-Worm Tracker, Paper)
- Tierpsy (Paper)
- WF-NTP (Wide field-of-view Nematode Tracking Platform, Paper)
Requires the Tracker that should be used for the optimization to be installed. We tested the code with the MWT, Tierpsy and WF-NTP. We used the following versions of the respective Trackers which all come with installation instructions:
- MWT: GitLab Repo
- Tierpsy: GitLab Repo
- WF-NTP: GitHub Repo
The code was tested using a conda environment with Python 3.10.12. We tested it on MacOs and Windows machines.
The following packages are required: matplotlib, numpy, pandas, optuna, joblib
Alternatively, a requirements.txt file is provided to allow reproducible installation with pip. larva-tagger-tune can be installed in a virtual environment with the following steps (for Unix-like systems):
git clone https://github.com/Lilly-May/larva-tagger-tune
python3.10 -m venv larva-tagger-tune
cd larva-tagger-tune
source bin/activate
pip install -r requirements.txt
Windows users will have to type Scripts/activate.bat (if in cmd) as an activation command instead of source bin/activate.
The code can be run from the command line. An example call is:
python ParameterOptimization.py MWT /Path/to/WorkingDir /Path/to/VideoDir /Path/to/target_larvae_nr.csv --plot --nr_processes 3
The script requires four positional arguments:
- Tracker: The tracker that should be used for the optimization. Currently, MWT, Tierpsy and WF-NTP are supported.
- WorkingDir: The path to the working directory. This directory is expected to have a subdirectory TRACKER-cli with the respective tracker installation.
- VideoDir: The path to the directory containing the videos that should be analyzed.
- TargetFile: The path to the .csv file containing the target number of larvae for each video (see below for detailed description).
Additionally, the optimization process can be customized by specifying optional arguments. You can get a list and description of all optional arguments by calling:
python ParameterOptimization.py --help
The target number file is a .csv file containing the target number of larvae for each video. Since is it possible that larvae leave the frame during the video recording, the target number of larvae can change over time. Therefore, the target number file contains the target number of larvae for each second of the video.
The file has to be in the following csv format (first visualized as table, then as csv):
| Video_name | Second | Nr_larvae | Second | Nr_larvae | Second | Nr_larvae |
|---|---|---|---|---|---|---|
| A1DF31_A1_2022-07-12-150920-0000_ffv1 | 0 | 12 | 32 | 11 | 44 | 10 |
| A1DF39_B1_2022-07-12-185350-0000_ffv1 | 0 | 11 | 52 | 10 |
As csv:
Video_name,Second,Nr_larvae,Second,Nr_larvae,Second,Nr_larvae
A1DF31_A1_2022-07-12-150920-0000_ffv1,0,12,32,11,44,10
A1DF39_B1_2022-07-12-185350-0000_ffv1,0,11,52,10
The tuple (Second, Nr_larvae) can be repeated as often as needed. Rows do not need to have the same number of columns. If the target number of larvae is constant over the whole video, the file can be simplified by simply specifying the Second 0 and the target number of larvae once, so that the csv file has 3 column in total.
The optimization algorithm is based on the Optuna framework, which is commonly used for hyperparameter optimization for neural networks. It suggests a set of hyperparameters, which are then used to run the tracker on the videos. Testing one set of hyperparameters is called a trial. Based on results from previous trials, Optuna will suggest new hyperparameters to test. Additionally, optuna has an option to prune unpromising trials, which can be activated by setting the flag "--prune".