Visualization

In this section you find the reference documentation of the modules contained in the visualization module.

visualize

Module for visualization.

visualization.visualize.configure_figure_output(args)

Set the figure output options of this process (like matplotlib rcParams).

Applications call this once at start with their parsed arguments; save_figure then uses figure_format, figure_dpi and figure_png_palette from them.

visualization.visualize.convert_png_to_palette(png_file)

Convert a PNG file in place to a 256-color palette image if that makes it smaller.

Parameters:

png_filePath or str

PNG file to convert.

visualization.visualize.figure_cache_key(renderer, renderer_modules, plot_config, rendered_data, context=None)

Return a SHA-256 key for identical plot inputs and rendering settings.

Parameters:

rendererstr

Stable identifier for the renderer.

renderer_modulesdict

Mapping of renderer component names to their source file paths.

plot_configdict

Plot settings that affect the visible figure.

rendered_dataobject

Normalized data supplied to the renderer.

contextRunContext or None, optional

Context containing figure output settings.

Returns:

str

SHA-256 digest representing the rendered figure inputs.

visualization.visualize.figure_output_settings(context=None)

Return figure output options from the context or from configure_figure_output.

visualization.visualize.pdf_report(path)

Write figures to a multi-page PDF, closing each figure after it is added.

Parameters:

pathpathlib.Path or str

Destination PDF path.

Yields:

_PdfReport

Report with an add(fig) method.

visualization.visualize.plot_1d(data, **kwargs)

Produce a high contrast one dimensional plot from multiple data sets.

Parameters:

data: numpy structured array or dict of structured arrays

Columns: x, y and optionally errors. Dict keys are the legend labels; the first entry is the reference for ratio or difference plots.

**kwargs:

Plot options (palette, big_plot, title, no_legend, legend_fontsize, no_markers, empty_markers, plot_ratio, plot_difference, xscale, yscale, xlim, ylim, xtitle, ytitle, error_type, error_label) and any kwargs accepted by plt.plot.

Returns:

pyplot.figure

Figure in which the plot was produced.

Raises:

ValueError

if a ratio or difference is requested with one data set.

visualization.visualize.plot_hist_2d(data, ax=None, **kwargs)

Produce a two dimensional histogram plot.

Parameters:

data: numpy structured array

Columns are used as the x-axis and y-axis titles.

ax: matplotlib.axes.Axes, optional

Axes to draw on. If not provided, a new figure is created.

**kwargs:

title, cmap and any kwargs accepted by plt.hist2d.

Returns:

pyplot.figure

Figure in which the plot was produced.

visualization.visualize.plot_histogram(data, ax=None, **kwargs)

Plot a one-dimensional histogram on the provided or current axes.

Parameters:

dataarray-like

Values to plot.

axmatplotlib.axes.Axes, optional

Axes to draw on. If not provided, the current axes are used.

**kwargs

Keyword arguments passed to Axes.hist.

Returns:

matplotlib.figure.Figure

Figure containing the histogram.

visualization.visualize.plot_ratio_difference(ax1, data_dict, plot_ratio, gs, plot_args)

Plot the ratio or difference plot in the lower panel.

visualization.visualize.plot_table(table, y_title, **kwargs)

Produce a high contrast one dimensional plot from an astropy.Table.

The first column is the x-axis; each further column is one data set.

Parameters:

table: astropy.Table or astropy.QTable

Table with at least two columns.

y_title: str

The y-axis title.

**kwargs:

Options as for plot_1d().

Returns:

pyplot.fig

Figure instance.

Raises:

ValueError

if table has less than two columns.

visualization.visualize.save_figure(fig, output_file, figure_format=None, log_title='', dpi='figure', close=False, pil_kwargs=None, context=None)

Save figure to output file(s).

A figure suffix in output_file is replaced by each format; other dots are kept. Formats default to the configured figure_format or PNG. PNG files are converted to a 256-color palette if figure_png_palette is configured.

Parameters:

fig: plt.figure

Figure to save.

output_file: Path, str

Output path, with or without a format suffix.

figure_format: list

List of formats to save the figure.

log_title: str

Title of the figure to be added to the log message.

dpistr or int, optional

DPI for fig.savefig; a configured figure_dpi overrides it for PNG.

closebool, optional

Close the figure after saving. Defaults to False.

pil_kwargsdict, optional

Keyword arguments passed to Pillow when saving PNG files.

visualization.visualize.set_style(palette='default', big_plot=False)

Set the plotting style (colour palette, font and marker sizes) for following plots.

Parameters:

palette: str

Colour palette: classic (default), modified classic, autumn, purples or greens.

big_plot: bool

If True, fonts and markers are made bigger.

Raises:

KeyError

if provided palette does not exist.

legend_handlers

Helper functions for legend handlers used for plotting.

class visualization.legend_handlers.BaseLegendHandler(telescope_type=None)

Base telescope handler that can handle any telescope type.

legend_artist(_, __, ___, handlebox)

Create the appropriate patch based on telescope type.

class visualization.legend_handlers.EdgePixelObject

Edge-Pixel Object.

class visualization.legend_handlers.HESSHandler(telescope_type=None)

Legend handler for HESS telescopes.

class visualization.legend_handlers.HexEdgePixelHandler

Legend handler class to plot a hexagonal “edge” pixel.

class visualization.legend_handlers.HexOffPixelHandler

Legend handler class to plot a hexagonal “off” pixel.

class visualization.legend_handlers.HexPixelHandler

Legend handler class to plot a hexagonal “on” pixel.

class visualization.legend_handlers.LSTHandler(telescope_type=None)

Legend handler for LST telescopes.

class visualization.legend_handlers.MAGICHandler(telescope_type=None)

Legend handler for MAGIC telescopes.

class visualization.legend_handlers.MSTHandler(telescope_type=None)

