Visualization

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

visualize

Module for visualization.

visualization.visualize.filter_plot_kwargs(kwargs)

Filter out kwargs that are not valid for plt.plot.

visualization.visualize.get_colors(palette='default')

Get the colour list of the palette requested.

If no palette is provided, the default is returned.

Parameters:

palette: str

Colour palette.

Returns:

list

Colour list.

Raises:

KeyError

if provided palette does not exist.

visualization.visualize.get_lines()

Get the line style list used in this module.

Returns:

list

List with line styles.

visualization.visualize.get_markers()

Get the marker list used in this module.

Returns:

list

List with markers.

visualization.visualize.handle_kwargs(kwargs)

Extract and handle keyword arguments.

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

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

A ratio plot can be added at the bottom to allow easy comparison. Additional options, such as plot title, plot legend, etc., are given in kwargs. Any option that can be changed after plotting (e.g., axes limits, log scale, etc.) should be done using the returned plt instance.

Parameters:

data: numpy structured array or a dictionary of structured arrays

Each structured array has two columns, the first is the x-axis and the second the y-axis. The titles of the columns are set as the axes titles. The labels of each dataset set are given in the dictionary keys and will be used in the legend.

**kwargs:

• palette: string Choose a colour palette (see set_style for additional information).

• title: string Set a plot title.

• no_legend: bool Do not print a legend for the plot.

• big_plot: bool Increase marker and font sizes (like in a wide light curve).

• no_markers: bool Do not print markers.

• empty_markers: bool Print empty (hollow) markers

• plot_ratio: bool Add a ratio plot at the bottom. The first entry in the data dictionary is used as the reference for the ratio. If data dictionary is not an OrderedDict, the reference will be random.

• plot_difference: bool Add a difference plot at the bottom. The first entry in the data dictionary is used as the reference for the difference. If data dictionary is not an OrderedDict, the reference will be random.

• Any additional kwargs for plt.plot

Returns:

pyplot.figure

Instance of pyplot.figure in which the plot was produced

Raises:

ValueError

if asked to plot a ratio or difference with just one set of data

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

Produce a two dimensional histogram plot.

Any option that can be changed after plotting (e.g., axes limits, log scale, etc.) should be done using the returned plt instance.

Parameters:

data: numpy structured array

The columns of the structured array are used as the x-axis and y-axis titles.

**kwargs:

• title: set a plot title.

• Any additional kwargs for plt.hist2d

Returns:

pyplot.figure

Instance of pyplot.figure in which the plot was produced.

visualization.visualize.plot_main_data(data_dict, kwargs, plot_args)

Plot the main data.

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

Plot the ratio or difference plot.

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

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

A ratio plot can be added at the bottom to allow easy comparison. Additional options, such as plot title, plot legend, etc., are given in kwargs. Any option that can be changed after plotting (e.g., axes limits, log scale, etc.) should be done using the returned plt instance.

Parameters:

table: astropy.Table or astropy.QTable

The first column of the table is the x-axis and the second column is the y-axis. Any additional columns will be treated as additional data to plot. The column titles are used in the legend (except for the first column).

y_title: str

The y-axis title.

**kwargs:

• palette: choose a colour palette (see set_style for additional information).

• title: set a plot title.

• no_legend: do not print a legend for the plot.

• big_plot: increase marker and font sizes (like in a wide light curve).

• no_markers: do not print markers.

• empty_markers: print empty (hollow) markers

• plot_ratio: bool Add a ratio plot at the bottom. The first entry in the data dictionary is used as the reference for the ratio. If data dictionary is not an OrderedDict, the reference will be random.

• plot_difference: bool Add a difference plot at the bottom. The first entry in the data dictionary is used as the reference for the difference. If data dictionary is not an OrderedDict, the reference will be random.

• Any additional kwargs for plt.plot

Returns:

pyplot.fig

Instance of pyplot.fig.

Raises:

