Add guide on choosing entity_id and entity_uri for HERD references#192
Add guide on choosing entity_id and entity_uri for HERD references#192bendichter wants to merge 2 commits into
Conversation
Moves the reference page proposed in pynwb#2206 into nwb-overview. It documents how to pick entity_id (a CURIE whose prefix is registered with bioregistry.io) and entity_uri (the resolved canonical URL) when adding external resource references with HERD.add_ref, including a table of commonly used registries and a fallback for resources without per-term URLs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| .. _external_resources_entity_guide: | ||
|
|
||
| Choosing ``entity_id`` and ``entity_uri`` for external references | ||
| ================================================================= |
There was a problem hiding this comment.
Since nwb-overview is an entry-point for users, I think it would be useful if we could transform this page a bit more intro an entry-point for users to the concept of External Resources. The current content is great, and I think a few basic changes would suffice to start to push the page in that direction:
- Add a page heading "Using External Resources" or maybe "Using Ontologies and Identifiers with NWB" since new users may not know what the term External Resources means
- Add a brief intro paragraph to describe what External Resources are and why this is useful
- Add a paragraph (or subsection) on how to use external resources with links to the corresponding tutorials in PyNWB
If those changes would hold up this PR (e.g., require further discussion) then I think it's perfectly fine to also just create a follow-up issue and address this in a separate PR.
oruebel
left a comment
oruebel
left a comment
There was a problem hiding this comment.
The content looks good. Just a small suggestion to make the page a bit more friendly for users who have not used external resources before.
Add a top-level "Using Ontologies and Identifiers with NWB" heading, an intro explaining what external resources are and why they are useful, and a "How to add external resources to an NWB file" section linking to the HDMF HERD and TermSet tutorials and PyNWB's term-validation tutorial. The existing entity_id/entity_uri guidance becomes a section beneath it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
This looks great. Thanks @bendichter . Can we close the issue in pynwb with this guide? Also we should update this guide to point to the NWB-specific tutorial in NeurodataWithoutBorders/pynwb#2200 once it's released. |
| attribute="location", | ||
| key="area_42", | ||
| entity_id="42", | ||
| entity_uri="https://afni.nimh.nih.gov/pub/dist/atlases/macaque/D99_macaque/", |
There was a problem hiding this comment.
This URI doesn't resolve
| entity_uri="https://afni.nimh.nih.gov/pub/dist/atlases/macaque/D99_macaque/", | |
| entity_uri="https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/nonhuman/macaque_tempatl/atlas_d99v2.html", |
3 participants
Motivation
Moves the reference page proposed in NeurodataWithoutBorders/pynwb#2206 into nwb-overview, where cross-API user guidance lives.
Users adding external resource references with
HERD.add_refneed clear guidance on what to put in theentity_idandentity_urifields, which is currently undocumented and was a recurring point of confusion (e.g. which of the manyNCBITaxon/taxonomy/NCBI_TAXONforms to use, and what to do for atlases without per-term URLs).What this adds
A narrative reference page (
docs/source/external_resources_entity_guide.rst), added to the For Users toctree, that documents:entity_idshould be a CURIE (prefix:identifier) whose prefix is registered with bioregistry.io. The Bioregistry maps each CURIE to a canonical, resolvable URL and disambiguates overlapping identifier schemes.entity_urishould be the URL the CURIE resolves to, which you can look up viahttps://bioregistry.io/<entity_id>.NCBITaxon,ROR,ORCID,UBERON,MBA,HBA,DANDI) with verified exampleentity_id→entity_uripairs and the common NWB fields each applies to.entity_uriand the term's atlas-specific ID inentity_id.Notes
hdmf.common.resources.HERD/add_refresolve via the existing hdmf intersphinx mapping inconf_extlinks.py.entity_urivalues are inline literals (not hyperlinks); only the two stable homepages (bioregistry.io, the W3C CURIE spec) are linked.🤖 Generated with Claude Code