Skip to content
Snippets Groups Projects

LarvaTagger.jl

Build Status

LarvaTagger.jl is a graphical user application for the manual and automatic tagging of behaving Drosophila larvae.

Manual tagging with LarvaTagger.jl

This package features a web-based GUI for visualizing behaving larvae and assigning discrete behavior tags, at each time step.

A CLI is also available for batch processing: automatic tagging of track data files, training new taggers from labelled data, etc.

LarvaTagger.jl alone comes with no automatic tagger. It is designed to work in combination with MaggotUBA.

A Docker image is available, with all automatic tagging capabilities installed. If you have Docker or Singularity/Apptainer installed, take a look at the dedicated instructions page.

Support for various data file formats is implemented by PlanarLarvae.jl. Behavior labels from manual and automatic tagging are saved in json files along with the corresponding track data files.

Installing

To natively run LarvaTagger.jl, you will need julia>=1.7.

If you are not familiar with installing Julia, you may appreciate installation helpers such as Juliaup or jill (preferred).

git clone https://gitlab.pasteur.fr/nyx/larvatagger.jl LarvaTagger
cd LarvaTagger
julia --project=. -e 'using Pkg; Pkg.instantiate()'

Calling Pkg.instantiate in a copy of the project is preferred over using Pkg.add, because LarvaTagger.jl depends on several unregistered packages.

With Julia 1.6

LarvaTagger.jl is known to work also with julia==1.6. However, with this version, Pkg.instantiate does not take into account version constraints. In particular, Makie must be manually downgraded to version 0.17.13:

julia --project=. -e 'using Pkg; Pkg.add(name="Makie", version="0.17.13")'

Alternative procedure

Users who would prefer not to clone the repository or implicitly use the shipped Manifest.toml file can follow the following steps instead:

mkdir LarvaTagger
cd LarvaTagger
julia --project=. -q
julia> # press the ] key
(LarvaTagger) pkg> add https://gitlab.pasteur.fr/nyx/PlanarLarvae.jl
(LarvaTagger) pkg> add https://gitlab.com/dbc-nyx/ObservationPolicies.jl
(LarvaTagger) pkg> add https://gitlab.com/dbc-nyx/TidyObservables.jl
(LarvaTagger) pkg> add https://gitlab.pasteur.fr/nyx/LarvaTagger.jl

Note however that some versions of the dependencies may cause LarvaTagger.jl to break. For example for now, LarvaTagger.jl does not support Makie>=0.18.

Upgrading

From a local copy of the git repository, be sure to be on the appropriate branch (in most cases the main branch) and update (or pull) it:

git checkout main
git pull

Upgrading the Julia package can be done similarly to the installation step:

julia --project=. -e 'using Pkg; Pkg.instantiate()'

Launching the graphical user interface

The GUI is provided by a webserver.

Running LarvaTagger.jl sets the server up. Once the server is ready, the app can be loaded in a webbrowser at the address indicated (typically localhost:9284).

Using the larvatagger.jl script

If you cloned the repository, we recommend you run LarvaTagger.jl using the larvatagger.jl script to be found in the scripts directory:

scripts/larvatagger.jl open path/to/data/file --browser

The script will actually open a Julia interpreter, and give some guidance on how to exit the interpreter.

For now, larvatagger.jl open cannot be run with no input arguments. A track data file is required.

The --browser argument may open a new tab in your webbrowser, but this feature is known to not work in some situations.

The first time the application is loaded, it may take a while for a window in your webbrowser to open, and the data to be plotted.

From the Julia interpreter

As an alternative to the larvatagger.jl script, in the LarvaTagger directory created above, launch the Julia interpreter:

julia --project=.

In the interpreter, to launch the editor, type:

julia> using LarvaTagger; display(larvaeditor("path/to/data/file"))

To exit the interpreter, type exit() or press Ctrl+D.

Automatic tagging

LarvaTagger.jl comes with no automatic tagger per default.

To extend the editor with MaggotUBA automatic tagging, checkout out the recommended installation steps for TaggingBackends and MaggotUBA.

If the JULIA_PROJECT environment variable was used to control the location of the TaggingBackends Julia package, this variable should be equally set prior to carrying out any of the below steps.

If the backend directory is created right in the LarvaTagger directory, LarvaTagger.jl will automatically find it.

Otherwise, to let larvaeditor know about MaggotUBA or any other backend, in the Julia interpreter, type:

julia> using LarvaTagger; display(larvaeditor("path/to/data/file"; backend_directory="path/to/MaggotUBA's/parent/directory"))

Similarly, to let larvatagger.jl know about MaggotUBA:

scripts/larvatagger.jl open <path/to/data/file> --backends=<path/to/MaggotUBA's/parent/directory> --browser

The larvatagger.jl script can also be used to train a new tagger:

scripts/larvatagger.jl train <path/to/backend> <path/to/data/repository> <tagger-name>

and apply this tagger to a tracking data file:

scripts/larvatagger.jl predict <path/to/backend> <tagger-name> <path/to/data/file> --skip-make-dataset

To run larvatagger.jl predict in parallel on multiple data files using the same tagger, append the --data-isolation argument to avoid data conflicts. Indeed, without this latter argument, a tagger accesses dedicated locations in the filesystem and these locations would be shared by all the simultaneously running larvatagger.jl instances. --data-isolation makes the tagger use temporary directories instead, so that these directories are specific to the running process, in addition to be specific to the tagger.

The train and predict commands admit more arguments. Check them out with:

scripts/larvatagger.jl --help

The trained taggers are stored in the models directory in the backend. MaggotUBA-based taggers are stored in the shape of .pt and .json files. After training a tagger, post-processing rules can be manually added into the clf_config.json file. See the following comment.

Developer documentation

See the release announcements, change logs and project structure.