Module: source_localization

EEG source localization algorithms and related nodes.

These are domain-specific nodes that are designed to solve the inverse problem of estimating the source activity given some EEG (or MEG) observations. Also includes some nodes that act on the resulting solutions (for instance, operate on regions of interest). This category also includes some nodes for managing location information.

AssignChannelLocations

Assign standard channel locations from a pre-defined sensor montage file.

For some devices (such as EEG headsets), specific channel labels correspond to well-known sensor locations, for example "Cz" in EEG is the sensor on the top of the head in the 10-20 labeling system. For each device, there may also be multiple alternative labeling systems (e.g., C3 for the 10-20 system would be in a different place than C3 in the BioSemi system). This node can open a specified montage file and look up the channel locations based on the channel labels in the data (assuming that at least the labels are set in the data), and if no montage file is given, this node can search through all known montages and find the file that best matches the data (in the sense that more of the channel labels in the data are found in the file than in other files). If there is significant ambiguity (e.g., multiple similarly well matching files), a warning will be emitted.

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
  • montage
    Optionally the montage file to use. If not given, the best-matching one will be searched (see node description for more information).

    • verbose name: Montage File (Optional)
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • force_override
    Force-override channel locations.

    • verbose name: Force Override
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)

ELORETA

Estimate brain source activity using the Exact Low-Resolution Brain Electromagnetic Tomography (eLORETA) algorithm.

This node accepts an EEG time series, and estimates for each time point the current source density (CSD) for a large number of locations (e.g., a few 1000) in the brain. The result is a time series with the EEG channels replaced by as many channels as there are source locations, and otherwise the same format as the input data. The set of source locations is defined by a headmodel, which is selectable via the headmodel_file parameter. Like sLORETA, this is a rather easy-to-use and very fast source estimation method. Important: the input data to this node should previously have been re-referenced to common average reference using the ReReferencing node (with default settings). Note: by default, the headmodel will be matched to EEG channel space using the EEG channel names, which are then assumed to be in the 10-20 (or the finer-grained 10-5) system. If your EEG channels do not use this label system, you need to know the locations of your channels relative to the 10-20 locations (which can be found in the resources/montages/standard-10-5-* file), and using that, you can either try to replace the channel labels by the closest 10-5 equivalent labels, or, likely better, select the interpolate option in this node to directly interpolate the head model for your given channel locations.

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
  • headmodel
    Head model file to use (*.h m). If omitted, the node checks if the data has a current head model associated with it, e.g., because a previous node has annotated it, and then uses that head model. If a relative path is given, the file is searched in the resources/headmodels folder of the cpe.

    • verbose name: Head Model File
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • regu
    Regularization strength. Larger values yield smoother solutions. In theory this is proportional to the sensor noise level. Ad-hoc choices work fairly well for visualization and basic source localization.

    • verbose name: Regularization Strength
    • default value: 0.05
    • port type: FloatPort
    • value type: float (can be None)
  • interpolate
    Rely on channel locations rather than labels. If this is enabled, the head model will be matched to the data using the channel locations rather than channel labels. This is only useful if the labels are unrecognized (e.g., non-standard labels), and if there are high-quality measured channel locations available. These locations must be in the same coordinate system as NeuroPype's default 10-5 locations (see node documentation for more details).

    • verbose name: Interpolate Using Channel Locations
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • max_iter
    Maximum number of iterations.

    • verbose name: Max Iterations
    • default value: 20
    • port type: IntPort
    • value type: int (can be None)

LCMVBeamforming

Estimate brain source activity using the linearly-constrained minimum variance (LCMV) beamforming algorithm.

This node accepts and EEG time series, and estimates for each time point the current source density (CSD) for a large number of locations (e.g., a few 1000) in the brain. The result is a time series with the EEG channels replaced by as many channels as there are source locations, and otherwise the same format as the input data. The set of source locations is defined by a headmodel, which is selectable via the headmodel_file parameter. Note that, as with other source estimation nodes, the input EEG should have been re-referenced to common average reference, which can be achieved using the ReReferencing node with default settings. Lastly, to use LCMV beamforming, it is also necessary to provide as the secondary input a running estimate of the data covariance matrix. That covariance can be estimated in principle using a variety of techniques (and thus combinations of nodes); one setup is to use the per-element covariance matrix node on the re-referenced EEG, and the smooth the result using either the moving average or exponential moving average nodes. Note: by default, the headmodel will be matched to EEG channel space using the EEG channel names, which are then assumed to be in the 10-20 (or the finer-grained 10-5) system. If your EEG channels do not use this label system, you need to know the locations of your channels relative to the 10-20 locations (which can be found in the resources/montages/standard-10-5-* file), and using that, you can either try to replace the channel labels by the closest 10-5 equivalent labels, or, likely better, select the interpolate option in this node to directly interpolate the head model for your given channel locations.

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
  • covariance
    Data covariance.

    • verbose name: Covariance
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • headmodel
    Head model file to use (*.h m). If omitted, the node checks if the data has a current head model associated with it, e.g., because a previous node has annotated it, and then uses that head model. If a relative path is given, the file is searched in the resources/headmodels folder of the cpe.

    • verbose name: Head Model File
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • shrinkage
    Shrinkage regularization strength. This can improve numeric conditioning, especially when the data covariance matrix used was estimated from a very short time window and/or over many channels (e.g., >64). Ad-hoc choices work fairly well.

    • verbose name: Regularization Strength
    • default value: 0.001
    • port type: FloatPort
    • value type: float (can be None)
  • rescale_activations
    Rescale estimated brain source activations to correct scale. This can be disabled if the scale does not affect subsequent processing (e.g., because of data normalization) and can yield a modest performance improvement.

    • verbose name: Rescale Activations
    • default value: True
    • port type: BoolPort
    • value type: bool (can be None)
  • interpolate
    Rely on channel locations rather than labels. If this is enabled, the head model will be matched to the data using the channel locations rather than channel labels. This is only useful if the labels are unrecognized (e.g., non-standard labels), and if there are high-quality measured channel locations available. These locations must be in the same coordinate system as NeuroPype's default 10-5 locations (see node documentation for more details).

    • verbose name: Interpolate Using Channel Locations
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)
  • normalize_leadfield
    Normalize the lead-field matrix. This can be used to fix problems with the scaling of the lead field matrix (e.g., when using a new or alternative head model).

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

