LarvaTagger.jl
LarvaTagger.jl
is a graphical user application for the manual and automatic tagging of behaving Drosophila larvae.
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
).
larvatagger.jl
script
Using the 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.