diff --git a/_pages/plugins/andi-j/index.md b/_pages/plugins/andi-j/index.md index 8c7349ee7..be2987853 100644 --- a/_pages/plugins/andi-j/index.md +++ b/_pages/plugins/andi-j/index.md @@ -41,7 +41,7 @@ AnDi-J is organised around two menu commands under {% include bc path="Plugins|A | Command | Purpose | |---|---| -| [**Trajectory Analysis**](/plugins/andi-j/trajectory-analysis) | Per-trajectory observables: mean squared displacement (MSD) analysis, diffusion coefficient *D*, anomalous exponent *α*, the *D*–*α* plane, diffusion-model classification, turning angles and PSD. | +| [**Trajectory Analysis**](/plugins/andi-j/trajectory-analysis) | Per-trajectory observables: mean squared displacement (MSD) analysis, diffusion coefficient *D*, anomalous exponent *α*, the *D*–*α* plane, diffusion-model classification, turning angles, PSD and a summary table per experiment. | | [**Trajectory Segmentation**](/plugins/andi-j/trajectory-segmentation) | Per-frame predictions of *α* and *D* along each trajectory, change-point detection that splits it into homogeneous segments, and the diffusive state (immobile, confined, free diffusion, or directed) of each segment. | Both commands share the same [Data Manager](/plugins/andi-j/input-data#data-manager) for loading and grouping data, and both can analyse several experiments (conditions) at once, each with its own colour, overlaid for comparison. @@ -51,7 +51,7 @@ Both commands share the same [Data Manager](/plugins/andi-j/input-data#data-mana | Page | Contents | |---|---| | [Input data](/plugins/andi-j/input-data) | Expected `.csv` layout, the [Data Manager](/plugins/andi-j/input-data#data-manager) ([loading trajectories](/plugins/andi-j/input-data#loading-trajectories), [units](/plugins/andi-j/input-data#units)), and [selecting the segmentation model](/plugins/andi-j/input-data#selecting-the-segmentation-model). | -| [Trajectory Analysis](/plugins/andi-j/trajectory-analysis) | [tMSD](/plugins/andi-j/trajectory-analysis#tmsd-visualization), [diffusion coefficient](/plugins/andi-j/trajectory-analysis#diffusion-coefficient), [anomalous exponent](/plugins/andi-j/trajectory-analysis#anomalous-exponent), [*D* vs *α*](/plugins/andi-j/trajectory-analysis#d-vs-alpha), [diffusion model](/plugins/andi-j/trajectory-analysis#diffusion-model), [turning angles](/plugins/andi-j/trajectory-analysis#turning-angles) and [PSD](/plugins/andi-j/trajectory-analysis#psd). | +| [Trajectory Analysis](/plugins/andi-j/trajectory-analysis) | [tMSD](/plugins/andi-j/trajectory-analysis#tmsd-visualization), [diffusion coefficient](/plugins/andi-j/trajectory-analysis#diffusion-coefficient), [anomalous exponent](/plugins/andi-j/trajectory-analysis#anomalous-exponent), [*D* vs *α*](/plugins/andi-j/trajectory-analysis#d-vs-alpha), [diffusion model](/plugins/andi-j/trajectory-analysis#diffusion-model), [turning angles](/plugins/andi-j/trajectory-analysis#turning-angles), [PSD](/plugins/andi-j/trajectory-analysis#psd) and [summary](/plugins/andi-j/trajectory-analysis#summary). | | [Trajectory Segmentation](/plugins/andi-j/trajectory-segmentation) | [Visualization](/plugins/andi-j/trajectory-segmentation#visualization), [*D* vs *α* density](/plugins/andi-j/trajectory-segmentation#d-vs-alpha), [segment stats](/plugins/andi-j/trajectory-segmentation#segment-stats) and [diffusive state](/plugins/andi-j/trajectory-segmentation#diffusive-state). | | [ML models](/plugins/andi-j/ml-models) | The bundled models, the ONNX contract, how to plug in your own models, and how to [contribute them](/plugins/andi-j/ml-models#contributing-a-model). | diff --git a/_pages/plugins/andi-j/trajectory-analysis.md b/_pages/plugins/andi-j/trajectory-analysis.md index 574ed4839..eb3b40019 100644 --- a/_pages/plugins/andi-j/trajectory-analysis.md +++ b/_pages/plugins/andi-j/trajectory-analysis.md @@ -2,7 +2,7 @@ title: AnDi-J › Trajectory Analysis name: AnDi-J icon: /media/plugins/andi-j/logo.png -description: Per-trajectory anomalous-diffusion observables in AnDi-J - tMSD, diffusion coefficient, anomalous exponent, D vs α, diffusion model, turning angles and PSD. +description: Per-trajectory anomalous-diffusion observables in AnDi-J - tMSD, diffusion coefficient, anomalous exponent, D vs α, diffusion model, turning angles, PSD and summary table. nav-title: Trajectory Analysis nav-links: - title: Overview @@ -19,9 +19,9 @@ nav-links: This tool allows to perform single-trajectory analysis of the input experiments. Every tab has a side **Experiments** panel where each experiment can be toggled on/off and, where relevant, restricted to the **2D**, **X**, or **Y** component. -{% include notice icon="info" content="**Saving data.** Every tab has a **Save plot** button that exports its plot as a vector image (`svg`), which you can edit in tools such as Inkscape or Illustrator. The **Diffusion coefficient**, **Anomalous exponent**, **Diffusion Model**, **Turning Angles** and **PSD** tabs also save their values as a `csv` file for further analysis (**Save D…**, **Save α…**, **Save models…**, **Save angles…** and **Save PSD…**). Their first columns are `experiment` and, for per-trajectory values, `track_id`; commas in experiment names are written as semicolons. In **D vs α**, tagged populations can be saved as trajectory files (see [Population tagging](#d-vs-alpha))." %} +{% include notice icon="info" content="**Saving data.** Every tab has a **Save plot** button that exports its plot as a vector image (`svg`), which you can edit in tools such as Inkscape or Illustrator. The **Diffusion coefficient**, **Anomalous exponent**, **Diffusion Model**, **Turning Angles**, **PSD** and **Summary** tabs also save their values as a `csv` file for further analysis (**Save D…**, **Save α…**, **Save models…**, **Save angles…**, **Save PSD…** and **Save table…**). Their first columns are `experiment` and, for per-trajectory values, `track_id`; commas in experiment names are written as semicolons. In **D vs α**, tagged populations can be saved as trajectory files (see [Population tagging](#d-vs-alpha))." %} -{% include notice icon="info" content="**Units.** The **Units** button of the tMSD Visualization, Diffusion coefficient, D vs α and PSD tabs opens a window to choose the time (frames, ns, μs, ms, s) and space (nm, μm, mm, m) units of the plots and `csv` exports, whose column headers name them. Physical units need the calibration of the [Data Manager](/plugins/andi-j/input-data#units); without it, the window shows px and frames and cannot change them." %} +{% include notice icon="info" content="**Units.** The **Units** button of the tMSD Visualization, Diffusion coefficient, D vs α, PSD and Summary tabs opens a window to choose the time (frames, ns, μs, ms, s, min) and space (nm, μm, mm, m) units of the plots and `csv` exports, whose column headers name them. Physical units need the calibration of the [Data Manager](/plugins/andi-j/input-data#units); without it, the window shows px and frames and cannot change them." %} ## tMSD Visualization @@ -100,10 +100,10 @@ The dropdown at the start of the toolbar chooses the view: Features: * **Marginal KDEs** — the plots along the top and right edges show a kernel density estimate of the population for α and *D*, respectively. -* **Population tagging** — in **Select** mode, *circle* (lasso) a cluster of points (see blue area in the figure below), type a name in **Population tag:** and click **Tag population**. The enclosed trajectories are recoloured to a shade of their parent colour and added as a new dataset to the [Turning Angles](#turning-angles) and [Diffusion Model](#diffusion-model) tabs. A management table below the plot lists each population (tag, source datasets, colour — click the colour to change it). Click **Save…** in the **Save** column to export the population's trajectories as a `csv` in the [input format](/plugins/andi-j/input-data) (`TRACK_ID, POSITION_X, POSITION_Y, POSITION_T, FRAME`), plus an `EXPERIMENT` column naming the experiment each trajectory comes from. The file can be loaded again in the Data Manager, which ignores the extra column; with a calibration, positions are written in μm and `POSITION_T` in seconds, so the file loads back calibrated. `TRACK_ID` keeps the trajectory's id when the population comes from one experiment and is renumbered from 0 when it mixes several, so ids stay unique; commas in experiment names are written as semicolons. +* **Population tagging** — in **Select** mode, *circle* (lasso) a cluster of points (see blue area in the figure below), type a name in **Population tag:** and click **Tag population**. The enclosed trajectories are recoloured to a shade of their parent colour and added as a new dataset to the [Turning Angles](#turning-angles) and [Diffusion Model](#diffusion-model) tabs. A trajectory can belong to several populations; where they overlap, the latest population is drawn on top. A management table below the plot lists each population (tag, source datasets, number of trajectories, **Show**, colour — click the colour to change it in every tab). Untick **Show** to hide a population from this plot only: its points take their parent's colour again. **Delete selected** deletes the highlighted populations (click, Ctrl- or Shift-click a row) from every tab, after a confirmation. Click **Save…** in the **Save** column to export the population's trajectories as a `csv` in the [input format](/plugins/andi-j/input-data) (`TRACK_ID, POSITION_X, POSITION_Y, POSITION_T, FRAME`), plus an `EXPERIMENT` column naming the experiment each trajectory comes from. The file can be loaded again in the Data Manager, which ignores the extra column; with a calibration, positions are written in μm and `POSITION_T` in seconds, so the file loads back calibrated. `TRACK_ID` keeps the trajectory's id when the population comes from one experiment and is renumbered from 0 when it mixes several, so ids stay unique; commas in experiment names are written as semicolons. * **Plot manipulation** — Log *D* axis toggle, rubber-band **Zoom**, **Pan**, **Reset view**, in both views. -{% include img align="center" name="D vs alpha tab" src="/media/plugins/andi-j/d-vs-alpha-tab.png" caption="**D vs α** in Scatter view, with marginal KDEs and a tagged population (top), and in Density view (bottom)." %} +{% include img align="center" name="D vs alpha tab" src="/media/plugins/andi-j/d-vs-alpha-tab.png" caption="**D vs α** in Scatter view, with marginal KDEs, a tagged population and the population table (top), and in Density view (bottom)." %} ## Diffusion Model @@ -136,3 +136,35 @@ To learn about the PSD for anomalous diffusion analysis, we recommend reading th * Sposini, V., Krapf, D., Marinari, E., Sunyer, R., Ritort, F., Taheri, F., … & Oshanin, G. (2022). Towards a robust criterion of anomalous diffusion. [Communications Physics, 5(1), 305](https://www.nature.com/articles/s42005-022-01079-8). {% include img align="center" name="PSD tab" src="/media/plugins/andi-j/psd-tab.png" caption="**PSD** tab with a drawn slope line." %} + +## Summary + +A table with **one row per experiment** and values aggregated over its trajectories. Click the ▸ next to an experiment's name to show its **X** and **Y** rows. Click a column header marked ⓘ for a description of the value; the descriptions are listed below. + +* Values from the other tabs (*D*, α, eMSD) appear when the tab opens and are updated each time it is shown, so they follow the parameters chosen in those tabs. +* **Compute** fills the trajectory statistics of every experiment: α₂, VACF, mean speed, step anisotropy, FMI, centre of mass and directness. +* **α (ML)** and **Diffusion model** come from the ML model of the [Anomalous exponent](#anomalous-exponent) or [Diffusion Model](#diffusion-model) tab. Run it there to fill or update these values; **Compute** does not run it. +* Yellow cells are not computed yet; hover over one to see where to compute it. Empty cells are values not defined for that row (for example FMI in 2D). +* **Units** sets the units of *D*, mean speed and centre of mass. **Save table…** saves a `csv` with one row per experiment and component (`2D`, `X`, `Y`); values not defined or not computed are left empty. + +{% include img align="center" name="Summary tab" src="/media/plugins/andi-j/summary.png" caption="**Summary** tab with two experiments expanded to their X and Y rows, after **Compute** and the ML model." %} + +In the formulas, r(t) = (x(t), y(t)) is a trajectory sampled every Δt (one frame), and ⟨…⟩ is the average over all times and trajectories of the experiment. + +* **N**, **Length** — number of trajectories, and their length in frames as median (min–max). +* **D** — mean over the trajectories of *D* from the [Diffusion coefficient](#diffusion-coefficient) tab. +* **Dₓ / Dᵧ** — ratio of the diffusion coefficients along x and y, computed from the X and Y values of **D**. A value of 1 means isotropic diffusion; values far from 1 mean faster motion along one axis. +* **α (tMSD)** — mean of the anomalous exponents of the trajectories, each from a log–log linear fit of the trajectory's tMSD with the time lags of the [Anomalous exponent](#anomalous-exponent) tab. α < 1: subdiffusion · α = 1: normal diffusion · α > 1: superdiffusion. +* **α (eMSD)** — anomalous exponent from a log–log linear fit of the ensemble MSD, eMSD(Δ) ∝ Δα, over the lags of the [tMSD Visualization](#tmsd-visualization) tab. The eMSD averages the squared displacement from the first frame of each trajectory. If α (eMSD) ≠ α (tMSD), the time and ensemble averages differ (see **Ergodicity gap**). *Reference:* R. Metzler, J.-H. Jeon, A. G. Cherstvy, E. Barkai, [*Phys. Chem. Chem. Phys.* **16**, 24128 (2014)](https://doi.org/10.1039/C4CP03465A). +* **α (ML)** — mean of the α predicted by the ML model for each trajectory. +* **Diffusion model** — the most frequent diffusion model among the trajectories, with the percentage of trajectories assigned to it. +* **Ergodicity gap** — ratio of the time-averaged and ensemble-averaged MSDs, averaged over the lags of the [tMSD Visualization](#tmsd-visualization) tab: G = mean over Δ of ⟨tMSD(Δ)⟩ / eMSD(Δ). G ≈ 1: time and ensemble averages agree, as for an ergodic process such as Brownian motion or fractional Brownian motion. G ≠ 1: weak ergodicity breaking, as for continuous-time random walks (CTRW), annealed transient time motion (ATTM) or ageing systems. *References:* Y. He, S. Burov, R. Metzler, E. Barkai, [*Phys. Rev. Lett.* **101**, 058101 (2008)](https://doi.org/10.1103/PhysRevLett.101.058101); R. Metzler *et al.* (2014), above. +* **α₂ (non-Gaussian)** — measures whether the displacements over one frame are Gaussian: α₂ = ⟨\|r\|⁴⟩ / ((1 + 2/d) ⟨\|r\|²⟩²) − 1, where d is the number of dimensions: 2 for 2D, 1 for X or Y. In 1D this is α₂ = ⟨Δx⁴⟩ / (3⟨Δx²⟩²) − 1. α₂ = 0 for Gaussian displacements. α₂ > 0 means heavier tails than a Gaussian. This typically comes from heterogeneity: particles, or parts of trajectories, with different diffusion coefficients ("Fickian yet non-Gaussian" diffusion). *Reference:* B. Wang, J. Kuo, S. C. Bae, S. Granick, [*Nat. Mater.* **11**, 481 (2012)](https://doi.org/10.1038/nmat3308). +* **VACF** — correlation between consecutive steps, normalised by the step variance: C = ⟨v(t) · v(t+Δt)⟩ / ⟨\|v(t)\|²⟩, with v(t) = r(t+Δt) − r(t). C ≈ 0: uncorrelated steps (Brownian motion, continuous-time random walk). C < 0: anti-persistent steps (fractional Brownian motion with α < 1 gives C = 2α−1 − 1, confinement). C > 0: persistent steps (directed or superdiffusive motion). Static localisation noise pushes C towards −0.5. A strongly negative C can therefore also mean noisy data. *Reference:* S. Burov, J.-H. Jeon, R. Metzler, E. Barkai, [*Phys. Chem. Chem. Phys.* **13**, 1800 (2011)](https://doi.org/10.1039/C0CP01879A). +* **Mean speed** — accumulated distance of each trajectory divided by its duration, averaged over the trajectories: v = ⟨ Σ \|r(t+Δt) − r(t)\| / (T Δt) ⟩. For X and Y, \|Δx\| or \|Δy\| replaces the step length. The value depends on the frame rate and on localisation noise, which adds apparent motion, so compare it only between experiments recorded the same way. +* **Step anisotropy** — orientation order of the steps. With φ = atan2(Δy, Δx) the direction of each one-frame step: S = ⟨cos 2φ⟩. S = 1: all steps along x. S = −1: all steps along y. S = 0: no preferred axis. Opposite steps (φ and φ + 180°) count the same, so S measures alignment along an axis, not drift in one direction (see **FMI** and **Centre of mass**). +* **FMI** (forward migration index) — net displacement along one axis relative to the path length, averaged over the trajectories: FMIx = ⟨ (xend − xstart) / dacc ⟩, with dacc = Σ \|r(t+Δt) − r(t)\|. FMIy is the same with y. It ranges from −1 to 1. Values near 0 mean no drift along that axis. In a chemotaxis assay with the gradient along one axis, FMI along the gradient measures how efficiently the cells follow it. +* **Centre of mass** — mean end point of the trajectories, each shifted to start at the origin: Mend = ⟨ rend − rstart ⟩. Mend close to (0, 0) means no net drift. Its x and y components give the direction of the drift; the 2D value is its distance from the origin. +* **Directness** — straight-line distance between start and end divided by the path length, averaged over the trajectories: Directness = ⟨ \|rend − rstart\| / dacc ⟩. It ranges from 0 to 1, where 1 is a straight line. It decreases with trajectory length: for Brownian motion, Directness ≈ 1/√T for trajectories of T frames, since the net displacement grows as √T and the path length as T. Localisation noise also lowers it. Compare it only between experiments with similar lengths and frame rates, for example by setting the same **Max. length** for all files in the [Data Manager](/plugins/andi-j/input-data#loading-trajectories). + +*Reference* for mean speed, FMI, centre of mass and directness: P. Zengel *et al.*, [*BMC Cell Biol.* **12**, 21 (2011)](https://doi.org/10.1186/1471-2121-12-21). diff --git a/media/plugins/andi-j/d-vs-alpha-tab.png b/media/plugins/andi-j/d-vs-alpha-tab.png index 10be63c95..f0fb6a8f3 100644 Binary files a/media/plugins/andi-j/d-vs-alpha-tab.png and b/media/plugins/andi-j/d-vs-alpha-tab.png differ diff --git a/media/plugins/andi-j/summary.png b/media/plugins/andi-j/summary.png new file mode 100644 index 000000000..ed7fdaac8 Binary files /dev/null and b/media/plugins/andi-j/summary.png differ