goldpan.runmeta

Run metadata (high voltage, trigger setting, …) per event, from a table keyed by series.

Metadata applies to whole series, but an analysis needs it per event: a cut, a histogram, a colour. This joins the two in one pass over the events. numpy.unique(series, return_inverse=True) finds the few distinct series and the inverse index picks the table row of each event, so there is no string comparison per event and no pandas merge:

from goldpan import runmeta

meta = runmeta.read_table("series.csv")                    # a CSV with a `series` column and any others
cols = runmeta.per_event(q["series"], meta)                # {"hv_v": array, "trigger_value": array, ...}, one value per event
sel = (cols["hv_v"] == -34.0) & (cols["trigger_value"] == 2)

for key, idx in runmeta.groups(q["series"], meta, by=("hv_v", "trigger_value")):
    print(key, len(idx))                                   # idx: the indices of the events of that chunk

The table is data and is not in this library. Where it lives (a file next to the outputs, or the detector registry) is not decided here: every function takes the table as an argument. Numeric columns come back as float arrays (an empty cell is NaN), the others as text. The series column is always text. write_table writes such a table (a program that makes the file, such as a form in a browser, builds the columns and calls it); read_table of the file gives the same table back.

Functions

groups(series, table[, by])	Yield (key, event_indices) for each distinct combination of the by columns, sorted by key.
per_event(series, table[, columns])	One value per event for each metadata column, as {column: array} in the order of series.
read_table(path)	Read a CSV with a series column into {column: numpy array}.
write_table(path, table)	Write a table ({column: sequence}, as read_table gives it) to the CSV file path and return what read_table gives for that file.

goldpan.runmeta.read_table(path)

Read a CSV with a series column into {column: numpy array}.

A column whose every cell is a number becomes a float array (an empty cell is NaN), any other column stays text. series always stays text: names such as 07221121_2214 are numbers to float (it accepts underscores). A series listed twice is an error.

goldpan.runmeta.write_table(path, table)

Write a table ({column: sequence}, as read_table gives it) to the CSV file path and return what read_table gives for that file.

table needs a series column (text, every series once), written first; the other columns follow in the order of the mapping and have as many values as series. A column is all numbers (None or NaN is an empty cell) or all text (None is an empty cell), so the file reads back the same: a text column whose every cell looks like a number, or that mixes the two, is an error that names the column, and so are true/false values and a table without rows. Nothing is written when the table is refused.

goldpan.runmeta.per_event(series, table, columns=None)

One value per event for each metadata column, as {column: array} in the order of series.

series is the series column of the events. A series that is not in table is an error that names it. columns picks which table columns to return (default: all but series).

goldpan.runmeta.groups(series, table, by=('hv_v', 'trigger_value'))

Yield (key, event_indices) for each distinct combination of the by columns, sorted by key.

The combinations are found on the small table first, so the cost is one pass over the events.