[Enhancement]: Create HDMF_File, Update tests that use HERD, Update HERD Documentation, Add check for container and file

[mavaylon1]

What would you like changed or added to the documentation and why?

To more realistically simulate the workflow a user would have (from a PyNWB standpoint), we should create a HDMF_File. This will allow general testing for future HDMF version, but more specifically to HERD:

• Add check that the container is in the file (when the file is provided as a field).
• Add test for the file check would require a large overall on setting parents to containers. It would be easier to just create this HDMF_FIle and update the tests suite accordingly
• Update the documentation

Update HERD documentation to use the following suggestion:

I also think we should change the examples/tutorial to be more realistic. Right now, you create a HERDManagerContainer object to represent a file, but in the later examples, the file object and the file of the data object do not match each other, and I think that is confusing.

# Class to represent a file
class HERDManagerContainer(Container, HERDManager):
    def __init__(self, **kwargs):
        kwargs['name'] = 'HERDManagerContainer'
        super().__init__(**kwargs)

Instead, I suggest using a SimpleMultiContainer as the base for the file, and in each example, create a new file, create a new data object, and add the data object to the file before using it:

# Class to represent a file
from hdmf.common import SimpleMultiContainer
class HdmfFile(SimpleMultiContainer, HERDManager):
    def __init__(self, **kwargs):
        kwargs['name'] = 'SimpleMultiContainer'
        super().__init__(**kwargs)

...

file = HdmfFile()
species = DynamicTable(name='species', description='My species', columns=[col1])
file.add_container(species)

Then in the examples, the file argument does not need to be passed because it can be retrieved from the data object.

er.add_ref_termset(
	container=species,
	attribute='Species_Data',
	key='Ursus arctos horribilis',
	termset=terms
)

This is a more realistic use case, in my opinion. This structure also has the advantage of making the code examples being more standalone / not dependent on earlier objects, except for the definition of HdmfFile.

All of this would help make this tutorial more analogous to its use in PyNWB, so that we could copy and paste relevant parts of this tutorial to create a PyNWB tutorial with minimal modifications, e.g., HdmfFile -> NWBFile. add_container -> add_acquisition. Perhaps all of this should be a separate PR though. Up to you. Happy to help with these suggested changes.

Do you have any interest in helping write or edit the documentation?

Yes.

[mavaylon1]

Note: I will tackle this in January 2024