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:

Parameters:	vertices : array (length N) vertex indices (0 based). pos : array (N by 3) \| None locations in meters. If None, then zeros are used. values : array (length N) \| None values at the vertices. If None, then ones are used. hemi : ‘lh’ \| ‘rh’ Hemisphere to which the label applies. comment : str Kept as information but not used by the object itself. name : str Kept as information but not used by the object itself. filename : str Kept as information but not used by the object itself. subject : str \| None Name of the subject the label is from. color : None \| matplotlib color Default label color and alpha (e.g., `(1., 0., 0., 1.)` for red). verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).

vertices : array (length N)

vertex indices (0 based).

pos : array (N by 3) | None

locations in meters. If None, then zeros are used.

values : array (length N) | None

values at the vertices. If None, then ones are used.

hemi : ‘lh’ | ‘rh’

Hemisphere to which the label applies.

comment : str

Kept as information but not used by the object itself.

name : str

Kept as information but not used by the object itself.

filename : str

Kept as information but not used by the object itself.

subject : str | None

Name of the subject the label is from.

color : None | matplotlib color

Default label color and alpha (e.g., (1., 0., 0., 1.) for red).

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Attributes

color	(None \| tuple) Default label color, represented as RGBA tuple with values between 0 and 1.
comment	(str) Comment from the first line of the label file.
hemi	(‘lh’ \| ‘rh’) Hemisphere.
name	(None \| str) A name for the label. It is OK to change that attribute manually.
pos	(array, shape = (n_pos, 3)) Locations in meters.
subject	(str \| None) Subject name. It is best practice to set this to the proper value on initialization, but it can also be set manually.
values	(array, len = n_pos) Values at the vertices.
verbose	(bool, str, int, or None) See above.
vertices	(array, len = n_pos) Vertex indices (0 based)

Methods

`__add__`(other)	Add BiHemiLabels.
`__hash__`() <==> hash(x)
`__len__`()	Return the number of vertices.
`__sub__`(other)	Subtract BiHemiLabels.
`center_of_mass`([subject, restrict_vertices, …])	Compute the center of mass of the label.
`copy`()	Copy the label instance.
`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.
`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 BiHemiLabels.

__hash__() <==> hash(x)¶

__len__()[source]¶: Return the number of vertices.

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

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 [R15].

Parameters:

Parameters:	subject : string \| None The subject the label is defined for. restrict_vertices : bool \| 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_dir : str, or None Path to the SUBJECTS_DIR. If None, the path is obtained by using the environment variable SUBJECTS_DIR. surf : str 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:	vertex : int Vertex of the spatial center of mass for the inferred hemisphere, with each vertex weighted by its label value.

subject : string | None

The subject the label is defined for.

restrict_vertices : bool | 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_dir : str, or None

Path to the SUBJECTS_DIR. If None, the path is obtained by using the environment variable SUBJECTS_DIR.

surf : str

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:

vertex : int

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

Notes

References

[R15]

(1, 2) Larson and Lee, “The cortical dynamics underlying effective switching of auditory spatial attention”, NeuroImage 2012.

copy()[source]¶

Copy the label instance.

Returns:

Returns:	label : instance of Label The copied label.

label : instance of Label

The copied label.

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

Fill the surface between sources for a source space label.

Parameters:

Parameters:	src : SourceSpaces 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. name : None \| str Name for the new Label (default is self.name).
Returns:	label : Label The label covering the same vertices in source space but also including intermediate surface vertices.

src : SourceSpaces

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.

name : None | str

Name for the new Label (default is self.name).

Returns:

label : Label

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

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

Get the source space’s triangles inside the label.

Parameters:

Parameters:	tris : ndarray of int, shape (n_tris, 3) The set of triangles corresponding to the vertices in a source space. vertices : ndarray 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_tris : ndarray of int, shape (n_tris, 3) The subset of tris used by the label

tris : ndarray of int, shape (n_tris, 3)

The set of triangles corresponding to the vertices in a source space.

vertices : ndarray 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_tris : ndarray 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:

Parameters:	vertices : ndarray 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_verts : ndarray of in, shape (n_label_vertices,) The vertices of the label corresponding used by the data.

vertices : ndarray 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_verts : ndarray 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:

Parameters:	subject_from : str \| None The name of the subject of the current label. If None, the initial subject will be taken from self.subject. subject_to : str The name of the subject to morph the label to. This will be put in label.subject of the output label file. smooth : int Number of iterations for the smoothing of the surface data. Cannot be None here since not all vertices are used. grade : int, list (of two arrays), 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_dir : string, or None Path to SUBJECTS_DIR if it is not set in the environment. n_jobs : int Number of jobs to run in parallel. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).
Returns:	label : instance of Label The morphed label.

subject_from : str | None

The name of the subject of the current label. If None, the initial subject will be taken from self.subject.

subject_to : str

The name of the subject to morph the label to. This will be put in label.subject of the output label file.

smooth : int

Number of iterations for the smoothing of the surface data. Cannot be None here since not all vertices are used.

grade : int, list (of two arrays), 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_dir : string, or None

Path to SUBJECTS_DIR if it is not set in the environment.

n_jobs : int

Number of jobs to run in parallel.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

label : instance of Label

The morphed 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.

save(filename)[source]¶

Write to disk as FreeSurfer *.label file.

Parameters:

Parameters:	filename : string Path to label file to produce.

filename : string

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:

Parameters:	subject : str \| None The name of the subject used. If None, the value will be taken from self.subject. smooth : int 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. grade : int, list (of two arrays), 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_dir : string, or None Path to SUBJECTS_DIR if it is not set in the environment. n_jobs : int Number of jobs to run in parallel verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more). Defaults to self.verbose.
Returns:	label : instance of Label The smoothed label.

subject : str | None

The name of the subject used. If None, the value will be taken from self.subject.

smooth : int

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.

grade : int, list (of two arrays), 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_dir : string, or None

Path to SUBJECTS_DIR if it is not set in the environment.

n_jobs : int

Number of jobs to run in parallel

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). Defaults to self.verbose.

Returns:

label : instance 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:

Parameters:	parts : int >= 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. subject : None \| str Subject which this label belongs to (needed to locate surface file; should only be specified if it is not specified in the label). subjects_dir : None \| str Path to SUBJECTS_DIR if it is not set in the environment. freesurfer : bool 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:	labels : list of Label (len = n_parts) The labels, starting from the lowest to the highest end of the projection axis.

parts : int >= 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.

subject : None | str

Subject which this label belongs to (needed to locate surface file; should only be specified if it is not specified in the label).

subjects_dir : None | str

Path to SUBJECTS_DIR if it is not set in the environment.

freesurfer : bool

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:

labels : list of Label (len = 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.