Add Tonic/Basal Fluorescence Analysis Mode for Pharmacological Experiments

[pauladkisson]

Summary

For pharmacological experiments (drug injection, Parkinson's disease models), the relevant signal is a slow shift in overall tonic fluorescence rather than discrete transient events. The current GuPPy pipeline is built around event-triggered PSTH and transient detection, neither of which is appropriate when there are no individual transients to detect. A new analysis mode is needed that quantifies mean fluorescence within user-defined time epochs and compares them to a pre-manipulation baseline.

Motivation

• The Nelson lab works with Parkinson's disease models in which dopamine release is markedly impaired — there are no transients to detect; the relevant measure is the basal level of dopamine
• They also run pharmacological experiments (e.g., drug injection after a baseline period) where the question is: how did the overall fluorescence shift after the drug?
• Alexandra Nelson described this explicitly: "the kind of basal, tonic, whatever you want to call it, dopamine release is the more relevant measure, which doesn't have any little blips on it"
• The existing PSTH pipeline in src/guppy/orchestration/psth.py requires discrete event timestamps and produces peri-event averages; it cannot represent the "how did the signal change after drug injection" question
• Transient detection (src/guppy/analysis/transients.py) presupposes the existence of peaks; it produces no meaningful output when the signal is a slow sustained shift
• Paul noted that the isosbestic control fit may diverge from a step-change in signal (drug onset), making the standard pipeline unreliable for this use case

Proposed Solution

• Add a analysis_mode parameter to GuPPyParamtersUsed.json (e.g., "psth" | "tonic" | "both") to select the analysis branch run in Step 5
• For "tonic" mode: accept user-defined epoch window definitions (e.g., baseline start/end, post-manipulation start/end) as parameters; compute mean z-score or dF/F within each epoch; report the difference from baseline as the tonic response metric (absolute delta and percent change)
• Output per-session epoch averages as CSVs in the same session folder structure used by transient outputs, enabling multi-session group analysis using the same pattern as src/guppy/analysis/transients_average.py
• Add a tonic fluorescence panel to the visualization dashboard in src/guppy/orchestration/visualize.py showing the signal trace with epoch windows overlaid and per-epoch mean values
• Add a GUI section for specifying epoch windows (start/end time inputs per epoch, with an option to define epochs relative to a TTL event)

Open Questions

• Should epoch windows be specified as absolute recording times (seconds since start) or as offsets relative to a TTL event timestamp (e.g., "30 seconds before injection TTL, 120 seconds after")? Supporting both would maximize flexibility
• Should "tonic" mode bypass the isosbestic fitting step, or should the fitted signal be used as the input? For step-change responses, the fitted control channel may track the signal in a way that removes the very shift the lab wants to measure
• What normalization should be reported for the baseline comparison — percent change, absolute delta z-score, or should users choose?
• Should the tonic mode require isosbestic control data (many pharmacological recordings may have it), or gracefully degrade to a single-channel analysis when no control channel is available?
• Does multi-session group averaging for tonic analyses require a separate group analysis step analogous to the existing group transient average?