Merge pull request #414 from open-ephys/issue-405

Add microvolt conversion equations

Author: jonnew

OpenEphys.Onix1/AnalogInputDataFrame.cs

@@ -21,8 +21,26 @@ public AnalogInputDataFrame(ulong[] clock, ulong[] hubClock, Mat analogData)
         }
 
         /// <summary>
-        /// Get the buffered analog data array.
+        /// Gets the buffered analog data array.
         /// </summary>
+        /// <remarks>
+        /// Analog samples are organized in 12xN matrix with rows representing channel number and
+        /// N columns representing samples acquired at 100 kHz. Each column is a 12-channel vector of ADC
+        /// samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. When <see
+        /// cref="AnalogInput.DataType"/> is set to <see cref="AnalogIODataType.Volts"/>, each sample is
+        /// internally converted to a voltage value and represented using a <see cref="float"/>. When <see
+        /// cref="AnalogInput.DataType"/> is set to <see cref="AnalogIODataType.S16"/>, each 16-bit ADC sample
+        /// is represented as a <see cref="short"/>. In this case, the following equation can be used to
+        /// convert a sample to volts:
+        /// <code> 
+        /// Channel Voltage (V) = ADC Sample × (Input Span / 2^16)
+        /// </code> 
+        /// where <c>Input Span</c> is 5V, 10V, or 20V  when the <see cref="AnalogIOVoltageRange"/> is set to
+        /// ±2.5V, ±5V, or ±10V, respectively. Note that <see cref="AnalogIOVoltageRange"/> can be set
+        /// independently for each channel in <see cref="ConfigureBreakoutBoard.AnalogIO"/>. Therefore, the
+        /// conversion factor may be different for each channel.
+        /// </remarks>
         public Mat AnalogData { get; }
     }
 

OpenEphys.Onix1/NeuropixelsV1DataFrame.cs

@@ -27,35 +27,46 @@ public NeuropixelsV1DataFrame(ulong[] clock, ulong[] hubClock, int[] frameCount,
         /// Gets the frame count value array.
         /// </summary>
         /// <remarks>
-        /// A 20-bit counter on the probe that increments its value for every frame produced.
-        /// The value ranges from 0 to 1048575 (2^20-1), and should always increment by 1 until it wraps around back to 0.
-        /// This can be used to detect dropped frames.
+        /// A 20-bit counter on the probe that increments its value for every "frame" produced by the probe.
+        /// Thirteen frames are produced for each 384-channel column of samples in  <see cref="SpikeData"/>.
+        /// The value ranges from 0 to 1048575 (2^20-1), and should always increment by 1 until it wraps
+        /// around back to 0. This can be used to detect dropped frames.
         /// </remarks>
         public int[] FrameCount { get; }
 
         /// <summary>
-        /// Gets the spike-band data as a <see cref="Mat"/> object.
+        /// Gets spike-band electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Spike-band data has 384 electrodes (rows) with columns representing the samples acquired at 30 kHz.
-        /// Each sample is a 10-bit, offset binary value encoded as a <see cref="ushort"/>. To convert to
-        /// microvolts, the following equation can be used:
-        /// <code>
-        /// V_electrode (uV) = 1171.875 uV / AP Gain × (ADC result – 512)
+        /// Spike-band (0.3-10 kHz) samples are organized in 384xN matrix with rows representing
+        /// channel number and N columns representing samples acquired at 30 kHz. Each column is a 384-channel
+        /// vector of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 10-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
+        /// <code> 
+        /// Electrode Voltage (µV) = (1,171.875 / AP Gain) × (ADC Sample – 512) 
         /// </code>
+        /// where <c>AP Gain</c> can be 50, 125, 250, 500, 1000, 1500, 2000, or 3000 depending on the value of <see
+        /// cref="NeuropixelsV1ProbeConfiguration.SpikeAmplifierGain"/>.
         /// </remarks>
         public Mat SpikeData { get; }
 
         /// <summary>
-        /// Gets the LFP band data as a <see cref="Mat"/> object.
+        /// Gets LFP-band electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// LFP-band data has 384 electrodes (rows) with columns representing the samples acquired at 2.5 kHz.
-        /// Each sample is a 10-bit, offset binary value encoded as a <see cref="ushort"/>. To convert to
-        /// microvolts, the following equation can be used:
-        /// <code>
-        /// V_electrode (uV) = 1171.875 uV / LFP Gain × (ADC result – 512)
+        /// LFP-band (0.5-500 Hz) samples are organized in 384xN matrix with rows representing channel
+        /// number and N columns representing samples acquired at 2.5 kHz. Each column is a 384-channel vector
+        /// of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 10-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
+        /// <code> 
+        /// Electrode Voltage (µV) = (1,171.875 / LFP Gain) × (ADC Sample – 512)
         /// </code>
+        /// where <c>LFP Gain</c> can be 50, 125, 250, 500, 1000, 1500, 2000, or 3000 depending on the value of <see
+        /// cref="NeuropixelsV1ProbeConfiguration.LfpAmplifierGain"/>.
         /// </remarks>
         public Mat LfpData { get; }
     }

