Merge branch 'dev' into dev

docs/gallery/domain/ecephys.py

@@ -45,7 +45,7 @@
 device = nwbfile.create_device(name='trodes_rig123', source="a source")
 
 #######################
-# Once you have created the :py:class:`~pynwb.ecephys.Device`, you can create an
+# Once you have created the :py:class:`~pynwb.device.Device`, you can create an
 # :py:class:`~pynwb.ecephys.ElectrodeGroup`.
 
 electrode_name = 'tetrode1'

docs/gallery/domain/icephys.py

@@ -31,8 +31,8 @@
 # Device metadata
 # ^^^^^^^^^^^^^^^
 #
-# Device metadata is represented by :py:class:`~pynwb.ecephys.Device` objects.
-# To create a device, you can use the :py:class:`~pynwb.ecephys.Device` instance method
+# Device metadata is represented by :py:class:`~pynwb.device.Device` objects.
+# To create a device, you can use the :py:class:`~pynwb.device.Device` instance method
 # :py:meth:`~pynwb.file.NWBFile.create_device`.
 
 device = nwbfile.create_device(name='Heka ITC-1600', source='a source')

docs/gallery/general/extensions.py

@@ -225,3 +225,107 @@ def __init__(self, **kwargs):
 
 io = NWBHDF5IO('cache_spec_example.nwb', mode='r', load_namespaces=True)
 nwbfile = io.read()
+
+####################
+# .. _MultiContainerInterface:
+# Creating and using a custom MultiContainerInterface
+# -----------------------------------------------------
+# It is sometimes the case that we need a group to hold zero-or-more or one-or-more of the same object.
+# Here we show how to create an extension that defines a group (`PotatoSack`) that holds multiple objects (`Pototo`es)
+# and then how to use the new data types. First, we use `pynwb` to define the new data types.
+
+from pynwb.spec import NWBNamespaceBuilder, NWBGroupSpec, NWBAttributeSpec
+
+name = 'test_multicontainerinterface'
+ns_path = name + ".namespace.yaml"
+ext_source = name + ".extensions.yaml"
+
+potato = NWBGroupSpec(neurodata_type_def='Potato',
+                      neurodata_type_inc='NWBDataInterface',
+                      doc='time of multicontainer', quantity='*',
+                      attributes=[
+                          NWBAttributeSpec(name='weight',
+                                           doc='weight of potato',
+                                           dtype='float',
+                                           required=True),
+                          NWBAttributeSpec(name='age',
+                                           doc='age of potato',
+                                           dtype='float',
+                                           required=False),
+                          NWBAttributeSpec(name='help',
+                                           doc='help',
+                                           dtype='text',
+                                           value="It's a potato")
+                      ])
+
+potato_sack = NWBGroupSpec(neurodata_type_def='PotatoSack',
+                           neurodata_type_inc='NWBDataInterface',
+                           name='potato_sack',
+                           doc='test of multicontainer', quantity='?',
+                           groups=[potato],
+                           attributes=[
+                               NWBAttributeSpec(name='help',
+                                                doc='help',
+                                                dtype='text',
+                                                value="It's a sack of potatoes")
+                           ])
+
+ns_builder = NWBNamespaceBuilder(name + ' extensions', name)
+ns_builder.add_spec(ext_source, potato_sack)
+ns_builder.export(ns_path)
+
+####################
+# Then create Container classes registered to the new data types (this is generally done in a different file)
+
+from pynwb import register_class, load_namespaces
+from pynwb.file import MultiContainerInterface, NWBContainer
+
+load_namespaces(ns_path)
+
+
+@register_class('Potato', name)
+class Potato(NWBContainer):
+    __nwbfields__ = ('name', 'weight', 'age', 'source')
+
+    @docval({'name': 'name', 'type': str, 'doc': 'who names a potato?'},
+            {'name': 'weight', 'type': float, 'doc': 'weight of potato in grams'},
+            {'name': 'age', 'type': float, 'doc': 'age of potato in days'},
+            {'name': 'source', 'type': str, 'doc': 'source of potato',
+             'default': 'the ground'})
+    def __init__(self, **kwargs):
+        super(Potato, self).__init__(kwargs['source'], name=kwargs['name'])
+        self.weight = kwargs['weight']
+        self.age = kwargs['age']
+
+
+@register_class('PotatoSack', name)
+class PotatoSack(MultiContainerInterface):
+
+    __clsconf__ = {
+        'attr': 'potatos',
+        'type': Potato,
+        'add': 'add_potato',
+        'get': 'get_potato',
+        'create': 'create_potato',
+    }
+
+    __help = 'info about potatoes'
+
+
+####################
+# Then use the objects (again, this would often be done in a different file).
+
+from pynwb import NWBHDF5IO, NWBFile
+
+potato_sack = PotatoSack(source='pantry',
+                         potatos=Potato(name='potato1', age=2.3, weight=3.0,
+                                        source='the ground'))
+
+nwbfile = NWBFile("source", "a file with metadata", "NB123A", '2018-06-01T00:00:00')
+
+pmod = nwbfile.create_processing_module('module_name', 'source', 'desc')
+pmod.add_container(potato_sack)
+
+
+with NWBHDF5IO('test_multicontainerinterface.nwb', 'w') as io:
+    io.write(nwbfile)

