channel_matching

Decide which of a recording's channels a run receives.

A configuration asks for channels by exact name or by type, each with a sampling-rate requirement, and a type with a count range. The platform answers in two steps, and this module is those steps:

1. :func:match_channels. An exact requirement takes the channels whose identity is the canonical form of its name, else of the first of its alternatives the recording offers. A type requirement then takes every remaining channel of its type, in montage order. Either way a channel is taken only at a sampling rate the requirement accepts; one at another rate is left out, never refused.
2. :func:keep_first_per_type. Where a type matched more channels than its count range allows, the first ones in montage order are kept.

An explicit choice of channels narrows step 1 to the chosen ones, and a choice that exceeds a type's maximum is refused rather than trimmed, so step 2 applies only when nothing was chosen.

The functions take any channel with an index, a name, a source_name, a type and a sample_rate: a stored channel or a manifest's :class:~yousleep_common.models.analysis_manifest.ChannelRef.

ChannelMatch dataclass

Bases: Generic[C]

The channels a recording offers a configuration, and the exact names it lacks.

MatchableChannel

Bases: Protocol

What matching reads of a channel.

index property

Position of the signal in the recording.

name property

What the user calls the channel.

sample_rate property

Sampling rate in Hz, when known.

source_name property

The label the recording's header carries.

type property

The channel's signal type.

canonical_label(label)

Return the label's canonical identity, else the label: one spelling for one thing.

channel_identity(channel)

Return what a channel is, for exact matching.

A stored channel may carry its identity as canonical_name; otherwise it is the canonical form of the header label, else of the name.

keep_first_per_type(matched, recording)

Keep, per type, as many channels as the configuration takes, the first ones in the order given.

This is what the platform does when nothing was chosen explicitly and a recording offers more channels of a type than the analysis takes: montages list the primary derivations first, so the first ones are kept.

Parameters:

Name	Type	Description	Default
matched	Sequence[C]	Matched channels, as :func:match_channels returns them.	required
recording	RecordingInput	The configuration's recording input.	required

Returns:

Type	Description
tuple[list[C], list[C]]	The channels kept, in the order given, and the ones left out.

match_channels(channels, recording, *, requested=None)

Return the channels a recording offers the configuration's requirements.

Parameters:

Name	Type	Description	Default
channels	Sequence[C]	The recording's channels, in montage order.	required
recording	RecordingInput	The configuration's recording input.	required
requested	Collection[str] | None	An explicit choice, by channel name. When given, only the chosen channels can match.	None

Returns:

Type	Description
ChannelMatch[C]	The matched channels and the exact requirements left unmatched.

rate_accepted(channel, requirements)

Whether the channel's sampling rate is one the requirement accepts; an unknown rate is not held against it.

type_maxima(recording)

Return, per declared type with an upper bound, the most channels of it the configuration takes.