[docs] Apply suggestions from code review

Co-authored-by: Michael Sonntag <[email protected]>

Author: jgrewe

docs/source/annotations.rst

@@ -71,4 +71,4 @@ If we do not know the exact path of the *Section* we are looking for, we need to
 .. literalinclude:: examples/annotations.py
     :lines: 28 - 31
 
-The result of the ``find_sections`` will always be 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.
+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/data_handling.rst

@@ -4,12 +4,12 @@
 Working with data
 =================
 
-Storing data is one thing, but we want to work with it. The following examples illustrate reading of data from *DataArray*, *Tag* and *MultiTag* entities We will use the dummy dataset already used in the :doc:`tagging <./tagging>` example. The figure below shows what is stored in the dataset. 
+Storing data is one thing, but we want to work with it. The following examples illustrate reading of data from *DataArray*, *Tag* and *MultiTag* entities. We will use the dummy dataset already used in the :doc:`tagging <./tagging>` example. The figure below shows what is stored in the dataset. 
 
 .. figure:: ./images/tag1.png
    :alt: a system's response to a stimulus
 
-At some instance in time a system was exposed to a stimulus that leads to the system's response. The response has been recorded and stored in a *DataArray* the A *Tag* is used to highlight the "stimulus-on" segment of the data.
+At some instance in time a system was exposed to a stimulus that leads to the system's response. The response has been recorded and stored in a *DataArray*, a *Tag* is used to highlight the "stimulus-on" segment of the data.
 
 .. literalinclude:: examples/tagging_example.py
     :caption: :download:`example code <examples/tagging_example.py>`
@@ -29,7 +29,7 @@ The first and maybe most common problem is to read the data stored in a
 Reading all data
 ~~~~~~~~~~~~~~~~
 
-In *NIX* when you open a *DataArray* the stored the data is **not** automatically read from file. This keeps the object lightweight and easy to create. To read the data you can simply access the data in a numpy style:
+In *NIX* when you open a *DataArray* the stored data is **not** automatically read from file. This keeps the object lightweight and easy to create. To read the data you can simply access it in a numpy style:
 
 .. literalinclude:: examples/tagging_example.py
     :caption: :download:`example code <examples/tagging_example.py>`
@@ -52,21 +52,21 @@ Reading partial data
 ~~~~~~~~~~~~~~~~~~~~
 
 In other instances it might be wanted to read only parts of the data.
-Reading slices of the data ist straight forward using the the numpy style.
+Reading slices of the data is straight forward using the numpy style.
 
 .. literalinclude:: examples/tagging_example.py
     :caption: :download:`example code <examples/tagging_example.py>`
     :lines: 98-101
 
-An alternative approach is to use the ``DataArray.get_slice`` method which by default works with indices but can also work in data coordinates. E.g. we know that the data is 1-D and covers a span of 3.5s and we want to have the data in the interval 0.5s through 1.75s. The method returns a ``nixio.DataView`` object. The actual reading is done be accessing the data.
+An alternative approach is to use the ``DataArray.get_slice`` method which by default works with indices but can also work in data coordinates. E.g. we know that the data is 1-D and covers a span of 3.5s and we want to have the data in the interval 0.5s through 1.75s. The method returns a ``nixio.DataView`` object. The actual reading is done by accessing the data.
 
 .. literalinclude:: examples/tagging_example.py
     :caption: :download:`example code <examples/tagging_example.py>`
     :lines: 103-106
     :emphasize-lines: 3
 
 The arguments ``positions`` and ``extents`` are passed as lists. There must be one entry for each dimension of the data. In this case, since the data is 1-D, positions and extents are 1-element lists.
-Note: the slice is defined by the starting point(s) and the *extent(s)* not with start and end points.
+Note: the slice is defined by the starting point(s) and the *extent(s)*, not with start and end points.
 
 Reading tagged data
 ~~~~~~~~~~~~~~~~~~~
@@ -85,7 +85,7 @@ In order to read the data that belongs to the highlighted region(s) *Tag* and *M
    :emphasize-lines: 10
    :caption: Reading data segments tagged by the *Tag* or *MultiTag* can be done using the ``tagged_data`` method (:download:`example code <examples/multiple_regions.py>`).
 
