HFIR gamma-background analysis

This repository provides read-only access to the released HPGe gamma spectra, run metadata, detector locations/orientations, shield configurations, and selected paper products from Gamma Backgrounds for Experiments at the High Flux Isotope Reactor (arXiv:2607.05834).

The public bundle contains 1,802 calibrated text spectra in 354 run records. The browser and export tools do not require CERN ROOT and never write to the canonical SQLite database.

The repository also provides file-level corrections for six misleading Cycle 494 and Cycle 495 transition labels. See reference_data/hfir_reactor_state_annotations.csv. These corrections use measured Cd-113 line rates. They do not supply an official interval reactor power history and do not change the database.

Start here

Browse and export the released data

On Linux or macOS, from the repository root:

./scripts/setup_analysis.sh --browser-only
./scripts/run_data_browser.sh

Open http://localhost:8501. The browser supports:

• filtering by official HFIR cycle, operating/outage classification, shield, run text, and recorded location;
• a selectable, cropped HFIR location map where gold stars mark downward-facing detectors and red arrows mark the horizontal direction of tilted detectors (arrow length is only a visual cue, not a tilt magnitude);
• a run timeline in the America/New_York timezone;
• overlays of up to six calibrated spectra with energy range, rebinning, normalization, logarithmic scale, and Poisson errors; and
• CSV downloads of filtered run records and displayed spectrum bins.

The setup is safe to rerun. It downloads and verifies the versioned data bundle, creates .env with repository-relative defaults, removes the original creator's absolute directory from the downloaded database, and installs the lightweight browser environment in .venv.

Run the paper-facing analyses

The full setup also installs PyROOT and downloads the official arXiv source and ancillary files:

./scripts/setup_analysis.sh
source .env
.venv/bin/python scripts/public_analysis.py all

This needs Linux x86-64 for the PyPI ROOT wheel. On macOS or for a production ROOT build, use the conda instructions printed by the setup script:

./scripts/setup_analysis.sh
conda env create -f environment.yml
conda activate hfir-bg-analysis
source .env
python scripts/check_public_data_setup.py --sanitize-database-path
python scripts/public_analysis.py all

Allow approximately 3 GB for the downloads, environment, and generated output.

Does this reproduce every paper plot?

No. The repository makes the boundary explicit:

• Figure 14 is recalculated from the public calibrated spectra and database.
• The requested three-location portion of Figure 19 is replotted from the authoritative published unfolded-flux CSVs. It is not a new unfolding.
• Publication artifacts for all 28 numbered figures can be collected, but the other figures are source artwork, ancillary results, require external inputs, or have not yet been ported from legacy analysis code.

The complete machine-readable inventory is config/paper_figures.json. Inspect it with:

.venv/bin/python scripts/reproduce_paper.py --list
.venv/bin/python scripts/reproduce_paper.py --all --dry-run

See Paper figure reproducibility for the status definitions and exact output behavior. The broader release remains useful even when a paper-exact plotting workflow is unavailable: all 1,802 calibrated spectra can be browsed, filtered, loaded, and exported independently.

Requested analysis products

After the full setup, run:

.venv/bin/python scripts/public_analysis.py all

Outputs are written to analysis/public_analysis/:

• unfolded_key_locations.{png,pdf}: isotropic and front-face response-model results for MIF reactor-on, MIF reactor-off, and Shield Center;
• unfolded_key_locations_manifest.csv: the exact official ancillary input used for each curve;
• shield_configuration_spectra.{png,pdf,csv}: the Figure 14 comparison of no added water/lead, seven water layers, six water layers plus floor lead, and seven water layers plus floor lead; and
• shield_configuration_rates_30_60_keV.csv: reactor-on, reactor-off, and reactor-only rates with statistical errors.

Generate either group separately with public_analysis.py unfolded or public_analysis.py shields.

For the Figure 7 floor-scan supplemental-data review—including typical per-point counts, a representative spectrum, quantile spectra, and a bin-width occupancy study—run:

.venv/bin/python scripts/analyze_floor_scan_statistics.py

The method and exact selection are documented in Figure 7 floor-scan point statistics. A generated review package is included for immediate inspection.

