[docs] example update for create_data_array api change

jgrewe · jgrewe · commit ca32f0a83e59 · 2021-07-02T11:15:49.000+02:00
diff --git a/docs/source/annotations.rst b/docs/source/annotations.rst
@@ -12,13 +12,13 @@ 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-22
+    :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: 25
+    :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. 
 
@@ -35,11 +35,11 @@ which leads to an output like this. The argument ``max_depth=-1`` notes that the
 The *Sections* add much like dictionaries. To access e.g. the "resting potential" of the cell we may call:
 
 .. literalinclude:: examples/annotations.py
-    :lines: 25
+    :lines: 26
 
 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: 29 - 32
+    :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.
diff --git a/docs/source/examples/annotations.py b/docs/source/examples/annotations.py
@@ -4,16 +4,15 @@ def main():
 
     nixfile = nixio.File.open("annotations.nix", mode=nixio.FileMode.Overwrite)
     block = nixfile.create_block("recording 1", "nix.session")
-    
+
     session = nixfile.create_section('recording session', 'odml.recording')
     session['experimenter'] = 'John Doe'
     session['recording date'] = '2014-01-01'
-    
+
     subject = session.create_section('subject', 'odml.subject')
     subject['id'] = 'mouse xyz'
 
     cell = subject.create_section('cell', 'odml.cell')
-    v = -64.5
     p = cell.create_property('resting potential', -64.5)
     p.uncertainty = 2.25
     p.unit = 'mV'
@@ -27,11 +26,10 @@ def main():
     print(block.metadata["subject"]["cell"]["resting potential"])
 
     print(session.find_sections(lambda s: s.name.lower() == "cell"))
-    
+
     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"])
     nixfile.close()
 
 if __name__ == "__main__":
     main()
-
diff --git a/docs/source/examples/categoryData.py b/docs/source/examples/categoryData.py
@@ -13,10 +13,7 @@ def create_data():
 
 def store(nixfile, data, categories):
     b = nixfile.create_block("test", "nix.session")
-    data_array = b.create_data_array("category data", "nix.categorical", data=data)
-    data_array.label = "temperature"
-    data_array.unit = "K"
-
+    data_array = b.create_data_array("category data", "nix.categorical", data=data, label="temperature", unit="K")
     data_array.append_set_dimension(categories)
 
     return data_array
diff --git a/docs/source/examples/continuousRecording.py b/docs/source/examples/continuousRecording.py
@@ -48,9 +48,8 @@ def main():
 
     nixfile = nixio.File.open("continuous_recording.nix", nixio.FileMode.Overwrite, compression=nixio.Compression.DeflateNormal)
     block = nixfile.create_block("Session 1", "nix.recording_session")
-    data_array = block.create_data_array("multichannel_data", "nix.sampled.multichannel", dtype=nixio.DataType.Double, shape=(chunk_samples, number_of_channels))
-    data_array.label = "voltage"
-    data_array.unit = "mV"
+    data_array = block.create_data_array("multichannel_data", "nix.sampled.multichannel", dtype=nixio.DataType.Double,
+                                         shape=(chunk_samples, number_of_channels), label="voltage", unit="mV")
     data_array.append_sampled_dimension(0.001, label="time", unit="s")
     data_array.append_set_dimension(labels=["channel %i" % i for i in range(number_of_channels)])
 
diff --git a/docs/source/examples/irregularlySampledData.py b/docs/source/examples/irregularlySampledData.py
@@ -52,9 +52,8 @@ def main():
     block = file.create_block("block name", "nix.session")
 
     # create a 'DataArray' to take the data, add some information about the signal
-    data = block.create_data_array("sinewave", "nix.irregular_sampled", data=values)
-    data.unit = "mV"
-    data.label = "voltage"
+    data = block.create_data_array("sinewave", "nix.irregular_sampled", data=values,
+                                   label="voltage", unit="mV")
     # add a descriptor for the xaxis
     data.append_range_dimension(ticks=times, label="time", unit="s")
 
diff --git a/docs/source/examples/multipleTimeSeries.py b/docs/source/examples/multipleTimeSeries.py
@@ -61,17 +61,11 @@ def main():
     block = file.create_block("block name", "nix.session")
     # create a 'DataArray' to take the data, add some information about the signal
     y = np.vstack((sine, cosine))
