Merge branch 'master' of https://github.com/g-node/nixpy into v1.5

.gitignore

@@ -46,3 +46,6 @@ Makefile
 .cache
 .eggs
 .mypy_cache
+
+# vscode
+.vscode

README.rst

@@ -1,8 +1,6 @@
 .. image:: https://github.com/G-Node/nixpy/workflows/NIXPy%20tests%20and%20linting/badge.svg?branch=master
     :target: https://github.com/G-Node/nixpy/actions
-.. image:: https://travis-ci.org/G-Node/nixpy.svg?branch=v1.5
-    :target: https://travis-ci.org/G-Node/nixpy
-.. image:: https://ci.appveyor.com/api/projects/status/72l10ooxbvf0vfgd/branch/v1.5?svg=true
+.. image:: https://ci.appveyor.com/api/projects/status/72l10ooxbvf0vfgd/branch/master?svg=true
     :target: https://ci.appveyor.com/project/G-Node/nixpy
 .. image:: https://coveralls.io/repos/github/G-Node/nixpy/badge.svg?branch=v1.5
     :target: https://coveralls.io/github/G-Node/nixpy?branch=v1.5
@@ -14,10 +12,7 @@
 Versions
 --------
 
-This repository's `master` is the development branch of *NIXPY*.
-It is not guaranteed to build or work properly.
-At times it may not even work at all.
-We strongly recommend using the latest stable version, which can be found on PyPI as nixio_.
+This repository's `master` is the development branch of *NIXPY*. It is not guaranteed to build or work properly. At times it may not even work at all. We strongly recommend using the latest stable version, which can be found on PyPI as nixio_.
 
 About NIXPY
 -----------
@@ -31,13 +26,6 @@ The simplest way to install *NIXPY* is from PyPI using pip. The name of the pack
 
     pip install nixio
 
-Bindings for C++ NIX
---------------------
-
-The setup script will automatically build the bindings for *NIX* if it is detected on the system, otherwise only the pure Python version will be installed.
-
-For instructions on building *NIX*, see the `NIX README <https://github.com/G-Node/nix/blob/master/README.md>`_ file.
-
 
 To check if installed properly
 ------------------------------

appveyor.yml

@@ -1,4 +1,4 @@
-version: 1.4.{build}
+version: 1.5.{build}
 
 image: Visual Studio 2017
 
@@ -58,6 +58,7 @@ install:
   #     Invoke-WebRequest -URI $env:nix_exe_url -OutFile "nix.exe"
   # - 7z x nix.exe
   # - cd ..
+  - python -m pip install certifi
   - python -m pip install -U pip wheel
   - python -m pip install numpy h5py pytest-xdist
   - ps: cd "$env:APPVEYOR_BUILD_FOLDER"

docs/source/annotations.rst

@@ -0,0 +1,74 @@
+.. toctree::
+    :maxdepth: 1
+
+.. _metadata:
+
+Annotations with arbitrary metadata
+===================================
+
+The entities of the data model that were discussed so far carry just enough information to get a basic understanding of the stored data. Often much more information than that is required. Storing additional metadata is a central part of the NIX concept. We use a slightly modified version of the *odML* data model for metadata to store additional information. In brief: the model consists of *Sections* that contain *Properties* which in turn carry a list of values. Again, *Sections* can be nested to represent logical dependencies in the hierarchy of a tree. While all data entities discussed above are children of *Block* entities, the metadata lives parallel to the *Blocks*. The idea behind this is that several blocks may refer to the same metadata, or, the other way round the metadata applies to data entities in several blocks. The *types* used for the *Sections* in the following example are defined
+in the `odml terminologies <https://github.com/G-Node/odml-terminologies>`_
+
+Most of the data entities can link to metadata sections.
+
+.. literalinclude:: examples/annotations.py
+    :lines: 5-21
+    :caption: We can add arbitrary metadata in trees of *Sections* and *Properties* (:download:`example code <examples/annotations.py>`).
+
+For a quick view of the metadata tree pretty-print it:
+
+.. literalinclude:: examples/annotations.py
+    :lines: 24
+
+which leads to an output like this. The argument ``max_depth=-1`` notes that the full depth of the tree should be displayed. In the default case (``max_depth=1``) the display will be more compact and will not recursively traverse the whole tree. 
+
+.. code-block:: text
+
+    recording session [odml.recording]
+        |- experimenter: ('John Doe',)
+        |- recording date: ('2014-01-01',)
+    subject [odml.subject]
+        |- id: ('mouse xyz',)
+        cell [odml.cell]
+            |- resting potential: (-64.5,)mV
+
+The *Sections* add much like dictionaries. To access e.g. the "resting potential" of the cell we may call:
+
+.. literalinclude:: examples/annotations.py
+    :lines: 26
+
+Extending Properties
+--------------------
+
+Properties can carry multiple values and additional information such as a definition. 
+
+.. literalinclude:: examples/annotations.py
+    :lines: 33-35
+
+Reading the values will return a tuple. This has the background that one cannot change a tuple. Changing the values stored in a *Property* can be done e.g. by the ``extend_values`` method
+
+.. literalinclude:: examples/annotations.py
+    :lines: 37-38
+
+One can extend it by single values or by lists of values. 
+
+The data type of all values must, however, be the same. Adding a number to the list of strings will fail with a ``TypeError``:
+
+.. literalinclude:: examples/annotations.py
+    :lines: 40-43
+
+.. code-block:: text
+
+    New data type '<class 'numpy.int64'>' is inconsistent with the Property's data type '<class 'numpy.str_'>'
+
+**Note:** Once the property has been created, the data type can't be changed. One would need to create a replacement with the desired data type.
+
+Finding annotations
+-------------------
+
+If we do not know the exact path of the *Section* we are looking for, we need to search it by passing a function (in this case a lambda function) to the ``find_section`` method. The following code shows two examples in which we look first for a section with a given name or second a section which contains a property with a certain name. 
+
+.. literalinclude:: examples/annotations.py
+    :lines: 28 - 31
+
+The result of the ``find_sections`` will always be a list which may be empty if no match was found. Therefore, the call in the last line is to some extent risky and would lead to an ``OutOfBounds`` exception if the search failed.

