Add edge-safe event spectrogram workflows - #7
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Adds an “edge-safe” event-centred spectrogram workflow that retains a precise target window while reading extra STFT-only context, trims back to the requested interval, and then normalizes after trimming so discarded context can’t influence retained dB values. This is exposed via Python, CLI flags, and updated docs/tutorials, with new regression tests.
Changes:
- Add
SpectrogramGenerator.process_event()and move relative-dB normalization to occur after clip trimming. - Extend
scripts/generate_spectrograms.pywith--event-timeand related event padding flags. - Export a public downloader API from
onc_hydrophone_data.dataand refresh docs/notebook/tutorial materials accordingly.
Reviewed changes
Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_spectrogram_generator.py | Adds regression coverage for event-centred STFT context + trim-then-normalize behavior and input validation. |
| tests/test_hydrophone_downloader.py | Updates imports to use the new public onc_hydrophone_data.data API surface. |
| scripts/generate_spectrograms.py | Adds CLI event workflow flags and routes --event-time to process_event(). |
| README.md | Mentions the new event-centred spectrogram capability in the feature list. |
| onc_hydrophone_data/data/init.py | Introduces a public re-export surface for downloader APIs and helpers. |
| onc_hydrophone_data/audio/spectrogram_generator.py | Implements process_event(), adds output_stem, and changes normalization ordering to happen after trimming. |
| notebooks/ONC_Data_Download_Tutorial.ipynb | Reorganizes tutorial flow to lead with audio→local spectrogram workflow and introduces event-safe mode. |
| docs/quickstart.md | Clarifies the “audio first” workflow and links to ONC server-product guidance. |
| docs/onc_spectrogram_options.md | Reframes guidance to help users choose between local vs ONC spectrogram workflows. |
| docs/index.md | Updates landing page to present both workflows and links to edge-safe local event section. |
| docs/downloads.md | Clarifies JSON/CSV workflow distinctions (ONC products vs local generation). |
| docs/custom_spectrograms.md | Documents the new process_event() and CLI event mode, plus edge-context semantics. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+730
to
+732
| base_name = Path(output_stem).name if output_stem else audio_path.stem | ||
| if not base_name or base_name in {'.', '..'}: | ||
| raise ValueError("output_stem must contain a valid filename stem") |
Comment on lines
+682
to
+686
| if args.event_time is not None: | ||
| if is_directory: | ||
| raise ValueError("--event-time requires --input-file") | ||
| if args.clip_start is not None or args.clip_end is not None: | ||
| raise ValueError("--event-time cannot be combined with --clip-start/--clip-end") |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Why
Clipping exactly at an event interval can leave incomplete STFT windows at its boundaries. The new workflow reads extra computation-only context, trims back to the requested interval, and normalizes after trimming so discarded context cannot affect retained values.
User impact
Users can generate spectrograms around known signal times from Python, the CLI, or JSON with sensible defaults, clear metadata, and documented edge handling.
Validation
57 passed, 2 deselectedmkdocs build --strictgit diff --check