Module: special_purpose

Special-purpose processing nodes.

Includes nodes that will only work in special circumstances or narrow use cases. Warning: The applicability of nodes in this category is often more limited than what may be apparent from their name, so be sure to read the description very carefully.

AddNoise

Add noise to the given data.

This adds Gaussian distributed noise to the given data values. This node can be used to test the behavior of various other nodes in the presence of noise. It can also be used as a workaround when the data is linearly dependent and some algorithms run into numerical issues as a result. The noise level is calibrated only on non-streaming (e.g., calibration) chunks. That is, to use this node in a live setting, you will need to use another node to first buffer up some calibration data (e.g., AccumulateCalibrationData), or to load pre-recorded calibration data from a file (InjectCalibrationData).

Version 1.0.0

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • relative_amplitude
    Relative noise level. This is the scale of the noise relative to the scale of the data.

    • verbose name: Relative Amplitude
    • default value: 0.01
    • port type: FloatPort
    • value type: float (can be None)

BatchPackets

Concatenate multiple successive packets to maintain real-time rates.

Many processing nodes in NeuroPype have a fixed per-chunk overhead, and therefore, if fewer but longer chunks are being processed, this overhead goes down, which can make the difference between the pipeline running in real time or not (note though that, in some cases, even when all overhead is eliminated, the pipeline can still run slower than real time if the cost of processing the actual streaming data is high enough, especially with high sampling rates, many channels, and heavy processing nodes -- in these cases, using this node will not be sufficient). Normally, the pipeline is driven by input plugins that output all data since the last update (e.g., LSL), which naturally increases the chunk size as necessary to maintain real-time rates, and in these cases this node is not necessary. However, when the pipeline is driven with a fixed chunk size that is too small for real time, this node can be inserted to merge successive chunks in order to achieve real-time behavior. Since this node concatenates chunks, the meta-data properties of the output chunk are picked from the last chunk that was concatenated. In general it is recommended to use the 'fixed' batching mode and pick a batch size that is enough to make the pipeline real time. It is also possible to use the 'real-time' mode, in which the first signal stream with time axis and no instance axis is used to infer by how much the stream is lagging relative to the current clock, and the chunk size is chosen adaptively. However, this requires that this node uses the same clock as the one from which the time stamps in the stream's time axis were read off -- otherwise the batching will misbehave badly due to clock drift and offset. This node offers multiple different clocks that you can choose from for this purpose. The simplest alternative to using this node is to instead use an input node that does return all new data since the last update, instead of a fixed chunk size.

Version 1.0.0

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • batching
    Batching mode. If set to 'fixed', then a fixed number of successive packets (batchsize) are merged together. If set to 'realtime', then as many packets are merged as necessary to maintain real-time processing, thus the batch size is adaptive. Note that you need to select the right clock for 'realtime' mode.

    • verbose name: Batching Mode
    • default value: fixed
    • port type: EnumPort
    • value type: object (can be None)
  • batchsize
    Number of successive packets to merge. Only used if batching is set to 'fixed'.

    • verbose name: Batch Size (Fixed Mode)
    • default value: 1
    • port type: IntPort
    • value type: int (can be None)
  • realtime_clock
    Type of real-time clock to use when using 'realtime' batching mode. This must be the same clock that was used to time-stamp the data that is received by this node. The two available clocks are the UTC clock (wall clock) and the LSL clock. When using UTC and the data comes from another computer, both clocks must be synchronized, e.g., using NTP. The LSL clock is synchronized across computers, if LSL was used to transmit the data.

    • verbose name: Clock Type (Realtime Mode)
    • default value: UTC
    • port type: EnumPort
    • value type: object (can be None)
  • max_input_lag
    Maximum acceptable input packet lag. If the lag is larger than this, the node will stash the packet and batch it with the next one (in 'realtime' mode). In seconds.

    • verbose name: Max Input Lag (Realtime Mode)
    • default value: 0.1
    • port type: FloatPort
    • value type: float (can be None)
  • max_output_lag
    Maximum acceptable delay incurred by batching packets, in seconds. If this amount of lag between the stream's data and the selected clock is exceeded, a packet will be emitted. This limits the maximum chunk size that can be generated, but if this threshold is reached, your processing system has problems (either your pipeline is not fast enough for real time, or you use the wrong clock).

    • verbose name: Max Output Lag (Realtime Mode)
    • default value: 1
    • port type: FloatPort
    • value type: float (can be None)
  • axis
    Axis to concatenate along. If set to 'auto', concatenation goes along the instance axis if present, or time axis otherwise.

    • verbose name: Concatenate Axis
    • default value: auto
    • port type: EnumPort
    • value type: object (can be None)

