Commit 863fe2dd authored by amichaut's avatar amichaut
Browse files

updated readme

parent 6e4a4c40
Pipeline #55802 failed with stage
in 26 seconds
......@@ -7,50 +7,81 @@
# Track Analyzer :microscope: :bar_chart:
**Track Analyzer** is Python-based data visualization pipeline for tracking data. It *does not* perform any tracking, but takes as input any kind of tracked data. It analyzes trajectories by computing standard parameters such as velocity, acceleration, diffusion coefficient, divergence and curl maps, etc. This pipeline also offers a trajectory visualization in 2D (and soon in 3D rendering), using a selection tool allowing to perform some fate mapping and back-tracking.
**Track Analyzer** can be run by means of a Jupyter notebook based graphical interface, so no programming knowledge is required.
**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 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.
**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
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.
![image](resources/screenshot1.png)
![image](resources/screenshot2.png)
## Data requirements
**Track Analyzer** needs as input a text file of tracked data containing the positions coordinates (in 2D or 3D) along time and the tracks identifiers.
Optional: data can be plotted on the original image. **Track Analyzer** needs a grayscaled image file which can be a 3D or 4D tiff stack (2D timelapse or 3D timelapse). Other metadata such as time and length scales will be provided by the user through the graphical interface.
## Analysis modules
**Track Analyzer** contains a data selection module and three main analysis modules.
- Data selection module
Subsets of the datasets can be selected by spatial or time criteria, or track duration. A drawing tool offers the possibility to precisely select trajectories at a given frame and inspect either their past (back-tracking) or their future (fate-mapping).
- Trajectory-based analysis module
It offers trajectory visualization and computes trajectory parameters, such as: instantaneous velocities and accelaration, MSD analysis, trajectory averaging.
- Map-based analysis module
It computes averaging of velocities and acceleration data on a regular grid. These averaged maps can be used to compute 2D divergence and curl maps.
- Comparator module
A series of previously run analyses can be compared by plotting parameters together on the same plot.
**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.
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
## Installation
- Install Python 3.7: download miniconda 3.7: https://docs.conda.io/en/latest/miniconda.html
### 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`
- Run `pip install track-analyzer`
## Project organization
- **doc** => the documentation in html and pdf
- **example** => synthetic data examples are stored in the `example` folder. Each example contains a `params.csv` file containing for each track the "true" values.
- **track_analyzer** => the track analyzer python library
- **setup.py** => the installation script
- **requirements.txt** => the python dependencies
- **COPYING** => the licensing
- **README.md** => brief overview
- **analyze_traj_gui.ipynb** => the jupyter notebook used for the graphical interface
## Launching the graphical interface
Start a Jupyter notebook:
- go to the project folder run `cd <path_to_the_project_folder>`
- if not done yet, activate the environment: run `conda activate py37`
- launch a Jupyter notebook, run `jupyter notebook`
- a web browser opens, click on `analyze_traj_gui.ipynb`
## Running the pipeline
A [Jupyter notebook](https://jupyter.org/) comprises a series of 'cells' which are blocks of Python code to be run. 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'. Once the code is hidden, you might miss a cell. This is a common explanation if you get an error. If this happens, start the pipeline again a couple of cells above.
## Common issues
- (OUTDATED) The drawing tool depends on the [napari](https://github.com/napari/napari) project. The installation of this project can be tricky depending on your system. If you are not able to solve this installation, you can still use **Track Analyzer** without the drawing tool. You will then have to comment the `import napari` line in `codes/analyze_traj.py` and will not be able to use the ROI option in the data selection module.
\ No newline at end of file
- Activate environment (to be run every time you open a new terminal): run :`conda activate pyTA`
To install **Track Analyzer**, just run:
```sh
pip install track-analyzer`
```
### with a virtualenv
you can also use a [virtual environment](<https://virtualenv.pypa.io/en/stable/>)
```sh
python3 -m venv pyTA
cd pyTA
source bin/activate
pip install track-analyzer
```
to exit from the virtualenv
```sh
deactivate
```
To run track-analyzer
```sh
cd pyTA
source bin/activate
```
## Documentation
You can find a complete documentation
[![Doc](https://track-analyzer.pages.pasteur.fr/track-analyzer/)](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 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.
\ No newline at end of file
......@@ -25,17 +25,17 @@
Welcome to Track Analyzer's documentation!
==========================================
**Track Analyzer** is Python-based data visualization pipeline for tracking data.
**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 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.
| **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
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
**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.
......
......@@ -75,7 +75,7 @@ Archive overview
* **requirements.txt** => the python dependencies
* **COPYING** => the licensing
* **README.md** => brief overview
* **analyze_traj_gui.ipynb** => the jupyter notebook used for the graphical interface
* **run_TA.ipynb** => the jupyter notebook used for the graphical interface
===========================
......
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