Legend handler for MST telescopes.

class visualization.legend_handlers.OffPixelObject

Off-Pixel Object.

class visualization.legend_handlers.PixelObject

Pixel Object.

class visualization.legend_handlers.SCTHandler(telescope_type=None)

Legend handler for SCT telescopes.

class visualization.legend_handlers.SSTHandler(telescope_type=None)

Legend handler for SST telescopes.

class visualization.legend_handlers.SquareEdgePixelHandler

Legend handler class to plot a square “edge” pixel.

class visualization.legend_handlers.SquareOffPixelHandler

Legend handler class to plot a square “off” pixel.

class visualization.legend_handlers.SquarePixelHandler

Legend handler class to plot a square “on” pixel.

class visualization.legend_handlers.VERITASHandler(telescope_type=None)

Legend handler for VERITAS telescopes.

visualization.legend_handlers.calculate_center(handlebox, width_factor=3, height_factor=3)

Calculate the center of the handlebox based on given factors.

visualization.legend_handlers.get_telescope_config(telescope_type)

Return the configuration for a given telescope type.

Try both site-dependent and site-independent configurations (e.g. “MSTS” and “MST”).

Parameters:

telescope_typestr, None

The type of the telescope (e.g., “LSTN”, “MSTS”).

Returns:

dict

The configuration dictionary for the telescope type.

plot_array_layout

Plot array elements for a layout.

class visualization.plot_array_layout.PlotBounds(x_lim, y_lim)

Axis-aligned bounds for the layout in meters.

Attributes:

x_limtuple[float, float]

Min/max for x (meters).

y_limtuple[float, float]

Min/max for y (meters).

x_lim

Alias for field number 0

y_lim

Alias for field number 1

visualization.plot_array_layout.create_patches(telescopes, scale, show_label, ax, grayed_out_elements=None, highlighted_elements=None)

Create telescope patches and labels.

Parameters:

telescopesTable

Telescope data table.

scalefloat

Marker size scale factor.

show_labelbool

Show telescope labels.

axAxes

Matplotlib axes object.

grayed_out_elementslist or None

List of telescope names to plot as gray circles.

highlighted_elementslist or None

List of telescope names to plot with red circles around them.

Returns:

patcheslist

Shape patches.

radiilist

Telescope radii.

highlighted_patcheslist

List of highlighted telescope patches.

text_objectslist

List of text objects for labels.

visualization.plot_array_layout.finalize_plot(ax, patches, x_title, y_title, x_lim=None, y_lim=None, highlighted_patches=None)

Finalize plot appearance and limits.

visualization.plot_array_layout.generate_plot_combinations(args_dict, model_reader=None, *, context=None)

Yield model version and site combinations for plotting.

Parameters:

args_dictdict

Dictionary with command line arguments.

Yields:

tuple

Pair of (model_version, site) values.

visualization.plot_array_layout.get_patches(ax, telescopes, show_tel_label, axes_range, marker_scaling, grayed_out_elements=None, highlighted_elements=None, filter_x_lim=None, filter_y_lim=None)

Get plot patches and axis range.

Parameters:

axAxes

Matplotlib axes object.

telescopesTable

Telescope data table.

show_tel_labelbool

Show telescope labels.

axes_rangefloat or None

Axis range, auto if None.

marker_scalingfloat

Marker size scale factor.

grayed_out_elementslist or None

List of telescope names to plot as gray circles.

highlighted_elementslist or None

List of telescope names to plot with red circles around them.

Returns:

patcheslist

List of telescope patches.

axes_rangefloat

Calculated or input symmetric axis range (meters).

highlighted_patcheslist

List of highlighted telescope patches.

boundsPlotBounds

Min/max for x and y in meters.

text_objectslist

List of text objects for labels.

visualization.plot_array_layout.get_positions(telescopes)

Get X/Y positions depending on coordinate system.

For ground coordinates, rotates the positions by 90 degrees.

Returns:

x_rot, y_rotQuantity

Position coordinates.

visualization.plot_array_layout.get_sphere_radius(tel)

Get telescope sphere radius.

Returns:

radiusQuantity

Radius with units.

visualization.plot_array_layout.get_telescope_name(tel)

Get telescope name.

Returns:

namestr

Telescope name or fallback identifier.

visualization.plot_array_layout.get_telescope_patch(tel_type, x, y, radius, is_grayed_out=False)

Create patch for a telescope.

Parameters:

tel_type: str

Telescope type.

xQuantity

X position.

yQuantity

Y position.

radiusQuantity

Telescope radius.

is_grayed_outbool

Whether to plot telescope in gray.

Returns:

patchPatch

Circle or rectangle patch.

visualization.plot_array_layout.plot_array_layout(telescopes, show_tel_label=False, axes_range=None, marker_scaling=1.0, background_telescopes=None, grayed_out_elements=None, highlighted_elements=None, legend_location='best', bounds_mode='exact', padding=0.1, x_lim=None, y_lim=None)

Plot telescope array layout.

Parameters:

telescopesTable

Telescope data table.

show_tel_labelbool

Show telescope labels (default False).

axes_rangefloat or None

Axis range, auto if None.

marker_scalingfloat

Marker size scale factor.

background_telescopesTable or None

Optional background telescope table.

grayed_out_elementslist or None

List of telescope names to plot as gray circles.

highlighted_elementslist or None

List of telescope names to plot with red circles around them.

legend_locationstr

Location of the legend (default “best”).

Returns:

figFigure

Matplotlib figure object.

Other Parameters:

bounds_mode{“symmetric”, “exact”}

Controls axis limits calculation. “symmetric” uses +-R where R is the padded maximum extent (default), while “exact” uses individual x/y min/max bounds.

paddingfloat

Fractional padding applied around computed extents (used for both modes).

x_lim, y_limtuple(float, float), optional