ChannelBaselineCalibration

This node can be used to "zero" an output signal based on some initial baseline calibration data.

A typical use case is when you have a pipeline that computes an output signal that may be positive or negative, e.g., imagined movement or emotional state, and that output is biased in an undesirable way (e.g., emotional state pegged to "excited"). In such cases you can place this node at the end, an just prior to using the pipeline you gather a baseline period where you know that the desired output should be zero (e.g., neutral emotional state). This node will then compute the average on each channel of the output in that period, store it, and from then on subtract that value from the signal, so that a neutral state yields the desired unbiased zero output. The assumption is that then the entire output range will be shifted roughly as desired (e.g., negative emotional state would be below zero, etc.). The node can also be used on non-streaming data, in which case the baseline will be calculated from the entire data.

Version 1.0.1

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • calib_length
    Data length for calibration. In seconds when applied to a time-domain signal, otherwise this is the number of instances/segments/trials to calibrate on.

    • verbose name: Calibration Duration
    • default value: 15
    • port type: IntPort
    • value type: int (can be None)
  • estimator
    Type of estimator to use. The median estimator is robust.

    • verbose name: Estimator
    • default value: mean
    • port type: EnumPort
    • value type: object (can be None)

ImpedanceChannelRejection

Remove bad channels based on their impedance.

This node is meant to be used on data recorded from hardware with built-in impedance measurement capabilities. Specifically, the data is assumed to have an embedded square wave that is aligned with the sampling time points of the system, and the amplitude of that square wave can be used to infer the impedance (i.e., electrical resistance) of the EEG/EXG sensor. As of this writing, only Cognionics hardware is known to be compatible with this node. If this filter is used on streaming data and has not yet been calibrated, then it will first buffer n seconds of calibration data to determine what channels to keep, before any output is produced. The set of retained channels is considered "trainable state", and can be saved in model files for later reuse.

Version 1.0.0

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • threshold
    Impedance threshold (Mohms). Channels with impedance higher than this will be rejected.

    • verbose name: Impedance Threshold
    • default value: 2
    • port type: IntPort
    • value type: int (can be None)
  • period
    Embedded impedance signal period (samples). This is the period, in samples, of the impedance signal that is embedded in the data by the sensor.

    • verbose name: Impedance Signal Period
    • default value: 4
    • port type: IntPort
    • value type: int (can be None)
  • unit_conversion
    Factor for converting signal units to volts. This is usually taken care of by the data acquisition system.

    • verbose name: Unit Conversion Factor
    • default value: 1e-06
    • port type: FloatPort
    • value type: float (can be None)
  • calib_seconds
    Minimum amount of data 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 compute its measures before any output is produced.

    • verbose name: Gather This Much Calibration Data
    • default value: 15
    • port type: IntPort
    • value type: int (can be None)

OneSampleBuffer

One sample buffer for control signals.

This is primarily meant to handle default values for multi-channel user-provided control signals that update at most once per tick (i.e., there is only one sample per tick). The initial value of the control signal is sourced from the initi_values argument, and thereafter the initial value is optionally updated based on the data of the input signal. There is a distinct 'null' value, which will not override the default values, to allow users to override the defaults only partially.