OpenEphys.Onix1/NeuropixelsV2eBetaDataFrame.cs

@@ -4,7 +4,7 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Buffered data from a NeuropixelsV2e device.
+    /// Buffered data from a NeuropixelsV2-Beta probe.
     /// </summary>
     public class NeuropixelsV2eBetaDataFrame : BufferedDataFrame
     {
@@ -23,25 +23,29 @@ public NeuropixelsV2eBetaDataFrame(ulong[] clock, ulong[] hubClock, Mat amplifie
         }
 
         /// <summary>
-        /// Gets the amplifier data array.
+        /// Gets the buffered electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Wide band (0.5 Hz - 10 kHz) electrophysiology data array. Each element is an amplified sample from
-        /// 384 electrodes (rows) acquired at 30 kHz (columns). Each sample is a 14-bit, offset binary value
-        /// encoded as a <see cref="ushort"/>. To convert to microvolts, the following equation can be used:
+        /// Electrophysiology samples are organized in 384xN matrix with rows representing electrophysiology
+        /// channel number and N columns representing samples acquired at 30 kHz. Each column is a 384-channel
+        /// vector of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 14-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
         /// <code>
-        /// V_electrode (µV) = 0.76294 µV/bit × (ADC result – 8192) bits
+        /// Electrode Voltage (µV) = 0.76294 × (ADC Sample – 8192)
         /// </code>
         /// </remarks>
         public Mat AmplifierData { get; }
 
         /// <summary>
-        /// Gets the frame count array.
+        /// Gets the frame count value array.
         /// </summary>
         /// <remarks>
-        /// Frame count is a 20-bit counter on the probe that increments its value for every frame produced.
-        /// The value ranges from 0 to 1048575 (2^20-1), and should always increment by 1 until it wraps around back to 0.
-        /// This can be used to detect dropped frames.
+        /// A 20-bit counter on the probe that increments its value for every "frame" produced by the probe.
+        /// Sixteen frames are produced for each 384-channel column of samples in  <see cref="AmplifierData"/>.
+        /// The value ranges from 0 to 1048575 (2^20-1), and should always increment by 1 until it wraps
+        /// around back to 0. This can be used to detect dropped frames.
         /// </remarks>
         public int[] FrameCount { get; }
 

OpenEphys.Onix1/NeuropixelsV2eDataFrame.cs

@@ -4,7 +4,7 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Buffered data from a NeuropixelsV2e device.
+    /// Buffered data from a NeuropixelsV2 probe.
     /// </summary>
     public class NeuropixelsV2eDataFrame : BufferedDataFrame
     {
@@ -21,14 +21,17 @@ public NeuropixelsV2eDataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierDat
         }
 
         /// <summary>
-        /// Gets the amplifier data array.
+        /// Gets the buffered electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Wide band (0.5 Hz - 10 kHz) electrophysiology data array. Each element is an amplified sample from
-        /// 384 electrodes (rows) acquired at 30 kHz (columns). Each sample is a 12-bit, offset binary value
-        /// encoded as a <see cref="ushort"/>. To convert to microvolts, the following equation can be used:
+        /// Electrophysiology samples are organized in 384xN matrix with rows representing electrophysiology
+        /// channel number and N columns representing samples acquired at 30 kHz. Each column is a 384-channel
+        /// vector of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 12-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
         /// <code>
-        /// V_electrode (µV) = 3.05176 µV/bit × (ADC result – 2048) bits
+        /// Electrode Voltage (µV) = 3.05176 × (ADC Sample – 2048)
         /// </code>
         /// </remarks>
         public Mat AmplifierData { get; }

OpenEphys.Onix1/Nric1384DataFrame.cs

@@ -4,7 +4,7 @@
 namespace OpenEphys.Onix1
 {
     /// <summary>
-    /// Buffered data from a Nric1384 bioacquisition device.
+    /// Buffered data from a Nric1384 bioacquisition chip.
     /// </summary>
     public class Nric1384DataFrame : BufferedDataFrame
     {
@@ -28,29 +28,47 @@ public Nric1384DataFrame(ulong[] clock, ulong[] hubClock, int[] frameCount, Mat
         /// Gets the frame count value array.
         /// </summary>
         /// <remarks>
-        /// A 20-bit counter on the chip that increments its value for every frame produced. The value ranges from 0 to
-        /// 1048575 (2^20-1), and should always increment by 13 (one count is taken per super-frame and there are 13 frames 
-        /// in a super frame) until it wraps around back to 0. This can be used to detect dropped frames.
+        /// A 20-bit counter on the probe that increments its value for every "frame" produced by the probe.
+        /// Thirteen frames are produced for each 384-channel column of samples in  <see cref="SpikeData"/>.
+        /// The value ranges from 0 to 1048575 (2^20-1), and should always increment by 1 until it wraps
+        /// around back to 0. This can be used to detect dropped frames.
         /// </remarks>
         public int[] FrameCount { get; }
 
-
         /// <summary>
-        /// Gets the spike-band data as a <see cref="Mat"/> object.
+        /// Gets spike-band electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Spike-band data has 384 rows (channels) with columns representing the samples acquired at 30 kHz. Each sample is a
-        /// 10-bit, offset binary value encoded as a <see cref="ushort"/>.
+        /// Spike-band (0.3-10 kHz) samples are organized in 384xN matrix with rows representing
+        /// channel number and N columns representing samples acquired at 30 kHz. Each column is a 384-channel
+        /// vector of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 10-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
+        /// <code> 
+        /// Electrode Voltage (µV) = (1,171.875 / AP Gain) × (ADC Sample – 512) 
+        /// </code>
+        /// where <c>AP Gain</c> can be 50, 125, 250, 500, 1000, 1500, 2000, or 3000 depending on the value of <see
+        /// cref="ConfigureNric1384.SpikeAmplifierGain"/>.
         /// </remarks>
         public Mat SpikeData { get; }
 
 
         /// <summary>
-        /// Gets the LFP band data as a <see cref="Mat"/> object.
+        /// Gets LFP-band electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// LFP data has 32 rows (channels) with columns representing the samples acquired at 2.5 kHz. Each sample is a
-        /// 10-bit, offset binary value encoded as a <see cref="ushort"/>.
+        /// LFP-band (0.5-500 Hz) samples are organized in 384xN matrix with rows representing channel
+        /// number and N columns representing samples acquired at 2.5 kHz. Each column is a 384-channel vector
+        /// of ADC samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 10-bit, offset
+        /// binary value represented as a <see cref="ushort"/>. The following equation can be used to convert
+        /// a sample to microvolts:
+        /// <code> 
+        /// Electrode Voltage (µV) = (1,171.875 / LFP Gain) × (ADC Sample – 512)
+        /// </code>
+        /// where <c>LFP Gain</c> can be 50, 125, 250, 500, 1000, 1500, 2000, or 3000 depending on the value of <see
+        /// cref="ConfigureNric1384.LfpAmplifierGain"/>.
         /// </remarks>
         public Mat LfpData { get; }
     }

OpenEphys.Onix1/Rhd2164DataFrame.cs

@@ -26,22 +26,32 @@ public Rhd2164DataFrame(ulong[] clock, ulong[] hubClock, Mat amplifierData, Mat
         /// Gets the buffered electrophysiology data array.
         /// </summary>
         /// <remarks>
-        /// Each row corresponds to a channel. Each column corresponds to a sample whose time is indicated by
-        /// the corresponding element <see cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>.
-        /// Samples are 16-bits each and are represented using unsigned 16-bit integers. To convert to
-        /// micro-volts, the following equation can be used:
+        /// Electrophysiology samples are organized in 64xN matrix with rows representing electrophysiology
+        /// channel number and N columns representing sample index. Each column is a 64-channel vector of ADC
+        /// samples whose acquisition time is indicated by the corresponding elements in <see
+        /// cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 16-bit,
+        /// offset binary value encoded as a <see cref="ushort"/>. The following equation can be used to
+        /// convert a sample to microvolts:
         /// <code>
-        /// V_electrode (uV) = 0.195 µV × (ADC result – 32768)
+        /// Electrode Voltage (µV) = 0.195 × (ADC Sample – 32768)
         /// </code>
         /// </remarks>
         public Mat AmplifierData { get; }
 
         /// <summary>
-        /// Gets the buffered auxiliary data array.
+        /// Gets the buffered auxiliary data array. 
         /// </summary>
         /// <remarks>
-        /// Each row corresponds to a channel. Each column corresponds to a sample whose time is indicated by
-        /// the corresponding element <see cref="DataFrame.Clock"/> and <see cref="DataFrame.HubClock"/>.
+        /// Auxiliary samples are organized in 3xN matrix with rows representing electrophysiology channel
+        /// number and N columns representing sample index. Each column is a 3-channel vector of ADC samples
+        /// whose acquisition time is indicated by the corresponding elements in <see cref="DataFrame.Clock"/>
+        /// and <see cref="DataFrame.HubClock"/>. Each ADC sample is a 16-bit <see cref="ushort"/>. The
+        /// following equation can be used to convert a sample to volts:
+        /// <code>
+        /// Auxiliary Voltage (V) = 0.0000374 × ADC Sample
+        /// </code>
+        /// Note that auxiliary inputs have a 0.10-2.45V input range. Nonlinearities may occur if voltages
+        /// outside of this range are applied to auxiliary inputs.
         /// </remarks>
         public Mat AuxData { get; }
     }

OpenEphys.Onix1/Rhs2116Data.cs

@@ -11,7 +11,7 @@ namespace OpenEphys.Onix1
 {
     /// <summary>
     /// Produces a sequence of <see cref="Rhs2116DataFrame"/> objects with data from an Intan
-    /// Rhs2116 bioacquisition chip.
+    /// Rhs2116 bidirectional bioacquisition chip.
     /// </summary>
     /// <remarks>
     /// This data IO operator must be linked to an appropriate configuration, such as a <see
@@ -28,11 +28,11 @@ public class Rhs2116Data : Source<Rhs2116DataFrame>
         /// Gets or sets the buffer size.
         /// </summary>
         /// <remarks>
-        /// This property determines the number of samples that are collected from each of the 16 ephys
-        /// channels before data is propagated. For instance, if this value is set to 30, then 16x30 samples,
-        /// along with 30 corresponding clock values, will be collected and packed into each <see
-        /// cref="Rhs2116DataFrame"/>. Because channels are sampled at 30 kHz, this is equivalent to 1
-        /// millisecond of data from each channel.
+        /// This property determines the number of samples that are collected from each of the 16
+        /// electrophysiology channels before data is propagated. For instance, if this value is set to 30,
+        /// then 16x30 samples, along with 30 corresponding clock values, will be collected and packed into
+        /// each <see cref="Rhs2116DataFrame"/>. Because channels are sampled at 30 kHz, this is equivalent to
+        /// 1 millisecond of data from each channel.
         /// </remarks>
         public int BufferSize { get; set; } = 30;