Constants
The values every node agrees on: DATA_TYPE, the float32 every
sample is; the channel roles (signal, trigger, index,
quality, auxiliary, timestamp); the keys of a port context
and of a configuration; the two time bases. What they mean for the data
you get back is on Data Structures.
- class gpype.common.constants.Constants[source]
Bases:
ConstantsApplication-wide constants for g.Pype BCI framework.
Extends ioiocore Constants with g.Pype-specific constants, data types, and configuration keys for signal processing.
- DATA_TYPE
Default data type for numerical operations in the pipeline
alias of
float32
- INHERITED = -1
Special value indicating inherited timing or configuration
- class Keys[source]
Bases:
KeysConfiguration key constants for pipeline components.
Standard key names for configuration dictionaries used throughout the g.Pype framework.
- SAMPLING_RATE = 'sampling_rate'
Sampling rate in Hz (samples per second)
- CHANNEL_COUNT = 'channel_count'
Number of data channels in the signal
- FRAME_SIZE = 'frame_size'
Number of samples processed per frame
- FRAME_RATE = 'frame_rate'
Frame rate in Hz (frames per second, optional)
- DECIMATION_FACTOR = 'decimation_factor'
Factor by which to reduce the sampling rate
- CHANNEL_ROLES = 'channel_roles'
Per-channel semantic roles, one entry per channel. Absent means every channel is a signal channel.
- CHANNEL_LABELS = 'channel_labels'
Per-channel labels, one entry per channel. Absent means channels are unnamed and are referred to positionally.
- MONTAGE_SYSTEM = 'montage_system'
Name of the electrode system the labels come from, if any.
- EDGE_ID = 'edge_id'
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.
- MASTER_TIMELINE = 'master_timeline'
True on the stream that defines the master timeline.
- MASTER_PRIORITY = 'master_priority'
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.
- REMOTE_MASTER = 'remote_master'
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.
- UNOBSERVED_SOURCE = 'unobserved_source'
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_samplesandD-TIME-30.A replay core is a source that does not observe at all:
load_fromreproduces 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._pendingfor 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.
- CLOCK_SYNC = 'clock_sync'
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_NOTE = 'clock_note'
What the server’s Sync found wrong with that health, for a recording to carry as a note: absent while nothing is wrong.
- DEVICE_SERIAL = 'device_serial'
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.
- EXECUTION_MODE = 'execution_mode'
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.
- SAMPLE_COUNT = 'sample_count'
Total samples the source will emit, when it knows. A reader does; an amplifier never will.
- CHANNEL_UNITS = 'channel_units'
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_GAINS = 'channel_gains'
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_OFFSETS = 'channel_offsets'
- CHANNEL_CLIPPING = 'channel_clipping'
[low, high]in the channel’s own unit, the range a value was clipped to before storage.
- CHANNEL_FILTERS = 'channel_filters'
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.
- SAMPLING_RATE_EXACT = 'sampling_rate_exact'
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.
- START_TIME = 'start_time'
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.
- TRUST = 'trust'
whether the file was sealed, whether anything was recovered. Carried so a result derived from an unsealed recording can say so.
- Type:
How much the source vouches for the data
- GAPS = 'gaps'
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.
- MARKERS = 'markers'
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.
- TRIALS = 'trials'
Per-trial provenance of a
(time, channel, trial)block, as[[source_sample, label], ...], one entry per trial in the trial axis’s order.source_sampleis the marker’s sample in the recording the trial was cut from;labelis its condition. Published byEpochs, 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.
- INPUT = 'input'
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, underload_from, on an edge it is not assigned to, and where the path names no regular file.
- PROVENANCE = 'provenance'
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
INPUTnested under"input". Stamped once byPipeline.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.provenancereads it.- Type:
This run’s provenance record
- class TimeBase[source]
Bases:
objectWhat 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.
- WALL_CLOCK = 'wall_clock'
Advances with the host clock. Every live source, including a synthetic one such as Generator.
- RECORDED = 'recorded'
Advances through recorded data at whatever speed the reader is asked for, including as fast as the file can be read.
- class ExecutionMode[source]
Bases:
objectHow 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.
- REALTIME = 'realtime'
Frames arrive as the clock produces them. Every live source, and a reader replaying at a pace.
- BATCH = 'batch'
The whole recording arrives in one cycle, already synchronised, and the run ends when it has been processed.
- class ChannelRoles[source]
Bases:
objectSemantic 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.
- SIGNAL = 'signal'
Measured signal; what filters and spatial processing operate on
- INDEX = 'index'
Position on the master timeline
- TRIGGER = 'trigger'
Event or marker channel; must never be filtered
- QUALITY = 'quality'
Data validity, saturation or link quality indicator
- AUXILIARY = 'auxiliary'
Auxiliary sensor, e.g. accelerometer or battery
- TIMESTAMP = 'timestamp'
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.
- class Residency[source]
Bases:
objectResidency mode values for distributed pipeline execution.
- STANDALONE = 'standalone'
All nodes run locally, link acts as passthrough
- EDGE = 'edge'
Edge nodes run, link sends to server
- SERVER = 'server'
Server nodes run, link receives from edge
- class Bind[source]
Bases:
objectWhich 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.
- ANY = 'any'
Every interface, on both address families. What a LAN or container deployment needs, and what the broker has always done.
- LOOPBACK = 'loopback'
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.