HERD Updates

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## HDMF 3.11.1 (Upcoming)
 
+### Enhancements
+- Added `add_ref_termset`, updated helper methods for `HERD`, and revised `add_ref` to support validations prior to populating the tables. @mavaylon1 [#968](https://github.com/hdmf-dev/hdmf/pull/968)
+
 ### Minor Improvements
 - Updated `__gather_columns` to ignore the order of bases when generating columns from the super class. @mavaylon1 [#991](https://github.com/hdmf-dev/hdmf/pull/991)
 - Improve HTML rendering of tables. @bendichter [#998](https://github.com/hdmf-dev/hdmf/pull/998)

docs/gallery/plot_external_resources.py

@@ -91,6 +91,7 @@
 # sphinx_gallery_thumbnail_path = 'figures/gallery_thumbnail_externalresources.png'
 from hdmf.common import HERD
 from hdmf.common import DynamicTable, VectorData
+from hdmf.term_set import TermSet
 from hdmf import Container, HERDManager
 from hdmf import Data
 import numpy as np
@@ -269,7 +270,7 @@ def __init__(self, **kwargs):
 ###############################################################################
 # Using the get_object_type
 # ------------------------------------------------------
-# The :py:class:`~hdmf.common.resources.HERD.get_object_entities` method
+# The :py:func:`~hdmf.common.resources.HERD.get_object_entities` method
 # allows the user to retrieve all entities and key information associated with an `Object` in
 # the form of a pandas DataFrame.
 
@@ -306,6 +307,52 @@ def __init__(self, **kwargs):
     entity_uri='https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=10090'
 )
 
+###############################################################################
+# Using add_ref_termset
+# ------------------------------------------------------
+# :py:class:`~hdmf.common.resources.HERD` has multiple ways for users to add
+# external references. The :py:func:`~hdmf.common.resources.HERD.add_ref_termset`
+# method allows users to not only validate terms, i.e., keys, but also adds the
+# ability to iteratively add references for entire datasets, lists, arrays, etc.
+
+# The :py:func:`~hdmf.common.resources.HERD.add_ref_container` method is directly
+# used for populating :py:class:`~hdmf.common.resources.HERD` when writing a file.
+# :py:func:`~hdmf.common.resources.HERD.add_ref_termset` can be used for new files;
+# however, it is also the best practice when adding references for existing files.
+
+# :py:func:`~hdmf.common.resources.HERD.add_ref_termset` has many optional fields,
+# giving the user a range of control when adding references. Let's see an example.
+er = HERD()
+terms = TermSet(term_schema_path='example_term_set.yaml')
+file = HERDManagerContainer(name='file')
+
+er.add_ref_termset(file=file,
+                   container=species,
+                   attribute='Species_Data',
+                   key='Ursus arctos horribilis',
+                   termset=terms)
+
+###############################################################################
+# Using add_ref_termset for an entire dataset
+# ------------------------------------------------------
+# As mentioned above, :py:func:`~hdmf.common.resources.HERD.add_ref_termset`
+# supports iteratively validating and populating :py:class:`~hdmf.common.resources.HERD`.
+
+# When populating :py:class:`~hdmf.common.resources.HERD`, users may have some terms
+# that are not in the :py:class:`~hdmf.term_set.TermSet`. As a result,
+# :py:func:`~hdmf.common.resources.HERD.add_ref_termset` will return an all the missing
+# terms in a dictionary. It is up to the user to either add these terms to the
+# :py:class:`~hdmf.term_set.TermSet` or remove them from the dataset.
+
+er = HERD()
+terms = TermSet(term_schema_path='example_term_set.yaml')
+file = HERDManagerContainer(name='file')
+
+er.add_ref_termset(file=file,
+                   container=species,
+                   attribute='Species_Data',
+                   termset=terms)
+
 ###############################################################################
 # Write HERD
 # ------------------------------------------------------

docs/gallery/plot_term_set.py

@@ -190,3 +190,6 @@
 # To add a column that is validated using :py:class:`~hdmf.term_set.TermSetWrapper`,
 # wrap the data in the :py:func:`~hdmf.common.table.DynamicTable.add_column`
 # method as if you were making a new instance of :py:class:`~hdmf.common.table.VectorData`.
+species.add_column(name='Species_3',
+                   description='...',
+                   data=TermSetWrapper(value=['Ursus arctos horribilis', 'Mus musculus'], termset=terms),)

src/hdmf/backends/io.py

@@ -89,8 +89,8 @@ def write(self, **kwargs):
                 from hdmf.common import HERD
                 herd = HERD(type_map=self.manager.type_map)
 
-            # add_ref_term_set to search for and resolve the TermSetWrapper
-            herd.add_ref_term_set(container) # container would be the NWBFile
+            # add_ref_container to search for and resolve the TermSetWrapper
+            herd.add_ref_container(container) # container would be the NWBFile
             # write HERD
             herd.to_zip(path=self.herd_path)