edfcore 0.1.6 → 0.1.8

package/src/index.ts

@@ -43,12 +43,15 @@ export type {
   EdfClockTime,
   EdfDiagnostic,
   EdfDiagnosticCode,
+  EdfEnvelopeChunk,
+  EdfEnvelopeSignal,
   EdfGap,
   EdfHeader,
   EdfInspection,
   EdfKnownDiagnosticCode,
   EdfLocation,
   EdfPatientId,
+  EdfPhysicalEnvelope,
   EdfRawHeaderFields,
   EdfRawSignalFields,
   EdfRecordIndex,
@@ -59,8 +62,11 @@ export type {
   EdfSeverity,
   EdfSignal,
   EdfStartTime,
+  EdfStatusWord,
   EdfTimeline,
+  EdfTriggerEvent,
   EdfVariant,
+  EnvelopeSelection,
   FetchLike,
   HttpResponseLike,
   HttpSourceOptions,
@@ -69,6 +75,7 @@ export type {
   ReadOptions,
   RecordRange,
   RecordSelection,
+  TriggerSelection,
   WindowSelection,
 } from './types.js';
 
@@ -147,5 +154,7 @@ export { buildRecordIndex, buildTimeline } from './record-index.js';
 // Convenience layer
 // ===========================================================================
 
+export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
+export { envelopeOfSamples, readEnvelope, toPhysicalEnvelope } from './envelope.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/src/types.ts

@@ -367,6 +367,85 @@ export interface EdfChunk {
   readonly diagnostics: readonly EdfDiagnostic[];
 }
 
+/**
+ * One signal's min/max envelope over a window, at a resolution the caller chose.
+ *
+ * The unit is the bucket, not the sample: `min[i]` and `max[i]` are the extremes of every sample
+ * that fell in bucket `i`. Drawing a twelve-hour recording into a thousand pixels needs exactly
+ * this and nothing else — the peaks are what a reader of an EEG trace is looking at, and they
+ * are the first thing naive subsampling throws away.
+ */
+export interface EdfEnvelopeSignal {
+  readonly signalIndex: number;
+  /** Digital extremes per bucket. Convert with `toPhysicalEnvelope`, never with `toPhysical`. */
+  readonly min: Int32Array;
+  readonly max: Int32Array;
+  /** Samples that landed in each bucket. Zero where the window had no samples to cover it. */
+  readonly counts: Int32Array;
+  /** Total samples reduced, i.e. the sum of `counts`. */
+  readonly sampleCount: number;
+  readonly firstSampleIndex: number;
+  readonly startSeconds: number;
+  readonly outOfDigitalRangeCount: number;
+}
+
+/** A contiguous run of records, reduced to buckets. One per run, exactly as `readWindow` splits. */
+export interface EdfEnvelopeChunk {
+  readonly records: RecordRange;
+  readonly startSeconds: number;
+  readonly durationSeconds: number;
+  /** Buckets actually filled. Never more than requested, and fewer for a short run. */
+  readonly bucketCount: number;
+  readonly secondsPerBucket: number;
+  readonly byteLength: number;
+  readonly signals: readonly EdfEnvelopeSignal[];
+  readonly precededByGap: EdfGap | undefined;
+  readonly diagnostics: readonly EdfDiagnostic[];
+}
+
+export interface EnvelopeSelection extends WindowSelection {
+  /**
+   * How many buckets to reduce the window into — in a viewer, the pixel width of the plot.
+   *
+   * A bucket per pixel is the point: asking for more buckets than the window has samples wastes
+   * work and yields empty buckets, so the count is clamped to the sample count of the densest
+   * signal in the run.
+   */
+  readonly buckets: number;
+}
+
+/** A physical-unit envelope. Separate from the digital one for the same reason `toPhysical` is. */
+export interface EdfPhysicalEnvelope {
+  readonly min: Float64Array;
+  readonly max: Float64Array;
+}
+
+/** One decoded BioSemi Status sample. Only the bits BioSemi documents are named. */
+export interface EdfStatusWord {
+  /** All 24 bits, unsigned. Decode rig-specific conventions from this. */
+  readonly raw: number;
+  /** The parallel trigger input: the low 16 bits. */
+  readonly trigger: number;
+  readonly newEpoch: boolean;
+  readonly cmsInRange: boolean;
+  readonly batteryLow: boolean;
+}
+
+/** A change of the trigger word, timed on the Status channel's own sample grid. */
+export interface EdfTriggerEvent {
+  readonly sampleIndex: number;
+  readonly seconds: number;
+  /** Exact, in 100 ns units. Compare with this, never with the float. */
+  readonly ticks: bigint;
+  readonly trigger: number;
+  readonly status: EdfStatusWord;
+}
+
+export interface TriggerSelection {
+  readonly startSeconds: number;
+  readonly durationSeconds: number;
+}
+
 export interface EdfAnnotation {
   /** Verbatim on-disk value, relative to the header startdate/starttime (EDF+ 2.2.4). */
   readonly onsetSecondsFromHeaderStart: number;