roiextract 0.0.2__py3-none-any.whl

roiextract/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from importlib.metadata import version
+
+    __version__ = version("roiextract")
+except Exception:
+    __version__ = "Failed to determine the version"

roiextract/analytic.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+from numpy.linalg import norm
+from scipy.linalg import eig
+
+
+def ctf_optimize_ratio_similarity(
+    leadfield, template, mask, lambda_, regA=0.001, regB=0.001
+):
+    """
+    Optimize a linear combination of similarity with a template CTF and
+    within/outside CTF ratio
+
+    Parameters
+    ----------
+    leadfield: array_like
+        Lead field matrix for dipoles with fixed orientation with shape
+        (channels, voxels).
+    template: array_like
+        Template CTF pattern for voxels with shape (voxels,). Only values
+        within the ROI are used.
+    mask: array_like
+        Voxel mask of the region of interest with shape (voxels,). Contains
+        ones and zeros for voxels within and outside ROI, respectively.
+    lambda_: float
+        If 0, only ratio is optimized. If 1, only similarity. Values in between
+        allow tweaking the balance between optimization for similarity or ratio.
+    regA, regB: float
+        Regularization parameters to ensure that it is possible to calculate the
+        inverse matrices.
+
+    Returns
+    -------
+    w: array
+        Spatial filter produced by the optimization.
+
+    Raises
+    ------
+    ValueError
+        If the provided lambda_ value is out of [0, 1] range.
+    """
+    if lambda_ > 1.0 or lambda_ < 0.0:
+        raise ValueError("Value of lambda_ should lie in [0, 1] range")
+
+    # Make sure w0 is a row vector with unit length
+    template = np.atleast_1d(np.squeeze(template))
+    if template.ndim > 1:
+        raise ValueError(
+            f"Template weights should be a vector, got "
+            f"{template.ndim} dimensions instead"
+        )
+    template = template / norm(template)
+    template = template[np.newaxis, :]
+
+    # Split lead field matrix into in and out parts
+    L_in = leadfield[:, mask]
+    L_out = leadfield[:, ~mask]
+
+    # Solve the generalized eigenvalue problem
+    A_rat = L_out @ L_out.T
+    A_sim = L_in @ (template.T @ template) @ L_in.T
+    A = (1 - lambda_) * A_rat - lambda_ * A_sim
+    A_reg = A + regA * np.trace(A) * np.eye(*A.shape) / A.shape[0]
+    B = L_in @ L_in.T
+    B_reg = B + regB * np.trace(B) * np.eye(*B.shape) / B.shape[0]
+    [eigvals, eigvecs] = eig(A_reg, B_reg)
+
+    # Get the eigenvector that corresponds to the smallest eigenvalue
+    w = eigvecs[:, eigvals.argmin()]
+    if np.dot(w @ L_in, template.T) < 0:
+        w *= -1
+
+    return w

roiextract/filter.py

