Skip to content

docs(tutorials): add a tutorial for external resource references - #885

Open
ehennestad wants to merge 4 commits into
add-herd-user-apifrom
herd-tutorial
Open

docs(tutorials): add a tutorial for external resource references#885
ehennestad wants to merge 4 commits into
add-herd-user-apifrom
herd-tutorial

Conversation

@ehennestad

@ehennestad ehennestad commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Motivation

Add a tutorial for the HERD API, mirroring the PyNWB external resources tutorial so a reader can move between the two APIs.

Preview tutorial on ReadTheDocs:
https://matnwb--885.org.readthedocs.build/en/885/pages/tutorials/externalResources.html

What changed

  • tutorials/externalResources.mlx records and reads back external resource references on a file it builds itself: a subject's species, and a column of an electrodes table.
  • The tutorial has a page under General Tutorials.

Storing a HERD outside a file is left out, because to_zip and from_zip are not implemented in MatNWB.

How to test

nwbtest('Name', 'tests.system.tutorial.TutorialTest')

Todo

  • Verify and approve PRs below in stack
  • Verify tutorial is clear to follow and covers relevant parts of API

Checklist

  • Have you ensured the PR description clearly describes the problem and solutions?
  • Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
  • If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Claude Code

@ehennestad

Copy link
Copy Markdown
Collaborator Author

Pass the table as the object and the column name as Attribute. The reference is attached to the column itself, which is the object that holds the values, rather than to the table. A ragged column works the same way: Attribute names the column holding the values, and the index that groups them into rows is a separate property.

The last half of this paragraph is unclear - Either improve or drop it completely (The main point here is that the column itself is added as an attribute, not an index column)

@ehennestad
ehennestad marked this pull request as ready for review September 1, 2026 11:52
@codecov

codecov Bot commented Sep 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.36%. Comparing base (0995f9e) to head (0b4c7ae).

Additional details and impacted files
@@                Coverage Diff                 @@
##           add-herd-user-api     #885   +/-   ##
==================================================
  Coverage              95.36%   95.36%           
==================================================
  Files                    237      237           
  Lines                   8660     8660           
==================================================
  Hits                    8259     8259           
  Misses                   401      401           

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

ehennestad and others added 4 commits September 1, 2026 16:39
Walk through annotating values in a file with HERD: create a file,
record what a subject's species refers to in the NCBI Taxonomy, annotate
a column of an electrodes table with a brain region, read the
annotations back, and write and reload the file.

Follows the PyNWB external resources tutorial, so a reader can move
between the two APIs, and covers the same ground except for storing a
HERD outside a file, which MatNWB does not support yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Give the tutorial a page under General Tutorials, following the layout
the other tutorial pages use: a link to open it in MATLAB Online, a link
to the full page, and the exported HTML embedded in the page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Run matnwb_exportTutorials for the new tutorial, which stores its
outputs in the live script, writes the HTML the documentation page
embeds, and writes the plain code listing alongside the other tutorials.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Point each mention of HERD and Subject at its type documentation, so a
reader can look up what the type holds without leaving the tutorial.

Re-export the tutorial so the embedded HTML and the code listing match.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.

1 participant