Explicit axis limits in meters. If provided, these override axes_range and bounds_mode for the respective axis. If only one is provided, the other axis is derived per mode.

visualization.plot_array_layout.plot_array_layouts(args_dict, output_path, layouts, background_layout=None)

Plot multiple array layouts.

Parameters:

args_dictdict

Application arguments.

output_pathPath

Output path for figures.

layoutsdict

Dictionary of layout name to telescope table.

background_layoutTable or None

Optional background telescope table.

Returns:

figsdict

Dictionary of layout name to matplotlib figure object.

visualization.plot_array_layout.update_legend(ax, telescopes, grayed_out_elements=None, legend_location='best')

Add legend for telescope types and counts.

array_layout_cache

Cache identities for rendered array layouts.

visualization.array_layout_cache.array_layout_figure_name(layout, args_dict, background_layout=None)

Return the content-derived filename stem for an array layout figure.

Layout names and sites are intentionally omitted because they are not drawn in the figure. Rendered data, display options, renderer source, and output settings determine the identity.

Parameters:

layoutdict

Layout data containing array_elements and optional site fields.

args_dictdict

Plot options used to render the layout.

background_layoutastropy.table.Table or None, optional

Optional telescope data drawn behind the layout.

Returns:

str

Filename stem shared by figures with identical rendering inputs.

plot_camera

Plot camera pixel layout and trigger patches.

Model data (camera, trigger tables) are passed in by the caller so that this module does not import the model package.

visualization.plot_camera.parse_pixel_ids_to_print(print_pixels_id_arg, camera)

Parse the print_pixels_id argument into an integer pixel count.

Parameters:

print_pixels_id_argstr or int

Integer, 0 (suppress) or ‘All’.

cameraCamera

Camera used to determine the total pixel count for ‘All’.

Returns:

int

Number of pixel IDs to print; -1 when printing should be suppressed.

Raises:

ValueError

If the argument is not an integer string or ‘All’.

visualization.plot_camera.plot_pixel_layout(camera, camera_in_sky_coor=False, pixels_id_to_print=50)

Plot the pixel layout for an observer facing the camera.

Includes edge pixels, off pixels, pixel IDs (up to pixels_id_to_print), coordinate axes, the focal length, the average edge radius and the FoV.

Parameters:

cameraCamera

Camera object to plot.

camera_in_sky_coorbool, optional

Plot the camera in the sky coordinate system.

pixels_id_to_printint, optional

Number of pixel IDs to print in the plot.

Returns:

matplotlib.figure.Figure

Figure with the pixel layout.

visualization.plot_camera.plot_pixel_layout_with_image(camera, image=None, colormap='viridis', norm='lin', ax=None, vmin=None, vmax=None, add_color_bar=True, color_bar_label='Pixel Value', **kwargs)

Plot pixel layout with optional per-pixel values as colors.

Used to display DL1 images (e.g., integrated signal, peak timing) on the camera.

Parameters:

cameraCamera

Camera object with pixel geometry.

imagenp.ndarray, optional

Per-pixel values to display as colors (shape: n_pix,). If None, plot layout without colored values.

colormapstr, optional

Colormap name (default “viridis”).

normstr, optional

Normalization type: “lin” (linear), “log”, or “symlog” (default “lin”).

axplt.Axes, optional

Existing axes to plot on. If None, create new figure.

vmin, vmaxfloat, optional

Value range for normalization. If None, use data range.

add_color_barbool, optional

Whether to add a color bar (default True).

color_bar_labelstr, optional

Label for the color bar (default “Pixel Value”).

**kwargs

Additional arguments passed to plt.subplots() if ax is None.

Returns:

plt.Figure

Figure with the pixel layout and optional image overlay.

visualization.plot_camera.plot_selected_trigger_patches(camera, groups, sky_coordinates)

Draw selected trigger groups on a camera overview and a labelled close-up of their union.

Parameters:

cameraCamera

Camera object.

groupsdict

Mapping of group ID to its set of pixel IDs (see read_selected_trigger_patches()).

sky_coordinatesbool

Plot in sky coordinates (no vertical flip for single-mirror telescopes).

Returns:

matplotlib.figure.Figure

The generated figure.

visualization.plot_camera.read_selected_trigger_patches(definitions, members, patch_ids, camera_pixels)

Resolve the selected trigger groups into their pixel sets, with validation.

Parameters:

definitionsastropy.table.Table

Trigger group definitions with a group_id column.

membersastropy.table.Table

Trigger memberships with group_id and pixel_id columns.

patch_idslist of int

Selected trigger-group IDs.

camera_pixelsset of int

Pixel IDs present in the camera.

Returns:

dict

Mapping of group ID to its set of pixel IDs.

visualization.plot_camera.trigger_patches_for_pixel(members, pixel_id, camera_pixels)

Find the distinct trigger-group IDs containing a camera pixel.

Parameters:

membersastropy.table.Table

Trigger memberships with group_id and pixel_id columns.

pixel_idint

Camera pixel ID.

camera_pixelsset of int

Pixel IDs present in the camera.

Returns:

list of int

Sorted trigger-group IDs.

plot_telescope_structure

Plot the optical structure of a telescope: mirrors, camera housing and telescope structure.

The geometry is read from the model parameters with the nominal positions, that is without the random alignment errors of a particular instrument. Only simtools is needed. With shadowing, the structure is coloured by the light each element stops on its own; that needs the obdeect package.

visualization.plot_telescope_structure.plot_telescope_structure(geometry, output_file, shares=None)

Plot the telescope seen from the sky (x, y) and from the side (x, z).

Parameters:

geometry: TelescopeGeometry

Elements to draw (see telescope_geometry).

output_file: Path or str

Output file name without suffix (see save_figure).

shares: dict, optional