ValueError

if table has less than two columns.

visualization.visualize.prepare_data(data, kwargs)

Prepare data for plotting.

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

Save figure to output file(s).

Parameters:

fig: plt.figure

Figure to save.

output_file: Path, str

Path to save the figure (without suffix).

figure_format: list

List of formats to save the figure.

title: str

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

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

Set the plotting style to homogenize plot style across the framework.

The function receives the colour palette name and whether it is a big plot or not. The latter sets the fonts and marker to be bigger in case it is a big plot. The available colour palettes are as follows:

• classic (default): A classic colorful palette with strong colors and contrast.

• modified classic: Similar to the classic, with slightly different colors.

• autumn: A slightly darker autumn style colour palette.

• purples: A pseudo sequential purple colour palette (not great for contrast).

• greens: A pseudo sequential green colour palette (not great for contrast).

To use the function, simply call it before plotting anything. The function is made public, so that it can be used outside the visualize module. However, it is highly recommended to create plots only through the visualize module.

Parameters:

palette: str

Colour palette.

big_plot: bool

Flag to set fonts and marker bigger. If True, it sets them bigger.

Raises:

KeyError

if provided palette does not exist.

visualization.visualize.setup_plot(kwargs, plot_ratio, plot_difference)

Set up the plot style, figure, and gridspec.

legend_handlers

Helper functions for legend handlers used for plotting.

class visualization.legend_handlers.BaseLegendHandler(telescope_type)

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

Legend handler for HESS telescopes.

class visualization.legend_handlers.HESSObject

HESS Object.

class visualization.legend_handlers.HexEdgePixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.HexOffPixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.HexPixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.LSTHandler

Legend handler for LST telescopes.

class visualization.legend_handlers.LSTObject

LST Object.

class visualization.legend_handlers.MAGICHandler

Legend handler for MAGIC telescopes.

class visualization.legend_handlers.MAGICObject

MAGIC Object.

class visualization.legend_handlers.MSTHandler

Legend handler for MST telescopes.

class visualization.legend_handlers.MSTObject

MST Object.

class visualization.legend_handlers.MeanRadiusOuterEdgeHandler

Legend handler class to plot the mean radius outer edge of the dish.

class visualization.legend_handlers.MeanRadiusOuterEdgeObject

Object for Mean radius outer edge.

class visualization.legend_handlers.OffPixelObject

Off-Pixel Object.

class visualization.legend_handlers.PixelObject

Pixel Object.

class visualization.legend_handlers.SCTHandler

Legend handler for SCT telescopes.

class visualization.legend_handlers.SCTObject

SCT Object.

class visualization.legend_handlers.SSTHandler

Legend handler for SST telescopes.

class visualization.legend_handlers.SSTObject

SST Object.

class visualization.legend_handlers.SquareEdgePixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.SquareOffPixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.SquarePixelHandler

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

static legend_artist(_, __, ___, handlebox)

Legend artist.

class visualization.legend_handlers.VERITASHandler

Legend handler for VERITAS telescopes.

class visualization.legend_handlers.VERITASObject

VERITAS Object.

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

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.

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.

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

Finalize plot appearance and limits.