@@ -0,0 +1,154 @@
+import numpy as np
+import numpy.typing as npt
+import mne
+
+from typing import Collection
+
+from .utils import (
+    _check_input,
+    data2stc,
+    get_inverse_matrix,
+    get_label_mask,
+    get_aggregation_weights,
+)
+
+
+class SpatialFilter:
+    """
+    Convenience wrapper around a NumPy array that contains the spatial filter.
+
+    Parameters:
+    -----------
+    w: array_like, shape (n_channels,)
+        The weights of the spatial filter.
+    method: str, optional
+        Can be used to store the name of the method that was used to obtain the filter.
+    method_params: dict, optional
+        Can be used to store key parameters of the method for obtaining the filter.
+    name: str, optional
+        Can be used to add a unique name to the filter (e.g., name of the ROI).
+    """
+
+    def __init__(
+        self,
+        w: npt.ArrayLike,
+        method: str = "",
+        method_params: dict = dict(),
+        name: str = "",
+    ) -> None:
+        self.w = w
+        self.method = method
+        self.method_params = method_params
+        self.name = name
+
+    def __repr__(self) -> str:
+        """
+        Generate a short description for the filter in the following form:
+        ([x] - only added if present)
+
+        <SpatialFilter | [name] | [method (method_params)] | XX channels>
+        """
+        result = "<SpatialFilter"
+        if self.name:
+            result += f" | {self.name}"
+        if self.method:
+            params_str = [f"{k}={v}" for k, v in self.method_params.items()]
+            params_str = ", ".join(params_str)
+            params_str = f" ({params_str})" if params_str else ""
+            result += f" | {self.method}{params_str}"
+        result += f" | {self.w.size} channels>"
+
+        return result
+
+    @classmethod
+    def from_inverse(
+        cls,
+        fwd,
+        inv,
+        label,
+        inv_method,
+        lambda2,
+        roi_method,
+        subject,
+        subjects_dir,
+    ):
+        src = fwd["src"]
+        mask = get_label_mask(label, src)
+        W = get_inverse_matrix(inv, fwd, inv_method, lambda2)
+        w_agg = get_aggregation_weights(
+            roi_method, label, src, subject, subjects_dir
+        )
+        w = w_agg @ W[mask, :]
+        return cls(
+            np.atleast_1d(np.squeeze(w)),
+            method=f"{inv_method}+{roi_method}",
+            method_params=dict(lambda2=lambda2),
+            name=label.name,
+        )
+
+    def apply(self, data: npt.ArrayLike) -> np.array:
+        # TODO: check that the first dimension of data is suitable
+        return self.w @ data
+
+    def apply_raw(self, raw: mne.io.Raw | mne.io.RawArray) -> np.array:
+        return self.apply(raw.get_data())
+
+    def get_ctf(
+        self,
+        L: npt.ArrayLike,
+        mode: str = "power",
+        normalize: str | None = "sum",
+    ) -> np.array:
+        _check_input("mode", mode, ["power", "amplitude"])
+        _check_input("normalize", normalize, ["norm", "max", "sum", None])
+
+        # Estimate the CTF
+        ctf = self.w @ L
+        if mode == "power":
+            ctf = ctf**2
+
+        # Normalize if needed
+        if normalize == "norm":
+            ctf /= np.linalg.norm(ctf)
+        elif normalize == "max":
+            ctf /= np.abs(ctf).max()
+        elif normalize == "sum":
+            ctf /= np.abs(ctf).sum()
+        return ctf
+
+    def get_ctf_fwd(
+        self,
+        fwd: mne.Forward,
+        mode: str = "power",
+        normalize: str = "norm",
+        subject: str | None = None,
+    ) -> mne.SourceEstimate:
+        leadfield = fwd["sol"]["data"]
+        src = fwd["src"]
+        return data2stc(
+            self.get_ctf(leadfield, mode, normalize), src, subject=subject
+        )
+
+    def plot(self, info: mne.Info, **topomap_kwargs):
+        # Make sure that the provided info has the correct amount of channels
+        n_chans_filter = self.w.size
+        n_chans_info = len(info["ch_names"])
+        if n_chans_filter != n_chans_info:
+            raise ValueError(
+                f"The amount of channels in the provided Info object ({n_chans_info})"
+                f" does not match the length of the spatial filter ({n_chans_filter})"
+            )
+
+        w = np.squeeze(self.w)
+        return mne.viz.plot_topomap(w, info, **topomap_kwargs)
+
+
+def apply_batch(data, filters: Collection[SpatialFilter]) -> np.array:
+    # TODO: check that all filters have the same number of channels
+    # TODO: check that the first dimension of data is suitable
+    w = np.vstack([sf.w[np.newaxis, :] for sf in filters])
+    return w @ data
+
+
+def apply_batch_raw(raw, filters: Collection[SpatialFilter]) -> np.array:
+    return apply_batch(raw.get_data(), filters)

roiextract/numerical.py

