This package features a GUI for visualizing behaving larvae and editing discrete behavior tags at each time step.
This package features a GUI for visualizing behaving larvae and editing discrete behavior tags at each time step.
To run `LarvaTagger.jl`, you will need [`julia>=1.6`](https://julialang.org/downloads/) and some input data file, *e.g.* a `trx.mat` file or a pair of `.spine`/`.outline` files, preferably located in a repository with directory structure: `<screen_name>/<genotype@effector>/<protocol>/<date_time>`.
To natively run `LarvaTagger.jl`, you will need [`julia>=1.6`](https://julialang.org/downloads/) and some input data file, *e.g.* a `trx.mat` file or a pair of `.spine`/`.outline` files, preferably located in a repository with directory structure: `<screen_name>/<genotype@effector>/<protocol>/<date_time>`.
If you are not familiar with Julia, you may appreciate installation helpers such as [JILL.py](https://github.com/johnnychen94/jill.py).
If you are not familiar with installing Julia, you may appreciate installation helpers such as [JILL.py](https://github.com/johnnychen94/jill.py).
An example install procedure can be found in [`scripts/make_demontrator.sh`](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/blob/main/scripts/make_demonstrator.sh).
Alternatively, if you have Docker installed, take a look at the [dedicated instructions page](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/tree/docker/recipes).
## Install
## Install
...
@@ -17,6 +18,23 @@ cd LarvaTagger
...
@@ -17,6 +18,23 @@ cd LarvaTagger
julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Pkg; Pkg.instantiate()'
```
```
Calling `instantiate` in a copy of the project is preferred to using `Pkg.add`,
because `LarvaTagger.jl` depends on several unregistered packages.
Users who would prefer not to clone the repository or implicitly use the shipped `Manifest.toml` file
julia> using LarvaTagger; larvaeditor("path/to/data/file")
julia> using LarvaTagger; display(larvaeditor("path/to/data/file"))
```
```
The first time the editor is loaded, it may take a while for a window in your webbrowser to open, and the data to be plotted.
The first time the editor is loaded, it may take a while for a window in your webbrowser to open, and the data to be plotted.
The Firefox web browser showed better performance than Chrome-like browsers.
To exit the interpreter, type `exit()` or press Ctrl+D.
To exit the interpreter, type `exit()` or press Ctrl+D.
### Using the `larvatagger.jl` script
### Using the `larvatagger.jl` script
The `LarvaTagger/scripts` directory contains a`larvatagger.jl`executable file.
As an alternative to explicitly launching a Julia interpreter and typing some Julia code, if you cloned the repository, you can run the`larvatagger.jl`script instead:
To launch the editor, type:
```
```
scripts/larvatagger.jl open path/to/data/file
scripts/larvatagger.jl open path/to/data/file --browser
```
```
The script will also launch a Julia interpreter, and give extra guidance on *e.g.* how to exit the interpreter.
## Automatic tagging
## Automatic tagging
To extend the editor with `MaggotUBA` automatic tagging:
To extend the editor with `MaggotUBA` automatic tagging:
...
@@ -53,16 +71,20 @@ cd MaggotUBA
...
@@ -53,16 +71,20 @@ cd MaggotUBA
poetry install -vvv
poetry install -vvv
cd ..
cd ..
```
```
To let *larvaeditor* know about MaggotUBA, in the Julia interpreter, type:
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; larvaeditor("path/to/data/file"; backend_directory="path/to/MaggotUBA's/parent/directory")
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:
Similarly, to let *larvatagger.jl* know about MaggotUBA:
```
```
scripts/larvatagger.jl open "path/to/data/file" --backends="path/to/MaggotUBA's/parent/directory"
scripts/larvatagger.jl open "path/to/data/file" --backends="path/to/MaggotUBA's/parent/directory" --browser
```
```
Note however that [`MaggotUBA-adapter`](https://gitlab.pasteur.fr/nyx/MaggotUBA-adapter) requires the actual [`MaggotUBA`](https://gitlab.pasteur.fr/les-larves/structured-temporal-convolution/-/tree/dev-branch) code that is not open access yet.
Note however that [`MaggotUBA-adapter`](https://gitlab.pasteur.fr/nyx/MaggotUBA-adapter) requires the actual [`MaggotUBA`](https://gitlab.pasteur.fr/les-larves/structured-temporal-convolution/-/tree/light-stable-for-tagging) code that is not open access yet.
As a consequence, it is likely the installation step fails.
As a consequence, it is likely the installation step fails.
The `MaggotUBA` tagging core will be fully released in the near future.
The `MaggotUBA` tagging core will be fully released in the near future.
Images are published on [Docker Hub](https://hub.docker.com/repository/docker/flaur/larvatagger).
They ship with `LarvaTagger.jl` and, optionally, with a MaggotUBA-based toy backend for automatic tagging.
Try:
```
docker pull flaur/larvatagger:0.5-20220418
```
Beware that images that ship with backends are relatively large files (>6GB).
## Running an image
A number of options must be passed to the `docker` command for the container to open a data file:
```
docker -iv $(pwd):/data -p 9284:9284 larvatagger open /data/path/to/your/file
```
with `path/to/your/file` a relative path to your file.
In the command above, `/data` represents the local directory, made available within the container.
This is required, since no files outside the container can be accessed.
The port *LarvaTagger.jl* listens to must also be exported with `-p 9284:9284` so that it can be accessed from outside the container.
Just like the `scripts/larvatagger.jl` script, the docker image admits more commands, including `import`, or options such as `--help`.
For these other commands, neither `-i` nor `-p 9284:9284` are necessary.
See also standalone script [`scripts/larvatagger.sh`](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/blob/main/scripts/larvatagger.sh) that wraps `docker` and exposes a simpler interface. For example:
```
scripts/larvatagger.sh open path/to/your/file
```
## Building an image
The `scripts/larvatagger.sh` script features a `build` command:
```
scripts/larvatagger.sh build
```
Optionally, if you have read access to the original MaggotUBA repository, you can fetch include a toy backend with:
```
scripts/larvatagger.sh build --get-backend
```
In both cases, `larvatagger.sh` will try to run the server and UI using a sample data file expected as file `test/sample_data`.
Pick a file in the format you expect to most frequently manipulate (either *Choreography* files, FIMTrack v2 csv files, *trx.mat* files as generated by JBM tagging pipeline, etc) and copy it at that location.