-The *MultiTag* version of the ``tagged_data`` method takes two arguments. The first is the index of the tagged region (0 for the first), the second argument is name (you can also use the index or the id) of the referenced *DataArray*. Since the *Tag* tags only a single region, it only takes one argument, i.e. the name (id, index) of the referenced *DataArray*.
+The *MultiTag* version of the ``tagged_data`` method takes two arguments. The first is the index of the tagged region (0 for the first), the second argument is the name of the referenced *DataArray* (you can also use the index or the id). Since the *Tag* tags only a single region, it takes only one argument, i.e. the name (id, index) of the referenced *DataArray*.
 
 .. figure:: ./images/reading_tagged_data.png
    :alt: reading tagged data
@@ -98,4 +98,3 @@ obtained using the ``feature_data`` methods.
    :lines: 69 - 76
    :emphasize-lines: 6, 7
    :caption: ``feature_data`` works analogously, the first argument is the index of the tagged region, the second the name (or id or index) of the feature. Here the feature stores a single number, i.e. the frequency of the stimulus for each tagged region which is plotted below the highlighted regions in the figure above (:download:`example code <examples/multiple_regions.py>`). 
-

docs/source/faq.rst

@@ -28,7 +28,7 @@ units which is not supported/not necessarily possible for non-SI units.
 It is largely safe to use non-SI units when providing metadata or
 specifying the unit of the data stored in a *DataArray*. It may become
 problematic in the context of *Dimensions*. Some functions support
-reading data with the positions provided by the *Tags* in these cases we
+reading data with the positions provided by the *Tags*, in these cases we
 rely on scalability of the units.
 
 If you feel this is unjustified, feel free to improve our unit-handling

docs/source/finding_things.rst

@@ -12,7 +12,7 @@ the relations between entities.
 
 Still, reading a *NIX* file that has been created by another person or
 has been automatically written by a recording tool such
-as [relacs](https://github.com/relacs/relacs) might be confusing a
+as [relacs](https://github.com/relacs/relacs) might be confusing at
 first. The following recommendation should help you when exploring an
 unknown file.
 
@@ -42,8 +42,8 @@ Recommendations when opening an unknown NIX file
 Standardization helps
 ---------------------
 
-Having a well-defined data model and the respective APIsto store and
-annotate scientific data with a is a huge step toward standardization
+Having a well-defined data model and the respective API store and
+annotate scientific data with related metadata is a huge step toward standardization
 and reusability.  As mentioned [before](./standardization.md), if the
 file is created according to known definitions, finding stuff in an
 unknown file is considerably simplified.
@@ -55,19 +55,19 @@ first channel and it is further known that the file is created e.g. by
 
 .. code:: python
 
-    nixfile = nixio.File.open("relacs_example.nix", nix.FileMode.ReadOnly);
+    nixfile = nixio.File.open("relacs_example.nix", nixio.FileMode.ReadOnly);
     block = f.blocks()[0];
     arrays = [da for da in block.data_arrays if "relacs.data.sampled.v-1" in da.type.lower()]
 
 With this kind of list comprehensions a large variety of searches can be easily performed. The above said assumes a “data-centered” view. The other way would be to
-assume a “metadata-centered” view and to scan the metadata tree and
+assume a “metadata-centered” view, to scan the metadata tree and
 perform an inverse search from the metadata to the data entities that
 refer to the respective section. Accordingly, ``Section`` and ``Sources`` define
 methods to get the referring *DataArray*\ s, *Tag*\ s, etc..
 
 .. code:: python
 
-    section = nixfile.sections()[0]
+    s = nixfile.sections()[0]
     blocks = s.referring_blocks()
     for b in blocks:
         print(b)

docs/source/image_data.rst

@@ -16,7 +16,7 @@ attribution in the code.
 
 .. literalinclude:: examples/imageData.py
     :lines: 59-64
-    :caption: Image data is just 3D data that can be easily stored in a *DataArray*. We need to add three dimension descriptors, though (to run the example you need the :download:`example code <examples/imageData.py>` , the :download:`image <examples/lenna.png>` *imagemagick* or *xv* packages). 
+    :caption: Image data is just 3-D data that can be easily stored in a *DataArray*. We need to add three dimension descriptors, though (to run the example you need the :download:`example code <examples/imageData.py>` , the :download:`image <examples/lenna.png>` *imagemagick* or *xv* packages). 
 
 .. image:: examples/lenna.png
     :alt: lenna
@@ -44,7 +44,7 @@ data. The same Tag can be applied to many references as long as
 
 .. literalinclude:: examples/singleROI.py
     :lines: 80-84
-    :caption: A *Tag* is used to tag a a single region of interest. Most image data is 3D with the third dimension representing the color channels (:download:`singleROI.py <examples/singleROI.py>`).
+    :caption: A *Tag* is used to tag a a single region of interest. Most image data is 3-D with the third dimension representing the color channels (:download:`singleROI.py <examples/singleROI.py>`).
 
 .. image:: images/single_roi.png
     :alt: single roi
@@ -64,7 +64,7 @@ For tagging multiple regions in the image data we again use a *MultiTag* entity.
     :alt: many rois
     :width: 240
 
-The start positions and extents of the ROIs are stored in two separate *DataArrays*, these are each 2-D the first dimension represents the number of regions , the second defines the position/extent for each single dimension of the data (height, width, color channels).
+The start positions and extents of the ROIs are stored in two separate *DataArrays*, these are each 2-D, the first dimension represents the number of regions, the second defines the position/extent for each single dimension of the data (height, width, color channels).
 
 The *MultiTag* has a ``tagged_data`` method that is used to retrieve the data tagged by the *MultiTag*.
 
@@ -74,4 +74,4 @@ The *MultiTag* has a ``tagged_data`` method that is used to retrieve the data ta
 
 .. image:: images/retrieved_rois.png
     :alt: many rois
-    :width: 240
+    :width: 240

docs/source/news.rst

@@ -50,7 +50,7 @@ Pass ``quiet=False`` in order to get some feedback on what the tool did. **Note:
 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. 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).
+* the metadata model was simplified to reflect 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 Entitiy 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.
 * *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).
