simtools-derive-bias-curves#

Derive and plot bias curves from NSB and proton trigger rates.

Description#

This application combines NSB (Night Sky Background) and proton trigger rates to generate bias curves showing how trigger rates vary with threshold.

The tool:

  1. Extracts NSB trigger rates from reduced event-data HDF5 files

  2. Calculates proton trigger rates from proton reduced event-data HDF5 files

  3. Plots both curves on the same figure for comparison

  4. Outputs ECSV tables for runwise NSB simulation, runwise proton simulation, and combined bias curves

  5. Calculates the trigger threshold as the intersection point between the NSB curve and the scaled proton curve

  6. Exports the trigger threshold as a model parameter (asum_threshold, dsum_threshold, or discriminator_threshold depending on the telescope’s default trigger type)

The input directory should contain both:

  • NSB reduced event-data HDF5 files (e.g., gamma*.reduced_event_data.hdf5)

  • Proton simulation reduced event-data HDF5 files (e.g., proton*.reduced_event_data.hdf5)

The input files can be generated using simtools-generate-bias-curve-submissions.

Notes#

  • The trigger threshold is the intersection of the log-linear fits shown on the plot for NSB and proton rates scaled by 0.1 * scaling_factor. Each fit uses its finite, positive rates and requires at least two distinct thresholds. The intersection must fall within the threshold range shared by both fits.

  • Threshold labels in the HDF5 FILE_INFO filenames preserve decimal values such as asum7.2 and asum7.4 as separate simulation points.

  • The exported model parameter (asum_threshold, dsum_threshold, or discriminator_threshold) is written to the standard model data output directory under <telescope>/<parameter_name>/.

  • If no intersection point is found, the application raises an error.

Command line arguments#

options#

–help

show this help message and exit

–event_data_directory

Directory containing NSB/proton reduced event-data HDF5 files (e.g. gamma* and proton*).

Required.

–scaling_factor

Scaling factor to account for ions we didn’t simulate.

Default: 1.35.

–figure_file

Output plot file path or output directory. Default: bias_curve.png

Default: bias_curve.png.

–nsb_table_file

Output ECSV table file for NSB trigger rates. If not specified, no table is written.

–proton_table_file

Output ECSV table file for proton rates. If not specified, no table is written.

–title

Title for the bias curve plot. Default: ‘Trigger Rate Bias Curves’

Default: Trigger Rate Bias Curves.

simulation model#

–model_version

Simulation production model version(s). Use –show_options model_version.

–parameter_version

model parameter version

Required.

–overwrite_model_parameters

JSON string with model parameters to overwrite

–site

Observatory site (e.g., North, South). Use –show_options site.

–telescope

telescope model name (e.g., LSTN-01, SSTS-design, …)

model repository#

–simulation_models_path

Path containing the simulation-model repository to read.

–simulation_models_git_path

Path to a local normal, bare, or mirror Git repository containing simulation models.

–simulation_models_git_revision

Git tag, ref, or commit to read from the simulation-model repository.

application#

–show_options

Print available values for a supported option and exit.

Examples#

Derive an MSTN-01 trigger-rate bias curve#

Combine NSB and proton reduced event-data files to derive the analogue-sum trigger threshold for the North MST.

Application: simtools-derive-bias-curves

Integration test: derive_bias_curves_mstn-01.yml

Command

simtools-derive-bias-curves --config tests/integration_tests/config/derive_bias_curves_mstn-01.yml

Configuration

event_data_directory: ${generated:bias_curves_input}
scaling_factor: 1.35
figure_file: simtools-output/derive_bias_curves_mstn-01
nsb_table_file: simtools-output/derive_bias_curves_mstn-01/nsb_table.ecsv
proton_table_file: simtools-output/derive_bias_curves_mstn-01/proton_table.ecsv
title: MSTN-01 Trigger Rate Bias Curves
site: North
telescope: MSTN-01
model_version: 7.0.0
parameter_version: 1.0.0
output_path: simtools-output