For the exploratory measured-data correction of paper Tables 3 and 8, use an empty output directory:

peak_output_dir=$(mktemp -d /tmp/hfir-peak-statistics.XXXXXX)
python3 scripts/reanalyze_paper_peak_statistics.py \
  --bundle data/HFIRBG_public_data_v1.1.0 \
  --output-dir "$peak_output_dir"

This ROOT-free command fits raw integer channels with a declared simultaneous Poisson model and writes full covariance, profiles where required, bootstrap diagnostics, shape/background likelihood comparisons, hashes, and calibrated global/window/bin applicability tests restricted to the declared high-count diagnostic subset. Results remain exploratory; the present Table 3 and Table 8 models both fail the declared fit-quality criteria. Those diagnostics have not yet been applied to the historical paper procedure, so this failure does not show that the legacy model is adequate. Table 3 phase 2 fits one yield per run/component, then writes exposure-summed detector counts/rates, per-run and aggregate ratios, full propagated covariance, one normalized heterogeneity table, temporal-model identifiability, a compact yield-model comparison, and an exact historical reconstruction record. Table 8 uses a Fe/Cu canonical component set, treats the overlapping Al-27 and Ge-70 hypotheses as equal-status noncanonical sensitivities, and writes both all-declared and fit-quality-acceptable model-sensitivity covariance. No output is unfolded flux or a cadmium-abundance inference. See Paper peak-statistics correction, phase 2.

Table 8 also has a distinct local native-channel measured-count lane:

table8_output_dir=$(mktemp -d /tmp/hfir-table8-local.XXXXXX)
python3 scripts/reanalyze_paper_peak_statistics.py \
  --bundle data/HFIRBG_public_data_v1.1.0 \
  --output-dir "$table8_output_dir" \
  --table 8 \
  --table8-workflow local \
  --bootstrap-replicates 1

It fits four isolated triplets and one four-parent multiplet, preserves full within-domain covariance, and reports row-local Q/V/R status instead of applying the rejected global fit as a blanket veto. The current result is 12 supported quantitative, nine model-sensitive, and three ratio-unreliable rows. It is a new measured-data calculation, not a response validation. See Table 8 local ratios and response-model bridge.

The text spectra are measured detector counts, not unfolded incident flux. The public bundle includes ROOT-free NumPy copies of the two Geant4 response matrices used for the published unfolds, but reproducing a new unfold also requires the external unfolder. The full setup therefore uses the official arXiv ancillary CSVs as the authoritative unfolded results.

Export data without the web interface

The exporter writes ordinary, long-form CSV and accepts environment variables or explicit --db/--data-root paths.

Export the complete run and file catalogs:

.venv/bin/python scripts/export_public_data.py catalog
.venv/bin/python scripts/export_public_data.py files

Filter runs using the official calendar classification:

.venv/bin/python scripts/export_public_data.py catalog \
  --cycle 491 --calendar-state operating --contains MIF \
  --output analysis/exports/cycle491_mif.csv

Find file IDs for a run, then export calibrated bins for one or more files:

.venv/bin/python scripts/export_public_data.py files \
  --run-id 42 --output analysis/exports/run42_files.csv

.venv/bin/python scripts/export_public_data.py spectra \
  --file-id 100 --file-id 101 \
  --normalization counts/s/keV --rebin 8 --emin 30 --emax 3000 \
  --output analysis/exports/selected_spectra.csv

Use spectra --run-id 42 to export every calibrated file assigned to a run. Each spectrum row retains the file/run identifiers, live time, canonical A0/A1 calibration, bin center/width, raw counts, normalized value, and statistical error.

For Python or notebooks, the same ROOT-free API is available directly:

from src.public_data.browser import (
    load_spectrum,
    query_file_metadata,
    rebin_by_factor,
    spectrum_dataframe,
)

files = query_file_metadata()             # one row per calibrated file
spectrum = load_spectrum(int(files.iloc[0].file_id))
spectrum = rebin_by_factor(spectrum, 8)
bins = spectrum_dataframe(spectrum, "counts/s/keV")

HFIR reactor-cycle calendar

