Time synchronization

Time synchronization puts recordings from the same experiment on one shared clock. You can play a behavior video beside calcium or electrophysiology traces, scrub every source together, and inspect the measured alignment quality without changing the original files.

Quick start

1. Select the recordings in Data

   Open Data and select at least two files from the same experiment.

   • Hold Command on macOS or Ctrl on Windows and Linux to select individual files.
   • Hold Shift to select a continuous range.

2. Open the synchronized viewer

   Right-click any file in the selection and choose Open synchronized viewer. When every selected file is supported, Relay opens one Viewer for the synchronized sources and a separate Controls window.

   To synchronize everything in a folder, right-click the folder and choose the same command. Relay scans the folder and its nested folders, including folders you have not expanded yet.

3. Review files when Relay finds a mixed group

   Folder scans and selections containing unsupported files open a review in the Data window. Check the compatible and skipped counts, inspect why each file was skipped, then choose the Open files action. Notes, PDFs, and other unrelated files remain untouched and are not sent to the Viewer.

   If fewer than two compatible files remain, the open action stays unavailable. Choose Cancel, add another timed recording, and try again. If a connected folder cannot be read, check the storage connection and use Try again.

   A normal double-click still opens each selected file separately. It never creates a synchronized Viewer.

4. Choose a reference clock

   In Controls → Align, choose the source that should define shared time. Every other source is mapped to this reference. Relay does not resample or modify the files.

5. Choose an alignment method

   Select Use acquisition clocks, Match sync pulses, or Match moments manually. The available evidence in your recordings determines which method is appropriate.

6. Align and review

   Select Align and save, then open Quality to review error, drift, matched points, and rejected points for each source.

Choose an alignment method

Use Use acquisition clocks when every source declares an absolute acquisition time, such as an NWB session start time or an absolute timestamp column.

Relay uses the declared clocks to calculate the offset. It will not assume that unrelated relative time axes both starting at 0 share a clock.

Tip

This is the simplest method when all acquisition systems were synchronized to the same computer or hardware clock.

Use Match sync pulses when each acquisition system recorded the same TTL, trigger, strobe, or frame-pulse train.

Relay pairs the event trains, fits both time offset and clock drift, and rejects isolated outlier matches. Each non-reference source needs at least two matching events. Three or more events are needed for an independent residual-quality measurement.

Tip

Distribute one hardware pulse to the imaging, electrophysiology, and behavior systems whenever possible. Pulses spread across the full recording produce a better drift estimate than pulses clustered at the beginning.

Use Match moments manually when the files do not contain a shared clock or pulse channel.

1. Choose a non-reference source.
2. Find one recognizable event in that source and enter its local time.
3. Enter the time of the same event in the reference source.
4. Select Add anchor and repeat for other sources or moments.

One anchor determines an offset. Two anchors can estimate drift. Use at least three well-spaced anchors when you want Relay to measure residual error instead of only fitting the supplied points.

Info

Useful manual anchors include the onset of wheel movement, a visible LED flash, stimulus delivery, or another event captured by both systems.

Supported timing sources

Video

MP4, MOV, AVI, WebM, and MKV recordings. Relay reads video duration and uses absolute clocks or sync events when the file metadata provides them. Otherwise, use manual anchors.

NWB and HDF5

ElectricalSeries and RoiResponseSeries data, including sample rate, starting time, channel count, and sync-like NWB intervals. Large Relay Drive files are range-streamed instead of downloaded in full.

CSV and TSV

Tables with a time column such as time, timestamp, seconds, or frame_time. Columns named like ttl, sync, trigger, clock, or frame_pulse are detected as pulse channels.

Suite2p and NumPy

Suite2p traces such as F.npy, Fneu.npy, and spks.npy. The trace needs a declared frameRate or fps in its Relay processing metadata. A processed NWB export can carry the timing information with the trace.

Imaging metadata

Metadata-backed calcium imaging and OME-Zarr sources can expose frame timestamps, frame rate, duration, and sync events without downloading an entire directory.