@@ -0,0 +1,82 @@
+import numpy as np
+
+from numpy.linalg import norm
+from scipy.optimize import minimize
+
+
+def _ctf_ratio(w, L, mask):
+    # Split the leadfield into within and outside parts
+    L_in = L[:, mask]
+    L_out = L[:, ~mask]
+
+    ctf_out = np.squeeze(w @ L_out)
+    ctf_in = np.squeeze(w @ L_in)
+
+    F_out = norm(ctf_out) ** 2
+    F_in = norm(ctf_in) ** 2
+
+    # Function and its gradient for optimization
+    F = F_out / F_in
+    dF = 2 * w @ (L_out @ L_out.T - F * L_in @ L_in.T) / F_in
+
+    return F, dF
+
+
+def _ctf_homogeneity(w, L, P0, mask):
+    # Use only voxels within the mask
+    L_in = L[:, mask]
+
+    # Make sure P0 is a row vector with unit length
+    P0 = np.squeeze(P0)[np.newaxis, :]
+    P0 = P0 / norm(P0)
+
+    ctf_in = np.squeeze(w @ L_in)
+    P_in = ctf_in**2
+    dotprod = np.squeeze(P_in @ P0.T)
+    L_P = L_in * np.tile(P0, (L.shape[0], 1))
+
+    F = dotprod**2 / norm(P_in) ** 2
+    dF = (
+        4
+        / (norm(P_in) ** 2)
+        * (dotprod * ctf_in @ L_P.T - F * ctf_in**3 @ L_in.T)
+    )
+
+    # multiply with -1 to minimize
+    return (-1) * F, (-1) * dF
+
+
+def _ctf_compromise(w, L, P0, mask, lambda_):
+    F_hom, dF_hom = _ctf_homogeneity(w, L, P0, mask)
+    F_rat, dF_rat = _ctf_ratio(w, L, mask)
+
+    F = lambda_ * F_hom + (1 - lambda_) * F_rat
+    dF = lambda_ * dF_hom + (1 - lambda_) * dF_rat
+
+    return F, dF
+
+
+def minimize_with_several_guesses(fun, x0s, args, **kwargs):
+    solutions = {}
+    for x0 in x0s:
+        result = minimize(fun, x0, args=args, **kwargs)
+        solutions[result.fun] = result
+
+    best_result = min(list(solutions.keys()))
+    return solutions[best_result]
+
+
+def ctf_optimize_ratio_homogeneity(
+    leadfield, template, mask, lambda_, x0s, return_scipy=False, **kwargs
+):
+    result = minimize_with_several_guesses(
+        _ctf_compromise,
+        x0s,
+        args=(leadfield, template, mask, lambda_),
+        jac=True,
+        **kwargs,
+    )
+    if return_scipy:
+        return result
+
+    return result.x

roiextract/optimize.py

