Visualization

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

• visualize

• legend_handlers

• simtel_event_plots

visualize

Module for visualization.

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.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_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.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.

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.get_telescope_patch(name, x, y, radius)

Create patch for a telescope.

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)

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.

Returns:

figFigure

Matplotlib figure object.

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_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

simtel_event_plots

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

visualization.simtel_event_plots.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.simtel_event_plots.plot_simtel_integrated_pedestal_image(filename, tel_id: int | None = None, half_width: int = 8, offset: int = 16, event_index: int | None = None)

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

visualization.simtel_event_plots.plot_simtel_integrated_signal_image(filename, tel_id: int | None = None, half_width: int = 8, event_index: int | None = None)

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

visualization.simtel_event_plots.plot_simtel_peak_timing(filename, tel_id: int | None = None, sum_threshold: float = 10.0, peak_width: int = 8, examples: int = 3, timing_bins: int | None = None, return_stats: bool = False, event_index: int | None = 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.simtel_event_plots.plot_simtel_step_traces(filename, tel_id: int | None = None, pixel_step: int = 100, max_pixels: int | None = None, event_index: int | None = 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.simtel_event_plots.plot_simtel_time_traces(filename, tel_id: int | None = None, n_pixels: int = 3, event_index: int | None = 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.simtel_event_plots.plot_simtel_waveform_matrix(filename, tel_id: int | None = None, vmax: float | None = None, event_index: int | None = None, pixel_step: int | None = 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.