Add Convenience Wrapper and Documentation for External Behavioral Timestamp Import

[pauladkisson]

Summary

Importing behavioral event timestamps from external sources — video tracking software, manually scored behavioral spreadsheets, or microcontroller logs — into GuPPy's CSV timestamp format is technically possible but undocumented and requires manual reformatting. A how-to guide and a convenience wrapper function would lower this barrier, enabling labs to align PSTH analyses to derived behavioral events (velocity onset, behavioral scoring) without writing custom data wrangling code.

Motivation

• The Nelson lab aligns photometry signals to two types of external events that are not raw TTLs:
  • Velocity-derived events: they detect movement onset/offset by thresholding a velocity trace computed from video tracking, and use those timestamps as PSTH alignment points
  • Manually scored behavioral events: a scientist watches video and records timestamps of specific behaviors (e.g., a particular motor behavior in a Parkinson's model), producing a column of numbers in a spreadsheet
• Alexandra Nelson confirmed both sources are currently handled in MATLAB and then re-aligned post-hoc — the lab would like to do this within GuPPy
• Venus confirmed this is technically supported by feeding a timestamp CSV to the existing pipeline, but the required format and file naming convention are not documented anywhere visible to users
• Xiaowen Zhuang also raised the case of behavioral data stored in Excel files from a microcontroller system; she wants to incorporate those into both the analysis and the eventual NWB export
• The gap is usability and discoverability, not pipeline capability

Proposed Solution

• Write a how-to guide (in the GitHub wiki, consistent with the existing documentation pattern referenced in the README) covering:
  • The required CSV column structure for timestamp files that GuPPy recognizes
  • How to name the file and where to place it in the session folder
  • A worked example converting manually scored timestamps from Excel to a valid GuPPy timestamp CSV
• Add a guppy.utils.import_timestamps module with keyword-only functions that accept common input forms and write a correctly-structured timestamp CSV to the session folder:
  • A pandas DataFrame with a timestamp column
  • An Excel file path with a configurable column name
  • A plain Python list or NumPy array of timestamps (in seconds)
• The module should validate inputs: timestamps are numeric, within the recording duration if duration is known, and produce clear error messages for common mistakes (wrong column name, mixed units)
• Expose the wrapper in src/guppy/testing/api.py alongside the existing step1 through step5 functions for programmatic workflow use

Open Questions

• Which external formats should be supported in a first version? At minimum: Excel (.xlsx), plain CSV with a named timestamp column, and raw Python list/array. Are there specific tracking software output formats the Nelson lab uses (e.g., DeepLabCut, SLEAP, Bonsai) that would benefit from dedicated readers?
• Should the wrapper optionally handle converting a continuous behavioral signal (e.g., a velocity trace with timestamps) into threshold-crossing event timestamps automatically? This would be genuinely useful for the velocity onset use case, but adds scope
• Where should the how-to documentation live — the GitHub wiki (current pattern), a docs/ folder added to the repo, or inline in the README?
• Should there be a GUI component for this (e.g., a file picker for behavioral data files), or is a programmatic API sufficient for a first version given that the target users are comfortable with Python?
• How should the imported timestamps be named/labeled so they appear with meaningful names (rather than a generic label) in PSTH outputs and eventual NWB export?