@@ -0,0 +1,288 @@
+import numpy as np
+
+from functools import partial
+
+from .analytic import ctf_optimize_ratio_similarity
+from .filter import SpatialFilter
+from .numerical import ctf_optimize_ratio_homogeneity
+from .quantify import ctf_quantify
+from .utils import (
+    get_label_mask,
+    resolve_template,
+    _check_input,
+    _report_props,
+    logger,
+)
+
+
+INITIAL_LAMBDAS = {"rat": 0, "sim": 0.999, "hom": 0.999}
+IS_DECREASING = {"rat": True, "sim": False, "hom": False}
+
+
+def suggest_lambda(opt_func, quant_func, criteria, threshold, tol=0.001):
+    initial_lambda = INITIAL_LAMBDAS[criteria]
+    props = quant_func(w=opt_func(lambda_=initial_lambda))
+    crit_thresh = threshold * props[criteria]
+    logger.info(
+        f"Suggesting lambda to obtain at least {threshold:.2g} of max {criteria}"
+    )
+    logger.info(f"Properties (lambda={initial_lambda}): {_report_props(props)}")
+    logger.info(f"Criteria threshold: {crit_thresh:.3g}")
+
+    left, right = 0, 1
+    while right - left > tol:
+        mid = (left + right) / 2
+        props = quant_func(w=opt_func(lambda_=mid))
+        logger.info(f"Properties (lambda={mid:.3g}): {_report_props(props)}")
+        if IS_DECREASING[criteria]:
+            if props[criteria] > crit_thresh:
+                left = mid
+            else:
+                right = mid
+        else:
+            if props[criteria] > crit_thresh:
+                right = mid
+            else:
+                left = mid
+
+    return (left + right) / 2
+
+
+def ctf_optimize(
+    leadfield,
+    template,
+    mask,
+    lambda_,
+    mode="similarity",
+    criteria="rat",
+    threshold=None,
+    initial="auto",
+    tol=0.001,
+    reg=0.001,
+    quantify=False,
+    name="",
+):
+    """
+    Derive a spatial filter that optimizes properties of the CTF for the extracted ROI time series
+
+    Parameters
+    ----------
+    leadfield: array_like
+        Lead field matrix for dipoles with fixed orientation with shape (channels, voxels).
+    template: array_like
+        Template CTF pattern for voxels with shape (voxels,). Only values within the ROI are used.
+    mask: array_like
+        Voxel mask of the region of interest with shape (voxels,). Contains ones and zeros for voxels within and
+        outside ROI, respectively.
+    lambda_: float
+        If 0, only ratio is optimized. If 1, only dot product. Values in between allow tweaking the balance between
+        optimization for dot product or ratio.
+    mode: str
+        Optimize a combination of ratio and similarity (mode="similarity") or ratio and homogeneity (mode="homogeneity").
+    reg: float
+        Regularization parameter to ensure that it is possible to calculate the inverse matrices.
+    quantify: bool
+        Whether to calculate CTF properties for the optimized spatial filter.
+
+    Returns
+    -------
+    sf: SpatialFilter
+        Spatial filter produced by the optimization.
+    props: dict, only returned if quantify=True
+        Dictionary that contains the estimates of CTF-based properties (ratio, similarity
+        and/or homogeneity).
+
+    Raises
+    ------
+    ValueError
+        If provided lambda_ value is out of [0, 1] range.
+    """
+    _check_input("mode", mode, ["similarity", "homogeneity"])
+    _check_input("initial", initial, ["auto", "ones", "reg"])
+    if lambda_ == "auto" and threshold is None:
+        raise ValueError("Threshold should be set if lambda_='auto' is used")
+
+    # Prepare the optimization and quantification functions
+    if mode == "similarity":
+        opt_func = partial(
+            ctf_optimize_ratio_similarity,
+            leadfield=leadfield,
+            template=template,
+            mask=mask,
+            regA=reg,
+        )
+        quant_func = partial(
+            ctf_quantify, leadfield=leadfield, mask=mask, w0=template
+        )
+    else:
+        # Setup the initial guess for numerical optimization
+        initial = ["ones", "reg"] if initial == "auto" else [initial]
+        x0s = []
+        if "ones" in initial:
+            x0_ones = np.ones((leadfield.shape[0],))
+            x0s.append(x0_ones)
+        if "reg" in initial:
+            # TODO: find some alternative to this formula (change lambda?)
+            regA = 0.1 if lambda_ == "auto" else np.exp(10 * lambda_**2 - 10)
+            x0_reg = ctf_optimize_ratio_similarity(
+                leadfield, template, mask, lambda_=0, regA=regA, regB=reg
+            )
+            x0s.append(x0_reg)
+
+        opt_func = partial(
+            ctf_optimize_ratio_homogeneity,
+            leadfield=leadfield,
+            template=template,
+            mask=mask,
+            x0s=x0s,
+        )
+        quant_func = partial(
+            ctf_quantify, leadfield=leadfield, mask=mask, P0=template
+        )
+
+    # Suggest lambda if needed
+    if lambda_ == "auto":
+        lambda_ = suggest_lambda(
+            opt_func, quant_func, criteria, threshold, tol=tol
+        )
+        logger.info(
+            f"lambda={lambda_:.2g} was selected using the {threshold:2g} threshold"
+        )
+
+    # Optimize the filter, normalize and quantify its properties if needed
+    w_opt = opt_func(lambda_=lambda_)
+    w_opt = w_opt / np.abs(w_opt).max()
+    sf = SpatialFilter(
+        w=w_opt,
+        method="ctf_optimize",
+        method_params=dict(lambda_=lambda_),
+        name=name,
+    )
+    if quantify:
+        props = quant_func(w=w_opt)
+        return sf, props
+
+    return sf
+
+
+def ctf_optimize_label(
+    fwd,
+    label,
+    template,
+    lambda_,
+    mode="similarity",
+    criteria="rat",
+    threshold=None,
+    initial="auto",
+    tol=0.001,
+    reg=0.001,
+    quantify=False,
+    name=None,
+):
+    # Extract data from Forward and Label
+    leadfield = fwd["sol"]["data"]
+    src = fwd["src"]
+    if name is None:
+        name = label.name
+
+    # Create a binary mask for the ROI
+    mask = get_label_mask(label, src)
+
+    # Support pre-defined options for template weights
+    template = resolve_template(template, label, src)
+
+    # Optimize the filter and quantify its properties if needed
+    return ctf_optimize(
+        leadfield,
+        template,
+        mask,
+        lambda_,
+        mode=mode,
+        criteria=criteria,
+        threshold=threshold,
+        initial=initial,
+        tol=tol,
+        reg=reg,
+        quantify=quantify,
+        name=name,
+    )
+
+
+def rec_optimize(
+    cov_matrix,
+    inverse,
+    template,
+    mask,
+    lambda_,
+    mode="similarity",
+    criteria="rat",
+    threshold=None,
+    tol=0.001,
+    reg=0.001,
+    quantify=False,
+    name="",
+):
+    return ctf_optimize(
+        cov_matrix.T @ inverse,
+        template,
+        mask,
+        lambda_,
+        mode=mode,
+        criteria=criteria,
+        threshold=threshold,
+        tol=tol,
+        reg=reg,
+        quantify=quantify,
+        name=name,
+    )
+
+
+def rec_optimize_label(
+    cov_matrix,
+    fwd,
+    inv,
+    label,
+    template,
+    lambda_,
+    mode="similarity",
+    criteria="rat",
+    threshold=None,
+    tol=0.001,
+    reg=0.001,
+    quantify=False,
+    name=None,
+    **inv_kwargs,
+):
+    from mne.minimum_norm.resolution_matrix import (
+        _get_matrix_from_inverse_operator,
+    )
+
+    # Extract data from Forward and Label
+    src = fwd["src"]
+    if name is None:
+        name = label.name
+
+    # Extract data from InverseOperator
+    inverse = _get_matrix_from_inverse_operator(inv, fwd, **inv_kwargs)
+
+    # Create a binary mask for the ROI
+    mask = get_label_mask(label, src)
+
+    # Support pre-defined options for template weights
+    template = resolve_template(template, label, src)
+
+    # Optimize the filter and quantify its properties if needed
+    return rec_optimize(
+        cov_matrix,
+        inverse,
+        template,
+        mask,
+        lambda_,
+        mode=mode,
+        criteria=criteria,
+        threshold=threshold,
+        tol=tol,
+        reg=reg,
+        quantify=quantify,
+        name=name,
+    )

