goldpan.adapters.rq_root

The ROOT RQ adapter: the processed quantities (RQs) of the collaboration’s reconstruction, read with uproot; and write, which puts our own processed quantities into the same layout.

The RQs of a series are in a ROOT file with a directory rqDir holding eventTree (event-level quantities) and zip<N> (the quantities of detector number N), row-aligned. This adapter returns them as a table of quantities: an Awkward Array with one record per event whose first fields are the event key (series, dump, event, as in goldpan.data.KEY_COLUMNS) followed by the RQs, so that goldpan.adapters.rq.attach can add them to an Events of the same events:

from goldpan.adapters import rq_root, rq
table = rq_root.read("24260424_145101.root", detector=7, branches=["EventType", "PTOFamps", "P*max", "P*std"])
events = rq.attach(events, table)

  • The detector number is never assumed: pass detector=.

  • branches limits what is read; names may use * and ? ("P*max"). None reads everything. A branch that the file does not have is filled with NaN (a series without a channel’s RQs is not an error), listed in meta-less form by missing().

  • The key comes from the file: DumpNumber becomes the label F<dump:04d> (3 is "F0003"), EventNumber is event, and series is series= or, by default, the series name found in the file name (d{8}_d{4,6}).

  • Values are returned as stored (including a fill value such as -999999 where a detector was not read out).

  • path may be one file, a list of files or a folder of .root files; their events follow one after another.

Needs uproot (pip install uproot, in requirements.txt).

Writing (write) keeps our names: a channel’s quantities become branches <channel>_<quantity> (Side2pC_adc_max) in zip<N>, not the collaboration’s P<letter>S<side><quantity>. Only the container is theirs: rqDir/eventTree with SeriesNumber, DumpNumber, EventNumber, rqDir/zip<N> row-aligned with it, every branch a double. read reads the files back.

The trigger type of an event (the quantity trigger_type, a text such as Physics) goes into eventTree as the number TRIGGER_CODES gives it, because a branch is a number: Unknown is 0 and the names of the DAQ’s trigger types keep their numbers (Physics is 1, BeginOfRunRandom 2, …). The table is also stored in every file as the string infoDir/trigger_types (JSON, name to number), and a label that is not in it is an error, never a guess. read returns the number; the labels are only recorded, not interpreted.

Where the files go is not decided here. write(events, path) writes exactly where it is told and does not check that the folder is outside a Git repository: that guard, and the single output root (GOLDSLUICE_OUTPUT, see goldpan.dataset), belong to batch mode (goldsluice run, goldsluice.batch.check_output_location). Called by hand, keep the output outside the repository yourself.

Module Attributes

REVISION

Raised by one when a change of this reader changes what it returns for the same file (a fix), so that goldsluice run redoes the outputs made with the old one (goldpan.adapters.revision).

TRIGGER_CODES

The number that write gives each trigger type label in eventTree (and stores as infoDir/trigger_types).

Functions

branches(path, *, detector)

The branch names of the first file of path: {"eventTree": [...], "zip<N>": [...]}.

iter_chunks(path, *[, chunk, branches, series])

Yield the table of read in pieces of at most chunk events, file by file, without reading a file at once.

missing(path, *, detector, branches)

The requested branches (wildcards included) that the first file of path does not have, and that read fills with NaN.

read(path, *, detector[, branches, series])

The RQs of path (a file, a list of files or a folder of .root files) as a table of quantities, one record per event.

write(events, path, *, detector)

Write the quantities of events (their pulses are not written) as RQ-style ROOT files in the folder path; returns the files.
goldpan.adapters.rq_root.REVISION = 1

Raised by one when a change of this reader changes what it returns for the same file (a fix), so that goldsluice run redoes the outputs made with the old one (goldpan.adapters.revision). Not for a change that leaves the results alone.

goldpan.adapters.rq_root.TRIGGER_CODES = {'BaselineControlRandom': 5, 'BeginOfRunRandom': 2, 'BeginOfRunTestSignal': 6, 'EndOfRunRandom': 4, 'EndOfRunTestSignal': 7, 'InRunRandom': 3, 'Physics': 1, 'PollingCycleMetadata': 8, 'SDUAccelerometerChannel0': 10, 'SDUAccelerometerChannel1': 11, 'SDUAccelerometerChannel2': 12, 'SDUAccelerometerChannel3': 13, 'SDUAntenna': 15, 'SDULEMO': 14, 'SDUPileUp': 17, 'SDUSync': 16, 'SaltingStub': 9, 'Unknown': 0}

The number that write gives each trigger type label in eventTree (and stores as infoDir/trigger_types).

goldpan.adapters.rq_root.read(path, *, detector, branches=None, series=None)[source]

The RQs of path (a file, a list of files or a folder of .root files) as a table of quantities, one record per event.

detector is the number of the zip<N> tree to read (required). branches: names (with */? wildcards) to read, None for all; a name that no tree has is filled with NaN. The first fields are series, dump, event.

Parameters:

  • detector (int)

  • series (str | None)

Return type:

Array

goldpan.adapters.rq_root.iter_chunks(path, *, chunk=256, detector, branches=None, series=None)[source]

Yield the table of read in pieces of at most chunk events, file by file, without reading a file at once.

Parameters:

  • chunk (int)

  • detector (int)

  • series (str | None)

Return type:

Iterator[Array]

goldpan.adapters.rq_root.branches(path, *, detector)[source]

The branch names of the first file of path: {"eventTree": [...], "zip<N>": [...]}.

Parameters:

detector (int)

Return type:

dict

goldpan.adapters.rq_root.missing(path, *, detector, branches)[source]

The requested branches (wildcards included) that the first file of path does not have, and that read fills with NaN.

Parameters:

detector (int)

Return type:

list

goldpan.adapters.rq_root.write(events, path, *, detector)[source]

Write the quantities of events (their pulses are not written) as RQ-style ROOT files in the folder path; returns the files. One file per series and dump, <series>_<dump>.root, which read accepts (a folder of them is one dataset).

Each file has rqDir/eventTree (SeriesNumber, DumpNumber, EventNumber, and trigger_type as a number if the events have it) and rqDir/zip<detector> (one branch <channel>_<quantity> for each quantity of each channel, our names), row-aligned, every branch a double. A goldsluice entry in events.meta (the provenance of a batch run) is stored as the string infoDir/goldsluice. detector is the number of the zip<N> tree: it is never assumed. An existing file of the same name is replaced.

Parameters:
Return type:

list