visualization.plot_array_layout.get_patches(ax, telescopes, show_tel_label, axes_range, marker_scaling, grayed_out_elements=None, highlighted_elements=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 axis range.

highlighted_patcheslist

List of highlighted telescope patches.

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(name, x, y, radius, is_grayed_out=False)

Create patch for a telescope.

Parameters:

namestr

Telescope name.

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')

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.

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

Add legend for telescope types and counts.

plot_camera

Plot camera pixel layout.

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.

Including in the plot edge pixels, off pixels, pixel ID for the first 50 pixels, coordinate systems, FOV, focal length and the average edge radius.

Parameters:

cameraCamera

Camera object to plot.

camera_in_sky_coorbool, optional

Flag to plot the camera in the sky coordinate system.

pixels_id_to_printint, optional

Number of pixel IDs to print in the plot.

Returns:

figplt.Figure

Figure with the pixel layout.

plot_corsika_histograms

Visualize Cherenkov photon distributions from CORSIKA.

visualization.plot_corsika_histograms.build_all_photon_figures(histograms_instance, test: bool = False)

Return list of all photon histogram figures for the given instance.

When test is True, only generate the first two figure groups to reduce runtime.

visualization.plot_corsika_histograms.derive_event_1d_histograms(histograms_instance, event_1d_header_keys, pdf: bool, hdf5: bool, overwrite: bool = False)

Create 1D event header histograms; optionally save to PDF and/or HDF5.

visualization.plot_corsika_histograms.derive_event_2d_histograms(histograms_instance, event_2d_header_keys, pdf: bool, hdf5: bool, overwrite: bool = False)

Create 2D event header histograms in pairs; optionally save PDF and/or HDF5.

If an odd number of keys is provided, the last one is ignored (with a warning).

visualization.plot_corsika_histograms.export_all_photon_figures_pdf(histograms_instance, test: bool = False)

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

The PDF name is derived from the HDF5 file name core and written under output_path.

visualization.plot_corsika_histograms.plot_1d_event_header_distribution(histograms_instance, event_header_element, log_y=True, bins=50, hist_range=None)

Plot the distribution of the quantity given by .

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

event_header_element: str

The key to the CORSIKA event header element.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_counts(histograms_instance, log_z=True)

Plot the 2D histogram of the photon positions on the ground.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_z: bool

if True, the intensity of the color bar is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_density(histograms_instance, log_z=True)

Plot the 2D histogram of the photon density distribution on the ground.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_z: bool

if True, the intensity of the color bar is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_direction(histograms_instance, log_z=True)

Plot the 2D histogram of the incoming direction of photons.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_z: bool

if True, the intensity of the color bar is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_event_header_distribution(histograms_instance, event_header_element_1, event_header_element_2, log_z=True, bins=50, hist_range=None)

Plot the distribution of the quantity given by CorsikaHistograms.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

event_header_element_1: str

The first key to the CORSIKA event header element

event_header_element_2: str

The second key to the CORSIKA event header element.

log_z: bool

if True, the intensity of the Y axis is given in logarithmic scale.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_num_photons_per_telescope(histograms_instance, log_z=True)

Plot the 2D histogram of the number of photons per event and per telescope.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_z: bool

if True, the intensity of the color bar is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_2d_time_altitude(histograms_instance, log_z=True)

Plot the 2D histogram of the time and altitude where the photon was produced.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_z: bool

if True, the intensity of the color bar is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_altitude_distr(histograms_instance, log_y=True)

Plot the distribution of altitude in which the photons were generated in km.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_counts_distr(histograms_instance, log_y=True)

Plot the 1D distribution, i.e. the radial distribution, of the photons on the ground.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_density_distr(histograms_instance, log_y=True)

Plot the photon density distribution on the ground.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_photon_per_event_distr(histograms_instance, log_y=True)

Plot the distribution of the number of Cherenkov photons per event.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_photon_per_telescope_distr(histograms_instance, log_y=True)

Plot the distribution of the number of Cherenkov photons per telescope.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_time_distr(histograms_instance, log_y=True)

Plot the distribution times in which the photons were generated in ns.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.plot_wavelength_distr(histograms_instance, log_y=True)

Plot the 1D distribution of the photon wavelengths.

Parameters:

histograms_instance: corsika.corsika_histograms.CorsikaHistograms

instance of corsika.corsika_histograms.CorsikaHistograms.

log_y: bool

if True, the intensity of the Y axis is given in logarithmic scale.

Returns:

list

List of figures for the given telescopes.

visualization.plot_corsika_histograms.save_figs_to_pdf(figs, pdf_file_name)

Save figures from corsika histograms to an output pdf file.

Parameters:

figs: list or numpy.array

List with the figures output by corsika_output_visualize.py.

pdf_file_name: str or Path

Name of the pdf file.

plot_tables

Plot tabular data.

visualization.plot_tables.generate_plot_configurations(parameter, parameter_version, site, telescope, output_path, plot_type, db_config)

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.

db_config: dict

Database configuration.

Returns:

tuple

Tuple containing a list of plot configurations and a list of output file names. Return None, if no plot configurations are found.

visualization.plot_tables.plot(config, output_file, db_config=None, data_path=None)

Plot tabular data from data or from model parameter files.

Parameters:

config: dict

Configuration dictionary for plotting.

output_file: str

Output file.

db_config: dict, optional

Database configuration dictionary for accessing the model parameter database.

data_path: Path or str, optional

Path to the data files (optional). Expect all files to be in the same directory.

visualization.plot_tables.read_table_data(config, db_config, data_path=None)

Read table data from file or parameter database.

Parameters:

config: dict

Configuration dictionary for plotting.

db_config: dict

Database configuration dictionary for accessing the model parameter database.

data_path: Path or str, optional

Path to the data files (optional). Expect all files to be in the same directory.

Returns:

Dict

Dict with table data (astropy tables).

plot_pixels

Functions for plotting pixel layout information.

visualization.plot_pixels.plot(config, output_file, db_config=None)

Plot pixel layout based on configuration.

Parameters:

configdict

Configuration dictionary containing: - file_name : str, name of camera config file - column_x : str, x-axis label - column_y : str, y-axis label - parameter_version: str, version of the parameter - telescope : str, name of the telescope

output_filestr

Path where to save the plot

db_configdict, optional

Database configuration.

Returns:

None

The function saves the plot to the specified output file.

visualization.plot_pixels.plot_pixel_layout_from_file(dat_file_path, telescope_model_name, **kwargs)

Plot the pixel layout from a camera config file.

This function reads the pixel configuration from the specified camera config file and generates a plot of the pixel layout for the given telescope model.

Parameters:

dat_file_pathstr or Path

Path to the camera config file containing pixel configuration

telescope_model_namestr

Name/model of the telescope

**kwargs

pixels_id_to_printint

Number of pixel IDs to print in the plot

titlestr

Plot title

xtitlestr

X-axis label

ytitlestr

Y-axis label

Returns:

matplotlib.figure.Figure

The generated figure

plot_simtel_events

Plots for light emission (flasher/calibration) sim_telarray events.

visualization.plot_simtel_events.generate_and_save_plots(simtel_files, plots, args, ioh)

Generate plots for files and save a multi-page PDF per input.

Also writes metadata JSON next to the PDF.

visualization.plot_simtel_events.plot_simtel_event_image(filename, distance=None, event_index=None)

Read a sim_telarray file and plot the DL1 image for one event via ctapipe.

Parameters:

filenamestr | pathlib.Path

Path to the .simtel file.

distanceastropy.units.Quantity | float | None, optional

Distance to annotate in the plot. If a Quantity, interpreted in meters. If not provided, no unit conversion is attempted.

event_indexint | None, optional

Zero-based index of the event to plot. If None, the first event is used.

Returns:

matplotlib.figure.Figure | None

The created figure, or None if no suitable event/image is available.

visualization.plot_simtel_events.plot_simtel_integrated_pedestal_image(filename, tel_id=None, half_width=8, offset=16, event_index=None)

Plot camera image of integrated pedestal per pixel away from the flasher peak.

visualization.plot_simtel_events.plot_simtel_integrated_signal_image(filename, tel_id=None, half_width=8, event_index=None)

Plot camera image of integrated signal per pixel around the flasher peak.

visualization.plot_simtel_events.plot_simtel_peak_timing(filename, tel_id=None, sum_threshold=10.0, peak_width=8, examples=3, timing_bins=None, return_stats=False, event_index=None)

Peak finding per pixel; report mean/std of peak sample and plot a histogram.

Parameters:

filenamestr | pathlib.Path

Path to the .simtel file.

tel_idint | None, optional

Telescope ID to use. If None, the first telescope with R1 data is chosen.

sum_thresholdfloat, optional

Minimum sum over samples for a pixel to be considered. Default is 10.0.

peak_widthint, optional

Characteristic peak width (samples) for CWT. Default is 8.

examplesint, optional

Number of example pixel traces to overlay. Default is 3.

timing_binsint | None, optional

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

return_statsbool, optional

If True, also return a statistics dictionary. Default is False.

event_indexint | None, optional

Zero-based index of the event to plot. If None, the first event is used.

Returns:

matplotlib.figure.Figure | tuple[matplotlib.figure.Figure, dict] | None

The created figure, or None if R1 waveforms are unavailable. If return_stats is True, a tuple (fig, stats) is returned, where stats has keys {"considered", "found", "mean", "std"}.

visualization.plot_simtel_events.plot_simtel_step_traces(filename, tel_id=None, pixel_step=100, max_pixels=None, event_index=None)

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

Parameters:

filenamestr | pathlib.Path

Path to the .simtel file.

tel_idint | None, optional

Telescope ID to use. If None, the first telescope with R1 data is chosen.

pixel_stepint, optional

Interval between pixel indices to plot. Default is 100.

max_pixelsint | None, optional

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

event_indexint | None, optional

Zero-based index of the event to plot. If None, the first event is used.

Returns:

matplotlib.figure.Figure | None

The created figure, or None if R1 waveforms are unavailable.

visualization.plot_simtel_events.plot_simtel_time_traces(filename, tel_id=None, n_pixels=3, event_index=None)

Plot R1 time traces for a few pixels of one event.

Parameters:

filenamestr | pathlib.Path

Path to the .simtel file.

tel_idint | None, optional

Telescope ID to use. If None, the first telescope with R1 data is chosen.

n_pixelsint, optional

Number of pixels with highest signal to plot. Default is 3.

event_indexint | None, optional

Zero-based index of the event to plot. If None, the first event is used.

Returns:

matplotlib.figure.Figure | None

The created figure, or None if R1 waveforms are unavailable.

visualization.plot_simtel_events.plot_simtel_waveform_matrix(filename, tel_id=None, vmax=None, event_index=None, pixel_step=None)

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

Parameters:

filenamestr | pathlib.Path

Path to the .simtel file.

tel_idint | None, optional

Telescope ID to use. If None, the first telescope with R1 data is chosen.

vmaxfloat | None, optional

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

event_indexint | None, optional

Zero-based index of the event to plot. If None, the first event is used.

pixel_stepint | None, optional

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

Returns:

matplotlib.figure.Figure | None

The created figure, or None if R1 waveforms are unavailable.

plot_simtel_event_histograms

Plot simtel event histograms filled with SimtelIOEventHistograms.

visualization.plot_simtel_event_histograms.plot(histograms, output_path=None, limits=None, rebin_factor=2, array_name=None)

Plot simtel event histograms.

Parameters:

histograms: SimtelIOEventHistograms

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

rebin_factor: int, optional

Factor by which to reduce the number of bins in 2D histograms for re-binned plots. Default is 2 (merge every 2 bins). Set to 0 or 1 to disable re-binning.

array_name: str, optional

Name of the telescope array configuration.

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_detailed_parameter_plot(pars, ks_statistic, psf_diameter, simulated_data, data_to_plot, is_best, pdf_pages, fraction=0.8, p_value=None)

Create a detailed plot for a parameter set showing all parameter values.

Parameters:

parsdict

Parameter set dictionary

ks_statisticfloat

KS statistic value for this parameter set

psf_diameterfloat

PSF diameter value for this parameter set

simulated_dataarray

Simulated data for plotting

data_to_plotdict

Data dictionary for plotting

is_bestbool

Whether this is the best parameter set

pdf_pagesPdfPages

PDF pages object to save the plot

fractionfloat, optional

PSF containment fraction (default: 0.8)

p_valuefloat, optional

P-value from KS test for statistical significance

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 from gradient descent

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

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

output_filePath

Output file path for saving the plot

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_optimization_plots(args_dict, gd_results, tel_model, data_to_plot, output_dir)

Create optimization plots for all iterations if requested.

Parameters:

args_dictdict

Dictionary containing command-line arguments with save_plots flag.

gd_resultslist

List of (params, rmsd, _, psf_diameter, _) tuples from gradient descent optimization.

tel_modelTelescopeModel

Telescope model object for naming files.

data_to_plotdict

Dictionary containing measured PSF data.

output_dirPath

Directory where the PDF file will be saved.

Notes

Creates a PDF file with plots for optimization iterations. Only creates plots every 5 iterations plus the final iteration to avoid excessively large files. Returns early if save_plots flag is not set.

visualization.plot_psf.create_parameter_progression_plots(results, best_pars, data_to_plot, pdf_pages, fraction=0.8)

Create plots for all parameter sets showing optimization progression.

Parameters:

resultslist

List of (pars, ks_statistic, p_value, psf_diameter, simulated_data) tuples

best_parsdict

Best parameter set for highlighting

data_to_plotdict

Data dictionary for plotting

pdf_pagesPdfPages

PDF pages object to save plots

fractionfloat, optional

PSF containment fraction (default: 0.8)

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)

