@@ -3,4 +3,95 @@ uid: data-elements
33title : Data Elements
44---
55
6- Data elements are produced by < xref:OpenEphys.Onix1 > Bonsai operators.
6+ Data elements are produced by < xref:OpenEphys.Onix1 > Bonsai operators. These
7+ pages contain information data elements that can help interpret and load data
8+ produced by < xref:dataio > .
9+
10+ In general, a data element comprises of properties which together contain
11+ timestamped data from a particular device. For example,
12+ < xref:OpenEphys.Onix1.Bno055Data > outputs
13+ [ Bno055DataFrames] ( xref:OpenEphys.Onix1.Bno055DataFrame ) which contains data
14+ produced by a BNO055 device:
15+ - The data produced by the BNO055 is contained in the Acceleration,
16+ Calibration, EulerAngle, Gravity, and Temperature properties of the
17+ Bno055DataFrame. Any of these properties can be individually selected and
18+ [ visualized] ( xref:visualize-data ) in Bonsai.
19+ - The < xref:OpenEphys.Onix1.DataFrame.Clock > property contains the precise
20+ hardware timestamp for the data in the properties described in the first
21+ bullet point created using the global ONIX Controller clock. This Clock
22+ property can be used to sync BNO055 data with data from all other devices
23+ from which ONIX is acquiring and put it all onto the same timeline.
24+ - The < xref:OpenEphys.Onix1.DataFrame.HubClock > property contains the precise
25+ hardware timestamp created using the clock on the hardware that contains
26+ the device.
27+
28+ There are some exceptions to the pattern described above. For example:
29+ - < xref:OpenEphys.Onix1.ContextTask > is an object passed through the
30+ configuration chain for writing to and reading from the ONIX hardware.
31+ - < xref:OpenEphys.Onix1.OutputClockParameters > outputs the parameters used to
32+ set the precise hardware output clock when the workflow starts.
33+
34+ These pages also describe the type of each property. This type information can
35+ be used to calculate the rate of data produced by the devices enabled in your
36+ experiment. For example, the < xref:OpenEphys.Onix1.NeuropixelsV2eData > operator
37+ (which outputs the data from a single Neuropixels 2.0 probe device) produces a
38+ sequence of
39+ [ NeuropixelsV2eDataFrames] ( xref:OpenEphys.Onix1.NeuropixelsV2eDataFrame ) . Using
40+ the fact that each sample comprises of a Clock property (8 bytes), a HubClock
41+ property (8 bytes), and an AmplifierData property (384* 2 bytes), this device's
42+ data rate is:
43+
44+ $$
45+ \begin{equation}
46+ \frac{2*384+8+8\,bytes}{sample}*\frac{30,000\,samples}{s}*\frac{1\,MB}{10^6bytes} = 23.52\,MB/s
47+ \label{eq:1x_npx2_bw}
48+ \end{equation}
49+ $$
50+
51+ NeuropixelsV2eDataFrame is actually a buffered data frame (as indicated by the
52+ presence of NeuropixelsV2eData's BufferSize property), meaning that several data
53+ samples and their timestamps are buffered into a single NeuropixelsV2eDataFrame.
54+ The above calculation was calculated under the assumption that
55+ NeuropixelsV2eData's BufferSize property is set to 1. Although the calculation
56+ is slightly different when BufferSize is more than 1, the end result ends up
57+ being the same. When BufferSize is more than 1, NeuropixelsV2eDataFrames are
58+ produced at a rate 30 kHz divided by the value of BufferSize. Each
59+ NeuropixelsV2eDataFrame comprises of:
60+
61+ - a Clock property: an array of <a class="xref external"
62+ href="https://learn.microsoft.com/dotnet/api/system.uint64 " target="_ blank"
63+ rel="noopener noreferrer nofollow">ulong</a > (each 8 bytes) of length N
64+ - a HubClock property: an array of <a class="xref external"
65+ href="https://learn.microsoft.com/dotnet/api/system.uint64 " target="_ blank"
66+ rel="noopener noreferrer nofollow">ulong</a > (each 8 bytes) of length N
67+ - an AmplifierData property: a
< xref:OpenCV.Net.Mat > of <a class="xref
68+ external" href="https://learn.microsoft.com/dotnet/api/system.uint16 "
69+ target="_ blank" rel="noopener noreferrer nofollow">ushort</a > (each 2 bytes)
70+ of size 384 x N
71+
72+ where N is a stand-in for BufferSize. Therefore, the calculation becomes:
73+
74+ $$
75+ \begin{equation}
76+ \frac{(2*384+8+8)*N\,bytes}{sample}*\frac{30,000/N\,samples}{s}*\frac{1\,MB}{10^6bytes} = 23.52\,MB/s
77+ \label{eq:1x_npx2_bw_buffersize}
78+ \end{equation}
79+ $$
80+
81+ N cancels out and the result is the same.
82+
83+ Knowing the type of each property can also be helpful in two more ways:
84+
85+ - A property's type indicates how a property can be used in Bonsai. Operators
86+ typically accept only a specific type or set of types as inputs. When types
87+ don't match, Bonsai indicates an error.
88+ - If a property is saved using a < xref:Bonsai.Dsp.MatrixWriter > (i.e. as a raw
89+ binary file), knowing its type informs how to load the data. For example,
90+ the [ dtypes] ( https://numpy.org/doc/stable/reference/arrays.dtypes.html ) in
91+ our [ example Breakout Board data-loading script] ( xref:breakout_load-data )
92+ were selected according to the size of each data being saved. For example,
93+ digital input clock samples are saved using 8 bytes which requires
94+ ` dt=np.uint64 ` when loading, and digital input pin samples are saved using a
95+ single byte which requires ` dt=np.uint8 ` when loading.
96+
97+
0 commit comments