Commit 42f6b75a authored by amichaut's avatar amichaut
Browse files

added reference to Galaxy to readme and doc

parent 1ff5e4cf
......@@ -8,7 +8,7 @@
# Track Analyzer :microscope: :bar_chart:
**Track Analyzer** is Python-based data visualization pipeline for tracking data.
It *does not* perform any tracking, but visualizes and quantified 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,
acceleration, diffusion coefficient, local density, etc.
Trajectories can also be plotted on the original image in 2D or 3D using custom color coding.
......@@ -17,8 +17,7 @@ Trajectories can also be plotted on the original image in 2D or 3D using custom
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.
**Track Analyzer** can be run without any programming knowledge using its graphical interface. The 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-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.
![screenshot_1](https://gitlab.pasteur.fr/track-analyzer/track-analyzer/-/raw/master/resources/screenshot_1.png)
......@@ -29,36 +28,29 @@ running a [Jupyter notebook](https://jupyter.org/) containing widgets allowing t
## 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.
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
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 in command line (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 text file named info.txt containing the metadata (see example)
- (optional) a tiff file named stack.tif
## Full version installation
If you want to benefit from all the functionalities (especially 3D rendering and hand-drawing selection), you need to install the full version locally on your machine.
It is fully written in Python, so you just need to have Python running on your machine. If you haven't installed Python yet, install Python 3.7. For instance, just download [miniconda 3.7](https://docs.conda.io/en/latest/miniconda.html). Then you can install **Track Analyzer** in a virtual environment using conda or virtualenv.
### Installation with conda
## Installation
### with conda
- If you haven't installed Python yet, install Python 3.7: download miniconda 3.7: https://docs.conda.io/en/latest/miniconda.html
- Open a Terminal (Mac & Linux) or open an Anaconda powershell (Windows)
- Create environment: run `conda create -n pyTA python=3.7`
- Activate environment (to be run every time you open a new terminal): run :`conda activate pyTA`
To install **Track Analyzer**, just run:
To install **Track Analyzer**, just run on a Terminal (Mac & Linux) or open an Anaconda powershell (Windows):
```sh
conda create -n pyTA python=3.7
conda activate pyTA
pip install track-analyzer
```
### with a virtualenv
### Installation with a virtualenv
you can also use a [virtual environment](<https://virtualenv.pypa.io/en/stable/>)
You can also use a [virtual environment](<https://virtualenv.pypa.io/en/stable/>)
```sh
python3 -m venv pyTA
......@@ -78,12 +70,15 @@ To run track-analyzer
source bin/activate
```
## 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/)).
## Documentation
You can find a complete documentation
[![here](https://track-analyzer.pages.pasteur.fr/track-analyzer/)](https://track-analyzer.pages.pasteur.fr/track-analyzer/)
You can find a complete documentation [here](https://track-analyzer.pages.pasteur.fr/track-analyzer/)
## Troubleshooting
The 3D visualization and the drawing selection tool depend on the [napari](<https://napari.org/>) package.
The 3D visualization and the drawing selection tool depend on the [napari](https://napari.org/) package.
The installation of this package can lead to issues depending on your system.
If you are not able to solve this installation, you will not be able to have access to 3D rendering. However, you will still be able to
use **Track Analyzer** without the drawing tool, by using coordinates sliders in the graphical interface.
......@@ -26,7 +26,7 @@ Welcome to Track Analyzer's documentation!
==========================================
**Track Analyzer** is Python-based data visualization pipeline for tracking data.
It *does not* perform any tracking, but visualizes and quantified 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,
acceleration, diffusion coefficient, local density, etc.
Trajectories can also be plotted on the original image in 2D or 3D using custom color coding.
......@@ -35,8 +35,8 @@ Trajectories can also be plotted on the original image in 2D or 3D using custom
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.
**Track Analyzer** can be run without any programming knowledge using its graphical interface. The interface is launched by
running a Jupyter notebook 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-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.
==========
......
......@@ -38,11 +38,12 @@ different (list of images), please convert it to tiff stack using `Fiji <https:/
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.
If **Track Analyzer** is run in command line (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 text file named info.txt containing the metadata (see example)
- (optional) a tiff file named stack.tif
- (optional) configuration files in a config directory
..
add a section descibing config and info files
......@@ -52,15 +53,17 @@ If **Track Analyzer** is run in command line (see below), the data directory mus
Running the pipeline
====================
There are two ways of running **Track Analyzer**:
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).
- using a Jupyter notebook based graphical interface (highly recommended)
- using terminal command lines
Using Galaxy (recommended for a first trial)
============================================
Using a notebook
================
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.
Documentation about Jupyter notebooks can be found `here <https://jupyter.org/>`_. Briefly, a notebook comprises a series of 'cells' which are blocks
Using a Jupyter notebook (recommended for advanced options)
===========================================================
The full version can be run using a Jupyter notebook. Documentation about Jupyter notebooks can be found `here <https://jupyter.org/>`_. Briefly, a notebook comprises a series of 'cells' which are blocks
of Python code to be executed. Each cell can be run by pressing Shift+Enter.
Each cell will execute a piece of code generating the pipeline graphical interface. They all depend on each other, therefore, they MUST be run in order.
By default, the code of each cell is hidden but it can be shown by pressing the button at the top of the notebook: 'Click here to toggle on/off the raw code'.
......@@ -76,8 +79,8 @@ To launch a notebook:
- a web browser opens, click on :code:`run_TA.ipynb`
- to shut down the notebook, press CTRL+C in the terminal.
Using command lines
====================
Using command lines (only if you need to run it on a distant machine)
====================================================================
If you need to run **Track Analyzer** from a terminal without any graphical interface, it is possible, but you won't beneficiate from the interactive
modules. Data filtering and analysis parameters will need to be passed through config files (see examples). **Track Analyzer** comes with two commands:
......@@ -87,15 +90,12 @@ modules. Data filtering and analysis parameters will need to be passed through c
- :code:`map_analysis` which runs the map analysis section (see below).
It takes as arguments: path to data directory (optional: use the flag -r or --refresh to refresh the database)
..
add third way with galaxy
==================
Analysis procedure
==================
**Track Analyzer** contains a data filtering section and three main analysis sections.
**Track Analyzer** contains a data filtering section and three main analysis sections. This section describes the procedure for the full version, but the installation-free version on Galaxy is very similar, only a few options aren't available.
Load data
=========
......@@ -192,17 +192,17 @@ Output
Database and configuration files
================================
Some files are necessary to the pipeline processing:
Some files that are necessary to the processing are generated when the pipeline is executed:
- *data_base.p* is a binary collection of python objects generated when the initial tracking file is loaded. It allows the initial loading to be skipped if the pipeline is run several times on the same tracking data. It can be refreshed if necessary.
- *info.txt* is a text file containing important metadata: 'lengthscale', 'timescale', 'z_step', 'image_width', 'image_height', 'length_unit', 'time_unit', 'table_unit', 'separator'. It can be interactively generated using the notebook
- *info.txt* is a text file containing important metadata: 'lengthscale', 'timescale', 'z_step', 'image_width', 'image_height', 'length_unit', 'time_unit', 'table_unit', 'separator'. It can be interactively generated using the notebook.
- if the original image stack is 4D (3D+t), a `stack_maxproj.tif` is generated by performing a maximum projection over the z dimension, so a 2D image can be used for 2D based plotting
- if run using command lines, the parameters are passed using several configuration files stored in the *config* folder in data directory output
Data output
===========
The trajectory analysis and the map analysis are generated respectively in a traj_analysis and map_analysis directory. Each subset's analysis is saved in a new folder.
The trajectory analysis and the map analysis are generated respectively in a *traj_analysis* and *map_analysis* directory. Each subset's analysis is saved in a new folder.
In each subset's directory:
......
This diff is collapsed.
This diff is collapsed.
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