[docs] update news and annotations

Author: jgrewe

docs/source/annotations.rst

@@ -37,6 +37,35 @@ The *Sections* add much like dictionaries. To access e.g. the "resting potential
 .. 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

docs/source/examples/annotations.py

@@ -29,6 +29,19 @@ def main():
 
     print(session.find_sections(lambda s: "resting potential" in s.props))
     print(session.find_sections(lambda s: "resting potential" in s.props)[0]["resting potential"])
+
+    observations = subject.create_property("observations", ["p10", "p12", "p14"])
+    observations.definition = "Some behavioral observations I did on several days"
+    print(observations.values)
+
+    observations.extend_values("p16")
+    observations.extend_values(["p18", "p20"])
+
+    try:
+        observations.extend_values(22)
+    except TypeError as e:
+        print(e)
+
     nixfile.close()
 
 if __name__ == "__main__":

docs/source/news.rst

@@ -2,39 +2,57 @@
 Changes in version 1.5
 ######################
 
-With version 1.5 we introduced several changes on the library as well as on the data model side (nix model version 1.2). Some are even breaking changes.
-1.5 libraries can open files that have been written with pre 1.5 libraries. Old files cannot be opened for ``ReadWrite`` access.
-You may want to convert such files using the ``nixio`` command line tool that comes with the library or via also implement upgrade into a script.
+With version 1.5 we introduced several changes on the library as well as on the data model side (nix model version 1.2). **Some of these changes are breaking changes.** That is, you may need to adapt your code. Or convert files (see below).
+
+Files written with nixpy versions < 1.5 (model version 1.1) can be opened for reading **but not** for writing. Trying to do so will lead to an exception:
+
+.. code-block:: python
+
+    import nixio
+    print("Opening in ReadOnly mode is possible.")
+    nixfile = nixio.File.open("old_format_file.nix", nixio.FileMode.ReadOnly)
+    print("file format version:", f.version)
+
+    print("Opening in ReadWrite model will fail:")
+    nixfile = nixio.File.open("old_format_file.nix", nixio.FileMode.ReadWrite)
+
+.. code-block:: text
+
+    Opening in ReadOnly mode is possible.
+    File format version: (1, 1, 0)
+    Opening in ReadWrite model will fail:
+        159         if mode == FileMode.ReadWrite:
+        160             if not can_write(self):
+    --> 161                 raise RuntimeError("Cannot open file for writing. "
+        162                                    "Incompatible version.")
+        163         elif mode == FileMode.ReadOnly:
+
+        RuntimeError: Cannot open file for writing. Incompatible version.
+
+
+You may want to convert such files using the ``nixio`` command line tool that comes with the library.
 
 .. code-block:: bash
 
    nixio upgrade --help
 
+
+Or implement conversion into your code:
+
 .. code-block:: python
 
     import nixio
     filename = "test.nix"
     nixio.file_upgrade(filename, quiet=False)
 
-Pass ``quiet=False`` in order to get some feedback on what the tool did. **Note** Files are replaced *in place*. Make sure to backup your files before upgrading.
+Pass ``quiet=False`` in order to get some feedback on what the tool did. **Note: Files are replaced *in place*. Make sure to backup your files before upgrading.**
 
 Model changes
 #############
 
-* the metadata model was simplified to reflects the changes introduced to the underlying **odml** data model. Accordingly the *Value* entity does no longer exist. New versions of the library can read but not write old data.
-* New *DataFrame* entity.
+* the metadata model was simplified to reflects the changes introduced to the underlying **odml** data model. Accordingly the *Value* entity does no longer exist. New versions of the library can read but not write old data. Experience showed that almost all use cases stored single Values in a *Property*. The overhead (code and also file size) of keeping each value in a separate Enitiy is not justified. The *Property* now keeps all information that was Value related, such as the uncertainty. If you want to store multiple values in a property this is still possible but they have to have the same data type. (see :ref:`Annotations with arbitrary metadata` for more information).
+* New *DataFrame* entity that stores tabular data. Each column has a name, unit, and data type. (see :ref:`The DataFrame` for more information).
 * *Tags* and *MultiTags* can link to DataFrames as features.
-* *RangeDimension* can link to DataFrames as source for the ticks.
-* *AliasRangeDimension* has been removed, the equivalent can be achieved with linking to a *DataArray*.
-
-The *DataFrame*
-###############
-
-The *DataFrame* is a new entity that stored tabular data. Each column has a name, unit, and data type. (see :ref:`The DataFrame` for more information)
-
-*RangeDimension*
-################
-
 * *RangeDimensions* ticks can now be stored within the dimension descriptor, or in linked DataArrays or DataFrames. Ticks must still be one-dimensional (see :ref:`RangeDimension` for more information).
 * Because of the above change, the former *AliasRangeDimension* is no longer needed. The same functionality is achieved by linking the *RangeDimension* to the *DataArray* itself.
 
@@ -45,7 +63,6 @@ API changes
 * ``SampledDimension.axis`` can now be called with an optional argument ``start_position`` to get an axis that starts at the given position. Starting at a given index is still possible.
 * ``Block.create_data_array`` has additional keyword-arguments to directly provide label and unit.
 
-
 Misc
 ####