Skip to content

Add AI4EPS event format reader - #846

Merged
d-chambers merged 4 commits into
devfrom
ai4eps-reader
Aug 10, 2026
Merged

Add AI4EPS event format reader#846
d-chambers merged 4 commits into
devfrom
ai4eps-reader

Conversation

@d-chambers

@d-chambers d-chambers commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Description

Second PR of the format-reader series (after #844). Adds a FiberIO reader for the AI4EPS earthquake DAS event HDF5 format, used by the quakeflow_das dataset (MIT licensed; the registered ai4eps_1.h5 test file is a trimmed excerpt of event ci37280444 windowed around the P arrival).

Layout: a single data dataset of shape (channel, time) whose attrs carry acquisition metadata (begin_time/end_time tz-aware ISO with an exclusive-stop convention, dt_s, dx_m, unit) and event metadata. Notes:

  • Detection requires the full attr structure including event_id (via h5_matches_structure) so generic files that happen to carry timing attrs are not claimed; a near-miss negative test pins this.
  • Event metadata lands as typed patch attrs: event_id, event_time, magnitude, magnitude_type, event_latitude/event_longitude/event_depth_km (prefixed to avoid colliding with instrument coordinates).
  • The reader warns when a file's end_time disagrees with begin_time + n * dt_s (beyond half a sample) instead of silently inventing timing.
  • Times are normalized to naive UTC; distance is channel index × dx_m.

Changelog

  • added: the AI4EPS format for AI4EPS earthquake DAS event files (e.g. quakeflow_das), including event id, time, magnitude, and hypocenter as patch attrs.

Checklist

I have (if applicable):

  • referenced the GitHub issue this PR closes. (n/a — part of the format-reader series)
  • documented the new feature with docstrings and/or appropriate doc page.
  • included tests. See testing guidelines.
  • added the "ready_for_review" tag once the PR is ready to be reviewed.

Summary by CodeRabbit

  • New Features

    • Added support for reading AI4EPS V1 earthquake DAS event HDF5 files.
    • Supports optional time and distance filtering during import.
    • Preserves event metadata, including event ID, origin time, magnitude, and hypocenter details.
    • Validates timing, coordinates, and measurement units during import.
    • Added the AI4EPS sample dataset to the available data registry.
  • Documentation

    • Documented AI4EPS fiber I/O support in the changelog.

@coderabbitai

coderabbitai Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This change adds AI4EPS event HDF5 support. It defines event metadata, reads selected data, registers the formatter and sample dataset, and adds tests and changelog documentation.

Changes

AI4EPS reader integration

Layer / File(s) Summary
AI4EPS format parsing
dascore/io/ai4eps/__init__.py, dascore/io/ai4eps/utils.py, dascore/io/ai4eps/core.py
Defines AI4EPS event attributes, format detection, UTC timestamps, coordinates, metadata extraction, scanning, and optional time and distance trimming.
Plugin and fixture registration
pyproject.toml, dascore/data_registry.txt
Registers AI4EPS__V1 and the ai4eps_1.h5 dataset.
Validation and documentation
tests/test_io/test_ai4eps/test_ai4eps.py, tests/test_io/test_common_io.py, docs/changelog.qmd
Adds AI4EPS-specific tests, common I/O coverage, removal of an obsolete skipped fixture, and changelog documentation.

Possibly related PRs

  • DASDAE/dascore#595: Adds a similar HDF5 fiber I/O format with registry, formatter, entry point, and common I/O test integration.
  • DASDAE/dascore#848: Adds another HDF5 fiber I/O reader with utilities, registration, fixtures, and tests.

Suggested labels: IO, documentation

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely identifies the main change: adding an AI4EPS event format reader.
Description check ✅ Passed The description explains the feature, format details, design decisions, documentation, tests, and checklist status.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ai4eps-reader

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot added documentation Improvements or additions to documentation IO Work for reading/writing different formats labels Aug 8, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/test_io/test_ai4eps/test_ai4eps.py`:
- Around line 82-93: Update test_near_miss_not_claimed to add a valid end_time
attribute while keeping event_id absent, so the fixture satisfies other metadata
requirements and independently verifies that AI4EPSV1().get_format rejects files
without event metadata.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d12f2ec5-0658-4473-9bac-4579a02758f6

📥 Commits

Reviewing files that changed from the base of the PR and between 80116a2 and ce825e2.

📒 Files selected for processing (8)
  • dascore/data_registry.txt
  • dascore/io/ai4eps/__init__.py
  • dascore/io/ai4eps/core.py
  • dascore/io/ai4eps/utils.py
  • docs/changelog.qmd
  • pyproject.toml
  • tests/test_io/test_ai4eps/test_ai4eps.py
  • tests/test_io/test_common_io.py

Comment thread tests/test_io/test_ai4eps/test_ai4eps.py
@d-chambers
d-chambers force-pushed the ai4eps-reader branch 2 times, most recently from 7ed746f to a720bc6 Compare August 8, 2026 20:28
@codecov

codecov Bot commented Aug 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (3cd0731) to head (38a6603).
⚠️ Report is 1 commits behind head on dev.

Additional details and impacted files
@@            Coverage Diff            @@
##               dev      #846   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          167       170    +3     
  Lines        18290     18374   +84     
=========================================
+ Hits         18290     18374   +84     
Flag Coverage Δ
network 48.85% <94.04%> (+0.21%) ⬆️
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown

✅ Documentation built:
👉 Download
Note: You must be logged in to github and a DASDAE member to access the link.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
dascore/io/ai4eps/utils.py (1)

44-50: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Narrow the exception handling in _safe_units.

The handler catches every Exception from get_quantity. This prevents scans from failing on malformed units, but it can also hide unexpected failures and silently remove data_units. Catch only the unit-parse exceptions used by this project, or isolate the scan-only fallback from the read path. Verify the exact exception types before narrowing.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dascore/io/ai4eps/utils.py` around lines 44 - 50, Update _safe_units to catch
only the specific unit-parsing exception types raised by get_quantity in this
project, verifying those types from the parser implementation or existing
callers. Preserve returning None for malformed units, while allowing unexpected
exceptions to propagate instead of silently dropping data_units.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@dascore/io/ai4eps/utils.py`:
- Around line 44-50: Update _safe_units to catch only the specific unit-parsing
exception types raised by get_quantity in this project, verifying those types
from the parser implementation or existing callers. Preserve returning None for
malformed units, while allowing unexpected exceptions to propagate instead of
silently dropping data_units.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e6c0b1a-ab94-4b7b-a513-8ae4b8362a13

📥 Commits

Reviewing files that changed from the base of the PR and between ce825e2 and c80769d.

📒 Files selected for processing (2)
  • dascore/io/ai4eps/utils.py
  • tests/test_io/test_ai4eps/test_ai4eps.py

@d-chambers

Copy link
Copy Markdown
Contributor Author

Re the nitpick on _safe_units catching broad Exception: kept intentionally — the units attr is arbitrary user/vendor text and pint's failure modes span UndefinedUnitError (an AttributeError subclass), DimensionalityError, DefinitionSyntaxError, TypeError, and ValueError depending on input; a units string must never be able to abort a directory scan. The function does nothing besides the one get_quantity call, so the catch can't mask unrelated logic errors.

Adds a FiberIO reader for the AI4EPS earthquake DAS event HDF5 format
(e.g. the quakeflow_das dataset): a single 'data' dataset whose attrs
carry acquisition metadata (begin_time, dt_s, dx_m, unit) and event
metadata, which lands on the patch as typed attrs (event_id, event_time,
magnitude, hypocenter). Detection requires the full attr structure
including event_id so generic files with timing attrs are not claimed.
The Carina reader (#849) now claims this file but merged without
removing the skip entry, so its common IO tests were silently skipped.
@d-chambers
d-chambers merged commit db17511 into dev Aug 10, 2026
19 checks passed
@d-chambers
d-chambers deleted the ai4eps-reader branch August 10, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation IO Work for reading/writing different formats

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant