Clean up niscope usage documentation (#1981)

* Fix links in docs

* Fix links for README

* Back out usage links change

* Remove duplicated documentation

* Regenerate niscope README

* correct argument name mistake

* Clarify more performance as "faster fetching". May help users searching how to fetch fast, as well.

* Fix use of bolding of methods in usage doc

* Correct mistake in numpy usage codeblock. Each returned wfm was only 400 samples

* Add some more comments to the new example

* Remove fetch_into codeblock and reference example

* Regenerate

* Reword sentence about fetch  performance

* Reword new example description

Author: ni-jfitzger

docs/_static/niscope_usage.inc

@@ -21,81 +21,7 @@ The following is a basic example of using the **niscope** module to open a sessi
         # Find all record number 3
         rec3 = [wfm for wfm in waveforms if wfm.record == 3]
 
-The waveform returned from `fetch <niscope/class.html#fetch>`_ is a flat list of Python objects
-
-    - Attributes:
-
-        -  **relative_initial_x** (float) the time (in seconds) from the trigger to the first sample in the fetched waveform
-        -  **absolute_initial_x** (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.
-        -  **x_increment** (float) the time between points in the acquired waveform in seconds
-        -  **channel** (str) channel name this waveform was acquired from
-        -  **record** (int) record number of this waveform
-        -  **gain** (float) the gain factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        -  **offset** (float) the offset factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        - **samples** (array of float) floating point array of samples. Length will be of the actual samples acquired
-
-    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:
-
-        - index 0 = record 0, channel 0
-        - index 1 = record 0, channel 1
-        - index 2 = record 1, channel 0
-        - index 3 = record 1, channel 1
-        - etc.
-
-
-If you need more performance or need to work with `SciPy <https://www.scipy.org/>`_, you can use the `fetch_into()` method instead of `fetch()`. This
-method takes an already allocated `numpy <http://www.numpy.org/>`_ array and puts the acquired samples in it. Data types supported:
-
-    - `numpy.float64`
-    - `numpy.int8`
-    - `numpy.in16`
-    - `numpy.int32`
-
-.. code-block:: python
-
-    voltage_range = 1.0
-    record_length = 2000
-    channels = [0, 1]
-    num_channels = len(channels)
-    num_records = 5
-    wfm = numpy.ndarray(num_channels * record_length, dtype=numpy.int8)
-    session.configure_vertical(voltage_range, niscope.VerticalCoupling.AC)
-    session.configure_horizontal_timing(50000000, record_length, 50.0, num_records, True)
-    with session.initiate():
-        waveform_infos = session.channels[channels].fetch_into(wfm=wfm, num_records=num_records)
-
-The waveform_infos returned from `fetch_into <niscope/class.html#fetch-into>`_ is a 1D list of Python objects
-
-    - Attributes:
-
-        -  **relative_initial_x** (float) the time (in seconds) from the trigger to the first sample in the fetched waveform
-        -  **absolute_initial_x** (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.
-        -  **x_increment** (float) the time between points in the acquired waveform in seconds
-        -  **channel** (str) channel name this waveform was asquire from
-        -  **record** (int) record number of this waveform
-        -  **gain** (float) the gain factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        -  **offset** (float) the offset factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        - **samples** (numpy array of datatype used) floating point array of samples. Length will be of the actual samples acquired
-
-    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:
-
-        - index 0 = record 0, channel 0
-        - index 1 = record 0, channel 1
-        - index 2 = record 1, channel 0
-        - index 3 = record 1, channel 1
-        - etc.
+If you need faster fetch performance, or to directly interface with `SciPy <https://www.scipy.org/>`_, you can use the **fetch_into()** method instead of **fetch()**. See the fetch_into example.
 
 
 `Other usage examples can be found on GitHub. <https://github.com/ni/nimi-python/tree/master/src/niscope/examples>`_

docs/niscope/examples.rst

@@ -21,6 +21,15 @@ niscope_fetch_forever.py
    :encoding: utf8
    :caption: `(niscope_fetch_forever.py) <https://github.com/ni/nimi-python/blob/master/src/niscope/examples/niscope_fetch_forever.py>`_
 
+niscope_fetch_info.py
+---------------------
+
+.. literalinclude:: ../../src/niscope/examples/niscope_fetch_info.py
+   :language: python
+   :linenos:
+   :encoding: utf8
+   :caption: `(niscope_fetch_info.py) <https://github.com/ni/nimi-python/blob/master/src/niscope/examples/niscope_fetch_info.py>`_
+
 niscope_read.py
 ---------------
 

generated/niscope/README.rst

@@ -142,81 +142,7 @@ The following is a basic example of using the **niscope** module to open a sessi
         # Find all record number 3
         rec3 = [wfm for wfm in waveforms if wfm.record == 3]
 
-The waveform returned from `fetch <niscope/class.html#fetch>`_ is a flat list of Python objects
-
-    - Attributes:
-
-        -  **relative_initial_x** (float) the time (in seconds) from the trigger to the first sample in the fetched waveform
-        -  **absolute_initial_x** (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.
-        -  **x_increment** (float) the time between points in the acquired waveform in seconds
-        -  **channel** (str) channel name this waveform was acquired from
-        -  **record** (int) record number of this waveform
-        -  **gain** (float) the gain factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        -  **offset** (float) the offset factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        - **samples** (array of float) floating point array of samples. Length will be of the actual samples acquired
-
-    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:
-
-        - index 0 = record 0, channel 0
-        - index 1 = record 0, channel 1
-        - index 2 = record 1, channel 0
-        - index 3 = record 1, channel 1
-        - etc.
-
-
-If you need more performance or need to work with `SciPy <https://www.scipy.org/>`_, you can use the `fetch_into()` method instead of `fetch()`. This
-method takes an already allocated `numpy <http://www.numpy.org/>`_ array and puts the acquired samples in it. Data types supported:
-
-    - `numpy.float64`
-    - `numpy.int8`
-    - `numpy.in16`
-    - `numpy.int32`
-
-.. code-block:: python
-
-    voltage_range = 1.0
-    record_length = 2000
-    channels = [0, 1]
-    num_channels = len(channels)
-    num_records = 5
-    wfm = numpy.ndarray(num_channels * record_length, dtype=numpy.int8)
-    session.configure_vertical(voltage_range, niscope.VerticalCoupling.AC)
-    session.configure_horizontal_timing(50000000, record_length, 50.0, num_records, True)
-    with session.initiate():
-        waveform_infos = session.channels[channels].fetch_into(wfm=wfm, num_records=num_records)
-
-The waveform_infos returned from `fetch_into <niscope/class.html#fetch-into>`_ is a 1D list of Python objects
-
-    - Attributes:
-
-        -  **relative_initial_x** (float) the time (in seconds) from the trigger to the first sample in the fetched waveform
-        -  **absolute_initial_x** (float) timestamp (in seconds) of the first fetched sample. This timestamp is comparable between records and acquisitions; devices that do not support this parameter use 0 for this output.
-        -  **x_increment** (float) the time between points in the acquired waveform in seconds
-        -  **channel** (str) channel name this waveform was asquire from
-        -  **record** (int) record number of this waveform
-        -  **gain** (float) the gain factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        -  **offset** (float) the offset factor of the given channel; useful for scaling binary data with the following formula:
-
-                voltage = binary data * gain factor + offset
-
-        - **samples** (numpy array of datatype used) floating point array of samples. Length will be of the actual samples acquired
-
-    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:
-
-        - index 0 = record 0, channel 0
-        - index 1 = record 0, channel 1
-        - index 2 = record 1, channel 0
-        - index 3 = record 1, channel 1
-        - etc.
+If you need faster fetch performance, or to directly interface with `SciPy <https://www.scipy.org/>`_, you can use the **fetch_into()** method instead of **fetch()**. See the fetch_into example.
 
 
 `Other usage examples can be found on GitHub. <https://github.com/ni/nimi-python/tree/master/src/niscope/examples>`_

src/niscope/examples/niscope_fetch_info.py

@@ -0,0 +1,61 @@
+#!/usr/bin/python
+
+import argparse
+import niscope
+import numpy
+import pprint
+import sys
+
+pp = pprint.PrettyPrinter(indent=4, width=80)
+
+
+def example(resource_name, channels, options, length, voltage):
+    # fetch_into() allows you to preallocate and reuse the destination of the fetched waveforms, which can result in better performance at the expense of the usability of fetch().
+    channels = [ch.strip() for ch in channels.split(",")]
+    num_channels = len(channels)
+    num_records = 5
+    total_num_wfms = num_channels * num_records
+    # preallocate a single array for all samples in all waveforms
+    # Supported array types are: numpy.float64, numpy.int8, numpy.int16, numpy.int32
+    # int8, int16, int32 are for fetching unscaled data, which is the fastest way to fetch.
+    # Gain and Offset are stored in the returned WaveformInfo objects and can be applied to the data by the user later.
+    wfm = numpy.ndarray(length * total_num_wfms, dtype=numpy.float64)
+    with niscope.Session(resource_name=resource_name, options=options) as session:
+        session.configure_vertical(range=voltage, coupling=niscope.VerticalCoupling.AC)
+        session.configure_horizontal_timing(min_sample_rate=50000000, min_num_pts=length, ref_position=50.0, num_records=num_records, enforce_realtime=True)
+        with session.initiate():
+            waveforms = session.channels[channels].fetch_into(waveform=wfm, num_records=num_records)
+        for i in range(len(waveforms)):
+            print(f'Waveform {i} information:')
+            print(f'{waveforms[i]}\n\n')
+            print(f'Samples: {waveforms[i].samples.tolist()}')
+
+
+def _main(argsv):
+    parser = argparse.ArgumentParser(description='Fetches data directly into a preallocated numpy array.', formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    parser.add_argument('-n', '--resource-name', default='PXI1Slot2', help='Resource name of an NI digitizer.')
+    parser.add_argument('-c', '--channels', default='0', help='Channel(s) to use')
+    parser.add_argument('-l', '--length', default=100, type=int, help='Measure record length')
+    parser.add_argument('-v', '--voltage', default=1.0, type=float, help='Voltage range (V)')
+    parser.add_argument('-op', '--option-string', default='', type=str, help='Option string')
+    args = parser.parse_args(argsv)
+    example(args.resource_name, args.channels, args.option_string, args.length, args.voltage)
+
+
+def main():
+    _main(sys.argv[1:])
+
+
+def test_example():
+    options = {'simulate': True, 'driver_setup': {'Model': '5164', 'BoardType': 'PXIe', }, }
+    example('PXI1Slot2', '0, 1', options, 100, 1.0)
+
+
+def test_main():
+    cmd_line = ['--option-string', 'Simulate=1, DriverSetup=Model:5164; BoardType:PXIe', ]
+    _main(cmd_line)
+
+
+if __name__ == '__main__':
+    main()
+