roiextract/quantify.py

@@ -0,0 +1,178 @@
+import numpy as np
+
+from numpy.linalg import norm
+
+from .utils import resolve_template, get_label_mask
+
+
+def ctf_ratio(w, L, mask, source_mask=None):
+    """
+    Calculates ratio of CTF outside/within ROI
+    """
+
+    # Take into account only a subset of sources if source mask is provided
+    L_all = L.copy()
+    if source_mask is not None:
+        mask = np.logical_and(mask, source_mask)
+        L_all = L[:, source_mask]
+
+    # TODO: check that the mask contains at least one source
+
+    # Split lead field matrix into in and out parts
+    L_in = L[:, mask]
+
+    ctf_all = np.squeeze(w @ L_all)
+    ctf_in = np.squeeze(w @ L_in)
+
+    # Adjusted value in the [0, 1] range
+    return norm(ctf_in) / norm(ctf_all)
+
+
+def ctf_similarity(w, L, w0, mask, source_mask=None):
+    """
+    Cosine similarity of desired and constructed CTFs within ROI
+    """
+
+    # Take into account only a subset of sources if source mask is provided
+    if source_mask is not None:
+        within_mask = source_mask[mask]
+        mask = np.logical_and(mask, source_mask)
+        assert within_mask.sum() > 0
+
+    # Use only voxels within the mask
+    L_in = L[:, mask]
+
+    # TODO: check that the mask contains at least one source
+    assert mask.sum() > 0
+
+    # Make sure w0 is a row vector with unit length
+    if source_mask is not None:
+        w0 = w0[within_mask]
+    if w0.size > 1:
+        w0 = np.squeeze(w0)
+    w0 = w0[np.newaxis, :]
+    w0 = w0 / norm(w0)
+
+    dotprod = np.squeeze(w @ L_in @ w0.T)
+    ctf = np.squeeze(w @ L_in)
+
+    # Adjusted value in the [0, 1] range
+    return np.abs(dotprod / norm(ctf))
+
+
+def ctf_homogeneity(w, L, P0, mask, source_mask=None):
+    """
+    Homogeneity of the CTF within ROI
+    """
+
+    # Take into account only a subset of sources if source mask is provided
+    if source_mask is not None:
+        within_mask = source_mask[mask]
+        mask = np.logical_and(mask, source_mask)
+        assert within_mask.sum() > 0
+
+    # TODO: check that the mask contains at least one source
+    assert mask.sum() > 0
+
+    # Use only voxels within the mask
+    L_in = L[:, mask]
+
+    # Make sure P0 is a row vector with unit length
+    if source_mask is not None:
+        P0 = P0[within_mask]
+    if P0.size > 1:
+        P0 = np.squeeze(P0)
+    P0 = P0[np.newaxis, :]
+    P0 = P0 / norm(P0)
+
+    ctf2 = (w @ L_in) ** 2
+    dotprod = np.squeeze(ctf2 @ P0.T)
+
+    # Adjusted value in the [0, 1] range
+    return np.abs(dotprod / norm(ctf2))
+
+
+def ctf_quantify(w, leadfield, mask, w0=None, P0=None, source_mask=None):
+    """
+    Calculate similarity within ROI and in/out ratio for a given filter
+
+    Parameters
+    ----------
+    w: array_like
+        Spatial filter that needs to be quantified in terms of CTF.
+    L: array_like
+        Lead field matrix for dipoles with fixed orientation with shape (channels, voxels).
+    mask: array_like
+        Voxel mask of the region of interest with shape (voxels,). Contains ones and zeros for voxels within and
+        outside ROI, respectively.
+    w0: array_like
+        Template CTF pattern for voxels within ROI with shape (voxels_roi,).
+    P0: array_like
+        Template power contribution for voxels within ROI with shape (voxels_roi,).
+    source_mask: array_like
+        Voxel mask with shape (voxels,). Ones correspond to all voxels that should be
+        considered when evaluating CTF properties.
+
+    Returns
+    -------
+    result: a dictionary with the estimated CTF properties
+        'rat': float
+            Ratio of CTF within ROI and total CTF, lies in [0, 1].
+        'sim': float
+            Similarity between the actual CTF and the template CTF pattern, lies in [0, 1]. It is only returned if w0 was provided.
+        'hom': float
+            Homogeneity of the power contributions of voxels within the ROI, lies in [0, 1]. It is only returned if P0 was provided.
+
+    """
+
+    result = dict()
+    result["rat"] = ctf_ratio(w, leadfield, mask, source_mask=source_mask)
+    if w0 is not None:
+        result["sim"] = ctf_similarity(
+            w, leadfield, w0, mask, source_mask=source_mask
+        )
+    if P0 is not None:
+        result["hom"] = ctf_homogeneity(
+            w, leadfield, P0, mask, source_mask=source_mask
+        )
+
+    return result
+
+
+def ctf_quantify_label(w, fwd, label, w0=None, P0=None, source_mask=None):
+    # Extract data from Forward
+    leadfield = fwd["sol"]["data"]
+    src = fwd["src"]
+
+    # Create a binary mask for the ROI
+    mask = get_label_mask(label, src)
+
+    # Support pre-defined options for template weights
+    if w0 is not None:
+        w0 = resolve_template(w0, label, src)
+    if P0 is not None:
+        P0 = resolve_template(P0, label, src)
+
+    return ctf_quantify(
+        w, leadfield, mask, w0=w0, P0=P0, source_mask=source_mask
+    )
+
+
+def rec_quantify(w, cov_matrix, inverse, template, mask, source_mask=None):
+    return ctf_quantify(
+        w, cov_matrix.T @ inverse, template, mask, source_mask=source_mask
+    )
+
+
+def rec_quantify_label(w, fwd, label, template, source_mask=None):
+    # Extract data from Forward
+    leadfield = fwd["sol"]["data"]
+    src = fwd["src"]
+
+    # Create a binary mask for the ROI
+    mask = get_label_mask(label, src)
+
+    # Support pre-defined options for template weights
+    template = resolve_template(template, label, src)
+
+    return ctf_quantify(w, leadfield, template, mask, source_mask=source_mask)

