goldpan.data

The in-memory container of one detector’s events: traces, quantities, readout, provenance.

This is the middle of the design in GoldpanGoldsluice/2026-10-25 (log repository): file formats live in adapters, the functions of goldpan are pure, and what passes between them is an Events, immutable. The simplest version is built first: one detector, and the traces of a channel are held in named segments (here only the default, "main"), so that hybrid sampling later (a coarse and a fine segment) changes no signature and no file.

An Events has

  • a Detector: its name, its channels (name, role, the readout unit and input they come through) and its Readout (the segments of a trace, each with a PulseConfig);

  • traces: {(channel, segment): array of shape (n_events, n_samples_of_the_segment)}, read-only (use ev.trace(channel));

  • quantities: an Awkward Array, one record per event. Its first fields identify the event, series, dump and event (event numbers restart in every dump), and t_trigger (seconds on the clock named in meta["clock"]) may follow; the rest are the quantities (RQs). Flat numbers and variable-length lists are both fields.

  • meta: provenance (source files, program versions, units of the quantities, the clock).

Nothing here opens a file. Build one by hand with Events.from_arrays (for a notebook or a test) or get one from an adapter.

Module Attributes

MAIN

The name of the default segment of a trace.

KEY_COLUMNS

The fields that identify an event in Events.quantities; they cannot be replaced by with_quantities.

TIME_COLUMN

The optional field with the trigger time in seconds, on the clock named in Events.meta["clock"].

Classes

ChannelInfo(name[, role, unit, input])

Detector(name, channels, readout)

Events(detector, traces, numpy.ndarray], ...)

Readout(segments)

Segment(name, n_samples, config, start_s)

goldpan.data.MAIN = 'main'

The name of the default segment of a trace.

goldpan.data.KEY_COLUMNS = ('series', 'dump', 'event')

The fields that identify an event in Events.quantities; they cannot be replaced by with_quantities.

goldpan.data.TIME_COLUMN = 't_trigger'

The optional field with the trigger time in seconds, on the clock named in Events.meta["clock"].

class goldpan.data.ChannelInfo(name: str, role: str | None = None, unit: str | None = None, input: str | None = None)[source]

Bases: object

Parameters:

  • name (str)

  • role (str | None)

  • unit (str | None)

  • input (str | None)

name: str

The channel’s name, unique inside its detector (for example Side2pC).

role: str | None = None

What the channel measures (phonon, charge, …), so that a cut can be applied to every channel of a role.

unit: str | None = None

The readout unit (a board) the channel comes through, if that matters.

input: str | None = None

The input on that unit.

class goldpan.data.Segment(name: str, n_samples: int, config: goldpan.config.PulseConfig, start_s: float | None)[source]

Bases: object

Parameters:
name: str

main for an ordinary trace, coarse and fine for hybrid sampling.

Type:

The segment’s name

n_samples: int

Samples per trace in this segment.

config: PulseConfig

its pretrigger window, glitch samples and sample period.

Type:

The readout of this segment

start_s: float | None

Time of the first sample relative to the trigger, in seconds (negative before it); None if unknown.

classmethod main(n_samples, config)[source]

The ordinary single segment: the trigger is sample config.pretrigger_samples.

Parameters:
Return type:

Segment

class goldpan.data.Readout(segments: tuple)[source]

Bases: object

Parameters:

segments (tuple)

segments: tuple

The Segment objects of a trace, with unique names.

classmethod single(n_samples, config)[source]

A readout with the one segment main.

Parameters:
Return type:

Readout

segment(name='main')[source]
Parameters:

name (str)

Return type:

Segment

config(name='main')[source]

The PulseConfig to pass to the functions of goldpan for this segment.

Parameters:

name (str)

Return type:

PulseConfig

time_axis(name='main')[source]

Time of each sample of the segment in seconds relative to the trigger (needs the sample period and start).

Parameters:

name (str)

Return type:

ndarray

class goldpan.data.Detector(name: str, channels: tuple, readout: goldpan.data.Readout)[source]

Bases: object

Parameters:
name: str

The detector’s name, unique inside a dataset.

channels: tuple

The ChannelInfo objects of the detector, with unique names.

readout: Readout

How its traces are sampled.

channel_names()[source]

The names of the channels, in order.

Return type:

list

channel(name)[source]

The ChannelInfo called name.

Parameters:

name (str)

Return type:

ChannelInfo

channels_with_role(role)[source]

The names of the channels whose role is role, in order.

Parameters:

role (str)

Return type:

list

class goldpan.data.Events(detector: goldpan.data.Detector, traces: Mapping[tuple, numpy.ndarray], quantities: awkward.highlevel.Array, meta: Mapping[str, Any] = <factory>)[source]

Bases: object

Parameters:
detector: Detector

The detector these events were recorded by.

traces: Mapping[tuple, ndarray]

{(channel, segment): (n_events, n_samples)}, read-only views.

quantities: Array

the key fields, the optional t_trigger, then the quantities.

Type:

One record per event

meta: Mapping[str, Any]

Provenance and units; a read-only copy.

classmethod from_arrays(detector, traces, *, series='', dump='', event=None, quantities=None, meta=None)[source]

Build Events by hand: traces is {channel: (n_events, n_samples)} (segment main).

series and dump are one value for every event or one per event; event defaults to 0, 1, 2, … quantities adds more columns.

Parameters:
Return type:

Events

property n_events: int
trace(channel, segment='main')[source]

The read-only array (n_events, n_samples) of a channel’s segment.

Parameters:
Return type:

ndarray

time_axis(segment='main')[source]

Time of each sample of segment, seconds relative to the trigger, from this detector’s own readout.

Parameters:

segment (str)

Return type:

ndarray

select(where)[source]

The events where where is True (a boolean array of length n_events) or at the given integer positions.

Return type:

Events

with_quantities(**columns)[source]

A new Events with columns added or replaced; each value has one entry per event. Key fields cannot be replaced.

Return type:

Events

static concatenate(*events)[source]

The events of several Events of the same detector, one after another (meta of the first is kept).

Parameters:

events (Events)

Return type:

Events