-    data = block.create_data_array("waveforms", "nix.regular_sampled.multiple_series", data=y)
-    data.unit = "mV"
-    data.label = "voltage"
+    data = block.create_data_array("waveforms", "nix.regular_sampled.multiple_series", data=y, label="voltage", unit="mV")
     # descriptor for first dimension is a set
-    set_dim = data.append_set_dimension()
-    set_dim.labels = ['sin', 'cos']
+    data.append_set_dimension(labels=['sin', 'cos'])
     # add a descriptor for the xaxis
-    dim = data.append_sampled_dimension(stepsize)
-    dim.unit = "s"
-    dim.label = "time"
-    dim.offset = 0.0  # optional
+    data.append_sampled_dimension(stepsize, offset=0.0, label="time", unit="s")
 
     # let's plot the data from the stored information
     plot_data(data)
diff --git a/docs/source/examples/multiple_points.py b/docs/source/examples/multiple_points.py
@@ -46,14 +46,10 @@ def main():
 
     nixfile = nixio.File.open("multiple_points.nix", nixio.FileMode.Overwrite)
     block = nixfile.create_block("recording session", "nix.session")
-    signal_array = block.create_data_array("signal", "nix.sampled", data=signal)
-    signal_array.label = "voltage"
-    signal_array.unit = "mV"
+    signal_array = block.create_data_array("signal", "nix.sampled", data=signal, label="voltage", unit="mV")
     signal_array.append_sampled_dimension(sampling_interval, label="time", unit="s")
 
-    event_array = block.create_data_array("threshold crossings", "nix.events.threshold_crossings", data=events)
-    event_array.label = "time"
-    event_array.unit = "s"
+    event_array = block.create_data_array("threshold crossings", "nix.events.threshold_crossings", data=events, label="time", unit="s")
     event_array.append_range_dimension_using_self()
 
     mtag = block.create_multi_tag("event tag", "nix.tag.events", event_array)
diff --git a/docs/source/examples/rangeDimensionLink.py b/docs/source/examples/rangeDimensionLink.py
@@ -13,9 +13,7 @@ def main():
     nixfile = nixio.File.open("range_link.nix", nixio.FileMode.Overwrite)
     b = nixfile.create_block("session", "nix.session")
 
-    data_array = b.create_data_array("event times", "nix.event.times", data=event_times)
-    data_array.label = "time"
-    data_array.unit = "s"
+    data_array = b.create_data_array("event times", "nix.event.times", data=event_times, label="time", unit="s")
     data_array.append_range_dimension_using_self()
 
     nixfile.close()
diff --git a/docs/source/examples/regularlySampledData.py b/docs/source/examples/regularlySampledData.py
@@ -54,9 +54,8 @@ def main():
     block = file.create_block("block name", "nix.session")
 
     # create a 'DataArray' to take the sinewave, add some information about the signal
-    data = block.create_data_array("sinewave", "nix.regular_sampled", data=y)
-    data.unit = "mV"
-    data.label = "voltage"
+    data = block.create_data_array("sinewave", "nix.regular_sampled", data=y,
+                                   label="voltage", unit="mV")
     # add a descriptor for the xaxis
     data.append_sampled_dimension(stepsize, label="time", unit="s", offset=0.0)
 
diff --git a/docs/source/examples/singleROI.py b/docs/source/examples/singleROI.py
@@ -69,12 +69,9 @@ def main():
     # create a 'DataArray' to take the sinewave, add some information about the signal
     data = block.create_data_array("lenna", "nix.image.rgb", data=img_data)
     # add descriptors for width, height and channels
-    height_dim = data.append_sampled_dimension(1)
-    height_dim.label = "height"
-    width_dim = data.append_sampled_dimension(1)
-    width_dim.label = "width"
-    color_dim = data.append_set_dimension()
-    color_dim.labels = channels
+    data.append_sampled_dimension(1, label="height")
+    data.append_sampled_dimension(1, label="width")
+    data.append_set_dimension(labels=channels)
 
     # create a Tag, position and extent must be 3-D since the data is 3-D
     position = [250, 250, 0]
