Metadata-Version: 2.4
Name: track_analyzer
Version: 0.6.0
Summary: Track Analyzer: quantification and visualization of tracking data
Home-page: https://gitlab.pasteur.fr/track-analyzer/track-analyzer
Download-URL: https://pypi.org/project/track-analyzer/
Author: Arthur Michaut
Author-email: arthur.michaut@gmail.com
License: GPLv3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: numpy>=2.0
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: scikit-image
Requires-Dist: scipy
Requires-Dist: seaborn>=0.12
Requires-Dist: lmfit
Requires-Dist: tifffile
Requires-Dist: jupyter
Requires-Dist: ipyfilechooser
Requires-Dist: ipywidgets
Requires-Dist: tqdm
Requires-Dist: shapely
Provides-Extra: napari
Requires-Dist: napari>=0.10; extra == "napari"
Requires-Dist: npe2>=0.7; extra == "napari"
Requires-Dist: magicgui>=0.8; extra == "napari"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![Doc](https://img.shields.io/badge/doc-master-blue.svg)](https://track-analyzer.pages.pasteur.fr/track-analyzer/)
[![Open Source License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/licenses/GPL-3.0)
[![PyPI](https://img.shields.io/pypi/v/track-analyzer)](https://pypi.org/project/track-analyzer/)

# Track Analyzer

**Track Analyzer** visualizes and quantifies objects that have
already been tracked through time. It does **not** perform tracking: it starts
with a table of trajectories and, optionally, the corresponding movie.

Explore motion through trajectory plots, velocity and acceleration measurements,
mean squared displacement (MSD), diffusion estimates, and 2D Voronoi analysis.
Grid-based maps summarize quantities such as velocity, divergence, and curl.
Spatial and temporal filtering makes it possible to analyze or compare subsets
and to investigate where selected objects came from and where they go.

## The analysis pipeline

1. **Prepare the inputs.** Provide a CSV or TXT table containing track IDs,
   frame numbers, X and Y coordinates, and optionally Z coordinates and other
   measurements. Supply metadata such as spatial and time scales. An optional
   TIFF image can be used as a background. For TrackMate, export the spots
   table. A preprocessed `data_base.p` can be reused.
2. **Select trajectories.** Filter by spatial ranges, time windows, and track
   length. Depending on the interface, select individual IDs or tracks
   passing through a region at a given time.
3. **Analyze trajectories.** Plot tracks and motion parameters, compute MSD
   and model fits, or estimate local area and density with 2D Voronoi
   tessellation.
4. **Create maps and compare results.** Analyze measurements on a regular 2D
   grid and compare or pool saved trajectory analyses. Compared datasets must
   use matching length and time units.
5. **Inspect outputs.** Depending on the selected analyses, results include
   tables, plots, TIFF stacks, and configuration files.

See the [pipeline overview](doc/source/user_guide/quickstart.rst) and
[outputs guide](doc/source/user_guide/outputs.rst) for details.

## Choose an interface

The interfaces use the same underlying pipeline, but do not all expose the
same settings or interactive features.

| Interface | Best suited for | Guide |
| --- | --- | --- |
| **napari** | Interactive local analysis, image and track previews, ROI drawing, maps, and synthetic datasets | [napari plugin](doc/source/user_guide/napari_plugin.inc) |
| **Jupyter notebook** | A local step-by-step workflow with widgets and access to Python code | [Notebook](doc/source/user_guide/notebook.rst) |
| **Galaxy** | Browser-based jobs without a local installation | [Galaxy](doc/source/user_guide/galaxy.rst) |
| **Command line** | Configuration-file-driven local or remote analysis | [Command line](doc/source/user_guide/command_line.rst) |

![Track Analyzer's napari Load data tab](doc/source/_static/screenshots/napari-load.png)

## Getting started

### Galaxy

Open the [Track Analyzer Galaxy tool](https://galaxy.pasteur.fr/root?tool_id=toolshed.pasteur.fr/repos/rplanel/track_analyzer/track-analyzer/0.1.0),
upload the tracking table and optional image, configure the job, and retrieve
its results from the Galaxy history. See the [Galaxy guide](doc/source/user_guide/galaxy.rst)
for input requirements and instructions.

### Local installation

Local workflows require Python 3.11 or newer. To use the napari plugin,
install napari 0.10 or newer with a Qt 6 backend. For example, with
[Miniconda](https://docs.conda.io/en/latest/miniconda.html), run the following
in a terminal (or Anaconda PowerShell on Windows):

```sh
conda create -y -n track-analyzer-napari -c conda-forge python=3.11
conda activate track-analyzer-napari
conda install -c conda-forge "napari>=0.10" pyqt6
```

From the root of a Track Analyzer source checkout, install the plugin and its
dependencies:

```sh
python -m pip install -e ".[napari]"
```

The checkout also provides the notebook, command-line tools, and example
datasets. Activate the environment before starting a local workflow.
Alternatively, install the package from PyPI with
`python -m pip install track-analyzer`; plugin availability depends on the
published release. The notebook and examples are available in the source
checkout.

### napari

Run `python -m napari` and open **Plugins > Track Analyzer**. Load and map
your table, save metadata and the preprocessed database, then configure
filters and run trajectory or map analysis. The separate **Plugins > Synthetic
Dataset Generator** widget creates synthetic tracks and can display them in
the viewer.

![Opening and enabling a trajectory analysis in napari](doc/source/_static/screenshots/napari-trajectory-controls.gif)

See the [napari guide](doc/source/user_guide/napari_plugin.inc) for previews,
comparison, export settings, and the synthetic dataset generator.

### Jupyter notebook

From the checkout, run `jupyter notebook` and open `run_TA.ipynb`. Execute
the cells in order to load data, configure filtering, and run analyses. See
the [notebook guide](doc/source/user_guide/notebook.rst).

### Command line

Prepare a dataset directory with `positions.csv` and `info.txt`, then create
and edit the default configuration files:

```sh
TA_config /path/to/dataset
traj_analysis /path/to/dataset
map_analysis /path/to/dataset
```

See the [command-line guide](doc/source/user_guide/command_line.rst) for input
requirements, optional images, parallel TIFF rendering, and synthetic data.
Each command also provides `--help`.

## Examples and documentation

The checkout includes synthetic datasets in [example/](example/). The
[examples guide](doc/source/user_guide/examples.rst) also describes how to
obtain real and synthetic data.

Read the [full documentation](https://track-analyzer.pages.pasteur.fr/track-analyzer/).
See the [release notes](doc/source/release_notes.rst) for version history and
the upcoming napari plugin.
To build it locally from the repository root:

```sh
python -m pip install -r doc/requirements.txt
python -m sphinx -b html doc/source doc/build/html
```

Open `doc/build/html/index.html` in a browser. For local installation and
napari troubleshooting, see the [installation guide](doc/source/user_guide/installation.rst).

## License

Track Analyzer is distributed under the GNU GPL, version 3 or later. See
[COPYING](COPYING).
