simtools-write-trigger-histograms#

Create trigger-histogram products from reduced event lists.

Overview#

Reads reduced event-data HDF5 files and writes trigger histograms. The products contain simulated and triggered event distributions used for production checks, CORSIKA-limit derivation, and Monte Carlo statistics estimates.

Use one or more input files or glob patterns. Files from each selected production are accumulated into the output HDF5 file. model_version, site, and the array-layout selection describe the simulation model associated with the input data.

By default, only events triggering at least two telescopes contribute to the trigger histograms. Set minimum_triggered_telescopes: 1 (or use --minimum_triggered_telescopes 1) when single- telescope triggers must be included, for example for a single-telescope layout.

For a directory of reduced event-data products, use event_data_directory. The application scans direct-child *.reduced_event_data.hdf5 files and groups files whose names differ only by a .part<digits> suffix. It writes one <group>.trigger_histograms.hdf5 product per group below output_path. With the htcondor backend, one job is submitted per group and the command returns after writing the submission manifest.

For a completed simulate_prod production, use production_path and one or more select expressions. The application reads the job manifests, groups reduced event-data files by their recorded configuration, and writes one trigger-histogram product per group. The site, model version, and array layout are read from each selected manifest; explicit layout or model options must agree with that metadata.

Input and output#

Role	Argument	Format	Description
Input	`event_data_files`	HDF5	Reduced event-data files or glob patterns.
Input	`event_data_directory`	Directory	Direct-child reduced event-data files.
Input	`production_path`	Directory	Production job manifests and their reduced event-data files.
Input	`select`	`KEY=VALUE`	Optional repeated metadata selection.
Output	`output_file`	HDF5	Trigger-histogram product.

The output can be passed to the CORSIKA-limit and Monte Carlo-statistics applications.

Malformed input files stop processing by default. Use skip_invalid_event_data_files to skip invalid files, and use max_workers to control parallel processing.

Command line arguments#

options#

–help

show this help message and exit

–event_data_files

Reduced event-data file or glob pattern. Provide one or more patterns to build histograms for multiple productions.

–event_data_directory

Directory containing reduced event-data files. Files with matching names after a ‘.part<digits>’ suffix is removed are processed into one output product.

–production_path

Directory containing production job metadata manifests to select input files from.

–require_complete_runs

Fail when selected run numbers are not contiguous within each configuration group.

–energy_bins_per_decade

Number of logarithmic energy bins per decade.

Default: 10.

–minimum_triggered_telescopes

Minimum number of triggered telescopes within each selected array layout required to fill trigger histograms.

Default: 2.

–angular_distance_bin_width

Angular-distance bin width. The range is taken from broad-range viewcone limits.

Default: 0.5 deg.

–core_distance_bin_width

Core-distance bin width. The range remains flexible and is rounded to a common physical grid.

Default: 20.0 m.

–skip_invalid_event_data_files

Skip malformed or incomplete reduced event-data files inside each input pattern. By default, stop at the first invalid file.

application#

–select: Selection expression as dotted.path=value. Can be repeated.
–show_options: Print available values for a supported option and exit.

simulation model#

–model_version: Simulation production model version(s). Use –show_options model_version.
–overwrite_model_parameters: JSON string with model parameters to overwrite
–site: Observatory site (e.g., North, South). Use –show_options site.
–array_layout_name: Array layout name(s) (e.g., CTAO-North-Alpha, LSTN-01). Telescope names are assumed as single-telescope layouts. Use –show_options array_layout_name.
–array_element_list: list of array elements (e.g., LSTN-01, LSTN-02, MSTN).

output#

–output_file

Output data file.

–output_file_format

file format of output data

Default: ecsv.

–skip_output_validation

skip output data validation against schema

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.

Examples#

Explicit input file#

Build trigger histograms from reduced events#

Aggregate reduced event data into an HDF5 product for limit and statistics studies.

Application: simtools-write-trigger-histograms

Integration test: write_trigger_histograms_from_file.yml

Command

simtools-write-trigger-histograms --config tests/integration_tests/config/write_trigger_histograms_from_file.yml

Configuration

array_element_list:
- MSTN-03
event_data_files: ${generated:proton_run000001_za20deg_azm180deg_North_CTAO-North-Alpha_7.0.0_test.reduced_event_data.hdf5}
model_version: 7.0.0
output_file: trigger_histograms.hdf5
output_path: simtools-output
site: South
energy_bins_per_decade: 10
minimum_triggered_telescopes: 1
angular_distance_bin_width: 0.5
core_distance_bin_width: 20.0

Input directory#

Build trigger histograms from a directory#

Group reduced event files by parameter space and write one HDF5 product per group.

Application: simtools-write-trigger-histograms

Integration test: write_trigger_histograms_from_directory.yml

Command

simtools-write-trigger-histograms --config tests/integration_tests/config/write_trigger_histograms_from_directory.yml

Configuration

array_element_list:
- MSTN-03
event_data_directory: ${generated:.}
model_version: 7.0.0
output_path: simtools-output
site: North
energy_bins_per_decade: 10
minimum_triggered_telescopes: 1
angular_distance_bin_width: 0.5

Production metadata#

simtools-write-trigger-histograms \
    --production_path /data/production \
    --select configuration.zenith_angle="20 deg" \
    --select configuration.energy_min="1 TeV" \
    --output_path trigger_histograms