roiextract/utils.py

@@ -0,0 +1,77 @@
+import logging
+import numpy as np
+import mne
+
+
+logger = logging.getLogger("roiextract")
+
+
+def _check_input(param, value, allowed_values):
+    if value not in allowed_values:
+        raise ValueError(f"Value {value} is not supported for {param}")
+
+
+def _report_props(props):
+    return ", ".join([f"{k}={v:.2g}" for k, v in props.items()])
+
+
+def get_label_mask(label, src):
+    vertno = [s["vertno"] for s in src]
+    nvert = [len(vn) for vn in vertno]
+    if label.hemi == "lh":
+        this_vertices = np.intersect1d(vertno[0], label.vertices)
+        vert = np.searchsorted(vertno[0], this_vertices)
+    elif label.hemi == "rh":
+        this_vertices = np.intersect1d(vertno[1], label.vertices)
+        vert = nvert[0] + np.searchsorted(vertno[1], this_vertices)
+    else:
+        raise ValueError("label %s has invalid hemi" % label.name)
+
+    mask = np.zeros((sum(nvert),), dtype=int)
+    mask[vert] = 1
+    return mask > 0
+
+
+def resolve_template(template, label, src):
+    if isinstance(template, str):
+        from mne.label import label_sign_flip
+
+        _check_input("template", template, ["mean_flip", "mean"])
+        signflip = label_sign_flip(label, src)[np.newaxis, :]
+
+        if template == "mean_flip":
+            return signflip
+        if template == "mean":
+            return np.ones((1, signflip.size))
+
+    return template
+
+
+def data2stc(data, src, subject=None):
+    vertno = [s["vertno"] for s in src]
+    return mne.SourceEstimate(
+        data=data, vertices=vertno, tmin=0, tstep=0.01, subject=subject
+    )
+
+
+def get_inverse_matrix(inv, fwd, method, lambda2):
+    # TODO: get rid of private dependency
+    from mne.minimum_norm.resolution_matrix import (
+        _get_matrix_from_inverse_operator,
+    )
+
+    return _get_matrix_from_inverse_operator(inv, fwd, method, lambda2)
+
+
+def get_aggregation_weights(method, label, src, subject, subjects_dir):
+    _check_input("method", method, ["mean", "mean_flip", "centroid"])
+    if method in ["mean", "mean_flip"]:
+        return resolve_template(method, label, src)
+
+    # find the center of mass
+    hemi_idx = 0 if label.hemi == "lh" else 1
+    label_vertices = label.get_vertices_used(src[hemi_idx]["vertno"])
+    centroid_idx = label.center_of_mass(
+        subject=subject, restrict_vertices=src, subjects_dir=subjects_dir
+    )
+    return (label_vertices == centroid_idx).astype(int)

