from __future__ import annotations
from typing import Optional, Union
import numpy as np
from ...common._private import channels
from ...common.constants import Constants
from ...common.montage import Montage
from ..core.io_node import IONode
#: Default input port identifier
PORT_IN = Constants.Defaults.PORT_IN
#: Default output port identifier
PORT_OUT = Constants.Defaults.PORT_OUT
[docs]
class ChannelSelector(IONode):
"""Selects channels by name, by role, or by position.
Router addresses channels by position, which is what you want when
wiring a pipeline and not what you want when a montage changes. This
addresses them by what they are:
ChannelSelector(labels=["C3", "Cz", "C4"])
ChannelSelector(roles=Constants.ChannelRoles.SIGNAL)
ChannelSelector(indices=[0, 2, 4], exclude=True)
Selecting by role is the device-agnostic form: every amplifier
appends different extras, and asking for the signal channels is the
same request on all of them.
Every failure is raised at setup, i.e. when the pipeline starts and
before a file or a socket exists. Skipping a channel that could not
be found would change the channel count silently, everything
downstream would accept it, and the operator would find out on
analysis day that an electrode is missing from the whole recording.
"""
#: Exactly one of these must be given -- the constructor refuses
#: any other count. Declared because no per-parameter field can say
#: it: read one at a time they all look merely optional, so a form
#: built from the catalog would offer three optional fields and
#: produce a document that always fails.
ONE_OF = (("labels", "roles", "indices"),)
[docs]
class Configuration(IONode.Configuration):
"""Configuration class for ChannelSelector parameters."""
[docs]
class Keys(IONode.Configuration.Keys):
"""Configuration keys for ChannelSelector settings."""
#: Whether the selection is inverted
EXCLUDE = "exclude"
[docs]
class OptionalKeys(IONode.Configuration.OptionalKeys):
"""Optional configuration keys."""
#: Channel labels to select
LABELS = "labels"
#: Channel roles to select
ROLES = "roles"
#: Channel indices to select
INDICES = "indices"
[docs]
def __init__(
self,
labels: Optional[list] = None,
roles: Optional[Union[str, list]] = None,
indices: Optional[list] = None,
exclude: bool = False,
**kwargs,
):
"""Initialize the channel selector.
Args:
labels: Channel names to select. Also reorders: the output
follows the order given.
roles: One role, or several, from Constants.ChannelRoles.
indices: Channel positions to select. Also reorders.
exclude: Invert the selection. Survivors keep input order.
**kwargs: Additional arguments for the parent IONode.
Raises:
ValueError: If not exactly one criterion is given, if it is
empty, or if it repeats an entry.
"""
given = [c for c in (labels, roles, indices) if c is not None]
if len(given) != 1:
raise ValueError(
"Give exactly one of 'labels', 'roles' or 'indices'."
)
if roles is not None and isinstance(roles, str):
roles = [roles]
criterion = given[0] if not isinstance(given[0], str) else roles
if len(criterion) == 0:
raise ValueError("The selection must not be empty.")
if len(set(map(str, criterion))) != len(criterion):
raise ValueError("The selection must not repeat an entry.")
opt = self.Configuration.OptionalKeys
if labels is not None:
# Normalise through the montage so an older name selects the
# channel it became, e.g. T3 selecting T7.
kwargs.setdefault(
opt.LABELS, [Montage.normalise(str(x)) for x in labels]
)
if roles is not None:
kwargs.setdefault(opt.ROLES, list(roles))
if indices is not None:
kwargs.setdefault(opt.INDICES, [int(x) for x in indices])
super().__init__(exclude=bool(exclude), **kwargs)
self._selection = None # Resolved channel positions
def _resolve(self, context: dict) -> list:
"""Resolve the configured criterion to channel positions.
Args:
context: Input port context.
Returns:
Channel positions, in selection order.
Raises:
ValueError: If anything requested is absent.
"""
opt = self.Configuration.OptionalKeys
count = channels.channel_count(context)
wanted_labels = self.config.get(opt.LABELS)
if wanted_labels:
if not channels.has_labels(context):
raise ValueError(
"Cannot select by label: the input declares no channel "
"labels. Use indices, or name the channels first with "
"a ChannelLabeler."
)
present = [
Montage.normalise(str(x)) for x in channels.labels_of(context)
]
missing = [x for x in wanted_labels if x not in present]
if missing:
raise ValueError(
f"Channel label(s) {missing} are not in the input. "
f"Available: {present}"
)
return [present.index(x) for x in wanted_labels]
wanted_roles = self.config.get(opt.ROLES)
if wanted_roles:
present = list(channels.roles_of(context))
missing = [r for r in wanted_roles if r not in present]
if missing:
raise ValueError(
f"No channel carries role(s) {missing}. Present roles: "
f"{sorted(set(present))}"
)
return [i for i, r in enumerate(present) if r in wanted_roles]
wanted = self.config.get(opt.INDICES)
out_of_range = [i for i in wanted if not 0 <= i < count]
if out_of_range:
raise ValueError(
f"Channel index/indices {out_of_range} are out of range for "
f"an input with {count} channel(s)."
)
return list(wanted)
[docs]
def setup(
self, data: dict[str, np.ndarray], port_context_in: dict[str, dict]
) -> dict[str, dict]:
"""Resolve the selection and describe the output channels.
Args:
data: Initial data dictionary.
port_context_in: Input port contexts.
Returns:
Output port contexts.
Raises:
ValueError: If the selection resolves to no channels at all.
"""
port_context_out = super().setup(data, port_context_in)
context = port_context_in[PORT_IN]
selected = self._resolve(context)
if self.config[self.Configuration.Keys.EXCLUDE]:
dropped = set(selected)
selected = [
i
for i in range(channels.channel_count(context))
if i not in dropped
]
if not selected:
raise ValueError(
"The selection leaves no channels; a node cannot emit an "
"empty frame."
)
self._selection = selected
out = port_context_out[PORT_OUT]
out[Constants.Keys.CHANNEL_COUNT] = len(selected)
out.update(channels.select(context, selected))
return port_context_out
[docs]
def step(self, data: dict[str, np.ndarray]) -> dict[str, np.ndarray]:
"""Emit the selected channels.
Args:
data: Input frame.
Returns:
The selected columns, in selection order.
"""
return {PORT_OUT: data[PORT_IN][:, self._selection]}