Element name -> (share of light stopped alone in per cent, photons crossing it), as from shadowing_shares. Without it, all structure elements are grey.

plot_corsika_histograms

Visualize Cherenkov photon distributions from CORSIKA.

visualization.plot_corsika_histograms.export_all_photon_figures_pdf(histograms_instance, pdf_file_name, labels=None)

Build and save all photon histogram figures into a single PDF.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms or list

Single histogram instance or list of CorsikaHistograms instances from multiple files. When a list is provided, 1D histograms from all files are combined into single plots with different colors, while 2D histograms of the same type are plotted sequentially.

pdf_file_name: str or Path

Name of the output pdf file to save the histograms.

labels: list or None

Optional list of labels for the input files. If None, file names are used as labels. The order should match the order of histograms_instance if it’s a list.

plot_tables

Plot tabular data.

visualization.plot_tables.fit_bias_curve(thresholds, rates)

Fit log10(rate) as a linear function of threshold.

Parameters:

thresholdsarray-like

Trigger thresholds.

ratesarray-like

Trigger rates; only finite positive values are used.

Returns:

tuple or None

Valid thresholds and fit coefficients (slope, intercept), or None if fewer than two distinct finite thresholds have corresponding finite, positive rates.

visualization.plot_tables.generate_plot_configurations(parameter, parameter_version, site, telescope, output_path, plot_type, model_reader=None, model_version=None, *, context=None)

Generate plot configurations for a model parameter from schema files.

Parameters:

parameter: str

Model parameter name.

parameter_version: str

Parameter version.

site: str

Site name.

telescope: str

Telescope name.

output_path: str or Path

Output path for the plots.

plot_type: str

Plot type or “all” for all plots.

model_version: str, optional

Exact model version used to read the table data.

Returns:

tuple or None

List of plot configurations and list of output file names, or None if no plot configurations are found.

visualization.plot_tables.plot(config, output_file, data_path=None, model_reader=None, *, context=None)

Plot tabular data from data or from model parameter files.

Parameters:

config: dict

Configuration dictionary for plotting.

output_file: str

Output file.

data_path: Path or str, optional

Path to the data files. All files are expected in the same directory.

visualization.plot_tables.plot_bias_curves(nsb_stats, proton_stats, config, output_path, trigger_threshold=None)

Plot NSB and proton bias curves.

Parameters:

nsb_statsdict

NSB statistics by threshold.

proton_statsdict

Proton statistics by threshold.

configdict

Plot configuration with title, ymin, ymax, and scaling_factor.

output_pathPath or str

Output path for plot image.

trigger_thresholdfloat, optional

Trigger threshold value to annotate on the plot.

visualization.plot_tables.read_table_data(config, data_path=None, model_reader=None, *, context=None)

Read table data from file or parameter repository.

Parameters:

config: dict

Configuration dictionary for plotting.

data_path: Path or str, optional

Path to the data files. All files are expected in the same directory.

Returns:

Dict

Dict with table data (numpy structured arrays).

visualization.plot_tables.resolve_plot_output_path(output, file_name='bias_curve.png')

Resolve output as either an explicit plot file or an output directory.

plot_pixels

Functions for plotting pixel layout information.

The camera (simtools.model.camera.Camera) and its raw pixel data are built by the caller, so this module does not import the model package.

visualization.plot_pixels.plot(output_file, camera, raw_pixels, *, rotate_angle=None, pixels_id_to_print=80)

Plot a pixel layout and save it to file.

Parameters:

output_filestr or Path

Path where to save the plot.

cameraCamera

Camera with pixel geometry (pixels, telescope_name, get_edge_pixels).

raw_pixelsdict

Unrotated pixel data with keys x, y and rotate_angle (radians).

rotate_angleastropy.units.Quantity, optional

Rotation applied to the telescope-specific pixel transform (default: from raw_pixels).

pixels_id_to_printint, optional

Pixel IDs below this value are printed.

visualization.plot_pixels.plot_pixel_layout(camera, raw_pixels, *, rotate_angle=None, pixels_id_to_print=50)

Create the pixel layout figure.

Parameters:

cameraCamera

Camera with pixel geometry; its pixel positions are transformed in place.

raw_pixelsdict

Unrotated pixel data with keys x, y and rotate_angle (radians).

rotate_angleastropy.units.Quantity, optional

Rotation applied to the telescope-specific pixel transform.

pixels_id_to_printint, optional

Pixel IDs below this value are printed.

Returns:

matplotlib.figure.Figure

The generated figure.

visualization.plot_pixels.raw_pixels_from_configuration(configuration)

Return unrotated pixel data from resolved camera components.

Parameters:

configurationdict

Output of resolve_camera_components().

Returns:

dict

Keys x, y (cm) and rotate_angle (radians).

visualization.plot_pixels.resolve_camera_components(model_reader, parameters)

Resolve camera component model parameters for plotting.

plot_trigger_patches

Analyze and plot camera trigger-patch configuration.

visualization.plot_trigger_patches.analyze_trigger_patch_configuration(camera, trigger_groups, trigger_members)

Calculate per-pixel patch distances and per-group spatial summaries.

Parameters:

cameraCamera

Camera geometry with pixel IDs and neighbor lookup.

trigger_groupsastropy.table.Table

Group definitions with group_id and kind columns.

trigger_membersastropy.table.Table

Memberships with group_id and pixel_id columns.

Returns:

tuple of astropy.table.Table

Per-pixel and per-group diagnostics. Distances are in camera-plane centimeters; undefined distances are NaN.

Raises:

ValueError

If the camera or trigger tables contain inconsistent identifiers.

visualization.plot_trigger_patches.format_trigger_patch_summary(pixel_table, group_table)

Format the page-two summary for both the report and application log.

Parameters:

pixel_tableastropy.table.Table

Per-pixel diagnostics.

group_tableastropy.table.Table