roiextract-0.0.2.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: roiextract
+Version: 0.0.2
+Summary: Data-independent and data-driven optimization of extraction of ROI time series based on M/EEG
+Project-URL: Homepage, https://github.com/ctrltz/roiextract
+Project-URL: Bug Tracker, https://github.com/ctrltz/roiextract/issues
+Author-email: Nikolai Kapralov <kapralov@cbs.mpg.de>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Requires-Dist: mne
+Requires-Dist: numpy
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+# ROIextract
+
+Optimization of extraction of ROI time series based on the cross-talk function (CTF) or source reconstruction of spatial patterns (REC). **Work in progress!**
+
+## Usage
+
+Obtain a spatial filter that optimizes CTF properties:
+
+```python
+from roiextract import ctf_optimize_label
+
+sf = ctf_optimize_label(fwd, label, template, lambda_)
+
+sf, props = ctf_optimize_label(fwd, label, template, lambda_, quantify=True)
+
+sf = ctf_optimize_label(fwd, label, template, lambda_='auto', threshold=0.95)
+```
+
+Plot the filter as a topomap:
+
+```python
+sf.plot(info)
+```
+
+Apply it to the data to obtain the time course of activity in the ROI/label:
+
+```python
+label_tc = sf.apply(data)
+```
+
+Estimate the CTF for the filter:
+
+```python
+ctf = sf.get_ctf_fwd(fwd)  # ctf is an instance of mne.SourceEstimate
+```
+
+Plot the CTF on the brain surface:
+
+```python
+ctf.plot()
+```