reference_data/hfir_cycle_calendar.csv is the durable cycle-date record covering this measurement campaign. It is transcribed from ORNL/TM-2023/3207 Appendix A, page A-3, and stores the source, DOI, retrieval date, schedule basis, and precision with every row.

The source publishes dates rather than transition times. Classifications therefore use day precision in America/New_York:

• calendar_cycle and calendar_reactor_state come from the official date intervals;
• reactor_cycle and reactor_state are separate labels inferred only from the original run name/description;
• a run spanning classifications is mixed; and
• malformed timestamps or dates outside the recorded interval remain unknown.

Do not infer an exact startup or shutdown time from a boundary date. Full provenance and limitations are in reference_data/README.md.

Data layout and portable paths

The setup downloads the data-v1.1.0 release into this ignored layout:

data/
└── HFIRBG_public_data_v1.1.0/
    ├── HFIRBG.db
    ├── migration_matrices/
    │   ├── migration_matrix_isotropic.npz
    │   └── migration_matrix_front.npz
    └── spectra/
        └── 1,802 calibrated .txt spectra

Version 1.0.1 corrects the Cycle492_NE_East cart coordinate used to display the detector orientation on the hall map. Version 1.1.0 adds the two portable, ROOT-free detector-response matrices used for the isotropic and front-face unfolding assumptions.

Configuration is controlled by:

• HFIRBGDATA: spectrum directory;
• HFIRBG_CALDB: canonical SQLite database;
• HFIRBG_ANALYSIS: generated-output root; and
• HFIRBG_PAPER_DATA: official paper ancillary directory.

.env.example supplies portable repository-relative defaults. The setup check modifies only the downloaded SQLite copy, replacing its creator-machine path with the bundle-relative spectra directory. HFIRBGDATA remains the authoritative override, so the repository contains no required user-specific absolute paths.

Validate a moved or manually downloaded bundle with:

python3 scripts/check_public_data_setup.py --sanitize-database-path

Do not run db.sync_files() against the canonical public database; all file, run, coordinate, shield, and calibration relationships are already populated.

ROOT-free response matrices

migration_matrices/migration_matrix_isotropic.npz and migration_matrices/migration_matrix_front.npz are compressed NumPy archives for the isotropic and uniform-front-face response assumptions, respectively. Each contains a float32 matrix array with shape (n_detected, n_generated), along with detected_energy_keV, generated_energy_keV, and simulated_generated_energy_mask arrays. Rows map to detected-energy bins and columns to generated-energy bins; both axes span 40--12000 keV in 1 keV bins. The matrix coefficients retain the normalization used for the published unfolding.

They can be read without CERN ROOT:

import numpy as np

with np.load("data/HFIRBG_public_data_v1.1.0/migration_matrices/"
             "migration_matrix_isotropic.npz") as response:
    matrix = response["matrix"]
    detected_energy_keV = response["detected_energy_keV"]
    generated_energy_keV = response["generated_energy_keV"]

The dense matrix expands to roughly 0.57 GB in memory. The metadata.json member in each archive records the scenario, source filename, energy bounds, and array convention.

Supplemental unfolding README

docs/UNFOLDING_RESULTS_README.md is an adapted and expanded repository guide to the ancillary file formats. After the full setup, the byte-for-byte official supplemental README referenced by the paper is at:

data/arxiv_2607.05834/anc/UNFOLDING_RESULTS_README.md

The same directory contains all per-location unfolded CSVs, plots, measurement metadata, and response-matrix validation summaries distributed with the paper.

Advanced and legacy analysis

The historical scripts/, src/database/, and src/utilities/ modules include peak fitting, calibration management, ROOT output, cart scans, and specialized paper-development workflows. Some can modify a database or write beside input spectra. They are intentionally not the default public-data path.

See Legacy analysis workflows before using those interfaces with a copy of the public database.

Troubleshooting

• Browser says data are not configured: run ./scripts/setup_analysis.sh --browser-only, then relaunch it.
• Port 8501 is occupied: run ./scripts/run_data_browser.sh --server.port 8502.
• ImportError: ROOT: the browser/export path does not need ROOT. For the full legacy/paper workflow, use the full setup or conda environment.
• Moved data: set HFIRBGDATA and HFIRBG_CALDB in .env, using quoted paths when they contain spaces.