Skip to content

Show how to inspect HERD after reading in the tutorial#1535

Open
rly wants to merge 1 commit into
devfrom
worktree-docs+1325-herd-read-tutorial
Open

Show how to inspect HERD after reading in the tutorial#1535
rly wants to merge 1 commit into
devfrom
worktree-docs+1325-herd-read-tutorial

Conversation

@rly

@rly rly commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Motivation

Resolves #1325.

The external resources tutorial's "Read HERD" section only called HERD.from_zip(...) and then deleted the zip, showing nothing about how to access the data. Combined with a read HERD rendering with empty collapsibles in Jupyter, this left users unsure how to get at the references they had just loaded.

The Jupyter rendering half of the issue was already addressed in #1510 (HERD.__repr__/_repr_html_ now surface a flattened references table). This PR fills the documentation gap.

Changes

  • Expand the "Read HERD" section of docs/gallery/plot_external_resources.py into an "Inspect the data after reading" walkthrough that demonstrates:
    • to_dataframe() for the flattened, one-row-per-association view,
    • the six interlinked tables via .to_dataframe(),
    • get_object_entities(file=..., container=...) for single-object lookup.
  • Note in the comments what the Jupyter display shows after Add HERD repr/_repr_html_ surfacing references as a flattened table #1510, so a read HERD is no longer perceived as empty.
  • Add a CHANGELOG entry.

This mirrors the reading/inspection section added to the pynwb tutorial in NeurodataWithoutBorders/pynwb#2200.

Verification

  • The full tutorial script runs end-to-end (exit 0).
  • The new read section returns non-empty data: to_dataframe() yields 2 rows and get_object_entities yields 2 rows.
  • ruff check and pre-commit hooks pass.

🤖 Generated with Claude Code

Expand the "Read HERD" section of the external resources tutorial to
demonstrate accessing a HERD after HERD.from_zip, using to_dataframe,
the interlinked tables, and get_object_entities, so a read HERD no
longer appears empty and inaccessible.

Resolves #1325

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jul 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.22%. Comparing base (c647ace) to head (96ace94).

Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #1535   +/-   ##
=======================================
  Coverage   93.22%   93.22%           
=======================================
  Files          41       41           
  Lines       10204    10204           
  Branches     2106     2106           
=======================================
  Hits         9513     9513           
  Misses        414      414           
  Partials      277      277           

☔ 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.

@rly rly requested a review from oruebel July 8, 2026 04:34
@rly rly enabled auto-merge (squash) July 8, 2026 04:35
@rly rly disabled auto-merge July 8, 2026 04:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Documentation]: I don't understand how to read HERD

1 participant