Per-group diagnostics.

Returns:

str

Multi-line summary text.

visualization.plot_trigger_patches.write_trigger_patch_report(camera, pixel_table, group_table, pdf_path)

Write a two-page PDF for trigger-patch diagnostics.

Parameters:

cameraCamera

Camera geometry used for both pages.

pixel_tableastropy.table.Table

Per-pixel output from analyze_trigger_patch_configuration().

group_tableastropy.table.Table

Per-group output from analyze_trigger_patch_configuration().

pdf_pathpathlib.Path or str

Destination PDF path.

Returns:

str

The page-two summary text for application logging.

plot_simtel_events

Plot sim_telarray events.

class visualization.plot_simtel_events.PlotSimtelEvent(file_name, telescope, event_ids=None, max_events=None, prepared_events=None)

Plot a single sim_telarray event.

Parameters:

file_namestr | pathlib.Path

Path to the sim_telarray file.

telescopestr

Telescope name or ID to process.

event_idsint or list of int, optional

IDs of the event(s) to process.

max_eventsint, optional

Maximum number of events to process.

make_output_paths(ioh, base)

Return output file path based on base name and input file.

plot(plots, args, output_file, save_png=False, dpi=300)

Generate all requested plots for the event.

Parameters:

plotslist of str

List of plot names to generate.

argsdict

Additional arguments for plot functions.

output_filePath

Base output file path for saving plots.

save_pngbool

Whether to save individual PNG files per plot.

dpiint

DPI for saved PNG files.

plot_peak_timing(event_index, sum_threshold=10.0, timing_bins=None)

Peak finding per pixel; plot histogram of peak sample times.

Parameters:

event_indexint

Event index.

sum_thresholdfloat, optional

Minimum sum over samples for a pixel to be considered.

timing_binsint | None, optional

Number of histogram bins. If None, use unit-width bins.

Returns:

matplotlib.figure.Figure | None

The created figure, or None if no pixels exceed threshold.

plot_pedestals(event_index)

Plot pedestal values for all pixels.

plot_signals(event_index)

Plot integrated trace values.

plot_step_traces(event_index, pixel_step=10, max_pixels=None)

Plot step-style R1 traces for regularly sampled pixels (0, N, 2N, …).

Parameters:

event_indexint

Event index.

pixel_stepint, optional

Interval between pixel indices to plot.

max_pixelsint | None, optional

Maximum number of pixels to plot. If None, plot all selected by pixel_step.

Returns:

matplotlib.figure.Figure

The created figure.

plot_time_traces(event_index, number_of_pixels=3)

Plot R1 time traces for pixels with highest signal.

Parameters:

event_indexint

Event index.

number_of_pixelsint, optional

Number of pixels with highest signal to plot.

Returns:

matplotlib.figure.Figure

The created figure.

plot_waveforms(event_index, vmax=None, pixel_step=None)

Create a pseudocolor image of R1 waveforms (sample index vs. pixel id).

Parameters:

event_indexint

Event index.

vmaxfloat | None, optional

Upper limit for color normalization. If None, determined automatically.

pixel_stepint | None, optional

Step between plotted pixel ids (e.g., 1 plots all, 2 plots every second pixel).

Returns:

matplotlib.figure.Figure

The created figure.

save(args, output_file)

Save generated plots to files.

trace_maxima(samples, sum_threshold)

Call the trace analysis function supplied with prepared event data.

visualization.plot_simtel_events.generate_and_save_plots(plots, args, ioh, prepared_events=None)

Generate events plots from a sim-telarray file and save a multi-page PDF per input.

Writes additionally metadata.

Parameters:

plotslist of str

List of plot names to generate.

argsdict

Additional arguments for plot functions.

iohOutputPaths

Paths used for output files and metadata.

prepared_eventsPreparedEvents

Events prepared by camera.event_images. Required to generate plots.

plot_simtel_event_histograms

Plot simtel event histograms filled with EventDataHistograms.

visualization.plot_simtel_event_histograms.plot(histograms, output_path=None, limits=None, array_name=None, add_distance_projections=False, use_broad_range_limits=False)

Plot simtel event histograms.

Parameters:

histograms: EventDataHistograms

Instance containing the histograms to plot.

output_path: Path or str, optional

Directory to save plots. If None, plots will be displayed.

limits: dict, optional

Dictionary containing limits for plotting. Keys can include: - “upper_radius_limit”: Upper limit for core distance - “lower_energy_limit”: Lower limit for energy - “viewcone_radius”: Radius for the viewcone

array_name: str, optional

Name of the telescope array configuration.

add_distance_projections: bool, optional

Add overall and sliced x/y projections to raw distance-vs-energy plots.

use_broad_range_limits: bool, optional

Restrict plot axes to the broad-range simulation limits in limits.

visualization.plot_simtel_event_histograms.plot_monte_carlo_statistics_diagnostics(output_dir, array_name, file_info, energy_edges, angular_edges, expected_counts, relative_uncertainty)

Write Monte Carlo statistics diagnostic plots.

Parameters:

output_dirstr or pathlib.Path

Directory to write plot files.

array_namestr

Array or telescope-selection name used in plot titles and filenames.

file_infodict, optional

Simulation metadata (zenith, azimuth, nsb_level) to make filenames unique per setup.

energy_edgesarray-like

Energy bin edges in TeV.

angular_edgesarray-like

Angular-distance bin edges in deg.

expected_countsnumpy.ndarray

Expected triggered events per angular-distance and energy bin.

relative_uncertaintynumpy.ndarray

Poisson relative uncertainty per angular-distance and energy bin.

visualization.plot_simtel_event_histograms.plot_trigger_histograms(loaded_histograms, output_dir)

Plot loaded trigger histograms, writing one directory per array layout.

Parameters:

loaded_histogramsiterable