ROIActivations

Compute the activations of regions of interest (ROIs) in the given atlas from current source density.

This node accepts as input a signal that has brain activity estimates (current source density) for each source location in the headmodel, which can be obtained by using one of the source estimation nodes (e.g., sLORETA). This node will then estimate average activity in selected (or all) ROIs that are defined in a brain atlas. The result is a time series with one channel for each region, and otherwise the same data format as the input. The atlas is essentially a parcellation of brain source locations (e.g., cells in a 3d grid or vertices in a triangle mesh of the brain surface) into regions, and is stored in the head model file. Some head models may have multiple atlases (although not the current default model), and the desired atlas can be selected using the atlas parameter.

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 process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • headmodel
    Override head model file to use (*.h m). If omitted, the node checks if the data has a current head model associated with it e.g., because a previous node has annotated it, (which is most likely the case for this node) and then uses that head model. If a relative path is given, the file is searched in the resources/headmodels folder of the cpe.

    • verbose name: Head Model File
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • atlas
    Optionally the name of the atlas to use. If the head model file contains multiple atlases in it, this allows to select the one to use.

    • verbose name: Atlas
    • default value: None
    • port type: StringPort
    • value type: str (can be None)
  • subset
    Subset of ROIs for which to calculate activations, optional. Setting this to non-empty will restrict the set of regions for which activations are calculated, for a modest performance gain.

    • verbose name: Restrict To Rois
    • default value: []
    • port type: ListPort
    • value type: list (can be None)

RemoveUnlocalizedChannels

Remove channels from the data that have no location assigned to them.

Elements of the space axis ("channels") have an associated 3xN sized .position porperty, which [NaN,NaN,NaN] for channels that have no location, and holds the spatial coordinates of the channel otherwise. This node removes those channels that have no location. Note: the node will only affect the first space axis in the data.

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

SLORETA

Estimate brain source activity using the Standardized Low-Resolution Brain Electromagnetic Tomography (sLORETA) algorithm.

This node accepts an EEG time series, and estimates for each time point the current source density (CSD) for a large number of locations (e.g., a few 1000) in the brain. The result is a time series with the EEG channels replaced by as many channels as there are source locations, and otherwise the same format as the input data. The set of source locations is defined by a headmodel, which is selectable via the headmodel_file parameter. Like eLORETA, this is a rather easy-to-use and very fast source estimation method. Important: the input data to this node should previously have been re-referenced to common average reference using the ReReferencing node (with default settings). Note: by default, the headmodel will be matched to EEG channel space using the EEG channel names, which are then assumed to be in the 10-20 (or the finer-grained 10-5) system. If your EEG channels do not use this label system, you need to know the locations of your channels relative to the 10-20 locations (which can be found in the resources/montages/standard-10-5-* file), and using that, you can either try to replace the channel labels by the closest 10-5 equivalent labels, or, likely better, select the interpolate option in this node to directly interpolate the head model for your given channel locations.

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
  • headmodel
    Head model file to use (*.h m). If omitted, the node checks if the data has a current head model associated with it, e.g., because a previous node has annotated it, and then uses that head model. If a relative path is given, the file is searched in the resources/headmodels folder of the cpe.

    • verbose name: Head Model File
    • default value:
    • port type: StringPort
    • value type: str (can be None)
  • regu
    Regularization strength. Larger values yield smoother solutions. In theory this is proportional to the sensor noise level. Ad-hoc choices work fairly well for visualization and basic source localization.

    • verbose name: Regularization Strength
    • default value: 0.05
    • port type: FloatPort
    • value type: float (can be None)
  • interpolate
    Rely on channel locations rather than labels. If this is enabled, the head model will be matched to the data using the channel locations rather than channel labels. This is only useful if the labels are unrecognized (e.g., non-standard labels), and if there are high-quality measured channel locations available. These locations must be in the same coordinate system as NeuroPype's default 10-5 locations (see node documentation for more details).

    • verbose name: Interpolate Using Channel Locations
    • default value: False
    • port type: BoolPort
    • value type: bool (can be None)

SelectROIs

Pick a subset of regions of interest in the given data.

This node assumes that source activity has previously been computed using one of the source-estimation nodes (e.g. sLORETA), and that region-of-interest activity has been calculated from the raw source activity using the ROIActivations node. The same effect can also be achieved using the Select Range node -- however, due to the large number of ROIs and their non-trivial naming, this node offers a more convenient user interface.

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
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • selection
    Regions of interest to retain. Multiple regions can be selected out of the given set of ROIs. These regions correspond to the Desikan-Killiany Atlas.

    • verbose name: Regions To Keep (Multi-Select)
    • default value: []
    • port type: SubsetPort
    • value type: list (can be None)

SelectRoiGroups

Selects among major groups of regions of interest taken from the Desikan-Killiany atlas.

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 process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • selection
    Groups of ROIs to retain. Multiple regions can be selected. These major regions correspond to the Desikan-Killiany Atlas.

    • verbose name: Regions To Keep (Multi-Select)
    • default value: []
    • port type: SubsetPort
    • value type: list (can be None)