| READLOCS | Read electrode location coordinates and other information from a file. Several standard file formats are supported. Users may also specify a custom column format. Defined format examples are given below (see File Formats). |
| Usage: | >> eloc = readlocs( filename ); >> EEG.chanlocs = readlocs( filename, 'key', 'val', ... ); >> [eloc, labels, theta, radius, indices] = readlocs( filename, 'key', 'val', ... ); |
| Inputs: | |
filename |
Name of the file containing the electrode locations {default: 2-D polar coordinates} (see >> help topoplot ) |
| Optional inputs: | |
'filetype' |
['loc'|'sph'|'sfp'|'xyz'|'asc'|'polhemus'|'besa'|'chanedit'|'custom'] Type of the file to read. By default the file type is determined using the file extension (see below under File Formats), 'loc' an EEGLAB 2-D polar coordinates channel locations file Coordinates are theta and radius (see definitions below). 'sph' Matlab spherical coordinates (Note: spherical coordinates used by Matlab functions are different from spherical coordinates used by BESA - see below). 'sfp' EGI Cartesian coordinates (NOT Matlab Cartesian - see below). 'xyz' Matlab/EEGLAB Cartesian coordinates (NOT EGI Cartesian). z is toward nose; y is toward left ear; z is toward vertex 'asc' Neuroscan polar coordinates. 'polhemus' or 'polhemusx' - Polhemus electrode location file recorded with 'X' on sensor pointing to subject (see below and readelp. |
'polhemusy' |
Polhemus electrode location file recorded with 'Y' on sensor pointing to subject (see below and readelp. 'besa' BESA-'.elp' spherical coordinates. (Not MATLAB spherical - see below). |
'chanedit' |
EEGLAB channel location file created by pop_chanedit. |
'custom' |
Ascii file with columns in user-defined 'format' (see below). |
'importmode' |
['eeglab'|'native'] for location files containing 3-D cartesian electrode coordinates, import either in EEGLAB format (nose pointing toward +X). This may not always be possible since EEGLAB might not be able to determine the nose direction for scanned electrode files. 'native' import original carthesian coordinates (user can then specify the position of the nose when calling the topoplot function; in EEGLAB the position of the nose is stored in the EEG.chaninfo structure). {default 'eeglab'} |
'format' |
[cell array] Format of a 'custom' channel location file (see above). {default: if no file type is defined. The cell array contains labels defining the meaning of each column of the input file. 'channum' [positive integer] channel number. 'labels' [string] channel name (no spaces). 'theta' [real degrees] 2-D angle in polar coordinates. positive => rotating from nose (0) toward left ear 'radius' [real] radius for 2-D polar coords; 0.5 is the head disk radius and limit for topoplot plotting). 'X' [real] Matlab-Cartesian X coordinate (to nose). 'Y' [real] Matlab-Cartesian Y coordinate (to left ear). 'Z' [real] Matlab-Cartesian Z coordinate (to vertex). '-X','-Y','-Z' Matlab-Cartesian coordinates pointing opposite to the above. 'sph_theta' [real degrees] Matlab spherical horizontal angle. positive => rotating from nose (0) toward left ear. 'sph_phi' [real degrees] Matlab spherical elevation angle. positive => rotating from horizontal (0) upwards. 'sph_radius' [real] distance from head center (unused). 'sph_phi_besa' [real degrees] BESA phi angle from vertical. positive => rotating from vertex (0) towards right ear. 'sph_theta_besa' [real degrees] BESA theta horiz/azimuthal angle. positive => rotating from right ear (0) toward nose. 'ignore' ignore column}. The input file may also contain other channel information fields. 'type' channel type: 'EEG', 'MEG', 'EMG', 'ECG', others ... 'calib' [real near 1.0] channel calibration value. 'gain' [real > 1] channel gain. 'custom1' custom field #1. 'custom2', 'custom3', 'custom4', etc. more custom fields |
'skiplines' |
[integer] Number of header lines to skip (in 'custom' file types only). |
| Note: | Characters on a line following '%' will be treated as comments. |
'readchans' |
[integer array] indices of electrodes to read. {default: all} |
'center' |
[(1,3) real array or 'auto'] center of xyz coordinates for conversion to spherical or polar, Specify the center of the sphere here, or 'auto'. This uses the center of the sphere that best fits all the electrode locations read. {default: [0 0 0]} |
| Outputs: | |
eloc |
structure containing the channel names and locations (if present). It has three fields: 'eloc.labels', 'eloc.theta' and 'eloc.radius' identical in meaning to the EEGLAB struct 'EEG.chanlocs'. |
labels |
cell array of strings giving the names of the electrodes. NOTE: Unlike the three outputs below, includes labels of channels *without* location info. |
theta |
vector (in degrees) of polar angles of the electrode locations. |
radius |
vector of polar-coordinate radii (arc_lengths) of the electrode locations |
indices |
indices, k, of channels with non-empty 'locs(k).theta' coordinate |
| File formats: | If 'filetype' is unspecified, the file extension determines its type. |
| '.loc' or '.locs' or '.eloc': | polar coordinates. Notes: angles in degrees: right ear is 90; left ear -90; head disk radius is 0.5. Fields: N angle radius label Sample: 1 -18 .511 Fp1 2 18 .511 Fp2 3 -90 .256 C3 4 90 .256 C4 ... |
| Note: | In previous releases, channel labels had to contain exactly four characters (spaces replaced by '.'). This format still works, though dots are no longer required. |
| '.sph': | Matlab spherical coordinates. Notes: theta is the azimuthal/horizontal angle in deg.: 0 is toward nose, 90 rotated to left ear. Following this, performs the elevation (phi). Angles in degrees. Fields: N theta phi label Sample: 1 18 -2 Fp1 2 -18 -2 Fp2 3 90 44 C3 4 -90 44 C4 ... |
| '.elc': | Cartesian 3-D electrode coordinates scanned using the EETrak software. See readeetraklocs. |
| '.elp': | Polhemus-.'elp' Cartesian coordinates. By default, an .elp extension is read as PolhemusX-elp in which 'X' on the Polhemus sensor is pointed toward the subject. Polhemus files are not in columnar format (see readelp. |
| '.elp': | BESA-'.elp' spherical coordinates: Need to specify 'filetype','besa'. The elevation angle (phi) is measured from the vertical axis. Positive rotation is toward right ear. Next, perform azimuthal/horizontal rotation (theta): 0 is toward right ear; 90 is toward nose, -90 toward occiput. Angles are in degrees. If labels are absent or weights are given in a last column, readlocs adjusts for this. Default labels are E1, E2, Fields: label phi theta Sample: Fp1 -92 -72 Fp2 92 72 C3 -46 0 C4 46 0 ... |
| '.xyz': | Matlab/EEGLAB Cartesian coordinates. Here. x is towards the nose, y is towards the left ear, and z towards the vertex. Note that the first column (x) is -Y in a Matlab 3-D plot, the second column (y) is X in a matlab 3-D plot, and the third column (z) is Z. Fields: channum x y z label Sample: 1 .950 .308 -.035 Fp1 2 .950 -.308 -.035 Fp2 3 0 .719 .695 C3 4 0 -.719 .695 C4 ... |
| '.asc', '.dat': | Neuroscan-.'asc' or '.dat' Cartesian polar coordinates text file. |
| '.sfp': | BESA/EGI-xyz Cartesian coordinates. Notes: For EGI, x is toward right ear, y is toward the nose, z is toward the vertex. EEGLAB converts EGI Cartesian coordinates to Matlab/EEGLAB xyz coordinates. Fields: label x y z Sample: Fp1 -.308 .950 -.035 Fp2 .308 .950 -.035 C3 -.719 0 .695 C4 .719 0 .695 ... |
| '.ced': | ASCII file saved by pop_chanedit. Contains multiple MATLAB/EEGLAB formats. Cartesian coordinates are as in the 'xyz' format (above). Fields: channum label theta radius x y z sph_theta sph_phi Sample: 1 Fp1 -18 .511 .950 .308 -.035 18 -2 2 Fp2 18 .511 .950 -.308 -.035 -18 -2 3 C3 -90 .256 0 .719 .695 90 44 4 C4 90 .256 0 -.719 .695 -90 44 The last columns of the file may contain any other defined fields (gain, calib, type, custom). |
| Author: | Arnaud Delorme, Salk Institute, 8 Dec 2002 (expanded from the previous EEG/ICA toolbox function) |
| See also: | readelp, writelocs, topo2sph, sph2topo, sph2cart() |