Commit 1f27f174 authored by amichaut's avatar amichaut
Browse files

updated doc with gifs and scripts

parent 9ae246f6
......@@ -5,7 +5,7 @@
![Conda](https://img.shields.io/conda/pn/bioconda/macsyfinder)
# Track Analyzer
# 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.
......
......@@ -22,7 +22,8 @@ copyright = '2021, Arthur Michaut'
author = 'Arthur Michaut'
# The full version, including alpha/beta/rc tags
release = '0.1a'
import track_analyzer as tra
release = tra.__version__
# -- General configuration ---------------------------------------------------
......@@ -47,7 +48,8 @@ exclude_patterns = []
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
......
......@@ -30,15 +30,17 @@ Installation
Track Analyzer installation
===========================
.. _installation:
with conda
==========
- Install Python 3.7: download miniconda 3.7: https://docs.conda.io/en/latest/miniconda.html
- 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`
- Create environment: run :code:`conda create -n pyTA python=3.7`
- Activate environment (to be run every time you open a new terminal): run :code:`conda activate pyTA`
Run ::
To install **Track Analyzer**, just run ::
pip install track-analyzer
......
......@@ -68,10 +68,13 @@ Once the code is hidden, you might miss a cell. This is a common explanation if
To launch a notebook:
- go to the project folder run :code:`cd <path_to_the_project_folder>`
- if not done yet, activate the environment: run :code:`conda activate <env_name>` (if you use conda)
- the notebook is at the root of the git repository, or you can just download it here:
:download:`run_TA.ipynb <../_static/run_TA.ipynb>` .
- go to the project folder, or where you downloaded the notebook by running :code:`cd <path_to_the_project_folder>` in a terminal
- activate the environment: run :code:`conda activate <env_name>` (see :ref:`installation<installation>` for more details)
- launch a Jupyter notebook, run :code:`jupyter notebook`
- a web browser opens, click on :code:`analyze_traj_gui.ipynb`
- to shut down the notebook, press CTRL+C in the terminal.
Using command lines
====================
......@@ -94,18 +97,42 @@ Analysis procedure
**Track Analyzer** contains a data filtering section and three main analysis sections.
Load data
=========
Just follow the notebook instructions, to load your data files.
.. image:: ../_static/gifs/loading_data.gif
:align: center
If you run **Track Analyzer** for the first time, enter the metadata.
.. image:: ../_static/gifs/setting_metadata.gif
:align: center
You can also set some plotting parameters such as image file format, colors to be used, image resolution, etc.
.. image:: ../_static/gifs/ploting_parameters.gif
:align: center
Data filtering section
======================
Subsets of the datasets can be filtered on spatiotemporal criteria: x, y, z positions, time subset and track duration.
A drawing tool also offers the possibility to hand-draw regions of interest.
.. image:: ../_static/gifs/filter_subsets.gif
:align: center
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.
These subsets can then be analyzed separately. The analysis will be run independently on each on them.
Alternatively, they can be analyzed together. Trajectories and computed quantities will then be plotted together using color-coding.
.. image:: ../_static/gifs/subset_naming.gif
:align: center
Trajectory analysis section
===========================
......@@ -122,6 +149,9 @@ All these quantities can also be averaged over the whole trajectory and plotted.
Trajectories can also be quantified using the Mean Squared Displacement (MSD) analysis. The MSD can be plotted and fitted with some diffusion models
to compute the diffusion coefficient.
.. image:: ../_static/gifs/trajectory_section.gif
:align: center
Map analysis section
====================
......@@ -142,6 +172,8 @@ The difference between the velocity mean and the vector average modulus is that
the grid unit, while the vector average modulus is the modulus of the vector averaged in the grid unit.
Divergence (contraction and expansion) maps, and curl (rotation) maps can also be plotted.
.. image:: ../_static/gifs/map_section.gif
:align: center
Comparator section
==================
......@@ -160,10 +192,10 @@ Database and configuration files
Some files are necessary to the pipeline processing:
- 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
- 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_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
- 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
===========
......@@ -172,15 +204,42 @@ The trajectory analysis and the map analysis are generated respectively in a tra
In each subset's directory:
- a config folder is generated with the configuration parameters used for this specific analysis
- all_data.csv stores the subset's table of positions
- track_prop.csv stores the averaged quantities along trajectories
- a *config* folder is generated with the configuration parameters used for this specific analysis
- *all_data.csv* stores the subset's table of positions
- *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.
- 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
========
Examples
========
Real data
=========
You can get familiar with **Track Analyzer** by running it on example data. For instance, you can analyze data of a C. elegans developing embryo provided by `the cell tracking challenge <http://celltrackingchallenge.net/3d-datasets/>`_. Download the data directory containing trajectories and metadata (these positions were extracted following napari's tutorial):
: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.
To run the script, open a terminal and run: ::
pip install imagecodecs
cd <path_to_script_folder>
python load_tracking.py <path_to_dataset_folder>
Warning: if you try to open the generated tiff file with `Fiji <https://fiji.sc/>`_, you will see that the t and z dimensions are not separated. You will have to run "stack to hyperstack" with z=35 and t=195. But this is only if you want to see the file in Fiji, you don't need to do this for **Track Analyzer**!
Synthetic data
==============
You can also analyze synthetic data that were generated to ensure that the analysis performed by **Track Analyzer** is correct. You can download several datasets :download:`here <../_static/example/synthetic_data.tar.gz>`. They all have a *param.csv* with the input values for each trajectory.
===============
Troubleshouting
Troubleshooting
===============
The 3D visualization and the drawing selection tool depend on the `napari <https://napari.org/>`_ package.
......
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