Loaded histogram records, each paired with its array layout.

output_dirstr or pathlib.Path

Base directory where plot files will be written.

plot_production_comparison

Plot event-level and signal-level comparisons across simulation productions.

visualization.plot_production_comparison.annotate_comparison_statistics(ax, statistics)

Overlay comparison metric values for baseline-vs-candidate comparisons on a plot.

visualization.plot_production_comparison.plot_event_level_comparison(metrics_per_production, output_path=None, array_layout_name=None, bins=40, figure_format=None, report_mode='diagnostic', compact_figures=None, comparison_title=None, comparison_context=None, *, context=None)

Create all event-level production comparison plots.

Parameters:

metrics_per_productionlist[ProductionEventMetrics]

Aggregated metrics per production.

output_pathpathlib.Path, optional

Output directory for the generated plots. Falls back to the current application output directory when omitted.

array_layout_namestr, optional

Array-layout selection used to collect the metrics. When set, plots are written into a subdirectory with that name.

binsint, optional

Number of bins for 1D histograms.

figure_formatlist[str] or str, optional

Figure formats to write. Formats supported by Matplotlib can be used. Defaults to the configured formats or ["png"].

comparison_titlestr, optional

Context heading shown above each plot, such as the configuration of a matched production pair.

comparison_contextdict, optional

Baseline and candidate configuration metadata. Compact reports omit fixed-energy and on-axis angular distributions when both configurations establish those conditions.

Returns:

pathlib.Path

Path to the JSON file containing the comparison statistics.

visualization.plot_production_comparison.plot_signal_level_comparison(metrics_by_telescope, output_path, bins=40, figure_format=None)

Create signal comparison plots for every telescope in a layout.

Parameters:

metrics_by_telescopedict[str, list[ProductionSignalMetrics]]

Metrics grouped by telescope name and ordered by production.

output_pathpathlib.Path

Base output directory.

binsint, optional

Number of histogram bins.

figure_formatlist[str] or str, optional

Figure formats to write. Defaults to the configured formats or ["png"].

Returns:

list[pathlib.Path]

Paths to the comparison statistics JSON files.

plot_resource_requirements

Plot normalized CORSIKA and sim_telarray resource requirements.

visualization.plot_resource_requirements.plot(rows, output_path, figure_format=None, report_mode='diagnostic')

Write resource plots versus energy.

Parameters:

rowsiterable[dict]

Normalized process rows returned by the resource collector.

output_pathstr or pathlib.Path

Destination directory for the figures.

figure_formatiterable[str], optional

File formats passed to visualization.visualize.save_figure().

report_modestr, optional

"diagnostic" writes one figure per metric and role, "compact" a multipage PDF, and "none" writes nothing.

Returns:

list[pathlib.Path]

Base paths of the written figures.

Notes

Byte-based quantities are plotted in MB or GB, selected from the largest value in each plot, using decimal units. Per-run plots use the *_bytes and raw time columns; per-event and per-triggered-event plots use their normalized columns. When both baseline and candidate rows are present, additional plots show candidate-to-baseline ratios for matching primary, site, layout, and model-version configurations.

plot_psf

Optical PSF plotting functions for parameter optimization visualization.

This module provides plotting functionality for PSF parameter optimization, including parameter comparison plots, convergence plots, and PSF diameter vs off-axis plots.

visualization.plot_psf.create_gradient_descent_convergence_plot(gd_results, threshold, output_file, fraction=0.8, use_ks_statistic=False)

Create convergence plot during gradient descent.

Parameters:

gd_resultslist

List of (params, metric, p_value, psf_diameter, simulated_data) tuples.

thresholdfloat

Optimization metric threshold used for convergence.

output_filePath

Output file path for saving the plot.

fractionfloat, optional

PSF containment fraction for labeling (default: 0.8).

use_ks_statisticbool

Whether to use KS statistic or RMSD labels and titles.

visualization.plot_psf.create_monte_carlo_uncertainty_plot(mc_results, output_file, fraction=0.8, use_ks_statistic=False)

Create uncertainty analysis plots showing optimization metric and p-value distributions.

Parameters:

mc_resultstuple

(mean_metric, std_metric, metric_values, mean_p, std_p, p_values, mean_psf_diameter, std_psf_diameter, psf_diameter_values) from the Monte Carlo analysis.

output_filePath

Output file path; its suffix is replaced by _ks or _rmsd.

fractionfloat, optional

PSF containment fraction for labeling (default: 0.8).

use_ks_statisticbool, optional

Whether KS statistic mode is being used (affects filename suffix).

visualization.plot_psf.create_psf_parameter_plot(data_to_plot, pars, psf_diameter, metric, is_best, pdf_pages, fraction=0.8, p_value=None, use_ks_statistic=False, second_metric=None)

Add a cumulative PSF plot of one parameter set to a PDF report.

Parameters:

data_to_plotdict

Data dictionary for plotting.

parsdict

Parameter set dictionary.

psf_diameter, metricfloat

PSF diameter and metric (RMSD, or KS statistic if use_ks_statistic).

is_bestbool

Whether this is the best parameter set.

pdf_pagesPDF report object

Open report for adding plots.

fraction, p_value, use_ks_statistic, second_metricoptional

PSF containment fraction, KS p-value, KS mode flag and second metric.

visualization.plot_psf.get_psf_diameter_label(fraction, unit='cm')

Generate PSF diameter label from the containment fraction, e.g. “D80 (cm)”.

Parameters:

fractionfloat

PSF containment fraction (0.8 for D80).

unitstr, optional

Unit appended in parentheses (default: “cm”).

Returns:

str

Label such as “D80 (cm)”, or “D80” if unit is empty.

visualization.plot_psf.get_significance_label(p_value)

Get significance label for p-value: GOOD (>0.05), FAIR (>0.01) or POOR.