diff --git a/docs/source/examples/spikeFeatures.py b/docs/source/examples/spikeFeatures.py
@@ -114,8 +114,7 @@ def main():
     block = file.create_block("block name", "nix.session")
 
     # create a 'DataArray' to take the membrane voltage
-    data = block.create_data_array("membrane voltage", "nix.regular_sampled.time_series", data=voltage)
-    data.label = "membrane voltage"
+    data = block.create_data_array("membrane voltage", "nix.regular_sampled.time_series", data=voltage, label="membrane voltage")
     # add descriptors for the time axis
     data.append_sampled_dimension(stepsize, label="time", unit="s")
 
@@ -128,9 +127,7 @@ def main():
     multi_tag.references.append(data)
 
     # save stimulus snippets in a DataArray
-    snippets = block.create_data_array("spike triggered stimulus", "nix.regular_sampled.multiple_series", data=sts)
-    snippets.label = "stimulus"
-    snippets.unit = "nA"
+    snippets = block.create_data_array("spike triggered stimulus", "nix.regular_sampled.multiple_series", data=sts, label="stimulus", unit="nA")
     snippets.append_set_dimension()
     snippets.append_sampled_dimension(stepsize, offset= -sta_offset * stepsize, label="time", unit="s")
 
diff --git a/docs/source/examples/spikeTagging.py b/docs/source/examples/spikeTagging.py
@@ -64,12 +64,11 @@ def plot_data(tag):
     block = file.create_block("block name", "nix.session")
 
     # create a 'DataArray' to take the membrane voltage
-    data = block.create_data_array("membrane voltage", "nix.regular_sampled.time_series", data=voltage)
-    data.label = "membrane voltage"
-    data.unit = "mV"
+    data = block.create_data_array("membrane voltage", "nix.regular_sampled.time_series", data=voltage, label="membrane voltage", unit="mV")
+
     # add descriptors for time axis
     data.append_sampled_dimension(time[1]-time[0], label="time", unit="s")
-    
+
     # create the positions DataArray
     positions = block.create_data_array("spike times", "nix.events.spike_times", data=spike_times)
     positions.append_range_dimension_using_self()
diff --git a/docs/source/examples/taggedFeature.py b/docs/source/examples/taggedFeature.py
@@ -60,9 +60,7 @@ def main():
     multi_tag.references.append(data)
 
     # save stimulus snippets in a DataArray
-    stimulus_array = block.create_data_array("stimulus", "nix.sampled", data=stimulus)
-    stimulus_array.label = "stimulus"
-    stimulus_array.unit = "nA"
+    stimulus_array = block.create_data_array("stimulus", "nix.sampled", data=stimulus, label="stimulus", unit="nA")
     # add a descriptor for the time axis
     stimulus_array.append_sampled_dimension(stepsize, label="time", unit="s")
 
diff --git a/docs/source/examples/untaggedFeature.py b/docs/source/examples/untaggedFeature.py
@@ -91,7 +91,7 @@ def plot_data(tag):
 
 
 if __name__ == '__main__':
-    stepsize = 0.0001 # s
+    stepsize = 0.0001  # s
     time, voltage, stimulus, stim_onset, stim_duration = fake_neuron(stepsize=stepsize)
 
     # create a new file overwriting any existing content
@@ -103,17 +103,15 @@ def plot_data(tag):
     block = file.create_block("block name", "nix.session")
 
     # create a 'DataArray' to take the membrane voltage
-    data = block.create_data_array("membrane voltage", "nix.sampled.time_series", data=voltage)
-    data.label = "membrane voltage"
-    data.unit = "mV"
+    data = block.create_data_array("membrane voltage", "nix.sampled.time_series", data=voltage,
+                                   label="membrane voltage", unit="mV")
     data.append_sampled_dimension(stepsize, label="time", unit="s")
-    
+
     # create a stimulus DataArray
-    stim = block.create_data_array("stimulus", "nix.sampled.time_series", data=stimulus)
-    stim.label = "stimulus current"
-    stim.unit = "nA"
+    stim = block.create_data_array("stimulus", "nix.sampled.time_series", data=stimulus,
+                                   label="current stimulus", unit="nA")
     stim.append_sampled_dimension(stepsize, label="time", unit="s")
