goldpan

goldpan: a library of reusable pulse operations, cuts and derived quantities for SuperCDMS-type traces, factored out of the exploratory work of the NSDF-Data project (https://github.com/villano-lab/NSDF-Data). It is the Python package goldpan in src/goldpan/. Its companion for reducing whole datasets is goldsluice.

Install it: python -m pip install goldpan (from PyPI), with the extras you need: goldpan[archive] (HDF5), goldpan[parquet] (the native format), goldpan[root] (RQs in ROOT files), goldpan[midas] (MIDAS files). To work on it, clone this repository and python -m pip install -e ".[archive,parquet,root,midas]" pytest; an edit to a module then takes effect at once. check_environment.py warns if it is not installed. Documentation: https://villano-lab.github.io/goldpan/ (the reference is read from the docstrings). How to contribute: CONTRIBUTING.md.

from goldpan import quantities as q
from goldpan import cuts, operations as op, io
from goldpan.config import DCRC_RUN76, Z7, PulseConfig

config = DCRC_RUN76                      # name the readout of your data (see below)
bstd = q.pretrigger_std(pulses, config)
quiet = cuts.quiet_baseline(pulses, config)

The container. goldpan.data.Events holds one detector's events and is immutable: its detector (name, channels with roles, and the readout with its segments), its traces (read-only arrays, one per channel and segment, ev.trace("A")), its quantities (an Awkward Array, one record per event; the first fields series, dump, event identify the event) and its meta (provenance). select, with_quantities and concatenate return new objects. Nothing in it opens a file: adapters do (next paragraph). See the design notes of 2026-10-25 and 2026-10-26 (GoldpanGoldsluice/ in the log repository).

from goldpan.data import ChannelInfo, Detector, Events, Readout
detector = Detector("S104", (ChannelInfo("A", role="phonon"), ChannelInfo("B", role="phonon")), Readout.single(4096, DCRC_RUN76))
ev = Events.from_arrays(detector, {"A": traces_a, "B": traces_b}, series="07221203_2025", dump="F0001")
std = q.pretrigger_std(ev.trace("A"), ev.detector.readout.config())      # the readout comes from the detector
quiet = ev.select(cuts.quiet_baseline(ev.trace("A"), ev.detector.readout.config()))

Adapters. The only code that knows a file format. goldpan.adapters.parquet is the native format (reads and writes; its docstring is the specification, format version 1: one Parquet file per series and dump, plain Arrow types, a _goldpan.json manifest), and goldpan.adapters.idx reads a dump of the NSDF archive. read returns an Events; iter_chunks reads a big dataset a chunk at a time. Someone with another format (MIDAS, ROOT) writes a small module with read(path, **kw) -> Events and checks it with goldpan.testing.check_adapter; goldpan.adapters.register makes it available to goldpan.adapters.read(path, format=...). How to write one, step by step, with a tested example (tests/example_adapter.py): the guide Writing an adapter in the documentation. A small synthetic dataset to test against is in tests/data/sample_dataset/.

from goldpan.adapters import idx, parquet
from goldpan.channels import sensor_channels
channels = {c.name: (c.detector, c.channel) for c in sensor_channels()}
ev = idx.read('~/idx/07221203_2025_F0001', detector_name='NSDF', channels=channels, config=DCRC_RUN76)   # the readout is given, never assumed
parquet.write(ev, 'my_dataset')                      # needs the extra: pip install pyarrow (or `pip install goldpan[parquet]`)
for chunk in parquet.iter_chunks('my_dataset', chunk=256): ...   # or parquet.read('my_dataset', channels=['Side2pC'])

Raw DAQ files. goldpan.adapters.midas reads the SuperCDMS SNOLAB MIDAS files (.mid, .mid.gz, .mid.lz4) into an Events: you give the detector number, the channel numbers behind your channel names and the readout (its sample period is checked against the file), and only those channels are copied. meta has the run number, start and stop time from the ODB and whether the end-of-run event was reached; polling-cycle and veto-only events are skipped and counted; max_events= and iter_chunks keep a 15 GB file manageable. Checked against a real Z7 file (format version 8). Hybrid sampling is not read yet.

The RQs of the reconstruction. goldpan.adapters.rq_root reads the processed quantities of the collaboration's ROOT files (rqDir/eventTree and rqDir/zip<N>, with uproot) as a table of quantities, one record per event with the key series, dump, event first; branches= takes names and wildcards ("P*max"), a missing branch is NaN, and the detector number is always given. goldpan.adapters.rq.attach(events, table) adds such a table to an Events of the same events, matched on the key (refusing missing events, duplicate rows and name clashes).

This is the beginning of the README. Read the rest at the original. Read the full README ↗