simtools-plot-simtel-events#

Plot simulated events from sim_telarray files.

Use --pedestal_source monitoring to use the per-pixel high-gain pedestal stored in sim_telarray camera monitoring data for pedestal plots and signal integration. The default, waveform, estimates the pedestal separately for each event from the last 10 waveform samples; a pulse tail in that window can bias the estimate. The monitoring option requires valid monitoring data for every selected event.

Produces diagnostic figures from sim_telarray (.simtel.zst) files. Meant to run after simulations (e.g., simtools-simulate-flasher, simtools-simulate-illuminator).

What it does

Loads the provided sim_telarray file
Generates selected plots (signals, pedestals, time traces, waveforms, peak timing, etc.)
Saves all figures to a single multi-page PDF
Optionally also saves individual PNG files per figure

Command line arguments

simtel_file (str, required): A sim_telarray file to visualize (.simtel.zst).
telescope (str, required): Telescope name to process (e.g., LSTN-04, MSTN-01).
plots (list, optional): Which plots to generate. Choices: pedestals, signals, peak_timing, time_traces, waveforms, step_traces, all. Default: all.
number_of_pixels (int, optional): For time_traces: number of brightest pixel traces to plot. Default: 3.
pixel_step (int, optional): For step_traces and waveforms: step between pixel indices. Default: 100.
max_pixels (int, optional): For step_traces: maximum number of pixels to plot. Default: None (no limit).
vmax (float, optional): For waveforms: upper limit of color scale. Default: None (auto-scale).
sum_threshold (float, optional): For peak_timing: minimum pixel sum to consider. Default: 10.0.
timing_bins (int, optional): For peak_timing: number of histogram bins. Default: None (unit-width bins).
event_id (int or list, optional): Specific event ID(s) to plot. Default: None (first event).
max_events (int, optional): Maximum number of events to process. Default: 1.
pedestal_source (str, optional): Pedestal source for pedestal plots and signal integration. Choices: waveform, monitoring. Default: waveform.
output_file (str, optional): Base name for output files. PDF will be named <base>_<inputstem>.pdf. If omitted, uses input file stem.
save_pngs (flag, optional): Also save individual PNG files per plot.
figure_dpi (int, optional): Resolution for PNG outputs (alias: dpi). Default: 300.
output_path (str, optional): Directory for output files.

Examples

Plot signals and time traces for a telescope:

simtools-plot-simtel-events \
–simtel_file run000010_North_7.0.0_simulate_flasher.simtel.zst \ –telescope LSTN-04 \ –plots signals time_traces \ –output_file flasher_inspect
Generate all plots with PNG outputs:

simtools-plot-simtel-events \
–simtel_file run000010.simtel.zst \ –telescope MSTN-01 \ –plots all \ –save_pngs –figure_dpi 200
Plot specific events:

simtools-plot-simtel-events \
–simtel_file run000010.simtel.zst \ –telescope LSTN-04 \ –event_id 5 10 15 \ –plots signals pedestals

Command line arguments#

options#

–help

show this help message and exit

–simtel_file

Input sim_telarray file (.simtel.zst)

Required.

–plots

Plots to generate. Choices: all, peak_timing, pedestals, signals, step_traces, time_traces, waveforms

Default: [‘all’]. Choices: all, peak_timing, pedestals, signals, step_traces, time_traces, waveforms.

–number_of_pixels

For time_traces: number of pixel traces

Default: 3.

–pixel_step

Step between pixel ids for step plots

Default: 10.

–max_pixels

Cap number of pixels for step traces

–vmax

Color scale vmax

–half_width

Half window width for integrated images

Default: 8.

–offset

offset between pedestal and peak windows (integrated_pedestal_image)

Default: 16.

–sum_threshold

Minimum pixel sum to consider in peak timing

Default: 10.0.

–peak_width

Expected peak width in samples

Default: 8.

–examples

Number of example traces to draw

Default: 3.

–timing_bins

Number of bins for timing histogram (contiguous if not set)

–distance

Optional distance annotation for event_image (same units as input expects)

–event_id

Event ID(s) of the events to be plotted

–max_events

Maximum number of events to process

Default: 1.

–pedestal_source

Pedestal source: estimate from each waveform or use sim_telarray monitoring data

Default: waveform. Choices: waveform, monitoring.

–save_pngs

Also save individual PNG images per plot

simulation model#

–site: Observatory site (e.g., North, South). Use –show_options site.
–telescope: telescope model name (e.g., LSTN-01, SSTS-design, …)

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

application#

–show_options: Print available values for a supported option and exit.

Example#

Plot an LST flasher event#

Visualize camera signals, timing, and event-level quantities for a simulated LST calibration flash.

Application: simtools-plot-simtel-events

Integration test: plot_simtel_events.yml

Command

simtools-plot-simtel-events --config tests/integration_tests/config/plot_simtel_events.yml

Configuration

simtel_file: ${generated:full_simulation_run000010_North_7.0.0_simtools-simulate-flasher_LSTN-04.simtel.zst}
plots: all
max_events: 1
number_of_pixels: 3
telescope: LSTN-04
output_file: event_plots
test: true
figure_dpi: 72
output_path: simtools-output