-    
+
     # create the Tag to highlight the stimulus-on segment
     tag = block.create_tag("stimulus presentation", "nix.epoch.stimulus_presentation", [stim_onset])
     tag.extent = [stim_duration]
diff --git a/docs/source/spike_time_data.rst b/docs/source/spike_time_data.rst
@@ -32,7 +32,7 @@ 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.
 
 .. literalinclude:: examples/untaggedFeature.py
-    :lines: 115-127
+    :lines: 111-122
     :caption: Source code for this example: :download:`untaggedFeature.py <examples/untaggedFeature.py>`.
     :emphasize-lines: 13
 
diff --git a/docs/source/storing_data.rst b/docs/source/storing_data.rst
@@ -57,8 +57,7 @@ store data in it.
 .. literalinclude:: examples/regularlySampledData.py
    :caption: Storing data in a DataArray (:download:`example code <examples/regularlySampledData.py>`).
    :language: python
-   :lines: 57 - 62
-   :emphasize-lines: 2
+   :lines: 57 - 61
 
 As promised, the *DataArray* contains all information to create a basic plot (see the figure above).
 
@@ -145,8 +144,8 @@ added to the *DataArray* entity upon creation:
 
 .. literalinclude:: examples/regularlySampledData.py
    :language: python
-   :lines: 58 - 63
-   :emphasize-lines: 5
+   :lines: 57 - 60
+   :emphasize-lines: 4
    :caption: A dimension in which the data has been gathered in regular intervals is described using a *SampledDimension* (:download:`example code <examples/regularlySampledData.py>`  
 
 
@@ -163,7 +162,7 @@ the described dimension.
 
 .. literalinclude:: examples/categoryData.py
    :language: python
-   :lines: 16 - 20
+   :lines: 16 - 17
    :caption: A categorical data dimension is described with a *SetDimension* which (optionally) stores labels for each category (:download:`example code <examples/categoryData.py>`)
 
 
@@ -189,8 +188,8 @@ is created.
 .. literalinclude:: examples/irregularlySampledData.py
    :caption: Storing irregularly sampled data (:download:`example code <examples/irregularlySampledData.py>`).
    :language: python
-   :lines: 45 - 60
-   :emphasize-lines: 2, 16
+   :lines: 45 - 58
+   :emphasize-lines: 14
 
 **Note:** The *ticks* of a *RangeDimension* must be numeric and ascending.
 
@@ -203,10 +202,10 @@ For example these might be the times of action potentials (aka spikes) recorded
 In such cases the *RangeDimension* is set up to link to the *DataArray* itself.
 
 .. literalinclude:: examples/rangeDimensionLink.py
-   :lines: 12 - 19
+   :lines: 12 - 17
    :language: python
    :caption: A *RangeDimension* can link to a *DataArray* as a source of the ticks (:download:`exmaple code <examples/rangeDimensionLink.py>`). 
-   :emphasize-lines: 8
+   :emphasize-lines: 6
 
 In the highlighted line we use a convenience function to establish the link between the dimension descriptor and the 
 
@@ -306,7 +305,7 @@ The following code shows how this works.
 
 .. literalinclude:: examples/continuousRecording.py
    :caption: Extending *DataArray* size e.g while recording continuously (:download:`example code <examples/continuousRecording.py>`) 
-   :lines: 47-66
+   :lines: 49-65
    :language: python
 
 
diff --git a/docs/source/tagging.rst b/docs/source/tagging.rst
@@ -84,7 +84,7 @@ Often it is not a single point or region but a multitude of points that we want
 For storing this kind of data we need two *DataArrays*, the first stores the recorded signal, the other the events. Finally, a *MultiTag* entity is used to link both. One can use the event times stored in one of the *DataArrays* to tag multiple points in the other signal.
 
 .. literalinclude:: examples/multiple_points.py
-    :lines: 49-61
+    :lines: 49-56
     :caption: To mark several points in a recorded signal we use a *MultiTag* to bind the signal and event times ( :download:`example code <examples/multiple_points.py>`) 
 
 Creating the *MultiTag* is very similar to the creation of the simpler *Tag* above. The main difference is that the tagged positions are not stored in the *MultiTag* itself but we use the event *DataArray* (events in the code example) for this purpose. Finally, the signal *DataArray* is added to the list of references.