visualization.plot_psf.plot_psf_histogram(measured, simulated, args_dict)

Write histogram comparing measured vs simulated PSF diameter distributions.

plot_ray_tracing_psf

Shared PSF plotting helpers for ray-tracing workflows.

visualization.plot_ray_tracing_psf.create_annotated_psf_image_figure(data, off_x, off_y, psf, containment_radius, image_range, bins=150, cmap=None, psf_kwargs=None, telescope_name=None)

Create a PSF image figure annotated with offset and PSF information.

Parameters:

datanumpy.ndarray

Structured array with X and Y columns, in the display unit.

off_x, off_yfloat

Off-axis components in degrees.

psfastropy.units.Quantity

PSF diameter; its unit sets the axis labels and annotation.

containment_radiusastropy.units.Quantity

Containment radius in the same unit as psf.

image_rangelist

Range passed to Axes.hist2d.

binsint

Number of histogram bins.

cmapmatplotlib colormap, optional

Colormap passed to Axes.hist2d.

psf_kwargsdict, optional

Keyword arguments passed to matplotlib.patches.Circle.

telescope_namestr, optional

Telescope name shown in the annotation box.

Returns:

matplotlib.figure.Figure

Created figure.

visualization.plot_ray_tracing_psf.create_cumulative_psf_figure(data, radius_key, cumulative_key, containment_radius_cm, psf_diameter_cm=None, **plot_kwargs)

Create a cumulative PSF plot.

Parameters:

datanumpy.ndarray

Structured array with radius and cumulative PSF columns.

radius_key, cumulative_keystr

Column names of the radius and cumulative PSF values.

containment_radius_cmfloat

Containment marker radius in cm.

psf_diameter_cmfloat, optional

PSF diameter marker in cm.

**plot_kwargs

Passed to Axes.plot.

Returns:

tuple

Figure and axes.

visualization.plot_ray_tracing_psf.create_psf_image_figure(data, containment_radius, center, psf_kwargs=None, use_current_axes=False, **hist_kwargs)

Create a 2D histogram plot of a PSF image with the containment circle.

Parameters:

datanumpy.ndarray

Structured array with X and Y columns.

containment_radiusfloat

Radius of the containment circle, in the same unit as the data.

centertuple

Center of the PSF circle, in the same unit as the data.

psf_kwargsdict, optional

Keyword arguments passed to matplotlib.patches.Circle.

use_current_axesbool

Draw on the current axes instead of a new figure.

**hist_kwargs

Passed to visualize.plot_hist_2d (image_range is an alias of range).

Returns:

tuple

Figure and axes.

visualization.plot_ray_tracing_psf.save_and_close_figure(fig, file_name)

Save a figure to an exact path and close it.

plot_mirrors

Functions for plotting mirror panel layout information.

visualization.plot_mirrors.plot(config, output_file, data_file_path, mirrors=None)

Plot mirror panel layout based on configuration.

Parameters:

configdict

Keys parameter (e.g., “mirror_list”, “primary_mirror_segmentation”) and telescope (e.g., “LSTN-01”).

output_filestr or Path

Path where to save the plot (without extension).

data_file_pathstr or Path

Exported mirror or segmentation file.

mirrorsMirrors, optional

Parsed mirror data; required for mirror lists.

visualization.plot_mirrors.plot_mirror_layout(mirrors, mirror_file_path, telescope_model_name)

Plot the mirror panel layout from a Mirrors object.

Parameters:

mirrorsMirrors

Mirror panel positions, diameters, focal lengths and shape types.

mirror_file_pathPath or str

Mirror list file (its header provides the statistics).

telescope_model_namestr

Telescope model name (e.g., “LSTN-01”, “MSTN-01”).

Returns:

matplotlib.figure.Figure

The generated figure object.

visualization.plot_mirrors.plot_mirror_ring_segmentation(data_file_path, telescope_model_name, parameter_type)

Plot mirror ring segmentation layout (polar view).

Parameters:

data_file_pathPath or str

Segmentation file with ring <nseg> <rmin> <rmax> <dphi> <phi0> lines.

telescope_model_namestr

Telescope model name (e.g., “LSTN-01”).

parameter_typestr

Segmentation parameter (e.g., “primary_mirror_segmentation”).

Returns:

matplotlib.figure.Figure or None

The generated figure object, or None if no ring data is found.

visualization.plot_mirrors.plot_mirror_segmentation(data_file_path, telescope_model_name, parameter_type)

Plot mirror segmentation layout from a standard segmentation file.

Parameters:

data_file_pathPath or str

Segmentation file with positions, diameters, shape types and segment IDs.

telescope_model_namestr

Telescope model name (e.g., “LSTN-01”).

parameter_typestr

Segmentation parameter (e.g., “primary_mirror_segmentation”).

Returns:

matplotlib.figure.Figure

The generated figure object.

visualization.plot_mirrors.plot_mirror_shape_segmentation(data_file_path, telescope_model_name, parameter_type)

Plot mirror shape segmentation layout (explicit hex and yhex shapes).

Parameters:

data_file_pathPath or str

Segmentation file with explicit shape definitions (hex, yhex).

telescope_model_namestr

Telescope model name (e.g., “LSTN-01”, “MSTN-design”).

parameter_typestr

Segmentation parameter (e.g., “primary_mirror_segmentation”).

Returns:

matplotlib.figure.Figure

The generated figure object.

plot_incident_angles

Plot incident angle histograms for focal, primary, and secondary mirrors.

Plots the primary-mirror hit radius if available.

members:

camera_plot_utils

Shared helpers for camera pixel plotting.

visualization.camera_plot_utils.add_pixel_legend(ax, on_pixels, off_pixels)

Add the pixel, edge pixel and disabled pixel legend.

Parameters:

axmatplotlib.axes.Axes