Version 1.0.0

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • initial_values
    These values are the initial values assigned to the output. The dict use channel names as the key values.

    • verbose name: Initial Values
    • default value: None
    • port type: DictPort
    • value type: dict (can be None)
  • null_value
    The null value. If the input signal has this value on some of its channels, the current value in the buffer will not be updated.

    • verbose name: Null Value
    • default value: nan
    • port type: FloatPort
    • value type: float (can be None)

ZMQInput

Read arbitrary data from a ZeroMQ socket.

This node should not be mistaken for a general-purpose network I/O node. This node is usually followed by a Demultiplex Packets node in order to receive multiple data packets, each of which may have one or more streams. Note: The ZeroMQ socket type is DEALER. The node is designed to operate as the receiver in an exclusive pair topology. Topologies other than exclusive pair are unsupported and will likely produce undefined behavior.

More Info...

Version 1.0.1

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Output signal.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: OUT
  • endpoint
    Endpoint on which to bind the ZeroMQ socket to listen for incoming messages to read. This is specified as a unique combination of protocol, host and port. For more information, see the ZeroMQ documentation.

    • verbose name: Endpoint
    • default value: tcp://127.0.0.1:10002
    • port type: StringPort
    • value type: str (can be None)
  • encoding
    Encoding type. Messages read from the bound ZeroMQ socket are decoded based on the value of this setting.

    • verbose name: Encoding
    • default value: pickle
    • port type: EnumPort
    • value type: object (can be None)
  • endpoint_override
    If set, this will override the value stored in endpoint.

    • verbose name: Endpoint Override
    • default value: tcp://*:10002
    • port type: StringPort
    • value type: str (can be None)
  • use_shared_socket
    Use a ZeroMQ socket that can be shared with an instance of the ZMQOutput node.

    • verbose name: Use Shared Socket
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • check_duplicate_messages
    Check for duplicate messages.

    • verbose name: Check Duplicate Messages
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • blocking_read
    Block until data is available. By If False, the node returns an empty packet whenever no data is available on a given update. If set to True, this node will block, which allows to run NeuroPype in lock-step with the data sender.

    • verbose name: Blocking Read
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • verbose
    Verbose output.

    • verbose name: Verbose
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

ZMQOutput

Write arbitrary data to a ZeroMQ socket.

This node should not be mistaken for a general-purpose network I/O node. This node is usually preceded by a Multiplex Packets node in order to send multiple data packets, each of which may have one or more streams. Note: The ZeroMQ socket type is DEALER. The node is designed to operate as the receiver in an exclusive pair topology. Topologies other than exclusive pair are unsupported and will likely produce undefined behavior.

More Info...

Version 1.0.0

Ports/Properties

  • set_breakpoint
    Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

    • verbose name: Set Breakpoint (Debug Only)
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • data
    Data to send.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: object (can be None)
    • data direction: IN
  • endpoint
    Endpoint on which to connect the ZeroMQ socket to write outgoing messages. This is specified as a unique combination of protocol, host and port. For more information, see the ZeroMQ documentation.

    • verbose name: Endpoint
    • default value: tcp://127.0.0.1:10001
    • port type: StringPort
    • value type: str (can be None)
  • encoding
    Encoding type. Messages written to the connected ZeroMQ socket are encoded based on the value of this setting.

    • verbose name: Encoding
    • default value: pickle
    • port type: EnumPort
    • value type: object (can be None)
  • endpoint_override
    If set, this will override the value stored in endpoint. Can optionally contain the placeholder %(CPE_ZMQ_TARGET_HOST)s, which will be substituted with the value of the environment variable of same name, or the default string 'worker'.

    • verbose name: Endpoint Override
    • default value: tcp://%(CPE_ZMQ_TARGET_HOST)s:10001
    • port type: StringPort
    • value type: str (can be None)
  • use_shared_socket
    Use a ZeroMQ socket that can be shared with an instance of the ZMQOutput node.

    • verbose name: Use Shared Socket
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)