Table Explorer (Table UI)
=========================

.. _table_exploration:

The Table Explorer (internally ``TableUI``) is a powerful interface for interacting with your measurement data. It allows you to visualize data structure, perform calculations, generate plots, and aggregate track information.

Overview
--------

The Table UI provides a spreadsheet-like view of your data with extensive capabilities for data manipulation and visualization. It is accessible from various parts of the application where measurement tables are displayed.

Menu Actions
------------

The menu bar provides access to file operations, column editing, and mathematical transformations.

For a complete list of commands (including Keyboard Shortcuts), see the :ref:`Table Explorer Menu Reference <ref_table_explorer_menus>`.

Plotting
--------

The Table UI offers versatile plotting capabilities. Select columns in the table and use **File > Plot...** (:kbd:`Ctrl+P`) to visualize them.

1D Plotting
~~~~~~~~~~~
If one column is selected (or no specific column), the 1D plot interface opens. It supports:

- **Distributions**: Histogram, KDE plot, ECDF plot.
  *Note:* When selecting a Histogram for a binned property (generated via **Math > Bin...**), the bar width is automatically synchronized to match the exact mathematical bin interval with a clear edge separation.
- **Categorical**: Countplot, Swarm plot, Violin plot, Strip plot, Box plot, Boxenplot.
- **Stats**: Option to compute KS test p-values and Cliff's Delta effect size.
- **Grouping**: Select X, Y, and Hue variables to group data.

2D Plotting
~~~~~~~~~~~
If two columns are selected, a scatter plot is automatically generated comparing the two variables. Select **Histogram** to switch to a co-binning heatmap displaying density distributions, or **KDE plot** to display a smooth 2D density contour map. If the X and Y metrics represent binned properties (via **Math > Bin...**), the generated 2D **Histogram** grid will perfectly align with both interval widths to form true spatial bounding boxes.

Time Series / Track Signals
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When viewing track data, you can visualize signals over time:

- **Plot instantaneous...** (:kbd:`Ctrl+I`): Switches the plotting mode to show track signals when rows are selected, allowing you to see the temporal evolution of metrics for selected cells.


Statistical Analysis
--------------------

The Table UI facilitates pairwise statistical comparisons between groups of data. These tests can be accessed through the **1D Plotting** interface by selecting the corresponding checkboxes.

Hypothesis Testing (p-value)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*   **Test Used**: Two-sample Kolmogorov-Smirnov test (``scipy.stats.ks_2samp``).
*   **Alternative Hypothesis**: ``less``. This explicitly checks if the cumulative distribution function (CDF) of the first group (Row) is *less* than that of the second group (Column).
*   **Interpretation**: In the context of the KS test, CDF(Row) < CDF(Col) implies that the values in the **Row** group are stochastically **larger** than the values in the **Column** group.
*   **Result**: The resulting pivot table displays color-coded p-values:
    *   **ns**: p > 0.05
    *   **\***: p <= 0.05
    *   **\*\***: p <= 0.01
    *   **\*\*\***: p <= 0.001
    *   **\*\*\*\***: p <= 0.0001
    *   *Note*: A significant result (red) means the Row group is significantly larger than the Column group.

Effect Size (Cliff's Delta)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

*   **Measure Used**: Cliff's Delta (non-parametric).
*   **Interpretation**: Quantifies the amount of difference between two groups. It ranges from -1 to 1, where 1 means all values in the **Row** group are larger than the **Column** group, and -1 means the opposite.
*   **Color Coding**: The pivot table colors cells based on the **absolute magnitude** of the effect size (`|d|`), using standard thresholds (Romano et al., 2006):
    *   **Negligible**: |d| < 0.147
    *   **Small**: 0.147 <= |d| < 0.33
    *   **Medium**: 0.33 <= |d| < 0.474
    *   **Large**: |d| >= 0.474

Track Collapsing
----------------

One of the most powerful features is the ability to aggregate data at the track level. This transforms your data from a **time-series format** (one row per timepoint) to a **track-based format** (one row per cell track). Use **File > Collapse tracks...** (:kbd:`Ctrl+G`) to open the projection mode dialog.

Global Operation
~~~~~~~~~~~~~~~~
Collapse the entire track into a single value using an aggregation function.

- **Operations**: `mean`, `median`, `min`, `max`, `first`, `last`, `prod`, `sum`.
- **Example 1**: You want to know if a cell *ever* expressed a marker. Use **max** on the intensity column.
- **Example 2**: You want to correlate cell size with fate. Use **mean** on the ``area`` column to get the average size of the cell over its lifetime.

@ Event Time
~~~~~~~~~~~~
Extract measurement values at a specific event time. This is useful for synchronizing data around biological events.

- **Prerequisite**: Your table must contain event times (columns starting with ``t_`` or ``t0``), typically generated by the *Event Detection* or *Event Annotation* modules.
- **Example**: "What was the cell's nuclear circularity **at the moment of division**?". Select ``@ t0`` (or your specific event column). The resulting table will contain the value of ``circularity`` at the frame corresponding to that event for each cell.

Per Status
~~~~~~~~~~
Aggregate measurements independently for each cell state or status.

- **Prerequisite**: Your table must contain status or classification columns (starting with ``status_`` or ``group_``).
- **Example**: Compare protein localization during the cell cycle.
    - If you have a ``status_cell_cycle`` column (with values like G1, S, G2), selecting this option with **mean** will create separate columns for each phase (e.g., ``mean_intensity_G1``, ``mean_intensity_S``).
    - You can then easily plot these against each other to see stage-specific differences.