@@ -94,4 +94,4 @@ Extended command line tool abilities; The ``nixio`` command line tool now bundle
                            tool is under active development. Please use the github issue tracker
                            (https://github.com/G-node/nixpy/issues) for bug reports and feature requests.
       validate            Validate NIX files for missing or inconsistent objects and annotations.
-      upgrade             Upgrade NIX files to newest file format version.
+      upgrade             Upgrade NIX files to newest file format version.

docs/source/sources.rst

@@ -23,7 +23,7 @@ subject.
 As mentioned above the Sources build a tree. The block (as the root of the tree) at the moment has only a single source attached to it 
 
 .. literalinclude:: examples/sources.py
-    :lines: 53 - 55 
+    :lines: 52 - 54 
 
 The output should yield:
 
@@ -39,7 +39,7 @@ Search and find
 In a data-centered search we can then ask the *DataArray* for it's *Source* to get information about the cell and get the linked metadata. A *DataArray* may have several sources attached to it. To make sure we get the right one (with the cell information) we perform a search on the sources using the **type** information.
 
 .. literalinclude:: examples/sources.py
-    :lines: 59 - 61 
+    :lines: 58 - 60 
 
 The output should give
 
@@ -53,10 +53,10 @@ The output should give
         |- BaselineRate: (15,)Hz
         |- Layer: ('4',)
 
-In a or source-centered search we can ask for the *DataArrays* that link to a source.
+In a source-centered search we can ask for the *DataArrays* that link to a source.
 
 .. literalinclude:: examples/sources.py
-    :lines: 63 
+    :lines: 62 
 
 This should return a list with a single entry:
 

docs/source/spike_time_data.rst

@@ -5,7 +5,7 @@ Spike time data
 
 Storing the times of spikes (action potentials) that are generated by neurons is one of the most common use cases.
 
-The data shown below is simulation data created using a Leaky Integrate and Fire (LIF)model neuron. To run the example codes in this section you will need the :download:`lif model <examples/lif.py>`.
+The data shown below is simulation data created using a Leaky Integrate and Fire (LIF) model neuron. To run the example codes in this section you will need the :download:`lif model <examples/lif.py>`.
 
 .. literalinclude:: examples/spikeTagging.py
     :lines: 58-78
@@ -20,7 +20,7 @@ The data shown below is simulation data created using a Leaky Integrate and Fire
 Adding features
 ---------------
 
-The following code shows how to use the **Features** of the NIX-model. Suppose that we have the recording of a signal in which a set of events is detected. Each event may have certain characteristics one wants to store. These are stored as **Features** of the events. There are three different link-types between the features and the events stored in the tag. *nix.LinkType.Untagged* indicates that the whole data stored in the **Feature** applies to the points defined in the tag. *nix.LinkType.Tagged* on the other side implies that the *position* and *extent* have to be applied also to the data stored in the **Feature**. Finally, the *nix.LinkType.Indexed* indicates that there is one point (or slice) in the **Feature** data that is related to each position in the Tag.
+The following code shows how to use the **Features** of the NIX-model. Suppose that we have the recording of a signal in which a set of events is detected. Each event may have certain characteristics one wants to store. These are stored as **Features** of the events. There are three different link-types between the features and the events stored in the tag. *nix.LinkType.Untagged* indicates that the whole data stored in the **Feature** applies to the points defined in the tag. *nix.LinkType.Tagged* on the other side implies that the *position* and *extent* have to be applied also to the data stored in the **Feature**. Finally, the *nix.LinkType.Indexed* indicates that there is one point (or slice) in the **Feature** data that is related to each position in the tag.
 
 The following examples show how this works.
 
@@ -29,7 +29,7 @@ The following examples show how this works.
 Tagging stimulus segments
 -------------------------
 
-Let's say we record the neuronal activity and in a certain epoch of that recording a stimulus was presented. This time interval is annotated using a **Tag**. This inidicates the time in which the stimulus was on but we may also want to link the stimulus itself to it. The stimulus is also stored as a **DataArray** be linked to the *Tag* as an *untagged* **Feature** of it.
+Let's say we record the neuronal activity and in a certain epoch of that recording a stimulus was presented. This time interval is annotated using a **Tag**. This inidicates the time in which the stimulus was on but we may also want to link the stimulus itself to it. The stimulus is also stored as a **DataArray** and can be linked to the *Tag* as an *untagged* **Feature** of it.
 
 .. literalinclude:: examples/untaggedFeature.py
     :lines: 111-122
@@ -39,7 +39,7 @@ Let's say we record the neuronal activity and in a certain epoch of that recordi
 .. image:: images/untagged_feature.png
     :alt: untagged feature
 
-In the recorded membrane voltage data is 10s long and we tag the interval between ``stimulus_onset`` and ``stimulus_onset + stimulus_duration`` (from 1 to 9 seconds). The stimulus itself is only 8s long and was played in the tagged interval. We use a *Tag* to bind stimulus and recorded signal together. The data stored in the "untagged" feature is the whole stimulus. The *Tag's* position and extent do not apply to the stimulus trace. 
+The recorded membrane voltage data is 10s long and we tag the interval between ``stimulus_onset`` and ``stimulus_onset + stimulus_duration`` (from 1 to 9 seconds). The stimulus itself is only 8s long and was played in the tagged interval. We use a *Tag* to bind stimulus and recorded signal together. The data stored in the "untagged" feature is the whole stimulus. The *Tag's* position and extent do not apply to the stimulus trace. 
 
 .. _tagged_feature:
 
@@ -72,8 +72,8 @@ different flags that define how this link has to be interpreted. In this case th
 position has to be used as an index in the first dimension of the Feature data. The **LinkType** has to be set to *indexed*.
 
 .. literalinclude:: examples/spikeFeatures.py
-    :lines: 135-147
-    :caption: From the stimulus, a set of snippets has been extracted and stored in 2D-DataArray. To be used as an ``Indexed`` feature it must be organized that the first dimension represents the number of snippets. The second dimension is the time. (:download:`example code <examples/spikeFeatures.py>`).
+    :lines: 130-135
+    :caption: From the stimulus, a set of snippets has been extracted and stored in a 2-D DataArray. To be used as an ``Indexed`` feature it must be organized that the first dimension represents the number of snippets. The second dimension is the time. (:download:`example code <examples/spikeFeatures.py>`).
 
 .. figure:: images/spike_features.png
     :alt: indexed feature