Function labels_to_stc

mne/label.py:2473–2545

Convert a set of labels and values to a STC. This function is meant to work like the opposite of `extract_label_time_course`. Parameters ---------- %(labels_eltc)s values : ndarray, shape (n_labels, ...) The values in each label. Can be 1D or 2D. tmin : float

(
    labels, values, tmin=0, tstep=1, subject=None, src=None, verbose=None
)

@verbose
def labels_to_stc(
    labels, values, tmin=0, tstep=1, subject=None, src=None, verbose=None
):
    """Convert a set of labels and values to a STC.

    This function is meant to work like the opposite of
    `extract_label_time_course`.

    Parameters
    ----------
    %(labels_eltc)s
    values : ndarray, shape (n_labels, ...)
        The values in each label. Can be 1D or 2D.
    tmin : float
        The tmin to use for the STC.
    tstep : float
        The tstep to use for the STC.
    %(subject)s
    %(src_eltc)s
        Can be omitted if using a surface source space, in which case
        the label vertices will determine the output STC vertices.
        Required if using a volumetric source space.

        .. versionadded:: 0.22
    %(verbose)s

    Returns
    -------
    stc : instance of SourceEstimate | instance of VolSourceEstimate
        The values-in-labels converted to a STC.

    See Also
    --------
    extract_label_time_course

    Notes
    -----
    Vertices that appear in more than one label will be averaged.

    .. versionadded:: 0.18
    """
    values = np.array(values, float)
    if values.ndim == 1:
        values = values[:, np.newaxis]
    if values.ndim != 2:
        raise ValueError(f"values must have 1 or 2 dimensions, got {values.ndim}")
    _validate_type(src, (SourceSpaces, None))
    if src is None:
        data, vertices, subject = _labels_to_stc_surf(
            labels, values, tmin, tstep, subject
        )
        klass = SourceEstimate
    else:
        kind = src.kind
        subject = _check_subject(
            src._subject, subject, first_kind="source space subject", raise_error=False
        )
        _check_option("source space kind", kind, ("surface", "volume"))