goldpan.registry

A registry of the facts about an experiment that analysis needs and the library must not contain: the readouts (how a pretrigger window, a glitch and a sample period are set), and the detectors (their number, type, readout and where each named channel is wired in a given file format).

This module is the mechanism only. No detector of any experiment is written in goldpan; the records are data and live outside the package, in folders of TOML files (for the Run 76 detector of this project, the registry/ folder of the repository, which is laid out so it can become a repository of its own). The readout presets DCRC_RUN76 and Z7 of goldpan.config are older and stay where they are; a registry may define readouts too, and a name is looked up in the registry first and then among those presets. A registry is built from sources; a folder of TOML files is the first kind, and anything with a load() method that yields (origin, tables) pairs can take its place later (a Git repository, a database) without a change anywhere else:

from goldpan import registry

reg = registry.load("~/NSDF-Data/registry")        # one or more folders; the environment variable GOLDPAN_REGISTRY is added
reg.readout_config("DCRC_RUN76")                   # a goldpan.config.PulseConfig (a preset, or the registry's own readout)
reg.detector("NAI-S2").number                      # 1
reg.detector("NAI-S2").read_defaults("idx")        # {'channels': {...}, 'roles': {...}}: the defaults of [sources.read]

A dataset definition file names the folders in [dataset] registry = [...] (see goldpan.dataset), and a source whose detector is a name in the registry takes its readout, its channels and its roles from there. Anything written in the definition file itself wins over the registry, key by key.

The files. Any file *.toml of a folder (sorted by name); every file holds the tables readouts and detectors, and the integer format_version (1):

format_version = 1

[readouts.DCRC_RUN76]
pretrigger_samples = 500
glitch_samples = 10
sample_period_s = 0.8e-6
status = "inferred"                                # "confirmed" or "inferred": required
evidence = "where the numbers come from"           # required: what a reader needs to judge the entry

[detectors."NAI-S2"]
number = 1                                         # the N of zip<N> in RQ files, the detector number of the MIDAS ODB
readout = "DCRC_RUN76"
status = "inferred"
evidence = "..."
[detectors."NAI-S2".idx]                           # defaults for [sources.read] of a source of this format
channels = { Side2pC = [0, 0] }

Adding a record. add_record(folder, "detectors", name, table) (or "readouts") checks a record as the reader does and appends it to a file of folder (default detectors.toml or readouts.toml, made with format_version if it is new), leaving everything else in the file, comments included, as it was; record_text gives the text it would add. A name that the folder already defines is refused, as are a missing status or evidence and a readout that is neither in the registry nor a preset. Write status = "confirmed" only for what a file or a document says: a guess is "inferred", and the evidence says what it rests on.

Readouts take pretrigger_samples, glitch_samples, sample_period_s (all three: nothing is assumed), status, evidence, description and series; detectors take number, type_code, tower, plane, odb_name, readout, status, evidence, description and series, plus one table per file format. Unknown keys are errors, as in the dataset definition file, and a name defined twice (in two files or two sources) is an error, so two folders can never disagree silently.

Module Attributes

FORMAT_VERSION

The version of the registry files; a reader refuses a newer one.

ENV_VAR

Folders to add to every registry opened with load, separated like PATH (os.pathsep).

Functions

add_record(folder, kind, name, table, *[, file])

Add a detector or a readout to the registry folder folder: check it (record_text), refuse a name the folder already defines and a detector whose readout is neither in the folder nor a preset of goldpan.config, append it to file (default <kind>.toml; a new file starts with format_version) and read the folder again to make sure it still loads, restoring the file if it does not.

compare(record, found)

What a detector record and another description of the same detector disagree on, as messages (empty if they agree).

load(*folders[, use_environment])

A Registry of the TOML files in folders (and of the folders of the environment variable GOLDPAN_REGISTRY, unless use_environment is false).

record_text(kind, name, table)

The TOML text of one record, as add_record appends it: kind is "detectors" or "readouts", name the record's name and table its keys (for a detector, a key whose value is a table, such as idx, is the defaults for that file format).

Classes

DetectorRecord(name, number, type_code, ...)

A detector: its identity, its readout, and per file format the defaults of [sources.read].

FolderSource(folder)

The registry files of one folder (*.toml, in name order).

ReadoutRecord(name, config, status, evidence)

A readout: the three numbers of a goldpan.config.PulseConfig, and where they come from.

Registry([sources])

The records of one or more sources, read and checked when it is made.
goldpan.registry.FORMAT_VERSION = 1