Axes object to add the legend to.

on_pixelslist

Enabled pixel patches (selects hexagonal or square legend handlers).

off_pixelslist

Disabled pixel patches.

visualization.camera_plot_utils.add_pixel_patch_collections(ax, on_pixels, edge_pixels, off_pixels)

Add patch collections for on, edge and off pixels to the axes.

Parameters:

axmatplotlib.axes.Axes

Axes object to add the patch collections to.

on_pixels, edge_pixels, off_pixelslist

Pixel patches (see create_pixel_patches_by_type()).

visualization.camera_plot_utils.create_pixel_patches_by_type(camera)

Create pixel patches categorized by type.

Parameters:

cameraCamera

Camera object containing pixel positions and status.

Returns:

tuple of (list, list, list)

Patches for enabled inner pixels, enabled edge pixels and disabled pixels.

visualization.camera_plot_utils.pixel_shape(camera, x, y)

Return the matplotlib patch of one pixel.

Parameters:

cameraCamera

Camera object containing pixel configuration.

x, yfloat

Coordinates of the pixel center.

Returns:

matplotlib.patches.Patch or None

Hexagon or rectangle patch; None if the pixel shape is not recognized.

visualization.camera_plot_utils.setup_camera_axis_properties(ax, camera, grid=False, axis_below=False, grid_alpha=None, y_scale_factor=1.0, padding=0)

Set up common axis properties for camera plots.

Parameters:

axmatplotlib.axes.Axes

Axes object to configure.

cameraCamera

Camera object containing pixel positions.

grid, axis_belowbool, optional

Show grid lines; place axis below the plot elements.

grid_alphafloat, optional

Transparency of grid lines (default grid alpha if None).

y_scale_factorfloat, optional

Scaling factor for y-axis limits.

paddingfloat, optional

Padding around the camera extent.

plot_science_comparison

Plot telescope-throughput science-result comparisons into PDF pages.

visualization.plot_science_comparison.plot_components(baseline_table, candidate_table, title, labels, pdf_pages)

Add absolute and relative pages for each optical efficiency component.

Parameters:

baseline_table, candidate_tablestr or pathlib.Path

Wavelength tables of one channel.

titlestr

Page title prefix.

labelstuple of str

Baseline and candidate legend labels.

pdf_pagesPDF report object

Open PDF report.

Returns:

str or None

Reason the components could not be compared.

visualization.plot_science_comparison.plot_metric_changes(changes, title, pdf_pages)

Add a page with scalar values and their relative change.

Parameters:

changesdict

Metric changes as returned by telescope_throughput.compare_results.

titlestr

Page title.

pdf_pagesPDF report object

Open PDF report.

visualization.plot_science_comparison.plot_spectra(baseline_tables, candidate_tables, title, labels, pdf_pages)

Add a page comparing the detected spectrum of each common channel.

Parameters:

baseline_tables, candidate_tablesdict

Wavelength-table paths by channel.

titlestr

Page title.

labelstuple of str

Baseline and candidate legend labels.

pdf_pagesPDF report object

Open PDF report.

Returns:

list of str

Channels that could not be compared.

plot_production_grid

Plot production-grid points on sky coordinate projections.

class visualization.plot_production_grid.ProductionGridPlotter(grid_points_file, output_path, column_units)

Plot production grid points on sky coordinate projections.

Parameters:

grid_points_filestr or Path

Path to the ECSV file containing grid points.

output_pathstr or Path

Path to save output plots.

normalize_grid_points()

Return normalized grid points for plotting and validation.

plot_azimuth_zenith_projection_with_color_scale(value_key, value_label, output_file_stem, plot_points=None)

Plot azimuth/zenith points with a color scale for one value column.

plot_limit_projections()

Plot all supported production-grid limit values.

plot_shower_statistics_vs_zenith(azimuth_center=180.0, azimuth_width=1.0)

Plot total and per-run showers against zenith angle.

Parameters:

azimuth_centerfloat, optional

Center of the azimuth interval used for the selected-azimuth plot.

azimuth_widthfloat, optional

Width in degrees of the selected azimuth interval.

Raises:

ValueError

If azimuth_width is not positive.

plot_sky_projection()

Create sky projection plots with Alt/Az and HA/Dec grid points.

plot_zenith_limits_for_azimuths(value_key, value_label, output_file_stem, azimuth_targets=(0.0, 180.0), azimuth_tolerance_deg=1e-06, plot_points=None)

Plot value versus zenith for selected azimuth pointings.

plot_corsika_limits

Plotting utilities for CORSIKA limits tables.

visualization.plot_corsika_limits.plot_limits(limits_table, output_dir)

Create plots of derived CORSIKA limits for each array and primary particle.

NSB levels are distinguished by color. Azimuth directions share a plot and use filled and open markers in ascending azimuth order.

Parameters:

limits_table (Table)

An astropy Table containing the CORSIKA limits data.

output_dir (str or Path)

Directory where the generated plots will be saved.

Returns:

list of Path

List of file paths to the generated plots.

matplotlib_backend

Configure the Matplotlib backend used by simtools visualizations.

visualization.matplotlib_backend.lazy_module(module_name)

Return a proxy that imports a plotting dependency on first use.

Parameters:

module_namestr

Fully qualified name of the plotting module to import lazily.

Returns:

_MatplotlibModuleProxy

Proxy that loads module_name when an attribute or item is accessed.

plot_pulse_response

Plot gain-resolved pulse-response measurements.

simtools.visualization.plot_pulse_response.plot_response(summary, waves, output_file)

Save peak, charge, width and mean-waveform panels in one PDF.

Parameters:

summaryastropy.table.Table

Mean metrics with standard deviations, counts, and illumination units.

waveslist of dict

Time in ns and baseline-subtracted waveform for each response and gain.

output_filepath-like

Destination PDF file.