docs/source/api/nixio.rst

@@ -1,5 +1,5 @@
-nixio package
-=============
+Internal API
+============
 
 Subpackages
 -----------

docs/source/basic_idea.rst

@@ -0,0 +1,17 @@
+Idea
+====
+
+The basic idea of the *NIX* project is to come up with a **generic**
+data model that defines as few structures/entities as possible while
+being able to represent a multitude of different data structures, allows
+for in-depth annotation and supports standardization.
+
+Designing a **generic** data model implies that the defined entities are
+named in a way that may seem uncommon but are more general than the
+*domain-specific* terms used in any given field or community.
+
+
+Please follow this link to the `C++ nix library documentation <https://nixio.readthedocs.io/en/master/data_model.html>`_ to lear more about the data model. 
+
+The idea of the *NIX* data model has been implemented using the
+`HDF5 <https://www.hdfgroup.org>`__ file format.

docs/source/conf.py

@@ -1,4 +1,4 @@
-# Copyright © 2014, German Neuroinformatics Node (G-Node)
+# Copyright © 2014-2021, German Neuroinformatics Node (G-Node)
 #
 # All rights reserved.
 #
@@ -9,40 +9,31 @@
 from nixio.info import RELEASE, COPYRIGHT, BRIEF
 
 # general config
-extensions              = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
-source_suffix           = '.rst'
-master_doc              = 'index'
-project                 = BRIEF
-copyright               = COPYRIGHT
-release                 = RELEASE
-exclude_patterns        = []
-pygments_style          = 'sphinx'
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.autosectionlabel']
+source_suffix = '.rst'
+master_doc = 'index'
+project = BRIEF
+copyright = COPYRIGHT
+release = RELEASE
+exclude_patterns = []
+pygments_style = 'sphinx'
 
 # html options
-htmlhelp_basename       = 'nixio'
+htmlhelp_basename = 'nixio'
 try:
-    html_theme          = 'sphinx_rtd_theme'
-    html_sidebars       = {
-        '**': [
-                'about.html', 'navigation.html', 'searchbox.html',
-            ]
-    }
+    html_theme = 'sphinx_rtd_theme'
+    html_sidebars = {'**': ['about.html', 'navigation.html', 'searchbox.html']}
 
-    html_theme_options  = {
-        'logo'          : 'logo.png',
-        'github_user'   : 'G-Node',
-        'github_repo'   : 'nixpy',
-        'github_button' : True,
-        'github_count'  : False,
-        'travis_button' : True,
-        'link'          : '#456BA8'
-    }
+    html_theme_options = {'logo_only': True,
+                          'display_version': True,
+                          'style_external_links': True,
+                          'prev_next_buttons_location': "both"}
+
+    html_logo = "nix_logo.png"
 
 except ImportError:
-    html_theme          = 'default'
+    html_theme = 'default'
 
 # intersphinx configuration
-intersphinx_mapping     = {
-    'http://docs.python.org/' : None,
-    'http://docs.scipy.org/doc/numpy': None
-}
+intersphinx_mapping = {'http://docs.python.org/': None,
+                       'http://docs.scipy.org/doc/numpy': None}

docs/source/contact.rst

@@ -0,0 +1,20 @@
+.. :toctree::
+         :maxdepth: 2
+
+Getting support
+===============
+
+If you experience problems using *NIX* feel free to join our IRC
+channel `#gnode at FreeNode <irc://irc.freenode.net/gnode>`__ or write
+an email to dev@g-node.org. If you find a bug or have a feature
+request please report it using the `project issue tracker
+<https://github.com/G-Node/nixpy/issues>`__.
+
+
+Contact
+-------
+
+The project is maintained by the `German Neuroinformatics Node,
+G-Node <http://www.g-node.org>`__. `G-Node at
+GitHub <https://github.com/g-node>`__,
+`email <mailto:dev@g-node.org>`__.