Jupyter notebook
================

The notebook provides a local, step-by-step graphical workflow with access to
the underlying Python code. Install Track Analyzer as described in
:doc:`installation`. Use the :doc:`pipeline overview <quickstart>` for the
meaning of each analysis stage.

Start the notebook
------------------

The notebook is ``run_TA.ipynb`` at the root of the checkout. In the
environment where Track Analyzer and Jupyter are installed, run:

.. code-block:: sh

   jupyter notebook

Open ``run_TA.ipynb`` in the browser. Run cells in order with **Shift+Enter**:
later controls depend on earlier cells. The button at the top toggles the
display of the raw code. If a widget or variable is missing, check that the
preceding cells were run; restart the kernel and run the cells in order if
necessary. Stop the notebook server with **Ctrl+C** in the terminal.

Prepare data and select subsets
-------------------------------

Use the preparation cells to load a table, identify its columns, enter
metadata, and configure plots. The notebook can also map custom variables.
An optional napari viewer supports visual selection and preview.

.. figure:: ../_static/screenshots/loading_data.png
   :alt: Notebook data-loading controls
   :align: center

   Notebook data-loading controls.

.. figure:: ../_static/screenshots/setting_metadata.png
   :alt: Notebook metadata controls
   :align: center

   Notebook metadata controls.

Run the filtering cells to configure subsets and optionally select individual
trajectories. Numeric ranges are available without drawing an ROI.

.. figure:: ../_static/screenshots/filter_subsets-1.png
   :alt: Notebook subset filtering controls
   :align: center

   Notebook subset filtering controls.

Run analyses
------------

Execute the trajectory and map cells after preparation and filtering; choose
the plots and parameters in their respective widgets. The comparator cells
can load and compare previously saved trajectory analyses. Outputs are saved
in the dataset directory as described in :doc:`outputs`.

.. figure:: ../_static/screenshots/trajectory_section.png
   :alt: Notebook trajectory analysis controls
   :align: center

   Notebook trajectory analysis controls.

.. figure:: ../_static/screenshots/map_section.png
   :alt: Notebook map analysis controls
   :align: center

   Notebook map analysis controls.

If a cell does not run with the keyboard shortcut, try the notebook's
**Run** button. napari-dependent previews and drawing tools require a working
local napari/Qt installation.