JSON events

JSON files can provide timestamps, sync events, frame or sample rate, duration, and absolute acquisition start time.

Warning

A sample rate describes spacing between samples; it does not prove that two files share a start time. Use an absolute acquisition clock, shared sync pulses, or manual anchors to establish the relationship between recordings.

Use the synchronized Viewer

The Viewer gives every selected source the same playhead:

• Play or pause all aligned recordings from the shared transport.
• Drag Shared time to inspect a specific moment across every source.
• Read each tile’s local source time, offset, and clock drift.
• View a synchronized video or a bounded signal preview for tabular, calcium, and electrophysiology data.
• Use the availability bars below the transport to see where each source contains data. A tile shows No data when the shared playhead falls outside that source’s time range.

Playback remains disabled until every selected source has a valid transform.

Read alignment quality

Open Controls → Quality after alignment. Relay reports measured values rather than estimated confidence labels.

Measurement	What it means
RMS error	Typical timing difference between matched events and the fitted clock model
Max error	Largest timing difference among the points used in the fit
Clock drift	Relative clock-rate difference in parts per million (ppm)
Matched points	Events or anchors used to fit the source clock
Rejected points	Outlier event matches excluded from the final fit

Quality grades are a prompt to inspect the measurements, not a substitute for experimental judgment:

• Excellent — low residual error and low drift with enough matched points to measure both.
• Good — usable residual error or drift, but not within the strictest thresholds.
• Review — limited evidence, large residual error, or high drift. One- and two-point fits always require review because their residual can be exactly zero without independently validating the fit.

Example workflows

GCaMP imaging with an MEA

1. Select the calcium trace source and the MEA NWB recording in Data.
2. Right-click either selected file and choose Open synchronized viewer.
3. Choose the MEA or imaging acquisition as the reference.
4. Use Match sync pulses if both systems recorded the same TTL train.
5. Align, inspect residual error and drift, then use the shared playhead to compare calcium activity with electrical spikes.

Mouse behavior video with neural activity

1. Select the behavior video, wheel-velocity table, and neural recording.
2. Open them together and choose the neural recording as the reference.
3. Match a shared trigger train. If no trigger was recorded, add manual anchors for visible or recorded events such as movement onset or an LED flash.
4. Scrub the shared time control to compare movement, video, and neural activity.

Ask Ray to set up alignment

You can also ask Ray from the prompt bar. Ray uses the same alignment engine and quality measurements as the Controls window.

Try prompts such as:

• “Open my selected files together for time synchronization.”
• “Use the MEA recording as the reference and align these sources from their TTL pulses.”
• “Show me the alignment quality and flag any source that needs review.”
• “Add a manual anchor mapping 12.4 seconds in the behavior video to 10.8 seconds in the NWB recording.”

Ray will refuse to align sources when the selected method lacks enough timing evidence. Ask it to read the source clocks if you want to see the detected timestamps, sync-event counts, sample rates, and errors before aligning.

Troubleshooting

A source says it is not ready

Open Align and read the source message. Confirm the format exposes a time axis. CSV and TSV files need a recognized time column or sampling rate; Suite2p arrays need frame-rate metadata.

No compatible acquisition clock

The files do not all declare absolute start times. Choose Match sync pulses when they share recorded triggers, or Match moments manually.

Not enough matching sync events

Confirm that both the reference and source contain at least two edges from the same pulse train. Check channel names and make sure the pulse signal crosses between low and high values.

The result needs review

Inspect matched and rejected points. Add more well-spaced pulses or manual anchors, verify that the same physical events were matched, and repeat the alignment.

Playback is disabled

Every source that passed review must load and align successfully. Return to Data and reopen the group to inspect source errors or exclude a recording that does not expose usable timing.

Info

Alignment settings, source summaries, transforms, and quality measurements are saved with the workspace. Temporary media URLs and expiring download links are not saved; Relay securely resolves the original files again when the workspace reloads.