Examples of how to use PyNWB in certain I/O scenarios

io_scenarios.py

import pynwb

foo_ext_path = 'foo.namespace.yaml' # custom extension
foo_nwb_path = 'foo.nwb'            # file using custom extension
bar_ext_path = 'bar.namespace.yaml' # another custom extension
bar_nwb_path = 'bar.nwb'            # file using this other custom extension
baz_nwb_path = 'baz.nwb'            # file with no extensions

############ READ #############

# 1 - Read from an NWB file, loading two extensions
io = pynwb.NWBHDF5IO(foo_nwb_path, ext=[foo_ext_path, bar_nwb_path], mode='r')
foo_nwb = io.read()
# ...
io.close()

# 2 - read a file without extensions
io = pynwb.NWBHDF5IO(baz_nwb_path, mode='r')
baz_nwb = io.read()
# ...
io.close()

# 3 - Read from an NWB file using extensions of in-memory
#     classes defined in another module
import barnwb # load extensions classes i.e. NWBContainer subclasses
io = pynwb.NWBHDF5IO(bar_nwb_path, ext=[foo_nwb_path, barnwb.get_type_map()], mode='r')
bar_nwb = io.read()
# ...
io.close()

# 4 - Read from two files that instantiate different specifications
#     but the namespaces have the same name
foo_io = pynwb.NWBHDF5IO(foo_nwb_path, ext=foo_ext_path, mode='r')
foo_nwb = foo_io.read()
bar_io = pynwb.NWBHDF5IO(bar_nwb_path, ext=bar_ext_path, mode='r')
bar_nwb = bar_io.read()
# ...
foo_io.close()
bar_io.close()

############ WRITE #############

# 1 - Write an NWB file with no extensions
nwbfile = pynwb.NWBFile(...)
# ...
io = pynwb.NWBHDF5IO(baz_nwb_path, mode='w')
io.write(nwbfile)
io.close()

# 2 - Alternative to write an NWB file with no extensions
nwbfile = pynwb.NWBFile(...)
# ...
pynwb.to_hdf5(nwbfile, baz_nwb_path)

# 3 - Write an NWB file with extensions that have in-memory classes
#     defined in a separate module
import foonwb # load extensions classes i.e. NWBContainer subclasses
nwbfile = pynwb.NWBFile(...)
# ... add a class from foonwb
io = pynwb.NWBHDF5IO(foo_nwb_path, ext=foonwb.get_type_map(), mode='w')
io.write(nwbfile)
io.close()

# 4 - Alternative to Write an NWB file with extensions that
#     have in-memory classes defined in a separate module
import foonwb # load extensions classes i.e. NWBContainer subclasses
nwbfile = pynwb.NWBFile(...)
# ... add a class from foonwb
pynwb.to_hdf5(foo_nwb_path, ext=foonwb.get_type_map())

# 5 - Write an NWB file with extensions that DO NOT have in-memory classes
#     defined
pynwb.load_namespace(foo_ext_path)
nwbfile = pynwb.NWBFile(...)
# ... add a class from foonwb
ext_cls = pynwb.get_class('my_namespace', 'NewNWBType')
# ... use dynamically created class to add to nwbfile
io = pynwb.NWBHDF5IO(foo_nwb_path, mode='w')
io.write(nwbfile)
io.close()

# 6 - Alternative to writing NWB file with extensions that DO NOT have
#     in-memory classes defined.
# This alternative does not require users to handle FORM objects
pynwb.load_namespace(foo_ext_path)
nwbfile = pynwb.NWBFile(...)
# ... add a class from foonwb
ext_cls = pynwb.get_class('my_namespace', 'NewNWBType')
# ... use dynamically created class to add to nwbfile
pynwb.to_hdf5(nwbfile, foo_nwb_path)

############ APPEND #############

# 1 - Read from a file that instantiates an extension, and append to it
import foonwb
io = pynwb.NWBHDF5IO(foo_nwb_path, ext=foo_ext_path, mode='a')
nwbfile = io.read()
# ... add a class from foonwb
io.write(nwbfile)
io.close()

# 2 - Read from a file that instantiates an extension, and append types
#     from a ion
import foonwb
import barnwb
io = pynwb.NWBHDF5IO(bar_nwb_path, ext=[foonwb.get_type_map(), bar.get_type_map()], mode='a')
nwbfile = io.read()
# ... add a class from foonwb or barnwb
io.write(nwbfile)
io.close()

# 3 - Write an NWB file multiple times. This would be used in the case where
#     a users needs to write multiple streams that cannot be exhausted simulatneously.
#     For example, converting a experiment that has multiple Datasets that are too big
#     to fit in memory together.
nwbfile = pynwb.NWBFile(...)
# ...
io = pynwb.NWBHDF5IO(baz_nwb_path, mode='w')
# ... add some NWBContainers with DataChunkIterators
io.write(nwbfile)
# ... add some more NWBContainers with DataChunkIterators
io.write(nwbfile)
io.close()

'''
Limitations:
    - users cannot write/append using two namespaces that have the same name
'''