Release notes
=============

0.6.0 (unreleased)
------------------

This upcoming release introduces a **napari plugin** for interactive
trajectory analysis. Track Analyzer still starts from trajectories produced by
a tracking tool; it does not perform tracking itself. The notebook, command
line, and Galaxy workflows remain available.

The notes below describe the current development version and may change before
release.

napari: an interactive analysis workflow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open **Plugins > Track Analyzer** to load and analyze trajectories alongside
image and track layers. The dock widget brings together five stages:

* **Load data**: import CSV or TXT tables, including TrackMate spots exports,
  inspect and map columns, configure metadata and trajectory gap handling,
  and save a processed database. Existing ``data_base.p`` files can also be
  loaded. Images are optional and can be opened separately in napari.
* **Filtering**: define named spatial, temporal, and track-length subsets,
  select tracks by ID or by location and time, and draw rectangular ROIs in the
  viewer. Tracks can provide a visual reference when no image is open.
* **Trajectory analysis**: configure and run trajectory visualizations,
  parameter plots, MSD analysis, and Voronoi analysis. Preview colored tracks
  and 2D Voronoi tessellations in the viewer.
* **Map analysis**: preview the grid and inspect scalar fields, vector fields,
  and vector means as viewer layers. Compute field ranges across frames and
  subsets, adjust color limits with a two-handle slider or typed custom
  values, and reuse computed grid values when running the analysis.
* **Comparator**: compare or pool saved trajectory analyses from one or more
  dataset roots, using shared numerical parameters and optional MSD plots.
  Selected datasets must use matching length and time units.

The widget displays progress and log messages, and notifies the user when
analyses finish. It saves results in the existing trajectory, map, and
comparison output folders. Loading starts without a preselected dataset, and
loaded data and plugin previews can be cleared without deleting source files.
See :doc:`user_guide/napari` for the workflow, prerequisites, and limitations.

Synthetic dataset generator
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A separate **Synthetic Dataset Generator** napari widget creates 2D or 3D
synthetic trajectories with configurable diffusion, velocity, space, and
timing. It can save a TIFF stack and display generated tracks in the viewer.
Normalized velocity coefficients make it easier to specify gradients across
the simulated space; physical polynomial coefficients remain available.
Generated tracks can then be imported into the main widget for analysis.

Performance and other changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* TIFF stack rendering can optionally use multiple processes for trajectory,
  Voronoi, scalar and vector map, and synthetic-data exports. It is off by
  default for the main analysis widget and may be slower for small stacks.
  The command-line tools expose the ``--parallelize`` option.
* Trajectory preprocessing and map interpolation have been optimized, and
  current map computations can be reused by the napari workflow.
* Additional fixes cover ROI selection, synthetic 3D data, notebook parameter
  handling, and compatibility with Matplotlib 3.10.
* The documentation and README now describe the shared pipeline first, then
  the specifics of each interface.

Installation and compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Local workflows now require **Python 3.11 or newer**, compared with the
  Python 3.6 minimum declared by version 0.5. The napari plugin requires
  **napari 0.10 or newer** and a Qt 6 backend.
* To try the development plugin from a source checkout, install it with
  ``python -m pip install -e ".[napari]"`` in the napari environment. See
  :doc:`user_guide/installation` for complete instructions. The development
  plugin should not be assumed to be available in the current PyPI release.
* The previously deprecated ``track_analyzer.deprecated`` module has been
  removed. Code importing it must be updated.

Earlier versions
----------------

0.5 (2024-08-22)
~~~~~~~~~~~~~~~~

* Moved filtering, trajectory, map, and comparison workflow code from the
  notebook into Python modules.
* Updated notebook information and fixed grid visualization and image-free
  origin selection.

0.4.1 (2023-06-06)
~~~~~~~~~~~~~~~~~~

* Added support for newer NumPy types, revised installation instructions,
  and cleaned up the notebook.

0.4 (2022-11-06)
~~~~~~~~~~~~~~~~

* Added polygon-based selection and hue options for scatter and swarm plots.
* Added TIFF metadata, frame labels, and frame increments for stack export.
* Fixed map coordinate export and temporal averaging issues.

0.3 (2022-07-01)
~~~~~~~~~~~~~~~~

* Added TrackMate-ready input and custom-variable support for trajectory
  plots, color coding, and maps.
* Added boxplots, scatter-plot binning and regression, and TIFF stack export.
* Reworked synthetic-data generation as a command-line tool and documented
  the Galaxy workflow, alongside configuration and plotting fixes.

0.2 (2021-06-23)
~~~~~~~~~~~~~~~~

* Minor corrections.

0.1 (2021-06-03)
~~~~~~~~~~~~~~~~

* Added Voronoi tessellation and per-track Voronoi-area averages.
* Improved subset filtering, notebook integration, and documentation after
  the initial release candidate.

0.1rc1 (2021-04-07)
~~~~~~~~~~~~~~~~~~~

* Initial release candidate with notebook-based trajectory selection,
  trajectory analysis, maps, and dataset comparison.
