WIP Tutorials for np1e & np2e headstages (#50)

- Preliminary tutorials for np1e & np2e - it's a WIP but needs to go up so people have access to workflows
- tutorials organized into partial templates rather than an extended markdown
  file so that bits and pieces can be reused for
- enums templating fixed (issue #48)
- Also, add references to the GUI in the template

Author: cjsha

src/onix-bonsai-onix1

@@ -12,7 +12,7 @@ function extractEnumData(model) {
     .filter(child => child.type === 'field')
     .map(child => ({
       'field&value': child.syntax.content[0].value,
-      'enumDescription': [child.summary, child.remarks].join(''),
+      'description': [child.summary, child.remarks].join(''),
     }));
 }
 

template/ManagedReference.extension.js

@@ -2,6 +2,10 @@
 
 {{!master(layout/_master.tmpl)}}
 
+{{#isClass}}
 {{>partials/class}}
+{{/isClass}}
 
-{{>partials/enum}}
+{{#isEnum}}
+{{>partials/enum}}
+{{/isEnum}}

template/ManagedReference.html.primary.tmpl

@@ -1,8 +1,10 @@
 {{!master(layout/_master.tmpl)}}
 
+{{^tut}}
 <h1>{{title}}</h1>
+{{/tut}}
+
 {{#isGuide}}
-<br>
 
 {{#workflow}}
 {{#isDevice}}
@@ -36,4 +38,8 @@
 {{/visualize}}
 {{/isGuide}}
 
-{{{conceptual}}}
+{{#tut}}
+{{>partials/tutorials/main}}
+{{/tut}}
+
+{{{conceptual}}}

template/conceptual.html.primary.tmpl

@@ -1,5 +1,3 @@
-{{#isClass}}
-
 {{#oe.operator.configureDevice}}
 
 <div class="CAUTION alert alert-danger">
@@ -57,8 +55,8 @@
 <table>
 
   <tr>
-    <th style = "white-space: nowrap;">Property</th>
-    <th style = "white-space: nowrap;">Type</th> 
+    <th style="white-space: nowrap;">Property</th>
+    <th style="white-space: nowrap;">Type</th> 
     <th>Description</th>
   </tr>
 
@@ -82,8 +80,8 @@
 <table>
 
   <tr>
-    <th style = "white-space: nowrap;">Property</th>
-    <th style = "white-space: nowrap;">Type</th> 
+    <th style="white-space: nowrap;">Property</th>
+    <th style="white-space: nowrap;">Type</th> 
     <th>Description</th>
   </tr>
 
@@ -93,6 +91,4 @@
 
 </table>
 
-{{/oe.operator.hub}}
-
-{{/isClass}}
+{{/oe.operator.hub}}

template/partials/class.tmpl.partial

@@ -1,5 +1,3 @@
-{{#isEnum}}
-
 <h1 class="text-break">
   {{oe.name}}
   {{#sourceurl}}<a class="header-action link-secondary" title="View source" href="{{sourceurl}}"><i class="bi bi-code-slash"></i></a>{{/sourceurl}}
@@ -12,13 +10,13 @@
 <table>
 
   <tr>
-    <th style = "white-space: no-wrap">Field & Value</th>
+    <th style="white-space: no-wrap">Field & Value</th>
     <th>Description</th>
   </tr>
 
   {{#oe.enum}}
   <tr>
-    <td style = "white-space: no-wrap">
+    <td style="white-space: no-wrap">
       <code>
         {{{field&value}}}
       </code>
@@ -29,6 +27,4 @@
   </tr>
   {{/oe.enum}}
 
-</table>
-
-{{/isEnum}}
+</table>

template/partials/enum.tmpl.partial

@@ -0,0 +1,16 @@
+<h3> {{data}} </h3>
+
+<div class="workflow">
+    <p><img src="../workflows/examples/{{{operator}}}.bonsai" alt="{{{operator}}} Workflow"></p>
+</div>
+
+<p>{{{graphDescription}}}</p>
+
+<p>{{{operator}}} is configured as follows:</p>
+
+<ul>
+    <li><code>DeviceName</code> is set to "{{{configureOperator}}}/{{{operator}}}". This is the only selection available in the drop down menu because the configuration chain contains a single {{{hub}}}.</li>
+    {{#bufferSize}}<li><code>BufferSize</code> is set to {{{bufferSize}}}. {{{bufferSize}}} samples will be collected from each of the probe channels into a <a class="xref" ref="api/OpenEphys.Onix1.{{{operator}}}Frame.html">{{{operator}}}Frame</a> that is propagated downstream (each frame will contain a {{{bufferSize}}}-element Clock vector and a {{{bufferSize}}}-sample {{{data}}} data vector).<!---To learn how to decide the ideal <code>BufferSize</code> value, refer to <a class="xref" href="breakoutboard-tut.html#analog-inputs">the corresponding section in the Breakout Board Tutorial</a>.---></li>{{/bufferSize}}
+    {{#multiple}}<li><code>ProbeIndex</code> is set to "PortA". {{{operator}}} generates data from a {{{data}}} connected to the headstage's Port A.</li>{{/multiple}} 
+    {{#additionalConfiguration}}<li>{{{.}}}</li>{{/additionalConfiguration}}
+</ul>

template/partials/tutorials/device.tmpl.partial

@@ -0,0 +1,84 @@
+<h1> {{title}} </h1>
+
+{{#overview}}
+
+<p>In this example, we will explore the {{{hub}}}'s functionality by demoing its capabilities. The workflow below can by copy/pasted into the Bonsai editor using the clipboard icon in the top right. This workflow:</p>
+
+<ul>
+    {{#workflowFunctions}}
+    <li>{{{.}}}</li>
+    {{/workflowFunctions}}
+</ul>
+
+<div class="workflow">
+    <p><img src="../workflows/examples/{{{hubSnakeCase}}}.bonsai" alt="{{{hub}}} Workflow"></p>
+</div>
+
+<div class="TIP alert alert-info">
+    <h5>TIP</h5>
+    <p>If you want a less busy starting point for using the {{{hub}}} then have a look at the <a class="xref" href="../articles/hubs/{{{hubSnakeCase}}}.html">{{{operator}}}</a> in the user guide.</p>
+</div>
+
+{{/overview}}
+
+{{#configure}}
+
+<h2> Configuring the {{{hub}}} </h2>
+
+<p>We start by configuring the hardware using a configuration chain. This chain creates a hardware context using <a class="xref" href="../api/OpenEphys.Onix1.CreateContext.html">CreateContext</a>, adds a {{{hub}}} configuration using <a class="xref" href="../api/OpenEphys.Onix1.Configure{{{configureOperator}}}.html">{{{configureOperator}}}</a>, and then starts acquisition using <a class="xref" href="../api/OpenEphys.Onix1.StartAcquisition.html">StartAcquisition</a>. Here we break down each of these operators.</p>
+
+<div class="workflow">
+    <p><img src="../workflows/examples/{{{configureOperator}}}.bonsai" alt="{{{configureOperator}}} Workflow"></p>
+</div>
+
+<h3> CreateContext </h3>
+
+<p>The <a class="xref" href="../api/OpenEphys.Onix1.CreateContext.html">CreateContext</a> operator determines the device driver and host-computer index that the system communicates through. The <code>Driver</code> property is set to "riffa", which is the name of the the PCIe device used by ONIX. In our case, because we are using a single ONIX system, the the <code>Index</code> property is set to 0. If second system was used on the same computer, a second <a class="xref" href="../api/OpenEphys.Onix1.CreateContext.html">CreateContext</a> operator would be required and its <code>Index</code> property set to 1.</p>
+
+<h3> {{{configureOperator}}} </h3>
+
+<p>The <a class="xref" href="../api/OpenEphys.Onix1.Configure{{{configureOperator}}}.html">{{{configureOperator}}}</a> operator is used to configure the {{hub}}. Configuration settings for the {{hub}} can be examined and edited by clicking on the operator to open its property pane to the right of the editor. Expanding the members of the property pane allows you to configure each of the devices contained by the {{hub}}. 
+{{#gui}}This {{hub}} has a configuration GUI that can be accessed by following the <a class="xref" href="./{{hubSnakeCase}}-gui-tut.html">{{hub}} GUI Tutorial</a>.{{/gui}}
+{{^nonDefaultProperties}}In this demo, the {{hub}} properties are set to their default values.{{/nonDefaultProperties}}
+{{#nonDefaultProperties}}In this demo, the {{hub}} properties are set to their default values, except:{{/nonDefaultProperties}}</p>
+
+<ul>
+    {{#nonDefaultProperties}}<li>{{{.}}}</li>{{/nonDefaultProperties}}
+</ul>
+
+<p>Aside from the configuration operations, the output of the <a class="xref" href="../api/OpenEphys.Onix1.Configure{{{configureOperator}}}.html">{{{configureOperator}}}</a> operator is timestamped and then saved to a CSV file. This file will contain the wall-clock time that data collection start along with metadata concerning important system configuration settings.</p>
+
+<h3> StartAcquisition </h3>
+
+<p>The <a class="xref" href="../api/OpenEphys.Onix1.StartAcquisition.html">StartAcquisition</a> operator begins acquisition after the hardware has been configured. In this example, we are going to be capturing data from the {{{hub}}}. <!---To learn how to decide the ideal <code>ReadBlockSize</code> value, refer to <a class="xref" href="breakoutboard-tut.html#startacquisition">the corresponding section in the Breakout Board Tutorial</a>---><!---<a class="xref">Setting ReadBlockSize Tutorial</a>--->.</p>
+
+{{/configure}}
+
+<h2> Streaming data </h2>
+
+<p>The rest of the workflow concerns capturing data to and from the {{{hub}}}, using a set of discrete "processing graphs" that either produce data from hardware (inputs/sources) or accept data produced by software (outputs/sinks). We describe these graphs in the following sections.</p>
+
+<div class="TIP alert alert-info">
+    <h5>TIP</h5>
+    <p>When trying to understand a workflow's operation, its very useful to visualize the data that being generated by each operator. You can open an operator's visualizer by double clicking the node while the workflow is running. The type of visualizer that opens will depend on the type of data handled by the operator and whether or not the appropriate Design library has been installed.</p>
+</div>
+
+{{#dataIOOperators}}{{>partials/tutorials/device}}{{/dataIOOperators}}
+
+<!---
+<h2>Loading data</h2>
+<p>The following python script can be used to load and plot the data produced by the workflow described in this tutorial.</p>
+
+[!code-python[](../workflows/examples/load-breakoutboard.py)]
+
+<div class="NOTE alert alert-info">
+    <h5>NOTE</h5>
+    <p>This script will attempt to load entire files into arrays. For long recordings, data will need to be split into more manageable chunks by:</p>
+    <ul>
+        <li>Modifying this script to partially load files</li>
+        <li>Modifying the workflow to cyclically creating new files after a certain duration</li>
+    </ul>
+</div>
+--->
+
+

template/partials/tutorials/main.tmpl.partial

@@ -1,5 +1,39 @@
-# Headstage 64 Tutorial
+---
+uid: hs64-tut
+title: Headstage64 Tutorial
+tut: true
+hub: Headstage64
+hubSnakeCase: headstage64
+configureOperator: Headstage64
+overview: 
+    workflowFunctions: 
+        -   Configures the Headstage64.
+        -   Streams RHD2164, BNO055, and TS4231 data.
+        -   Triggers electrical and optical stimulation.
+---
 
-:::workflow 
-![Headstage64](../workflows/examples/Headstage64.bonsai)
-:::
+> [!NOTE]
+> This page is a WIP
+
+<!-- configure: 
+    nonDefaultProperties: 
+dataIOOperators: 
+    -   operator: PortStatus
+        data: Port Status
+        graphDescription: This processing graph generates data about the communication status between the headstage/miniscope and the ONIX data acquisition system, timestamps it, and writes it to a .csv file.
+    -   operator: Rhd2164Data
+        data: RHD2164
+        graphDescription: This processing graph generates data from the headstage's Rhd2164Data, 
+        bufferSize: 36
+    -   operator: Bno055Data
+        data: BNO055
+        graphDescription: This processing graph generates data from the headstage's BNO055, writes it to a .csv file, and selects <code>Quaternion</code> data to send to an operator that automatically commutates the tether if there is a proper commutator connection.
+    -   operator: Ts4231PositionData
+        data: TS4231 Position
+        graphDescription: This processing graph generates position data from the headstage's TS4231 data.
+        additionalConfiguration: 
+            -   <code>P</code> is set to (0, 0, 0)
+            -   <code>Q</code> is set to (1, 0, 0)
+    -   operator: Ts4231Data
+        data: TS4231
+        graphDescription: This processing graph data from the headstage's TS4231 data. -->

tutorials/headstage64-tut.md

@@ -1,5 +1,36 @@
-# NeuropixelsV1e Tutorial
+---
+uid: np1e-tut
+title: NeuropixelsV1e Headstage Tutorial
+tut: true
+hub: NeuropixelsV1e Headstage
+hubSnakeCase: neuropixelsv1e
+configureOperator: NeuropixelsV1eHeadstage
+overview: 
+    workflowFunctions: 
+        -   Configures the NeuropixelsV1e Headstage.
+        -   Streams Neuropixels 1.0 and BNO055 data.
+        -   Commutates the tether automatically if there is a proper commutator connection.
+configure: 
+    gui: false
+    nonDefaultProperties:
+dataIOOperators: 
+    -   operator: PortStatus
+        data: Port Status
+        graphDescription: This processing graph generates data about the communication status between the headstage and the ONIX data acquisition system, timestamps it, and writes it to a .csv file.
+    -   operator: NeuropixelsV1eData
+        data: Neuropixels 1.0
+        graphDescription: This processing graph generates data from one of the headstage's Neuropixels 2.0 probes, and selects the <code>Clock</code> and <code>AmplifierData</code> data to write to .bin files.
+        multiple: false
+        bufferSize: 36
+    -   operator: NeuropixelsV1eBno055Data
+        data: BNO055
+        graphDescription: This processing graph generates data from the headstage's BNO055, writes it to a .csv file, and selects <code>Quaternion</code> data to send to a node that commutates the tether automatically if there is a proper commutator connection. Because <code>CsvWriter</code> is a <code>Sink</code> operator, it emits the same item downstream as it receives from upstream. Therefore, Bno55DataFrame members can by selected by hovering over <code>Output</code> in the context menu that appears by right-clicking the <code>CsvWriter</code> node. 
+---
+<!---
+[!code-python[](../workflows/examples/load-np1.py)]
 
-:::workflow 
-![NeuropixelsV1e](../workflows/examples/NeuropixelsV1e.bonsai)
-:::
+> [!NOTE]
+> This script will attempt to load entire files into arrays. For long recordings, data will need to be split into more manageable chunks by:
+> - Modifying this script to partially load files
+> - Modifying the workflow to cyclically creating new files after a certain duration
+--->