← source_localization package

CoregisterExistingLocations

Co-register the locations in the given data with the NeuroPype internal coordinate system.

Currently the only method supported is based on landmark locations; for this your data must have (), or you must specify, a set of named landmarks and their 3d positions in the same (arbitrary) coordinate system of your data. Note that if you have standard channel names for your data, then you don't need to use this node, since you can just look up the canonical locations by name -- use the AssignChannelLocations node. Therefore, this node is mostly useful if you don't have standard locations, or (more rarely) you have per-session digitized locations, and you also have landmarks in the same system that you trust to be measured well enough that you can rely on least-squares co-registration. This node can open a specified montage file (which is expected to have landmark positions in a well-defined canonical coordinate system with the same center as the 10-20 system), or it can search the .locs files that come with Neuropype to find your landmark labels in them (this will work if your landmarks have standard names, such as Nz, Iz, Cz, LPA, and RPA). () The node looks in specific predefined places of your data's chunk properties to check for potential fiducial locations. This includes a top-level 'landmarks' properties (formatted as a dictionary to 3-element lists of positions), a space-axis 'landmarks' property of the same format, or the XDF EEG fiducials specification inside the 'desc' property. These locations will be ignored if landmarks are explicitly listed, OR if the ignore_landmarks option is set. Version 0.6.0

Ports/Properties

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 filename 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)

landmarks

Known landmark locations (optional). This is formatted as a Python dictionary from landmark names to 3d coordinates, e.g., {'Nz': [0.1,0.2,-0.5], 'Iz': [0.2,-0.33,0.5], 'Cz': [0,0,0.6]}, where the names must follow standard naming (e.g. Nz, Iz, LPA, RPA, Cz), and the locations must be in the same coordinate system as the input data, which can be arbitrary. Note that you need at least 3 landmarks for successful coregistration, but more (e.g., 5) will reduce the error. If not given, the data must have a 'landmarks' field in the properties, which is expected to be a dictionary that is formatted the same as this dictionary.

• verbose name: Landmarks
• default value: None
• port type: DictPort
• value type: dict (can be None)

include_channels

List of channels to include as landmarks. Keep in mind that, unless your channels are well placed (at the quality of landmarks), for example using tape measure, including such channels may do more harm than help relative to using fiducial landmarks. Also note that, when your channels are not in the 10-20 system, this will require that an appropriate montage file that defines standard locations for those channels is either specified explicitly or can be automatically identified. That template will then also be used to localize any fiducial landmarks in your data, and not all templates will define all landmarks.

• verbose name: Include Channels
• default value: None
• port type: ListPort
• value type: list (can be None)

include_relabeled

List of channels along with their relabeled name in the desired montage file. This is similar to include_channels but you have the option to relabel them to 10-20 labels, which allows you to use the regular 10-20 (or rather 10-5) montage file. As with the include_channels option, you are advised to use only channels that are well-placed (eg with tape measure).

• verbose name: Include Relabeled
• default value: None
• port type: DictPort
• value type: dict (can be None)

ignore_landmarks

Ignore any landmarks that may be present in the dataset.

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

denoise

If enabled, this will denoise the measured per-channel locations towards a smooth non-linear warp in accordance with the denoising parameters.

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

stream_names

List of streams to update locations on. Leave empty to attempt on all signal streams. (Marker streams are ignored.)

• verbose name: Stream Names
• default value: []
• port type: ListPort
• value type: list (can be None)

max_shape_deviation

Maximum allowed average deviation between coregistered and template locations, in cm. If the result of the coregistration leaves electrodes further from the template locations than this, the result is discarded. This can be caused by issues during location measurement that cause part of the locations to be substantially deformed.

• verbose name: Max Shape Deviation
• default value: 1.9
• port type: FloatPort
• value type: float (can be None)

max_location_error

Maximum allowed average error between affine-coregistered and denoised locations, in cm. Only applied if denoising is used. If the average error is larger than this, the result is discarded. This can be caused by high error or jitter in individual location measurements that suggest that the cap is either deformed in a very complex way or location measurements were too inaccurate.

• verbose name: Max Location Error
• default value: 0.65
• port type: FloatPort
• value type: float (can be None)

on_error

How to proceeed in case landmark information is either absent or unusable. The raise option will raise an error; ignore will keep the data uncoregistered, and template will instead use the identified template, as in AssignChannelLocations.

• verbose name: On Error
• default value: raise
• port type: EnumPort
• value type: str (can be None)

denoise_alpha

If enabled, this will denoise the measured per-channel locations towards a smooth non-linear warp using the specified regularization parameter. A good starting value is 0.1, with larger values yielding stronger denoising. This uses a thin-plate spline fit of the noisy locations to transform the template locations.

• verbose name: Denoising Regularization
• default value: 0.1
• port type: FloatPort
• value type: float (can be None)

denoise_order

Spline order to use for denoising. Reasonable values are 3-6, where higher degrees can capture more complex spatial distortions.

• verbose name: Denoising Spline Order
• default value: 4
• port type: IntPort
• value type: int (can be None)

visualize

If enabled, opens a 3D scatter plot showing the channel positions: reference template positions (green), coregistered positions (purple), and original coregistered positions before denoising (red, if denoising is enabled).

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

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)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

• verbose name: Metadata
• default value: {}
• port type: DictPort
• value type: dict (can be None)