Commit 7c48ea18 authored by amichaut's avatar amichaut
Browse files

updated doc with trackmate and custom variables

parent 05c1996f
Pipeline #76497 passed with stages
in 21 seconds
...@@ -12,13 +12,13 @@ Quantification and visualization of tracking data ...@@ -12,13 +12,13 @@ Quantification and visualization of tracking data
It *does not* perform any tracking, but visualizes and quantifies any kind of tracked data. It *does not* perform any tracking, but visualizes and quantifies any kind of tracked data.
It analyzes trajectories by computing standard quantities such as velocity, It analyzes trajectories by computing standard quantities such as velocity,
acceleration, diffusion coefficient, local density, etc. acceleration, diffusion coefficient, local density, etc.
Trajectories can also be plotted on the original image in 2D or 3D using custom color coding. Trajectories can also be plotted on the original image in 2D or 3D using custom color-coding.
**Track Analyzer** provides a filtering section that can extract subsets of data based on spatiotemporal criteria. **Track Analyzer** provides a filtering section that can extract subsets of data based on spatiotemporal criteria.
The filtered subsets can then be analyzed either independently or compared. This filtering section also provides a tool The filtered subsets can then be analyzed either independently or compared. This filtering section also provides a tool
for selecting specific trajectories based on spatiotemporal criteria which can be useful to perform fate mapping and back-tracking. for selecting specific trajectories based on spatiotemporal criteria which can be useful to perform fate mapping and back-tracking.
**Track Analyzer** is distributed as two versions: an [installation-free web-base interface](https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0) run on [Galaxy](https://galaxyproject.org/), and full version run on a user-friendly Jupyter notebook. On both versions, **Track Analyzer** can be run without any programming knowledge using its graphical interface. The full version interface is launched by running a [Jupyter notebook](https://jupyter.org/) containing widgets allowing the user to load data and set parameters without writing any code. **Track Analyzer** is distributed as two versions: an [installation-free web-based interface](https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0) run on [Galaxy](https://galaxyproject.org/), and a full version that has to be run on a local machine. On both versions, **Track Analyzer** can be run without any programming knowledge using its graphical interface. The full version interface is launched by running a [Jupyter notebook](https://jupyter.org/) containing widgets allowing the user to load data and set parameters without writing any code.
![screenshot_1](https://gitlab.pasteur.fr/track-analyzer/track-analyzer/-/raw/master/resources/screenshot_1.png) ![screenshot_1](https://gitlab.pasteur.fr/track-analyzer/track-analyzer/-/raw/master/resources/screenshot_1.png)
...@@ -27,7 +27,7 @@ for selecting specific trajectories based on spatiotemporal criteria which can b ...@@ -27,7 +27,7 @@ for selecting specific trajectories based on spatiotemporal criteria which can b
## Data requirements ## Data requirements
**Track Analyzer** needs as input a text file (csv or txt file) of tracked data containing the position coordinates (in 2D or 3D) along time and the tracks identifiers. The mandatory input file of **Track Analyzer** is a data table (a csv or txt file) of tracks containing the position coordinates (in 2D or 3D) along time and the tracks identifiers.
Optionally, data can be plotted on the original image provided as a 3D or 4D tiff stack (ie. 2D+time or 3D+time). If the format of your movie is Optionally, data can be plotted on the original image provided as a 3D or 4D tiff stack (ie. 2D+time or 3D+time). If the format of your movie is
different (list of images), please convert it to tiff stack using [Fiji](https://fiji.sc/) for instance. different (list of images), please convert it to tiff stack using [Fiji](https://fiji.sc/) for instance.
...@@ -73,7 +73,7 @@ To run track-analyzer ...@@ -73,7 +73,7 @@ To run track-analyzer
## Installation-free version ## Installation-free version
The installation-free online version is available [here](https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0). It is run on the web-base platform [Galaxy](https://galaxyproject.org/), which is easy to use (some documentation regarding Galaxy is available [here](https://training.galaxyproject.org/training-material/)). A quickstart tutorial to Galaxy's interface is presented in Track Analyzer's [documentation](https://track-analyzer.pages.pasteur.fr/track-analyzer/). The installation-free online version is available [here](https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0). It is run on the web-based platform [Galaxy](https://galaxyproject.org/), which is easy to use (some documentation regarding Galaxy is available [here](https://training.galaxyproject.org/training-material/)). A quickstart tutorial to Galaxy's interface is presented in Track Analyzer's [documentation](https://track-analyzer.pages.pasteur.fr/track-analyzer/).
## Documentation ## Documentation
You can find a complete documentation [here](https://track-analyzer.pages.pasteur.fr/track-analyzer/). You can find a complete documentation [here](https://track-analyzer.pages.pasteur.fr/track-analyzer/).
......
...@@ -31,19 +31,26 @@ Quickstart ...@@ -31,19 +31,26 @@ Quickstart
Data requirements Data requirements
================= =================
**Track Analyzer** needs as input a text file (csv or txt file) of tracked data containing the position coordinates (in 2D or 3D) along time and the tracks identifiers. The mandatory input file of **Track Analyzer** is a data table (a csv or txt file) of tracks containing the position coordinates (in 2D or 3D) along time and the tracks identifiers.
Optionally, data can be plotted on the original image provided as a 3D or 4D tiff stack (ie. 2D+time or 3D+time). If the format of your movie is Optionally, data can be plotted on the original image provided as a 3D or 4D tiff stack (ie. 2D+time or 3D+time). If the format of your movie is
different (list of images), please convert it to tiff stack using `Fiji <https://fiji.sc/>`_ for instance. different (list of images), please convert it to tiff stack using `Fiji <https://fiji.sc/>`_ for instance.
The position file must contain columns with the x, y, (z) positions, a frame column and track id column. The positions coordinates can be in The position file must contain columns with the x, y, (z) positions, a frame column and track id column. The positions coordinates can be in
pixels or in scaled data. The information about the scaling and other metadata such as time and length scales will be provided by the user through the graphical interface. pixels or in scaled data. The information about the scaling and other metadata such as time and length scales will be provided by the user through the graphical interface.
If **Track Analyzer** is run through the Jupyter notebook (see below). The position file format is flexible and the user will be asked to interactively identify all the mandatory columns.
You can specify that the position file was generated by `Trackmate <https://imagej.net/plugins/trackmate/>`_. The columns are then automatically identified.
If **Track Analyzer** is run through Galaxy (see below). The position file format has to strictly follow the default column names: x, y, (z), frame, track.
However, if the position file was generated by `Trackmate <https://imagej.net/plugins/trackmate/>`_, then the columns are automatically identified.
If **Track Analyzer** is run using command lines (see below), the data directory must contain: If **Track Analyzer** is run using command lines (see below), the data directory must contain:
- a comma-separated csv file named positions.csv which column names are: x, y, (z), frame, track - a comma-separated csv file named positions.csv which column names are: x, y, (z), frame, track
- a text file named info.txt containing the metadata (see example) - a text file named info.txt containing the metadata (see example)
- (optional) a tiff file named stack.tif - (optional) a tiff file named stack.tif
- (optional) configuration files in a config directory - (optional) configuration files in a config directory
The default config files can be generated by running :code:`TA_config path_to_directory`. The config files are csv files that can be easily edited.
.. ..
add a section descibing config and info files add a section descibing config and info files
...@@ -53,14 +60,14 @@ If **Track Analyzer** is run using command lines (see below), the data directory ...@@ -53,14 +60,14 @@ If **Track Analyzer** is run using command lines (see below), the data directory
Running the pipeline Running the pipeline
==================== ====================
There are three ways of running **Track Analyzer**. Two user-friendly versions are available: an installation-free web-base tool run on `Galaxy <https://galaxyproject.org/>`_, and full version run on a user-friendly Jupyter notebook. On both versions, **Track Analyzer** can be run without any programming knowledge using its graphical interface. The full version interface is launched by running a `Jupyter notebook <https://jupyter.org/>`_ containing widgets allowing the user to load data and set parameters without writing any code. **Track Analyzer** can also directly be run using command lines (if you need to run if on a distant machine such as a cluster). There are three ways of running **Track Analyzer**. Two user-friendly versions are available: an installation-free web-based tool run on `Galaxy <https://galaxyproject.org/>`_, and full version run on a user-friendly Jupyter notebook. On both versions, **Track Analyzer** can be run without any programming knowledge using its graphical interface. The full version interface is launched by running a `Jupyter notebook <https://jupyter.org/>`_ containing widgets allowing the user to load data and set parameters without writing any code. **Track Analyzer** can also directly be run using command lines (if you need to run if on a distant machine such as a cluster).
Using Galaxy (recommended for a first trial) Using Galaxy (recommended for a first trial)
============================================ ============================================
The installation-free online version is available `here <https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0>`_. It is run on the web-base platform `Galaxy <https://galaxyproject.org/>`_, which is easy to use (some documentation regarding Galaxy is available `here <https://training.galaxyproject.org/training-material/>`_). This online version is slightly limited compared to the full version run on Jupyter notebook. Jupyter notebook offers 3D visualization and hand-drawing data selection using a `Napari <https://napari.org/>`_ viewer. Moreover, loaded data are computed step by step throughout the pipeline, which provides the user with a better interactivity with the data. Conversely, on Galaxy, the user needs to enter numerical parameters before the analysis can be run. The installation-free online version is available `here <https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0>`_. It is run on the web-base platform `Galaxy <https://galaxyproject.org/>`_, which is easy to use (some documentation regarding Galaxy is available `here <https://training.galaxyproject.org/training-material/>`_). This online version is slightly limited compared to the full version run on Jupyter notebook. Jupyter notebook offers 3D visualization and hand-drawing data selection using a `Napari <https://napari.org/>`_ viewer. Moreover, loaded data are computed step by step throughout the pipeline, which provides the user with better interactivity with the data. Conversely, on Galaxy, the user needs to enter numerical parameters before the analysis can be run.
A complete documentation about Galaxy is available `here <https://training.galaxyproject.org/training-material/>`_. Here's a quick overview of Galaxy's interface. Complete documentation about Galaxy is available `here <https://training.galaxyproject.org/training-material/>`_. Here's a quick overview of Galaxy's interface.
.. image:: ../_static/screenshots/galaxy_help.jpeg .. image:: ../_static/screenshots/galaxy_help.jpeg
:align: center :align: center
...@@ -69,7 +76,7 @@ A complete documentation about Galaxy is available `here <https://training.galax ...@@ -69,7 +76,7 @@ A complete documentation about Galaxy is available `here <https://training.galax
2. Choose your input files that were previously uploaded. 2. Choose your input files that were previously uploaded.
3. Enter the parameters necessary to your analysis. 3. Enter the parameters necessary to your analysis.
4. Hit the execution button to launch the execution on Galaxy's cluster. 4. Hit the execution button to launch the execution on Galaxy's cluster.
5. You can find in the history panel all the output of each analysis job. For each of the output element, you can have a quick look (6), or save it (7). Note that when you display output plots, it is not very intuitive how to display again the main interface. The double arrow 'Run this job again' button (8) displayed on every log file, is then useful. If you press the 'Run this job again' button, the interface will be displayed with the exact same set of parameters as the corresponding job. 5. You can find in the history panel all the output of each analysis job. For each of the output elements, you can have a quick look (6), or save it (7). Note that when you display output plots, it is not very intuitive how to display again the main interface. The double arrow 'Run this job again' button (8) displayed on every log file, is then useful. If you press the 'Run this job again' button, the interface will be displayed with the exact same set of parameters as the corresponding job.
Using a Jupyter notebook (recommended for advanced options) Using a Jupyter notebook (recommended for advanced options)
=========================================================== ===========================================================
...@@ -90,6 +97,7 @@ To launch a notebook: ...@@ -90,6 +97,7 @@ To launch a notebook:
- a web browser opens, click on :code:`run_TA.ipynb` - a web browser opens, click on :code:`run_TA.ipynb`
- to shut down the notebook, press CTRL+C in the terminal. - to shut down the notebook, press CTRL+C in the terminal.
Using command lines (only if you need to run it on a distant machine) Using command lines (only if you need to run it on a distant machine)
==================================================================== ====================================================================
...@@ -111,7 +119,7 @@ Analysis procedure ...@@ -111,7 +119,7 @@ Analysis procedure
Load data Load data
========= =========
Just follow the notebook instructions, to load your data files. Just follow the instructions on the graphical interface (on the Jupyter notebook or Galaxy), to load your data files.
.. image:: ../_static/screenshots/loading_data.png .. image:: ../_static/screenshots/loading_data.png
:align: center :align: center
...@@ -121,11 +129,14 @@ If you run **Track Analyzer** for the first time, enter the metadata. ...@@ -121,11 +129,14 @@ If you run **Track Analyzer** for the first time, enter the metadata.
.. image:: ../_static/screenshots/setting_metadata.png .. image:: ../_static/screenshots/setting_metadata.png
:align: center :align: center
If **Track Analyzer** is run through the Jupyter notebook, you can additionally select custom columns of variables you might want to plot. You can then have to type in their names and units to be displayed on the plots.
You can also set some plotting parameters such as image file format, colors to be used, image resolution, etc. You can also set some plotting parameters such as image file format, colors to be used, image resolution, etc.
.. image:: ../_static/screenshots/ploting_parameters.png .. image:: ../_static/screenshots/ploting_parameters.png
:align: center :align: center
Data filtering section Data filtering section
====================== ======================
...@@ -140,7 +151,7 @@ A drawing tool also offers the possibility to hand-draw regions of interest. ...@@ -140,7 +151,7 @@ A drawing tool also offers the possibility to hand-draw regions of interest.
Additionally, specific trajectories can be selected by using their position in a region of interest at a specific time. This feature can be Additionally, specific trajectories can be selected by using their position in a region of interest at a specific time. This feature can be
useful to inspect either their past (back-tracking) or their future (fate-mapping). Trajectories can also be selected just using their ids. useful to inspect either their past (back-tracking) or their future (fate-mapping). Trajectories can also be selected just using their ids.
These subsets can then be analyzed separately. The analysis will be run independently on each on them. These subsets can then be analyzed separately. The analysis will be run independently on each of them.
Alternatively, they can be analyzed together. Trajectories and computed quantities will then be plotted together using color-coding. Alternatively, they can be analyzed together. Trajectories and computed quantities will then be plotted together using color-coding.
.. image:: ../_static/screenshots/subset_naming.png .. image:: ../_static/screenshots/subset_naming.png
...@@ -153,9 +164,10 @@ Trajectory analysis section ...@@ -153,9 +164,10 @@ Trajectory analysis section
Trajectories can be plotted over the original image, frame by frame, with some custom color-coding (z color-coded, t color-coded, subset, or random). Trajectories can be plotted over the original image, frame by frame, with some custom color-coding (z color-coded, t color-coded, subset, or random).
The total trajectories can also be plotted together with the option to center their origin. This can be useful to detect some patterns in trajectories. The total trajectories can also be plotted together with the option to center their origin. This can be useful to detect some patterns in trajectories.
Several quantities can be computed and plotted: velocities and acceleration (spatial components and its modulus). Several quantities can be computed and plotted: velocities and acceleration (spatial components and their modulus).
The local cell density can be estimated by performing a Voronoi tesselation. The Voronoi diagram can be plotted and the area of each Voronoi cell can The local cell density can be estimated by performing a Voronoi tesselation. The Voronoi diagram can be plotted and the area of each Voronoi cell can
be calculated and plotted. Currently, only the Voronoi tesselation in 2D (even if the data are 3D) is available. be calculated and plotted. Currently, only the Voronoi tesselation in 2D (even if the data are 3D) is available.
If **Track Analyzer** is run through the Jupyter notebook, you can also plot other variables you selected.
All these quantities can also be averaged over the whole trajectory and plotted. All these quantities can also be averaged over the whole trajectory and plotted.
...@@ -220,7 +232,7 @@ In each subset's directory: ...@@ -220,7 +232,7 @@ In each subset's directory:
- a *config* folder is generated with the configuration parameters used for this specific analysis - a *config* folder is generated with the configuration parameters used for this specific analysis
- *all_data.csv* stores the subset's table of positions - *all_data.csv* stores the subset's table of positions
- *track_prop.csv* stores the averaged quantities along trajectories - *track_prop.csv* stores the averaged quantities along trajectories
- each plot is saved using an image format, size and resolution that can be chosen when the plotting parameters are set in notebook. Additionally, the default colors and color maps can be customized in the plotting parameters sections. - each plot is saved using an image format, size and resolution that can be customized. Additionally, the default colors and color maps can be customized in the plotting parameters sections.
- the data points of each plot is saved in a csv file with the same name as the image file, so you can replot the data using your favorite plotting software - the data points of each plot is saved in a csv file with the same name as the image file, so you can replot the data using your favorite plotting software
...@@ -235,7 +247,7 @@ You can get familiar with **Track Analyzer** by running it on example data. For ...@@ -235,7 +247,7 @@ You can get familiar with **Track Analyzer** by running it on example data. For
:download:`cell tracking challenge <../_static/example/Fluo-N3DH-CE.tar.gz>` :download:`cell tracking challenge <../_static/example/Fluo-N3DH-CE.tar.gz>`
Additionally, you can download the original timelapse for optimal visualization. Download the `dataset <http://data.celltrackingchallenge.net/training-datasets/Fluo-N3DH-CE.zip>`_. And run the following :download:`python script <../_static/example/load_tracking.py>` to extract image and generate a single tiff file that you can use during the analysis. Additionally, you can download the original timelapse for optimal visualization. Download the `dataset <http://data.celltrackingchallenge.net/training-datasets/Fluo-N3DH-CE.zip>`_. And run the following :download:`python script <../_static/example/load_tracking.py>` to extract the image and generate a single tiff file that you can use during the analysis.
To run the script, open a terminal and run: :: To run the script, open a terminal and run: ::
pip install imagecodecs pip install imagecodecs
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment