Source code for gpype.common.constants

import ioiocore as ioc
import numpy as np


[docs] class Constants(ioc.Constants): """Application-wide constants for g.Pype BCI framework. Extends ioiocore Constants with g.Pype-specific constants, data types, and configuration keys for signal processing. """ #: Default data type for numerical operations in the pipeline DATA_TYPE = np.float32 #: Special value indicating inherited timing or configuration INHERITED = -1
[docs] class Keys(ioc.Constants.Keys): """Configuration key constants for pipeline components. Standard key names for configuration dictionaries used throughout the g.Pype framework. """ #: Sampling rate in Hz (samples per second) SAMPLING_RATE: str = "sampling_rate" #: Number of data channels in the signal CHANNEL_COUNT: str = "channel_count" #: Number of samples processed per frame FRAME_SIZE: str = "frame_size" #: Frame rate in Hz (frames per second, optional) FRAME_RATE: str = "frame_rate" #: Factor by which to reduce the sampling rate DECIMATION_FACTOR: str = "decimation_factor" #: Per-channel semantic roles, one entry per channel. Absent #: means every channel is a signal channel. CHANNEL_ROLES: str = "channel_roles" #: Per-channel labels, one entry per channel. Absent means #: channels are unnamed and are referred to positionally. CHANNEL_LABELS: str = "channel_labels" #: Name of the electrode system the labels come from, if any. MONTAGE_SYSTEM: str = "montage_system" #: Which edge builds a world-facing node, matched against #: ``LaunchConfig.edge_id``. A node configuration key rather than #: a context key; absent or None means every edge. EDGE_ID: str = "edge_id" #: True on the stream that defines the master timeline. MASTER_TIMELINE: str = "master_timeline" #: Priority the master won its election with, from #: MasterPriority. Travels beside MASTER_TIMELINE so that a #: process receiving the stream over a Link can re-run the same #: election locally on the same rung, rather than guessing one. MASTER_PRIORITY: str = "master_priority" #: True on a stream whose master was elected in *another* #: process, i.e. one that crossed a Link. #: #: MASTER_TIMELINE cannot say this. It means "a node upstream of #: you has already claimed", which is what stops a second Sync #: claiming a second time -- true in one process, false across a #: Link, where the claimant cannot reach this process's timeline #: at all. Forwarding it leaves nobody claiming; dropping it #: leaves nobody claiming either, unless the receiver is told to #: claim in the absent source's place. That is what this says. REMOTE_MASTER: str = "remote_master" #: True on a stream whose source will not feed the rate #: estimator, so whichever node is master here must do it. #: #: Sync's numbered path publishes the position and leaves the #: estimator alone, because the one source that numbers its #: samples in band -- an amplifier -- observes from its own #: acquisition callback, **once per notification**. Sync sees #: frames, and on a BCI Core those differ four-fold, which is #: what makes the source's observation the better one. Not, #: as this used to say, because its arrival time has "not been #: through a queue": that time is carried in band precisely so #: it survives the queue, and measurement put the two within #: the 100 us stamp quantum of each other. See #: ``Sync._observe_samples`` and ``D-TIME-30``. #: #: A replay core is a source that does not observe at all: #: ``load_from`` reproduces the recorded candidacy, the frames #: and their boundaries, but there is no acquisition callback #: behind it. #: #: The consequence is silent and was measured on a BCI Core #: recording: the relation is never solved, the numbered stream #: replays perfectly anyway -- it carries its own positions -- #: and every sparse stream beside it is held in #: ``Sync._pending`` for the whole run. Not discarded, so not #: counted and not logged. 52 keystrokes in, 0 out. #: #: Distinct from REMOTE_MASTER, which says the master is real #: but unreachable. Here the master is in this process and #: perfectly reachable; it simply does not observe. UNOBSERVED_SOURCE: str = "unobserved_source" #: The clock-sync health of the edge that sent this stream: #: ``{offset, uncertainty, converged, epoch, edge}``, as the #: edge's start converged on it (D-TIME-69). Set by the edge's #: sending Link, read by the server's Sync; absent from a stream #: whose sender does not sync, such as a 4.0 edge. CLOCK_SYNC: str = "clock_sync" #: What the server's Sync found wrong with that health, for a #: recording to carry as a note: absent while nothing is wrong. CLOCK_NOTE: str = "clock_note" #: Serial number of the device that produced this stream. #: #: Provenance, not configuration: it answers "which physical #: amplifier is this recording from", which a configuration #: cannot. A BLE source discovers its device during start(), by #: which point its Configuration already exists and is read-only, #: so the serial has nowhere to go there -- but a port context is #: built at setup(), after the handle is open, which is exactly #: late enough. DEVICE_SERIAL: str = "device_serial" #: Execution mode of the run this stream belongs to, from #: Constants.ExecutionMode. Travels in the context so a node can #: declare its output shape accordingly in setup(), which is the #: one place the mode legitimately has to be visible. EXECUTION_MODE: str = "execution_mode" #: Total samples the source will emit, when it knows. A reader #: does; an amplifier never will. SAMPLE_COUNT: str = "sample_count" #: Physical unit per channel, one entry per channel. Absent #: means the source does not record units -- which is not the #: same as dimensionless, and is why this is absent rather than #: defaulted. CHANNEL_UNITS: str = "channel_units" #: Per-channel calibration, GTC's CHAN field set (D-BATCH-43): #: one entry per channel, None where a channel's own value is #: not recorded. #: #: Gain and offset are exact -- ``[numerator, denominator]``, #: the same shape as SAMPLING_RATE_EXACT -- never a float, so a #: stored calibration round-trips exactly rather than as a #: decimal a second conversion cannot undo. CHANNEL_GAINS: str = "channel_gains" CHANNEL_OFFSETS: str = "channel_offsets" #: ``[low, high]`` in the channel's own unit, the range a value #: was clipped to before storage. CHANNEL_CLIPPING: str = "channel_clipping" #: Hardware filters already applied, as a list of descriptions #: per channel (empty where none were). Free provenance a #: vendor's driver can supply and nothing downstream can #: reconstruct once the data has passed through them. CHANNEL_FILTERS: str = "channel_filters" #: The sampling rate as ``[numerator, denominator]``, when the #: source knows it exactly. SAMPLING_RATE stays the float the #: engine computes with; this is what a round trip restores, so #: 512000/1001 does not become a decimal on the way through. SAMPLING_RATE_EXACT: str = "sampling_rate_exact" #: Absolute time of the first sample, ISO 8601 with offset. A #: string rather than a datetime because a port context crosses #: a Link as JSON. START_TIME: str = "start_time" #: How much the source vouches for the data: whether the file #: was sealed, whether anything was recovered. Carried so a #: result derived from an unsealed recording can say so. TRUST: str = "trust" #: Recording interruptions, as ``[[first_missing, n_missing, #: reason], ...]`` on the sample grid. A dense block across a #: dropout is silently wrong, so a consumer that cuts epochs has #: to be able to see them. GAPS: str = "gaps" #: Events, as ``[[sample, duration, channel, label], ...]``, #: with sample relative to the first sample of the block. A #: trigger channel is how markers arrive; this is how they are #: reasoned about afterwards. MARKERS: str = "markers" #: Per-trial provenance of a ``(time, channel, trial)`` block, #: as ``[[source_sample, label], ...]``, one entry per trial in #: the trial axis's order. ``source_sample`` is the marker's #: sample in the recording the trial was cut from; ``label`` is #: its condition. Published by :class:`~gpype.Epochs`, which #: also drops MARKERS from the same context -- the time axis no #: longer indexes the source recording, so a marker position #: would name a meaningless row. TRIALS: str = "trials" #: The file a reader read, as ``{name, size, mtime, sha256}``: #: the basename, the size in bytes, the modification time as ISO #: 8601 in UTC, and the hex SHA-256 of the whole file. The digest #: is the identity; a copy keeps it under another name and mtime. #: Absent where the reader opened no file: on a server, under #: ``load_from``, on an edge it is not assigned to, and where the #: path names no regular file. INPUT: str = "input" #: This run's provenance record: the document (or, when the #: pipeline holds a function node, the names of those instead), its #: content hash, package versions, execution mode, any fitted #: artifacts and what trained them, and this stream's own #: ``INPUT`` nested under ``"input"``. Stamped once by #: ``Pipeline.start()`` (``common._private.provenance``) and #: merged into every source's own output context, so it crosses #: a Link as JSON like everything else here (D-BATCH-14). #: ``Result.provenance`` reads it. PROVENANCE: str = "provenance"
[docs] class TimeBase: """What a source's sample positions advance against. Two sources with different time bases cannot be merged: one moves with the host clock while the other moves through a recording, so there is no single instant that a given sample of each refers to. Declared rather than detected, because this is a correctness check, not a security boundary -- a source that misdeclares gets a meaningless pipeline, which is its own author's problem. """ #: Advances with the host clock. Every live source, including a #: synthetic one such as Generator. WALL_CLOCK: str = "wall_clock" #: Advances through recorded data at whatever speed the reader is #: asked for, including as fast as the file can be read. RECORDED: str = "recorded"
[docs] class ExecutionMode: """How a pipeline is driven. A pipeline is wholly one or the other -- there are no mixed pipelines, and therefore no barrier inside a pipeline and no end-of-stream token in the API. Declared by the *source*, not derived from the time base: a recording paced to the wall clock is a legitimate realtime pipeline, which is what makes those two properties independent. """ #: Frames arrive as the clock produces them. Every live source, #: and a reader replaying at a pace. REALTIME: str = "realtime" #: The whole recording arrives in one cycle, already #: synchronised, and the run ends when it has been processed. BATCH: str = "batch"
[docs] class ChannelRoles: """Semantic role of a channel within a port. Roles say *how a channel must be treated*, so that multichannel operations do not have to infer meaning from channel position. Labels say what a channel *is*; the two are independent. """ #: Measured signal; what filters and spatial processing operate on SIGNAL: str = "signal" #: Position on the master timeline INDEX: str = "index" #: Event or marker channel; must never be filtered TRIGGER: str = "trigger" #: Data validity, saturation or link quality indicator QUALITY: str = "quality" #: Auxiliary sensor, e.g. accelerometer or battery AUXILIARY: str = "auxiliary" #: Host time at which the sample beside it was acquired, #: wrapped as channels.wrap_time describes. #: #: Consumed by Sync and never forwarded, so it is internal #: to the stretch between a source and its Sync. It exists #: because that stretch may contain a Link: reading a clock #: on the far side of one measures the transport, not the #: acquisition, and the master-timeline fit built from those #: readings is then a fit to the network. TIMESTAMP: str = "timestamp"
[docs] class Residency: """Residency mode values for distributed pipeline execution.""" #: All nodes run locally, link acts as passthrough STANDALONE: str = "standalone" #: Edge nodes run, link sends to server EDGE: str = "edge" #: Server nodes run, link receives from edge SERVER: str = "server"
[docs] class Bind: """Which interfaces a SERVER-residency broker listens on. Deliberately separate from the endpoint. An endpoint's host is the address a *client* dials, which is not always the address the server binds: a container binds a wildcard and advertises its own address, and one string cannot carry both. Reading the endpoint as a bind address would therefore break exactly the deployment that needs the distinction. """ #: Every interface, on both address families. What a LAN or #: container deployment needs, and what the broker has always #: done. ANY: str = "any" #: The loopback addresses only, so nothing off this machine can #: reach the data socket at all. What a single-machine or #: embedded deployment wants, and what keeps a phone's data #: socket off the Wi-Fi it happens to be on. LOOPBACK: str = "loopback"
[docs] class Defaults(ioc.Constants.Defaults): #: Default frame size in samples FRAME_SIZE: int = 1