Fiber photometry data in NWB#
Neurodata Without Borders (NWB) is a common data format for neurophysiology, holding one experimental session per file. What NWB is and how it is structured are covered by NWB’s own documentation; this page covers only GuPPy’s side of it — what GuPPy puts in a file, what it needs from you in order to do that, and where its export stops.
For the mechanics of running an export, see Export a session to NWB.
What GuPPy writes#
An export has three parts:
<session_name>_output_<run_name>.nwb
acquisition/ the raw photometry, as it was recorded
<signal series> FiberPhotometryResponseSeries, one column per recording site
<control series> the isosbestic channel, same shape
events/
<event store> one EventsTable per raw behavioral event store
GuppyEvents the onsets GuPPy actually analyzed
processing/guppy/
recording_sites registry: one row per recording site
events registry: one row per event GuPPy aligned to
<trace_type>_<site> control_fit, dff and z_score traces
transients_<site>_<metric> detected transient peaks
transient_summary frequency and mean amplitude per trace
psth_<site>_<metric> peri-event PSTHs
peak_auc_<site>_<metric> peak and area summaries
cross_correlation_<metric>_<siteA>_<siteB>
tonic_epochs tonic signal means, one row per epoch
<covariate> a scored behavioral covariate, on its own timestamps
binned_metrics whole-session metrics, one row per time bin
binned_covariates the covariates binned onto those same bins
covariate_correlations the coefficients relating the two
valid_signal_intervals what survived artifact removal
guppy_parameters the parameters the run was produced with
Which of these appear depends on what the run computed: a run that skipped Tonic
Analysis or left Compute Binned Metrics? off simply has no such group, and one run in
Use Transients as Events? mode has the transients it aligned to listed in GuppyEvents
alongside — or instead of — its external TTLs.
The acquisition group is the recording, unmodified — exporting does not replace your raw data with GuPPy’s version of it. Everything GuPPy computed lives under processing/guppy, which is how NWB separates what was measured from what was inferred.
The GuPPy extension types#
The core NWB schema and the fiber-photometry extension cover the raw side. GuPPy’s derived products have no core type, so ndx-guppy defines them:
Type |
What it holds |
|---|---|
|
The registry of recording sites, one row each |
|
The registry of events GuPPy aligned to, one row each |
|
One derived trace — control fit, ΔF/F or z-score — for one recording site |
|
Detected transient peaks for one recording site and trace type |
|
Per-session transient frequency and mean amplitude |
|
A peri-event PSTH for one recording site and trace type |
|
The peak and area-under-curve summary of a PSTH |
|
The bootstrap confidence interval and significance flags over a PSTH |
|
A peri-event cross-correlation between two recording sites |
|
The tonic signal mean over each epoch of the tonic analysis |
|
Whole-session metrics over the time bins a recording site was tiled into |
|
The behavioral covariate scores binned onto those same bins |
|
The coefficients relating a binned metric to a binned covariate |
|
The intervals kept as valid signal after artifact removal |
|
The analysis parameters the session was processed with |
A behavioral covariate needs no extension type: its scores go in as a plain NWB TimeSeries
named after the covariate, and the binned and correlation tables reference that series rather
than repeating its name.
The two registry tables are what hold this together. A GuPPy recording site is a processing-level entity — a signal and isosbestic pair collapsed into one derived trace — and every product above references its row rather than repeating its name as a string. The registry in turn points back at the rows of the acquisition’s fiber photometry table, so a z-score trace reaches the physical fiber it came from through one chain of links.
Metadata GuPPy cannot know#
An analysis output describes signals, not the apparatus that produced them. GuPPy can read your storesList.csv and tell that a session has two recording sites, each with a signal and a control channel — but not which fiber, which LED wavelength, which virus, or which animal. NWB requires that chain, and no converter can invent it.
That is what Step 6: Input Metadata exists to collect, and why it is a form rather than something derived. It is also why the same information is often identical across an entire cohort: it describes your rig and your preparation, so it is written once and reused.
When GuPPy is not the whole experiment#
One session, one file is the point. A session that also produced electrophysiology, behavioral video, or pose estimates should have all of it in that one file — but GuPPy only ever sees the photometry, so its export can only write the photometry.
The way past that is NeuroConv, the conversion library GuPPy’s own export is built on. NeuroConv provides an interface per acquisition system or analysis tool — one for GuPPy’s outputs, others for the ephys, video and tracking formats — and runs several of them into a single file. Working at that level is more effort than clicking Export to NWB, and it is the right amount of effort when the GUI’s one-session-of-photometry scope is not your experiment. Beyond the GUI links the relevant NeuroConv guides.