The version of the registry files; a reader refuses a newer one.

goldpan.registry.ENV_VAR = 'GOLDPAN_REGISTRY'

Folders to add to every registry opened with load, separated like PATH (os.pathsep).

class goldpan.registry.ReadoutRecord(name, config, status, evidence, description='', series=(), origin='')[source]

Bases: object

A readout: the three numbers of a goldpan.config.PulseConfig, and where they come from.

Parameters:
name: str
config: Any

The PulseConfig.

status: str

"confirmed" or "inferred".

evidence: str
description: str = ''
series: Tuple[str, ...] = ()

The series (or patterns) the readout applies to, as written.

origin: str = ''

The file the record was read from.

class goldpan.registry.DetectorRecord(name, number, type_code, tower, plane, odb_name, readout, status, evidence, description='', series=(), read=<factory>, origin='')[source]

Bases: object

A detector: its identity, its readout, and per file format the defaults of [sources.read].

Parameters:
name: str
number: int | None

The N of zip<N> in RQ files and the detector number of the MIDAS ODB (Det07 is 7).

type_code: int | None

The ODB DetectorType (710 and 711 are Ge and Si HV, 700 and 701 iZIP).

tower: int | None
plane: int | None
odb_name: str | None

The DetectorName of the ODB (for example G149), when the name here is a different one.

readout: str | None

The name of the readout, to be found in the same registry.

status: str
evidence: str
description: str = ''
series: Tuple[str, ...] = ()
read: Mapping[str, Mapping[str, Any]]

Per file format, the keyword arguments of that adapter’s read that this detector sets.

origin: str = ''
read_defaults(format)[source]

The defaults for [sources.read] of a source of file format format (empty if the record has none).

Parameters:

format (str)

Return type:

dict

class goldpan.registry.FolderSource(folder)[source]

Bases: object

The registry files of one folder (*.toml, in name order). Anything with this load method is a source.

load()[source]

(origin, tables) for each file: the parsed TOML. ValueError if the folder is missing or a file is not TOML.

Return type:

Iterable[Tuple[str, Mapping]]

class goldpan.registry.Registry(sources=())[source]

Bases: object

The records of one or more sources, read and checked when it is made.

Parameters:

sources (Iterable)

readouts()[source]

All the readout records by name.

Return type:

dict

detectors()[source]

All the detector records by name.

Return type:

dict

has_readout(name)[source]
Parameters:

name (str)

Return type:

bool

has_detector(name)[source]
Parameters:

name (str)

Return type:

bool

readout(name)[source]

The readout record name; KeyError that lists the names there are.

Parameters:

name (str)

Return type:

ReadoutRecord

readout_config(name)[source]

The PulseConfig of the readout name: the registry’s own record if it has one, otherwise the preset of that name in goldpan.config (DCRC_RUN76, Z7). KeyError that lists both.

Parameters:

name (str)

detector(name)[source]

The detector record name; KeyError that lists the names there are.

Parameters:

name (str)

Return type:

DetectorRecord

goldpan.registry.load(*folders, use_environment=True)[source]

A Registry of the TOML files in folders (and of the folders of the environment variable GOLDPAN_REGISTRY, unless use_environment is false). An empty registry if there are none. ValueError for a folder that does not exist, a file that is not valid, or a name that two files define.

Parameters:

use_environment (bool)

Return type:

Registry

goldpan.registry.compare(record, found)[source]

What a detector record and another description of the same detector disagree on, as messages (empty if they agree). found is anything with the attributes number, type_code, tower, plane and name, such as the OdbDetector of goldpan.adapters.midas.detectors; only what the record states is compared (name against odb_name, else the record’s name).

Parameters:
Return type:

list

goldpan.registry.record_text(kind, name, table)[source]

The TOML text of one record, as add_record appends it: kind is "detectors" or "readouts", name the record’s name and table its keys (for a detector, a key whose value is a table, such as idx, is the defaults for that file format). Keys come in the order of the registry documentation, the file formats last. The record is checked as the reader checks it: ValueError says what is wrong.

Parameters:
Return type:

str

goldpan.registry.add_record(folder, kind, name, table, *, file=None)[source]

Add a detector or a readout to the registry folder folder: check it (record_text), refuse a name the folder already defines and a detector whose readout is neither in the folder nor a preset of goldpan.config, append it to file (default <kind>.toml; a new file starts with format_version) and read the folder again to make sure it still loads, restoring the file if it does not. Returns the path of the file written.

Parameters:
Return type:

Path