diff --git a/CHANGELOG.md b/CHANGELOG.md index edd9984ea..776fc54ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ - Enforce electrode ID uniqueness during insertion into table. @CodyCBakerPhD (#1344) - Fix integration tests with invalid test data that will be caught by future hdmf validator version. @dsleiter, @rly (#1366, #1376) - +- Fix build warnings in docs @oruebel (#1380) ## PyNWB 1.5.1 (May 24, 2021) diff --git a/docs/gallery/domain/ophys.py b/docs/gallery/domain/ophys.py index 37d279908..f59b20f92 100644 --- a/docs/gallery/domain/ophys.py +++ b/docs/gallery/domain/ophys.py @@ -119,7 +119,7 @@ # Storing fluorescence measurements # --------------------------------- # -# Now that ROIs are stored, you can store fluorescence (or dF/F [#]_) data for these regions of interest. +# Now that ROIs are stored, you can store fluorescence (or dF/F) data for these regions of interest. # This type of data is stored using the :py:class:`~pynwb.ophys.RoiResponseSeries` class. You will not need # to instantiate this class directly to create objects of this type, but it is worth noting that this is the # class you will work with after you read data back in. diff --git a/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst b/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst index a158ecdec..9da0ee022 100644 --- a/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst +++ b/docs/source/extensions_tutorial/2_create_extension_spec_walkthrough.rst @@ -11,7 +11,7 @@ generates a repository with the appropriate directory structure. After you finish the instructions `here `_, you should have a directory structure that looks like this -.. code-block:: c +.. code-block:: bash ├── LICENSE.txt ├── MANIFEST.in @@ -51,8 +51,8 @@ you should have a directory structure that looks like this └── create_extension_spec.py At its core, an NWB extension consists of YAML text files, such as those generated in the `spec` -folder. While you can write these YAML extension files by hand, PyNWB provides a convenient API -via the :py:mod:`~pynwb.spec` module for creating extensions. +folder. While you can write these YAML extension files by hand, PyNWB provides a convenient API +via the :py:mod:`~pynwb.spec` module for creating extensions. Open ``src/spec/create_extension_spec.py``. You will be modifying this script to create your own NWB extension. Let's first walk through each piece. diff --git a/docs/source/extensions_tutorial/3_spec_api.rst b/docs/source/extensions_tutorial/3_spec_api.rst index 54df0cca0..d4b42864c 100644 --- a/docs/source/extensions_tutorial/3_spec_api.rst +++ b/docs/source/extensions_tutorial/3_spec_api.rst @@ -34,8 +34,8 @@ within it Datasets, Attributes, Links, and/or other Groups. Groups are specified - ``neurodata_type_def`` declares the name of the neurodata type. - ``neurodata_type_inc`` indicates what data type you are extending (Groups must extend Groups, and Datasets must extend Datasets). -- To define a new neurodata type that does not extend an existing type, use - ``neurodata_type_inc=NWBContainer`` for a group or ``neurodata_type_inc=NWBData`` for a dataset. +- To define a new neurodata type that does not extend an existing type, use + ``neurodata_type_inc=NWBContainer`` for a group or ``neurodata_type_inc=NWBData`` for a dataset. ``NWBContainer`` and ``NWBData`` are base types for NWB. - To use a type that has already been defined, use ``neurodata_type_inc`` and not ``neurodata_type_def``. - You can define a group that is not a neurodata type by omitting both ``neurodata_type_def`` and ``neurodata_type_inc``. @@ -79,17 +79,20 @@ All larger blocks of numeric or text data should be stored in Datasets. Specifyi ``neurodata_type_def``, ``neurodata_type_inc``, ``doc``, ``name``, ``default_name``, ``linkable``, ``quantity``, and ``attributes`` all work the same as they do in :py:class:`~pynwb.spec.NWBGroupSpec`, described in the previous section. -``dtype`` defines the type of the data, which can be a basic type, compound type, or reference type. -See a list of options `here `_. -Basic types can be defined as string objects and more complex types via :py:class:`~pynwb.spec.NWBDtypeSpec` and `RefSpec `_. +``dtype`` defines the type of the data, which can be a basic type, compound type, or reference type. +See a list of `dtype options `_ +as part of the specification language docs. Basic types can be defined as string objects and more complex +types via :py:class:`~pynwb.spec.NWBDtypeSpec` and +`RefSpec `_. -``shape`` is a specification defining the allowable shapes for the dataset. See the shape specification -`here `_. ``None`` is -mapped to ``null``. Is no shape is provided, it is assumed that the dataset is only a single element. +``shape`` is a specification defining the allowable shapes for the dataset. See the +`shape specification `_ +as part of the specification language docs. ``None`` is mapped to ``null``. Is no shape is provided, it is +assumed that the dataset is only a single element. -If the dataset is a single element (scalar) that represents meta-data, consider using an Attribute (see -below) to store the data more efficiently instead. However, note that a Dataset can have Attributes, +If the dataset is a single element (scalar) that represents meta-data, consider using an Attribute (see +below) to store the data more efficiently instead. However, note that a Dataset can have Attributes, whereas an Attribute cannot have Attributes of its own. ``dims`` provides labels for each dimension of ``shape``. @@ -139,16 +142,16 @@ defined in the ``attributes`` field of a :py:class:`~pynwb.spec.NWBGroupSpec` or neurodata type, i.e., the ``neurodata_type_def`` and ``neurodata_type_inc`` keys are not allowed. The only way to match an object with a spec is through the name of the attribute so ``name`` is required. You cannot have multiple attributes on a single group/dataset that correspond to the same :py:class:`~pynwb.spec.NWBAttributeSpec`, since these would have to have the same name. Therefore, instead of -specifying number of ``quantity``, you have a ``required`` field which takes a boolean value. Another +specifying number of ``quantity``, you have a ``required`` field which takes a boolean value. Another key difference between datasets and attributes is that attributes cannot have attributes of their own. .. tip:: Dataset or Attribute? It is often possible to store data as either a Dataset or an Attribute. Our best advice is - to keep Attributes small. In HDF5 the typical size limit for attributes is 64Kbytes. If an attribute is going to - store more than 64Kbyte, then make it a Dataset. Attributes are also more efficient for storing very - small data, such as scalars. However, attributes cannot have attributes of their own, and in HDF5, + to keep Attributes small. In HDF5 the typical size limit for attributes is 64Kbytes. If an attribute is going to + store more than 64Kbyte, then make it a Dataset. Attributes are also more efficient for storing very + small data, such as scalars. However, attributes cannot have attributes of their own, and in HDF5, I/O filters, such as compression and chunking, cannot apply to attributes. - + Link Specifications ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/extensions_tutorial/extensions_tutorial_home.rst b/docs/source/extensions_tutorial/extensions_tutorial_home.rst index 6fec63b01..988794c4a 100644 --- a/docs/source/extensions_tutorial/extensions_tutorial_home.rst +++ b/docs/source/extensions_tutorial/extensions_tutorial_home.rst @@ -1,3 +1,5 @@ +.. _extending-nwb: + Extending NWB ============= diff --git a/docs/source/tutorial_source/convert.rst b/docs/source/tutorial_source/convert.rst deleted file mode 100644 index 6ed3030ad..000000000 --- a/docs/source/tutorial_source/convert.rst +++ /dev/null @@ -1,36 +0,0 @@ -Converting data to NWB -====================== - -The following are example Jupyter notebooks for converting custom lab data to NWB: - -crcns-ret-1: Meister lab retina data ------------------------------------- - -* **Notebook:** https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/docs/notebooks/convert-crcns-ret-1-meisterlab.ipynb -* **Example:** This example shows: - - * Use of ``UnitTimes``, ``SpikeUnit``, ``ImageSeries``, ``ElectrodeGroup``, ``EpochTimeSeries``, ``Device`` - * Creation and use of custom namespace and extension to extend ``ImageSeries`` to add custom metadata attributes - * Create external link for ``ImageSeries.data`` - * Read of crcns-ret-1 dataset - * Convert of the data to NWB - * Comparison of H5Gate and PyNWB - -* **Data:** Convert single-unit neural responses recorded from - isolated retina from lab mice (Mus Musculus) using - a 61-electrode array in response to various visual - stimuli. Recordings were done by Yifeng Zhang in - Markus Meister's lab at Harvard University in 2008. - Further description of the data are available here: - https://crcns.org/data-sets/retina/ret-1/about-ret-1 - -* **Data Terms of use** The data used on the notebook and, therefore also the NWB files generated by the notebook are governed - by the terms-of-use of CRCNS.org described here https://crcns.org/terms . - -* **Comparison to NWB 1.0.x`:** - - * **Notebook:** https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/docs/notebooks/convert-crcns-ret-1-meisterlab-compare-nwb-1.0.6.ipynb - * **Description:** This notebook shows the convert of the same data using the original NWB 1.0.x API to allow for comparison of the - NWB 1.0.x and NWB 2.x file. - -