mne.Label¶

class mne.Label(vertices=(), pos=None, values=None, hemi=None, comment='', name=None, filename=None, subject=None, color=None, verbose=None)[source]¶

A FreeSurfer/MNE label with vertices restricted to one hemisphere.

Labels can be combined with the + operator:

Duplicate vertices are removed.

If duplicate vertices have conflicting position values, an error is raised.

Values of duplicate vertices are summed.

Parameters

verticesarray, shape (N,): Vertex indices (0 based).
posarray, shape (N, 3) | None: Locations in meters. If None, then zeros are used.
valuesarray, shape (N,) | None: Values at the vertices. If None, then ones are used.
hemi‘lh’ | ‘rh’: Hemisphere to which the label applies.
commentstr: Kept as information but not used by the object itself.
namestr: Kept as information but not used by the object itself.
filenamestr: Kept as information but not used by the object itself.
subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
colorNone | matplotlib color: Default label color and alpha (e.g., (1., 0., 0., 1.) for red).
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Attributes

colorNone | tuple: Default label color, represented as RGBA tuple with values between 0 and 1.
commentstr: Comment from the first line of the label file.
hemi‘lh’ | ‘rh’: Hemisphere.
nameNone | str: A name for the label. It is OK to change that attribute manually.
posarray, shape (N, 3): Locations in meters.
subjectstr | None: The label subject. It is best practice to set this to the proper value on initialization, but it can also be set manually.
valuesarray, shape (N,): Values at the vertices.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.
verticesarray, shape (N,): Vertex indices (0 based)

Methods

`__add__`(other)	Add Labels.
`__hash__`(/)	Return hash(self).
`__len__`()	Return the number of vertices.
`__sub__`(other)	Subtract Labels.
`center_of_mass`([subject, restrict_vertices, ...])	Compute the center of mass of the label.
`compute_area`([subject, subjects_dir, ...])	Compute the surface area of a label.
`copy`()	Copy the label instance.
`distances_to_outside`([subject, ...])	Compute the distance from each vertex to outside the label.
`fill`(src[, name])	Fill the surface between sources for a source space label.
`get_tris`(tris[, vertices])	Get the source space's triangles inside the label.
`get_vertices_used`([vertices])	Get the source space's vertices inside the label.
`morph`([subject_from, subject_to, smooth, ...])	Morph the label.
`restrict`(src[, name])	Restrict a label to a source space.
`save`(filename)	Write to disk as FreeSurfer *.label file.
`smooth`([subject, smooth, grade, ...])	Smooth the label.
`split`([parts, subject, subjects_dir, freesurfer])	Split the Label into two or more parts.

__add__(other)[source]¶: Add Labels.

__len__()[source]¶

Return the number of vertices.

Returns

n_verticesint: The number of vertices.

__sub__(other)[source]¶: Subtract Labels.

center_of_mass(subject=None, restrict_vertices=False, subjects_dir=None, surf='sphere')[source]¶

Compute the center of mass of the label.

This function computes the spatial center of mass on the surface as in 1.

Parameters

subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
restrict_verticesbool | array of int | instance of SourceSpaces: If True, returned vertex will be one from the label. Otherwise, it could be any vertex from surf. If an array of int, the returned vertex will come from that array. If instance of SourceSpaces (as of 0.13), the returned vertex will be from the given source space. For most accuruate estimates, do not restrict vertices.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
surfstr: The surface to use for Euclidean distance center of mass finding. The default here is “sphere”, which finds the center of mass on the spherical surface to help avoid potential issues with cortical folding.

Returns

vertexint: Vertex of the spatial center of mass for the inferred hemisphere, with each vertex weighted by its label value.

See also

SourceEstimate.center_of_mass
vertex_to_mni

Notes

New in version 0.13.

References

1: Eric Larson and Adrian K.C. Lee. The cortical dynamics underlying effective switching of auditory spatial attention. NeuroImage, 64:365–370, 2013. doi:10.1016/j.neuroimage.2012.09.006.

compute_area(subject=None, subjects_dir=None, surface='white', *, verbose=None)[source]¶

Compute the surface area of a label.

Parameters

subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
surfacestr: The surface along which to do the computations, defaults to 'white' (the gray-white matter boundary).
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument. Defaults to self.verbose.

Returns

areafloat: The area (in m²) of the label.

Notes

..versionadded:: 0.24

Examples using compute_area:

copy()[source]¶

Copy the label instance.

Returns

labelinstance of Label: The copied label.

distances_to_outside(subject=None, subjects_dir=None, surface='white', *, verbose=None)[source]¶

Compute the distance from each vertex to outside the label.

Parameters

subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
surfacestr: The surface along which to do the computations, defaults to 'white' (the gray-white matter boundary).
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument. Defaults to self.verbose.

Returns

distndarray, shape (n_vertices,): The distance from each vertex in self.vertices to exit the label.
outside_verticesndarray, shape (n_vertices,): For each vertex in the label, the nearest vertex outside the label.

Notes

Distances are computed along the cortical surface.

New in version 0.24.

Examples using distances_to_outside:

fill(src, name=None)[source]¶

Fill the surface between sources for a source space label.

Parameters

srcSourceSpaces: Source space in which the label was defined. If a source space is provided, the label is expanded to fill in surface vertices that lie between the vertices included in the source space. For the added vertices, pos is filled in with positions from the source space, and values is filled in from the closest source space vertex.
nameNone | str: Name for the new Label (default is self.name).

Returns