roiextract-0.0.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+roiextract/__init__.py,sha256=_GA_t1v_b8OKJtvhKOcvCbl4A3dcJ4N_AHmPJCW2-pc,159
+roiextract/analytic.py,sha256=WuiQmHZ06Mvtd0MrcasbXiaukDJi1odprJM8oS-YLEI,2390
+roiextract/filter.py,sha256=uVRK0thESf8GsPYZpx9Ljghm_Vt_fI11u4TWwLRT3D4,4661
+roiextract/numerical.py,sha256=BtrBrJGf4d9-vcMLQb_LZbbdGjxvZPDZ1jg3jRzdPhA,1971
+roiextract/optimize.py,sha256=fy8GpCUWi5yGq0rrq5jQJAPMN__DwG6AhEW9FYRykXA,7851
+roiextract/quantify.py,sha256=jFwtGvzL_fvQxXAwRu99Mmfmz0VG7rkhILij1k4K8e0,5389
+roiextract/utils.py,sha256=wTcEv0ewTS17448BThnDuFbrjhdxNCebIFEayd6IMfc,2367
+roiextract-0.0.2.dist-info/METADATA,sha256=_m9pKYx3so-vruvq2dYXZa29yjNAwpsEZYyJdq88yRM,1502
+roiextract-0.0.2.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+roiextract-0.0.2.dist-info/licenses/LICENSE,sha256=EgvrKcYLEbvwsR_bnQY95QeSwsP2Y0Q_azHcXvri0XM,1073
+roiextract-0.0.2.dist-info/RECORD,,

roiextract-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.24.2
+Root-Is-Purelib: true
+Tag: py3-none-any

roiextract-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nikolai Kapralov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.