FixSignalUnit¶
Infer and then correct the unit of an electrophysiological signal (e.g
., EEG). This node works for signals where we expect the data to be in a known characteristic value range, which is customizable (for example, between +/- 10 uV and +/- 100 uV in the case of EEG). To allow for more specificity and robustness against various kinds of artifacts (such as drifts or high-frequency noise), this node also allows selecting a characteristic frequency band in which the signal shall lie in the expected range. Also, for robustness against bad/non-representative channels (e.g., channels with unusually low or high signal amplitude), a fraction of bad channels is by default excluded. Using this information, the node can then estimate the most likely unit of the incoming data. This is often necessary because many file formats and vendors don't do a particularly good job at documenting and/or consistently setting the signal range that their data is measured in. This node can be used very early in the pipeline (basically right after import and/or real-time input). In case that the unit of the signal is rather ambiguous, the node will emit a warning and assume the more likely unit. It is possible to set this node to skip a stream where the unit is already specified in the stream's meta_unit property, though the default setting is to recompute the unit and override the setting in the stream's meta_unit property. The node requires calibration data, the length of which can be configured. The node works both offline and online, and in the online case, the node will collect the required amount of data first before outputting anything. Version 0.9.6
Ports/Properties¶
data¶
Data to process.
desired_unit¶
Desired unit of the signal. If set to keep, then the signal is not altered (but the inferred unit will be stored in the annotation).
characteristic_range¶
Characteristic amplitude range of the signal of interest in a given frequency range. The defaults are well suited for EEG data but are likely far from optimal for other signal modalities.
characteristic_range_unit¶
Unit of the given characteristic range.
characteristic_frequencies¶
Frequency range within which the characteristic signal lies. The default is well suited for EEG, but is likely far from optimal for other signal modalities.
max_bad_channels_fraction¶
Max fraction of bad channels. If the signal is known to be clean, this could be lowered, but it should not matter much.
calib_seconds¶
Amount of data, in seconds, to gather for calibration. When this filter is run online and has not yet been calibrated, then it will first buffer this many seconds of data in order to infer the unit before any output is produced.
emit_calib_data¶
Emit the data buffer that was used for calibration, after calibration is complete, in a single chunk. If False, this filter will discard the calibration data. Since this chunk can be quite long, it is often preferable to discard it in a real-time pipeline, but if subsequent nodes need to see the processed calibration data to calibrate themselves (quite likely the case), it needs to be emitted.
off_band_slack¶
Width of the transition region around the characteristic frequency band in Hz. Signal content in the frequencies within the neighboring regions flanking the characteristic band will also count towards the signal amplitude. The running time is inversely proportional to this number (i.e., 2x sharper falloffs around the characteristic band require 2x the compute time.). Note that if the minimum frequency is below this, this parameter will be ignored.
off_band_suppression¶
Off-band suppression in dB. Larger values will be able to attenuate larger artifacts in the signal outside the characteristic band.
force_override¶
Force recalculation of the unit even if it is already specified in the meta_unit property of the signal stream.
use_caching¶
Enable caching. This will use the results from the last time the same file was processed rather than recompute the unit.
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.