Create a plot for PSF simulation results.

Parameters:

data_to_plotdict

Data dictionary for plotting.

parsdict

Parameter set dictionary.

psf_diameterfloat

PSF diameter value.

metricfloat

RMSD value (if use_ks_statistic=False) or KS statistic (if use_ks_statistic=True).

is_bestbool

Whether this is the best parameter set.

pdf_pagesPdfPages

PDF pages object for saving plots.

fractionfloat, optional

PSF containment fraction (default: 0.8).

p_valuefloat, optional

P-value from KS test (only used when use_ks_statistic=True).

use_ks_statisticbool, optional

If True, metric is KS statistic; if False, metric is RMSD.

second_metricfloat, optional

Second metric value to display alongside the primary metric (for final best plot).

visualization.plot_psf.create_psf_vs_offaxis_plot(tel_model, site_model, args_dict, best_pars, output_dir)

Create PSF diameter vs off-axis angle plot using the best parameters.

Parameters:

tel_modelTelescopeModel

Telescope model object.

site_modelSiteModel

Site model object.

args_dictdict

Dictionary containing parsed command-line arguments.

best_parsdict

Best parameter set.

output_dirPath

Output directory for saving plots.

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

Generate PSF diameter label based on containment fraction.

Parameters:

fractionfloat

PSF containment fraction (e.g., 0.8 for D80, 0.95 for D95)

unitstr, optional

Unit for the label (default: “cm”)

Returns:

str

Formatted PSF diameter label (e.g., “D80 (cm)”, “D95 (cm)”, “D95”)

visualization.plot_psf.get_significance_label(p_value)

Get significance label for p-value.

visualization.plot_psf.setup_pdf_plotting(args_dict, output_dir, tel_model_name)

Set up PDF plotting for gradient descent optimization if requested.

Parameters:

args_dictdict

Dictionary containing command-line arguments with plot_all flag.

output_dirPath

Directory where the PDF file will be saved.

tel_model_namestr

Name of the telescope model for filename generation.

Returns:

PdfPages or None

PdfPages object for saving plots if plotting is requested, None otherwise.

Notes

Creates a PDF file for saving cumulative PSF plots during gradient descent optimization. Returns None if plotting is not requested via the plot_all flag.

plot_incident_angles

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

Plots the primary-mirror hit radius if available.

members: