open-ephys / plugin-GUI

Software for processing, recording, and visualizing multichannel electrophysiology data
https://open-ephys.org/gui
GNU General Public License v3.0
193 stars 683 forks source link

Inconsistent output file voltage scaling #472

Open stinos opened 3 years ago

stinos commented 3 years ago

As mentioned in the output format documentation the bitVolts value is normally used to convert to microVolts and that works ok for data from headstages (tested with Open Ephys Acquisition Board + Intan Rhd2132, recording from Rythm Node in gui) but for the analog input channels on said board the value 0.00015258789 is used (probably the constant found in RHD2000Thread::getAdcBitVolts) which leads to values in Volts instead.

Is it guaranteed that the Rythm Node is always going to do this in future versions (i.e. can we safely assume that if a channel comes from the ADC it must be treated as Volt), or would it ever be made consistent with the other sources and documentation?

jsiegle commented 3 years ago

Yes, the "ADC" channel bitVolts value will always convert to volts, whereas for "headstage" channels it will convert to microvolts. We are actually planning to change the nomenclature from "headstage" to "electrode" in the future, but the conversion convention will stay the same.

I updated the documentation pages for the Binary, Open Ephys, and NWB formats to note the volts vs. microvolts distinction. Is there somewhere else where the documentation was inconsistent?

stinos commented 3 years ago

Ok, thanks for clarifying!

One minor thing: the channel names can be changed, so the logic if channel name starts with ADC is not completely failsafe to determine the unit of a channel. Could look at the bitVolts value, but that would again mean making assumptions. I checked other things but none of the outputfiles seem to have something which clearly distinguishes channel types. I think the proper way would be to have the DataChannel::getChannelType() value written into the openephys/json/... files as well. Would that be an acceptible change? (I can make a PR for that).

I updated the documentation pages for the Binary, Open Ephys, and NWB formats to note the volts vs. microvolts distinction

Thanks!

Is there somewhere else where the documentation was inconsistent?

Not that I encountered, but searching github for bitVolts shows other locations, mainly data loaders like OpenEphys.py and load_open_ephys_data.m.

We are actually planning to change the nomenclature from "headstage" to "electrode" in the future

Sounds good, avoids confusion.

jsiegle commented 3 years ago

That's a good point. In the Binary format, the channel type is specified is specified in the structure.oebin file (although the units label is currently incorrect for ADC channels). In the Open Ephys format, the bitVolts is listed in the Continuous_Data.openephys file, but the channel type is not indicated by anything other than the name.

Instead of a PR, let's just leave this issue open. We are planning a bunch of recording-related improvements in the next release, and one of those will be to make sure that the bitVolts units are unambiguous.