docs/source/overview_software_architecture.rst

@@ -10,20 +10,20 @@ PyNWB and functionality of the various components.
 .. _fig-software-architecture:
 
 .. figure:: figures/software_architecture.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture
 
-   Overview of the high-level software architecture of PyNWB.
+   Overview of the high-level software architecture of PyNWB (click to enlarge).
 
 
 .. _fig-software-architecture-purpose:
 
 .. figure:: figures/software_architecture_design_choices.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture Functions
 
    We choose a modular design for PyNWB to enable flexibility and separate the
-   various aspects of the NWB:N ecosystem.
+   various aspects of the NWB:N ecosystem (click to enlarge).
 
 .. raw:: latex
 
@@ -37,10 +37,10 @@ Main Concepts
 .. _fig-software-architecture-concepts:
 
 .. figure:: figures/software_architecture_concepts.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture Concepts
 
-   Overview of the main concepts/classes in PyNWB and their location in the overall software architecture.
+   Overview of the main concepts/classes in PyNWB and their location in the overall software architecture (click to enlarge).
 
 Container
 ^^^^^^^^^
@@ -128,7 +128,7 @@ ObjectMapper
 .. _fig-software-architecture-mainconcepts:
 
 .. figure:: figures/software_architecture_mainconcepts.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture Main Concepts
 
    Relationship between ``Containers``, ``Builders``, ``ObjectMappers``, and ``Specs``
@@ -183,10 +183,10 @@ BuildManager
 .. _fig-software-architecture-buildmanager:
 
 .. figure:: figures/software_architecture_buildmanager.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture BuildManager and TypeMap
 
-   Overview of ``BuildManager`` (and ``TypeMap``).
+   Overview of ``BuildManager`` (and ``TypeMap``) (click to enlarge).
 
 
 FORMIO
@@ -210,7 +210,7 @@ FORMIO
 .. _fig-software-architecture-formio:
 
 .. figure:: figures/software_architecture_formio.*
-   :scale: 100 %
+   :width: 100%
    :alt: PyNWB Software Architecture FormIO
 
-   Overview of ``FORMIO``.
+   Overview of ``FORMIO`` (click to enlarge).

src/pynwb/__init__.py

@@ -232,6 +232,7 @@ def __init__(self, **kwargs):
 from .file import NWBFile  # noqa: E402, F401
 
 from . import behavior  # noqa: F401,E402
+from . import device  # noqa: F401,E402
 from . import ecephys  # noqa: F401,E402
 from . import epoch  # noqa: F401,E402
 from . import icephys  # noqa: F401,E402

src/pynwb/device.py

@@ -0,0 +1,18 @@
+from .form.utils import docval, call_docval_func
+from . import register_class, CORE_NAMESPACE
+from .core import NWBContainer
+
+
+@register_class('Device', CORE_NAMESPACE)
+class Device(NWBContainer):
+    """
+    """
+
+    __nwbfields__ = ('name',)
+
+    @docval({'name': 'name', 'type': str, 'doc': 'the name of this device'},
+            {'name': 'source', 'type': str, 'doc': 'the source of the data'},
+            {'name': 'parent', 'type': 'NWBContainer',
+             'doc': 'The parent NWBContainer for this NWBContainer', 'default': None})
+    def __init__(self, **kwargs):
+        call_docval_func(super(Device, self).__init__, kwargs)

src/pynwb/ecephys.py

@@ -8,21 +8,7 @@
 from . import register_class, CORE_NAMESPACE
 from .base import TimeSeries, _default_resolution, _default_conversion
 from .core import NWBContainer, NWBTable, NWBTableRegion, NWBDataInterface, MultiContainerInterface
-
-
-@register_class('Device', CORE_NAMESPACE)
-class Device(NWBContainer):
-    """
-    """
-
-    __nwbfields__ = ('name',)
-
-    @docval({'name': 'name', 'type': str, 'doc': 'the name of this device'},
-            {'name': 'source', 'type': str, 'doc': 'the source of the data'},
-            {'name': 'parent', 'type': 'NWBContainer',
-             'doc': 'The parent NWBContainer for this NWBContainer', 'default': None})
-    def __init__(self, **kwargs):
-        call_docval_func(super(Device, self).__init__, kwargs)
+from .device import Device
 
 
 @register_class('ElectrodeGroup', CORE_NAMESPACE)