{"action":"created","comment":{"url":"https://api.github.com/repos/ni/nimi-python/pulls/comments/171689013","pull_request_review_id":100587594,"id":171689013,"diff_hunk":"@@ -10,8 +10,98 @@ The following is a basic example of using the **niscope** module to open a sessi\n         session.configure_vertical(range=1.0, coupling=niscope.VerticalCoupling.AC)\n         session.configure_horizontal_timing(min_sample_rate=50000000, min_num_pts=1000, ref_position=50.0, num_records=1, enforce_realtime=True)\n         with session.initiate():\n-            wfm, wfm_infos = session[args.channels].fetch(num_samples=args.length)\n-        print('Number of samples acquired: {:,}\\n'.format(len(wfm)))\n+            waveforms = session[[0,1]].fetch()\n+        print('Number of samples acquired: {:,}\\n'.format(len(waveforms.wfm)))\n+\n+The waveform returned from `fetch <http://nimi-python.readthedocs.io/en/master/niscope/functions.html#niscope.Session.fetch>`_ is a 1D list of Python objects\n+\n+    - Attributes:\n+\n+        -  **relative_initial_x** the time (in seconds) from the trigger to the first sample in the fetched waveform\n+        -  **absolute_initial_x** 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.\n+        -  **x_increment** the time between points in the acquired waveform in seconds\n+        -  **actual_samples** the actual number of samples fetched and placed in the waveform array\n+        -  **gain** the gain factor of the given channel; useful for scaling binary data with the following formula:\n+\n+            .. math::\n+\n+                voltage = binary data * gain factor + offset\n+\n+        -  **offset** the offset factor of the given channel; useful for scaling binary data with the following formula:\n+\n+            .. math::\n+\n+                voltage = binary data * gain factor + offset\n+\n+        - **wfm** floating point array of samples\n+\n+    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:\n+\n+        - index 0 = record 0, channel 0\n+        - index 1 = record 0, channel 1\n+        - index 2 = record 1, channel 0\n+        - index 3 = record 1, channel 1\n+        - etc.\n+\n+\n+If you need more performance, need to work with `SciPy <https://www.scipy.org/>`_, or are concerned about memory usage, you can use the `fetch_into()` method instead of `fetch()`. This\n+method takes an already allocated `numpy <http://www.numpy.org/>`_ array and puts the acquired samples in it. Data types supported:\n+\n+    - `numpy.float64`\n+    - `numpy.int8`\n+    - `numpy.in16`\n+    - `numpy.int32`\n+\n+.. code-block:: python\n+\n+    voltage_range = 1.0\n+    record_length = 2000\n+    channels = [0,1]\n+    num_channels = len(channels)\n+    wfm = numpy.ndarray(num_channels * record_length, dtype=numpy.int8)\n+    session.configure_vertical(voltage_range, niscope.VerticalCoupling.AC)\n+    session.configure_horizontal_timing(50000000, record_length, 50.0, 1, True)\n+    with session.initiate():\n+        waveform_infos = session.channels[channels].fetch_into(wfm=wfm)\n+\n+The waveform_infos returned from `fetch_into <http://nimi-python.readthedocs.io/en/master/niscope/functions.html#niscope.Session.fetch_into>`_ is a 1D list of Python objects\n+\n+    - Attributes:\n+\n+        -  **relative_initial_x** the time (in seconds) from the trigger to the first sample in the fetched waveform\n+        -  **absolute_initial_x** 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.\n+        -  **x_increment** the time between points in the acquired waveform in seconds\n+        -  **actual_samples** the actual number of samples fetched and placed in the waveform array\n+        -  **gain** the gain factor of the given channel; useful for scaling binary data with the following formula:\n+\n+            .. math::\n+\n+                voltage = binary data * gain factor + offset\n+\n+        -  **offset** the offset factor of the given channel; useful for scaling binary data with the following formula:\n+\n+            .. math::\n+\n+                voltage = binary data * gain factor + offset\n+\n+    - Such that all record 0 waveforms are first. For example, with a channel list of 0,1, you would have the following index values:\n+\n+        - index 0 = record 0, channel 0\n+        - index 1 = record 0, channel 1\n+        - index 2 = record 1, channel 0\n+        - index 3 = record 1, channel 1\n+        - etc.\n+\n+\n+.. note:: Unlike the normal `fetch()` the waveform_infos objects do not include the waveform for that record. Instead, samples are in the waveform passed into the function using the following layout:","path":"docs/_static/niscope_usage.inc","position":89,"original_position":89,"commit_id":"047c3285a4792ac84c1d7bf0d6df2a33b14db794","original_commit_id":"bf1d4b883e09eb0f079d5387148bf6d7c18bf411","user":{"login":"marcoskirsch","id":8085768,"avatar_url":"https://avatars0.githubusercontent.com/u/8085768?v=4","gravatar_id":"","url":"https://api.github.com/users/marcoskirsch","html_url":"https://github.com/marcoskirsch","followers_url":"https://api.github.com/users/marcoskirsch/followers","following_url":"https://api.github.com/users/marcoskirsch/following{/other_user}","gists_url":"https://api.github.com/users/marcoskirsch/gists{/gist_id}","starred_url":"https://api.github.com/users/marcoskirsch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/marcoskirsch/subscriptions","organizations_url":"https://api.github.com/users/marcoskirsch/orgs","repos_url":"https://api.github.com/users/marcoskirsch/repos","events_url":"https://api.github.com/users/marcoskirsch/events{/privacy}","received_events_url":"https://api.github.com/users/marcoskirsch/received_events","type":"User","site_admin":false},"body":"That's fair.\r\nBut for the Python 3 user, it makes fetch more different from fetch_into than it needs to be. And it makes fetch_into harder to use than it needs to be. I think it's more likely for a client of niscope to stick to one version of Python and call both methods in client code than to switch between versions of Python and stick to one fetch flavor.\r\n\r\nThe difference between Python versions would need to be documented of course.","created_at":"2018-03-01T20:48:17Z","updated_at":"2018-03-01T20:48:18Z","html_url":"https://github.com/ni/nimi-python/pull/755#discussion_r171689013","pull_request_url":"https://api.github.com/repos/ni/nimi-python/pulls/755","author_association":"MEMBER","_links":{"self":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/comments/171689013"},"html":{"href":"https://github.com/ni/nimi-python/pull/755#discussion_r171689013"},"pull_request":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/755"}},"in_reply_to_id":171676944},"pull_request":{"url":"https://api.github.com/repos/ni/nimi-python/pulls/755","id":172311740,"html_url":"https://github.com/ni/nimi-python/pull/755","diff_url":"https://github.com/ni/nimi-python/pull/755.diff","patch_url":"https://github.com/ni/nimi-python/pull/755.patch","issue_url":"https://api.github.com/repos/ni/nimi-python/issues/755","number":755,"state":"open","locked":false,"title":"Add documentation for niscope fetch() and fetch_into() on usage page","user":{"login":"texasaggie97","id":11483903,"avatar_url":"https://avatars1.githubusercontent.com/u/11483903?v=4","gravatar_id":"","url":"https://api.github.com/users/texasaggie97","html_url":"https://github.com/texasaggie97","followers_url":"https://api.github.com/users/texasaggie97/followers","following_url":"https://api.github.com/users/texasaggie97/following{/other_user}","gists_url":"https://api.github.com/users/texasaggie97/gists{/gist_id}","starred_url":"https://api.github.com/users/texasaggie97/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/texasaggie97/subscriptions","organizations_url":"https://api.github.com/users/texasaggie97/orgs","repos_url":"https://api.github.com/users/texasaggie97/repos","events_url":"https://api.github.com/users/texasaggie97/events{/privacy}","received_events_url":"https://api.github.com/users/texasaggie97/received_events","type":"User","site_admin":false},"body":"- [X] This contribution adheres to [CONTRIBUTING.md](https://github.com/ni/nimi-python/blob/master/CONTRIBUTING.md).\r\n- [X] I've updated [CHANGELOG.md](https://github.com/ni/nimi-python/blob/master/CHANGELOG.md) if applicable.\r\n- [X] I've added tests applicable for this pull request\r\n### What does this Pull Request accomplish?\r\n* Add usage documentation and example code for `fetch()` and `fetch_into()`\r\n### List issues fixed by this Pull Request below, if any.\r\n* Partial for #728 \r\n\r\n### What testing has been done?\r\n* Visual inspection of generated documentation","created_at":"2018-03-01T18:07:19Z","updated_at":"2018-03-01T20:48:18Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a3ee47f82f9d86c8b6fb8dad81612a67db9f40ca","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/ni/nimi-python/pulls/755/commits","review_comments_url":"https://api.github.com/repos/ni/nimi-python/pulls/755/comments","review_comment_url":"https://api.github.com/repos/ni/nimi-python/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ni/nimi-python/issues/755/comments","statuses_url":"https://api.github.com/repos/ni/nimi-python/statuses/047c3285a4792ac84c1d7bf0d6df2a33b14db794","head":{"label":"ni:docs/fancy_fetch","ref":"docs/fancy_fetch","sha":"047c3285a4792ac84c1d7bf0d6df2a33b14db794","user":{"login":"ni","id":5598284,"avatar_url":"https://avatars3.githubusercontent.com/u/5598284?v=4","gravatar_id":"","url":"https://api.github.com/users/ni","html_url":"https://github.com/ni","followers_url":"https://api.github.com/users/ni/followers","following_url":"https://api.github.com/users/ni/following{/other_user}","gists_url":"https://api.github.com/users/ni/gists{/gist_id}","starred_url":"https://api.github.com/users/ni/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ni/subscriptions","organizations_url":"https://api.github.com/users/ni/orgs","repos_url":"https://api.github.com/users/ni/repos","events_url":"https://api.github.com/users/ni/events{/privacy}","received_events_url":"https://api.github.com/users/ni/received_events","type":"Organization","site_admin":false},"repo":{"id":91020334,"name":"nimi-python","full_name":"ni/nimi-python","owner":{"login":"ni","id":5598284,"avatar_url":"https://avatars3.githubusercontent.com/u/5598284?v=4","gravatar_id":"","url":"https://api.github.com/users/ni","html_url":"https://github.com/ni","followers_url":"https://api.github.com/users/ni/followers","following_url":"https://api.github.com/users/ni/following{/other_user}","gists_url":"https://api.github.com/users/ni/gists{/gist_id}","starred_url":"https://api.github.com/users/ni/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ni/subscriptions","organizations_url":"https://api.github.com/users/ni/orgs","repos_url":"https://api.github.com/users/ni/repos","events_url":"https://api.github.com/users/ni/events{/privacy}","received_events_url":"https://api.github.com/users/ni/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ni/nimi-python","description":"Python bindings for NI Modular Instrument drivers.","fork":false,"url":"https://api.github.com/repos/ni/nimi-python","forks_url":"https://api.github.com/repos/ni/nimi-python/forks","keys_url":"https://api.github.com/repos/ni/nimi-python/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ni/nimi-python/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ni/nimi-python/teams","hooks_url":"https://api.github.com/repos/ni/nimi-python/hooks","issue_events_url":"https://api.github.com/repos/ni/nimi-python/issues/events{/number}","events_url":"https://api.github.com/repos/ni/nimi-python/events","assignees_url":"https://api.github.com/repos/ni/nimi-python/assignees{/user}","branches_url":"https://api.github.com/repos/ni/nimi-python/branches{/branch}","tags_url":"https://api.github.com/repos/ni/nimi-python/tags","blobs_url":"https://api.github.com/repos/ni/nimi-python/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ni/nimi-python/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ni/nimi-python/git/refs{/sha}","trees_url":"https://api.github.com/repos/ni/nimi-python/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ni/nimi-python/statuses/{sha}","languages_url":"https://api.github.com/repos/ni/nimi-python/languages","stargazers_url":"https://api.github.com/repos/ni/nimi-python/stargazers","contributors_url":"https://api.github.com/repos/ni/nimi-python/contributors","subscribers_url":"https://api.github.com/repos/ni/nimi-python/subscribers","subscription_url":"https://api.github.com/repos/ni/nimi-python/subscription","commits_url":"https://api.github.com/repos/ni/nimi-python/commits{/sha}","git_commits_url":"https://api.github.com/repos/ni/nimi-python/git/commits{/sha}","comments_url":"https://api.github.com/repos/ni/nimi-python/comments{/number}","issue_comment_url":"https://api.github.com/repos/ni/nimi-python/issues/comments{/number}","contents_url":"https://api.github.com/repos/ni/nimi-python/contents/{+path}","compare_url":"https://api.github.com/repos/ni/nimi-python/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ni/nimi-python/merges","archive_url":"https://api.github.com/repos/ni/nimi-python/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ni/nimi-python/downloads","issues_url":"https://api.github.com/repos/ni/nimi-python/issues{/number}","pulls_url":"https://api.github.com/repos/ni/nimi-python/pulls{/number}","milestones_url":"https://api.github.com/repos/ni/nimi-python/milestones{/number}","notifications_url":"https://api.github.com/repos/ni/nimi-python/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ni/nimi-python/labels{/name}","releases_url":"https://api.github.com/repos/ni/nimi-python/releases{/id}","deployments_url":"https://api.github.com/repos/ni/nimi-python/deployments","created_at":"2017-05-11T20:24:33Z","updated_at":"2018-02-26T22:17:33Z","pushed_at":"2018-03-01T20:42:24Z","git_url":"git://github.com/ni/nimi-python.git","ssh_url":"git@github.com:ni/nimi-python.git","clone_url":"https://github.com/ni/nimi-python.git","svn_url":"https://github.com/ni/nimi-python","homepage":"","size":4916,"stargazers_count":17,"watchers_count":17,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":5,"mirror_url":null,"archived":false,"open_issues_count":66,"license":{"key":"other","name":"Other","spdx_id":null,"url":null},"forks":5,"open_issues":66,"watchers":17,"default_branch":"master"}},"base":{"label":"ni:master","ref":"master","sha":"c6f0be895e5b9f9b4188fde51ea93c0089ee3f5f","user":{"login":"ni","id":5598284,"avatar_url":"https://avatars3.githubusercontent.com/u/5598284?v=4","gravatar_id":"","url":"https://api.github.com/users/ni","html_url":"https://github.com/ni","followers_url":"https://api.github.com/users/ni/followers","following_url":"https://api.github.com/users/ni/following{/other_user}","gists_url":"https://api.github.com/users/ni/gists{/gist_id}","starred_url":"https://api.github.com/users/ni/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ni/subscriptions","organizations_url":"https://api.github.com/users/ni/orgs","repos_url":"https://api.github.com/users/ni/repos","events_url":"https://api.github.com/users/ni/events{/privacy}","received_events_url":"https://api.github.com/users/ni/received_events","type":"Organization","site_admin":false},"repo":{"id":91020334,"name":"nimi-python","full_name":"ni/nimi-python","owner":{"login":"ni","id":5598284,"avatar_url":"https://avatars3.githubusercontent.com/u/5598284?v=4","gravatar_id":"","url":"https://api.github.com/users/ni","html_url":"https://github.com/ni","followers_url":"https://api.github.com/users/ni/followers","following_url":"https://api.github.com/users/ni/following{/other_user}","gists_url":"https://api.github.com/users/ni/gists{/gist_id}","starred_url":"https://api.github.com/users/ni/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ni/subscriptions","organizations_url":"https://api.github.com/users/ni/orgs","repos_url":"https://api.github.com/users/ni/repos","events_url":"https://api.github.com/users/ni/events{/privacy}","received_events_url":"https://api.github.com/users/ni/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ni/nimi-python","description":"Python bindings for NI Modular Instrument drivers.","fork":false,"url":"https://api.github.com/repos/ni/nimi-python","forks_url":"https://api.github.com/repos/ni/nimi-python/forks","keys_url":"https://api.github.com/repos/ni/nimi-python/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ni/nimi-python/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ni/nimi-python/teams","hooks_url":"https://api.github.com/repos/ni/nimi-python/hooks","issue_events_url":"https://api.github.com/repos/ni/nimi-python/issues/events{/number}","events_url":"https://api.github.com/repos/ni/nimi-python/events","assignees_url":"https://api.github.com/repos/ni/nimi-python/assignees{/user}","branches_url":"https://api.github.com/repos/ni/nimi-python/branches{/branch}","tags_url":"https://api.github.com/repos/ni/nimi-python/tags","blobs_url":"https://api.github.com/repos/ni/nimi-python/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ni/nimi-python/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ni/nimi-python/git/refs{/sha}","trees_url":"https://api.github.com/repos/ni/nimi-python/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ni/nimi-python/statuses/{sha}","languages_url":"https://api.github.com/repos/ni/nimi-python/languages","stargazers_url":"https://api.github.com/repos/ni/nimi-python/stargazers","contributors_url":"https://api.github.com/repos/ni/nimi-python/contributors","subscribers_url":"https://api.github.com/repos/ni/nimi-python/subscribers","subscription_url":"https://api.github.com/repos/ni/nimi-python/subscription","commits_url":"https://api.github.com/repos/ni/nimi-python/commits{/sha}","git_commits_url":"https://api.github.com/repos/ni/nimi-python/git/commits{/sha}","comments_url":"https://api.github.com/repos/ni/nimi-python/comments{/number}","issue_comment_url":"https://api.github.com/repos/ni/nimi-python/issues/comments{/number}","contents_url":"https://api.github.com/repos/ni/nimi-python/contents/{+path}","compare_url":"https://api.github.com/repos/ni/nimi-python/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ni/nimi-python/merges","archive_url":"https://api.github.com/repos/ni/nimi-python/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ni/nimi-python/downloads","issues_url":"https://api.github.com/repos/ni/nimi-python/issues{/number}","pulls_url":"https://api.github.com/repos/ni/nimi-python/pulls{/number}","milestones_url":"https://api.github.com/repos/ni/nimi-python/milestones{/number}","notifications_url":"https://api.github.com/repos/ni/nimi-python/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ni/nimi-python/labels{/name}","releases_url":"https://api.github.com/repos/ni/nimi-python/releases{/id}","deployments_url":"https://api.github.com/repos/ni/nimi-python/deployments","created_at":"2017-05-11T20:24:33Z","updated_at":"2018-02-26T22:17:33Z","pushed_at":"2018-03-01T20:42:24Z","git_url":"git://github.com/ni/nimi-python.git","ssh_url":"git@github.com:ni/nimi-python.git","clone_url":"https://github.com/ni/nimi-python.git","svn_url":"https://github.com/ni/nimi-python","homepage":"","size":4916,"stargazers_count":17,"watchers_count":17,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":5,"mirror_url":null,"archived":false,"open_issues_count":66,"license":{"key":"other","name":"Other","spdx_id":null,"url":null},"forks":5,"open_issues":66,"watchers":17,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/755"},"html":{"href":"https://github.com/ni/nimi-python/pull/755"},"issue":{"href":"https://api.github.com/repos/ni/nimi-python/issues/755"},"comments":{"href":"https://api.github.com/repos/ni/nimi-python/issues/755/comments"},"review_comments":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/755/comments"},"review_comment":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ni/nimi-python/pulls/755/commits"},"statuses":{"href":"https://api.github.com/repos/ni/nimi-python/statuses/047c3285a4792ac84c1d7bf0d6df2a33b14db794"}},"author_association":"COLLABORATOR"}}
{"actor":{"display_login":"marcoskirsch"}}