labelLabel: The label covering the same vertices in source space but also including intermediate surface vertices.

See also

Label.restrict
Label.smooth

get_tris(tris, vertices=None)[source]¶

Get the source space’s triangles inside the label.

Parameters

trisndarray of int, shape (n_tris, 3): The set of triangles corresponding to the vertices in a source space.
verticesndarray of int, shape (n_vertices,) | None: The set of vertices to compare the label to. If None, equals to np.arange(10242). Defaults to None.

Returns

label_trisndarray of int, shape (n_tris, 3): The subset of tris used by the label.

get_vertices_used(vertices=None)[source]¶

Get the source space’s vertices inside the label.

Parameters

verticesndarray of int, shape (n_vertices,) | None: The set of vertices to compare the label to. If None, equals to np.arange(10242). Defaults to None.

Returns

label_vertsndarray of in, shape (n_label_vertices,): The vertices of the label corresponding used by the data.

morph(subject_from=None, subject_to=None, smooth=5, grade=None, subjects_dir=None, n_jobs=1, verbose=None)[source]¶

Morph the label.

Useful for transforming a label from one subject to another.

Parameters

subject_fromstr | None: The name of the subject of the current label. If None, the initial subject will be taken from self.subject.
subject_tostr: The name of the subject to morph the label to. This will be put in label.subject of the output label file.
smoothint: Number of iterations for the smoothing of the surface data. Cannot be None here since not all vertices are used.
gradeint, list of shape (2,), array, or None: Resolution of the icosahedral mesh (typically 5). If None, all vertices will be used (potentially filling the surface). If a list, values will be morphed to the set of vertices specified in grade[0] and grade[1], assuming that these are vertices for the left and right hemispheres. Note that specifying the vertices (e.g., grade=[np.arange(10242), np.arange(10242)] for fsaverage on a standard grade 5 source space) can be substantially faster than computing vertex locations. If one array is used, it is assumed that all vertices belong to the hemisphere of the label. To create a label filling the surface, use None.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
n_jobsint: The number of jobs to run in parallel (default 1). If -1, it is set to the number of CPU cores. Requires the joblib package.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument. Defaults to self.verbose.

Returns

labelinstance of Label: The morphed label.

See also

mne.morph_labels: Morph a set of labels.

Notes

This function will set label.pos to be all zeros. If the positions on the new surface are required, consider using mne.read_surface with label.vertices.

restrict(src, name=None)[source]¶

Restrict a label to a source space.

Parameters

srcinstance of SourceSpaces: The source spaces to use to restrict the label.
nameNone | str: Name for the new Label (default is self.name).

Returns

labelinstance of Label: The Label restricted to the set of source space vertices.

See also

Label.fill

Notes

New in version 0.20.

save(filename)[source]¶

Write to disk as FreeSurfer *.label file.

Parameters

filenamestr: Path to label file to produce.

Notes

Note that due to file specification limitations, the Label’s subject and color attributes are not saved to disk.

smooth(subject=None, smooth=2, grade=None, subjects_dir=None, n_jobs=1, verbose=None)[source]¶

Smooth the label.

Useful for filling in labels made in a decimated source space for display.

Parameters

subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
smoothint: Number of iterations for the smoothing of the surface data. Cannot be None here since not all vertices are used. For a grade of 5 (e.g., fsaverage), a smoothing of 2 will fill a label.
gradeint, list of shape (2,), array, or None: Resolution of the icosahedral mesh (typically 5). If None, all vertices will be used (potentially filling the surface). If a list, values will be morphed to the set of vertices specified in grade[0] and grade[1], assuming that these are vertices for the left and right hemispheres. Note that specifying the vertices (e.g., grade=[np.arange(10242), np.arange(10242)] for fsaverage on a standard grade 5 source space) can be substantially faster than computing vertex locations. If one array is used, it is assumed that all vertices belong to the hemisphere of the label. To create a label filling the surface, use None.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
n_jobsint: The number of jobs to run in parallel (default 1). If -1, it is set to the number of CPU cores. Requires the joblib package.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument. Defaults to self.verbose.

Returns

labelinstance of Label: The smoothed label.

Notes

This function will set label.pos to be all zeros. If the positions on the new surface are required, consider using mne.read_surface with label.vertices.

split(parts=2, subject=None, subjects_dir=None, freesurfer=False)[source]¶

Split the Label into two or more parts.

Parameters

partsint >= 2 | tuple of str | str: Number of labels to create (default is 2), or tuple of strings specifying label names for new labels (from posterior to anterior), or ‘contiguous’ to split the label into connected components. If a number or ‘contiguous’ is specified, names of the new labels will be the input label’s name with div1, div2 etc. appended.
subjectstr | None: Subject which this label belongs to. Should only be specified if it is not specified in the label.
subjects_dirstr | pathlib.Path | None: The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.
freesurferbool: By default (False) split_label uses an algorithm that is slightly optimized for performance and numerical precision. Set freesurfer to True in order to replicate label splits from FreeSurfer’s mris_divide_parcellation.

Returns

labelslist of Label, shape (n_parts,): The labels, starting from the lowest to the highest end of the projection axis.

Notes

If using ‘contiguous’ split, you must ensure that the label being split uses the same triangular resolution as the surface mesh files in subjects_dir Also, some small fringe labels may be returned that are close (but not connected) to the large components.

The spatial split finds the label’s principal eigen-axis on the spherical surface, projects all label vertex coordinates onto this axis, and divides them at regular spatial intervals.