Getting started with BioImage Suite

Viewing and localizing intracranial EEG (iEEG) electrodes from volumetric brain images (CT and/or MR images) can be accomplished using ft_electrodeplacement, as demonstrated in the Analysis of human ECoG and sEEG recordings tutorial. Alternatively, users may choose to localize electrodes using BioImage Suite and subsequently view them in MATLAB using FieldTrip. Finally, users may also choose to localize electrodes using ft_electrodeplacement and subsequently view them in BioImage Suite.

This page covers (1) how electrodes that have been localized in BioImage Suite (*.mgrid files) can be loaded into MATLAB as a FieldTrip-compatible elec structure; and (2) how electrodes that have been localized in FieldTrip can be saved as BioImage Suite compatible *.mgrid files.

For a video tutorial on how to localize iEEG electrodes using the BioImage Suite Electrode Editor, see here: https://www.youtube.com/watch?v=j_8rT3naXgM. Once electrodes have been localized, a *.mgrid file containing information on electrode labels and coordinates is generated. Within the *.mgrid file, electrode coordinates are specified in milimeters according to a unique xyz coordinate system where the origin is one of the eight corner voxels (depending on the orientation of the brain volume where the electrodes are localized). This coordinate system is used to specify electrode coordinates in BioImage Suite regardless of if the brain volume has a traditional coordinate system (e.g., ACPC, MNI, etc.).

Using FieldTrip's bis2fieldtrip function, *.mgrid files can be loaded into MATLAB as a FieldTrip-compatible elec datatype structure, which can then be integrated with functional iEEG data and used for data exploration, analysis, and representation purposes. In addition to the *.mgrid file, bis2fieldtrip also requires the user to input the brain volume file (e.g., NIfTI, *.nii) corresponding to the given *.mgrid file (i.e., the *.mgrid file must be generated by identifying electrodes in the brain volume). This second input is critical because it provides the voxel size information and transformation matrix necessary to transform the electrode coordinates from the arbitrary xyz coordinate system into the coordinate system of the associated brain volume.

elec = bis2fieldtrip(<path to *.mgrid file>, <path to corresponding brain volume>)

Once the elec structure is created, check to make sure it contains a ‘unit’ field. If FieldTrip could not determine the units of the brain volume, then the unit field will not exist in the elec structure and will need to be inputted manually.

elec.unit = ‘mm’;

Manually inputting the unit field does not affect the electrode coordinates, which are stored in the ‘elecpos’ and ‘chanpos’ fields, and these coordinates should still correspond to the head space of the brain volume.

To sanity check that this is the case, you can view the electrode positions in the head volume using ft_electrodeplacement.

% First, load the brain volume corresponding to the *.mgrid file
ct = ft_read_mri(<path to brain volume corresponding to *.mgrid file>);
 
cfg = [];
cfg.elec = elec;
ft_electrodeplacement(cfg, ct);

If the electrode coordinates in elec correspond to a CT and the user intends to represent the electrode positions or electrophysiological data overlayed on a higher definition T1 MRI (recommended), the user will first have to pre-process and co-register the corresponding CT to a T1 MRI from the same subject.

Once the CT and MRI are co-registered, warp the electrode coordinates in elec (corresponding to the raw CT coordinate system) to the fused CT-MRI head space using ft_warp_apply.

% First, warp the coordinates in elec from native head space to voxel space
elec_vox = elec;
elec_vox.elecpos = ft_warp_apply(inv(ct. transform), elec.elecpos);
 
% Then, warp the coordinates from voxel space to the fused CT-MRI head space
elec_acpc_f = elec_vox;
elec_acpc_f.elecpos = ft_warp_apply(ct_acpc_f.transform, elec_vox.elecpos);
 
% Lastly, copy the coordinates in the ‘elecpos’ field to the ‘chanpos’ field
elec_acpc_f.chanpos = elec_acpc_f.elecpos;
 
% Check to make sure elec_acpc_f has all of the necessary fields
elec_acpc_f
 
  elec_acpc_f = 
       chanpos: [170x3 double]
       elecpos: [170x3 double]
       label: {170x1 cell}
       unit: 'mm'
       coordsys = ‘acpc’;

Because electrode labels are entered manually in BioImage Suite, they may not perfectly match the labels in the electrophysiology data. This will pose a problem if the user intends to integrate the anatomical data (in the elec structure) with the functional data. Therefore, the user should check to make sure all of the labels in the elec structure are accounted for in the channel labels associated with the functional data. An example script to assist in this process is outlined below:

% first load the header of the electrophysiology data file
header = ft_read_header(<path to electrophysiology data>);
 
% Generate a list of indices of the labels in header.label 
% that match labels in elec_acpc_f.label and vice versa
[sel1, sel2] = match_str(header.label, elec_acpc_f.label);
 
% Check if all of the labels in elec_acpc_f are in the header
if length(i_label_match) == length(elec_acpc_f.label) 
    % do nothing
else
    % create a list of the labels in elec that do not match those in header
    elec_nomatch = elec_acpc_f.label; % copy all of the labels in elec
    elec_nomatch(sel2) = []; % remove all labels in elec that have a match in header
 
    % create a list of the labels in header that do not match those in elec
    header_nomatch = header.label; % copy all of the labels in header
    header_nomatch(sel1) = []; % remove all labels in header that have a match in elec
end

If there are labels in elec_acpc_f that do not match those in the electrophysiological data, the user should easily be able to determine what labels need to be changed and what they should be changed to by comparing the list of labels in elec_nomatch and header_nomatch.

Once it is confirmed that all of the labels in elec_acpc_f match those in the electrophysiological data, the elec structure can be added to the electrophysiological data to facilitate integrated exploration, analysis, and representation of anatomical and functional electrophysiological data in FieldTrip, as described in the Analysis of human ECoG and sEEG recordings tutorial.

% load the electrophysiological data
cfg = [];
cfg.dataset    = <path to electrophysiological recording file>;]
cfg.continuous = 'yes';
data = ft_preprocessing(cfg);
 
% add the elec_acpc_f structure to the data
data.elec = elec_acpc_f;

It is also possible to localize electrodes in FieldTrip, using ft_electrodeplacement, and subsequently view and/or edit their positions in BioImage Suite. To accomplish this, the elec structure must be saved as a BioImage Suite compatible *.mgrid file using FieldTrip’s fieldtrip2bis function. The first input to fieldtrip2bis specifies the path to the *.mgrid file. The second input is the elec structure generated by ft_electrodeplacement. And the third input is the path to the brain volume file that was used to localize the electrodes.

fieldtrip2bis(<path to *.mgrid file>, elec, <path to corresponding brain volume file>)

Once the *.mgrid file is created, it can be loaded into the BioImage Suite Electrode Editor along with the corresponding brain volume file. If the electrodes appear severely misaligned in BioImage Suite, it is likely because the orientation of the brain volume in BioImage Suite does not match the orientation of the brain volume in FieldTrip, which may happen for a variety of reasons. To solve this problem, simply reorient the brain volume in BioImage Suite (in the brain volume window: Relabel → ReOrient Image → select from drop down) to match the orientation of the brain volume in FieldTrip, which can be determined from the coordinate system of the brain volume.