pygama.vis package#

This subpackage implements utilities to visualize data.

Submodules#

pygama.vis.waveform_browser module#

class pygama.vis.waveform_browser.WaveformBrowser(files_in: str | list[str], lh5_group: str, base_path: str = '', entry_list: Optional[Union[list[int], list[list[int]]]] = None, entry_mask: Optional[Union[list[int], list[list[int]]]] = None, dsp_config: Optional[str] = None, database: Optional[Union[str, dict]] = None, aux_values: Optional[DataFrame] = None, lines: str | list[str] = 'waveform', styles: Optional[Union[dict[str, list], str]] = None, legend: Optional[Union[str, list[str]]] = None, legend_opts: Optional[dict] = None, n_drawn: int = 1, x_unit: Optional[Union[Unit, str]] = None, x_lim: Optional[tuple[float | str | pint.util.Quantity]] = None, y_lim: Optional[tuple[float | str | pint.util.Quantity]] = None, norm: Optional[str] = None, align: Optional[str] = None, buffer_len: int = 128, block_width: int = 8)#

Bases: object

The WaveformBrowser is a tool meant for interacting with waveforms from LEGEND HDF5 files. It defines an interface for drawing waveforms from a file, drawing transformed waveforms defined using build_dsp() style JSON files, drawing horizontal and vertical lines at the values of calculated parameters, and filling a legend with calculated parameters.

Parameters:

  • files_in (str | list[str]) – name of file or list of names to browse. Can use wildcards.

  • lh5_group (str) – name of LH5 group in file to browse.

  • base_path (str) – base path for file. See LH5Store.

  • entry_list (list[int] | list[list[int]]) – list of event indices to draw. If it is a nested list, use local indices for each file, otherwise use global indices.

  • entry_mask (list[int] | list[list[int]]) – boolean mask indicating which events to draw. If a nested list, use a mask for each file, else use a global mask. Cannot be used with entry_list.

  • dsp_config (str) – name of DSP config JSON file containing a list of processors that can be applied to waveforms.

  • database (str | dict) – dictionary or JSON file with database of processing parameters.

  • aux_values (pandas.DataFrame) – table of auxiliary values that are one-to-one with the input waveforms that can be drawn or placed in the legend.

  • lines (str | list[str]) – name(s) of objects to draw 2D lines for. Waveforms will be drawn as a time-series. Scalar quantities will be drawn as horizontal or vertical lines, depending on units. Vectors will be drawn as multiple horizontal or vertical lines.

  • styles (dict[str, list] | str) –

    line colors and other style parameters to cycle through when drawing waveforms. Can be given as

    • dictionary of lists (e.g. {'color':['r', 'g', 'b'], 'linestyle':['-', '--', '.']})

    • name of predefined style (see matplotlib.style documentation)

    • None (use current matplotlib.rcParams style).

    If a single style cycle is given, use for all lines; if a list is given, match to lines list.

  • legend (str | list[str]) – formatting string and values to include in the legend. This can be a list of values (one for each drawn object). If just a name is given, it will be auto-formatted to 3 digits. Otherwise, formatting strings in brackets can be used (e.g. {energy:0.1f} keV, {timestamp:d} ns). Names will be searched in the input file, DSP processed parameters, or auxiliary data-table.

  • legend_opts (dict) – dictionary containing additional keyword arguments for matplotlib.legend.

  • n_drawn (int) – number of events to draw simultaneously when calling draw_next().

  • x_lim (tuple[float | str | pint.Quantity]) –

    range of x- or y-values and units passed as tuple.

    • None: Get range from first waveform drawn

    • pint.Quantity: set value and x-unit

    • float: get unit from first waveform drawn

    • str: convert to pint.Quantity (e.g. ('0*us', '10*us')).

  • y_lim (tuple[float | str | pint.Quantity]) –

    range of x- or y-values and units passed as tuple.

    • None: Get range from first waveform drawn

    • pint.Quantity: set value and x-unit

    • float: get unit from first waveform drawn

    • str: convert to pint.Quantity (e.g. ('0*us', '10*us')).

  • x_unit (pint.Unit | str) – unit of x-axis.

  • norm (str) – name of parameter (probably energy) to use to normalize waveforms. Useful when drawing multiple waveforms.

  • align (str) – name of parameter to use for x-offset. Useful, e.g., for aligning multiple waveforms at a particular timepoint.

  • buffer_len (int) – number of waveforms to keep in memory at a time.

  • block_width (int) – block width for ProcessinChain.

_update_auto_limit(x: ndarray, y: ndarray) → None#
clear_data() → None#

Reset the currently stored data.

draw_current(clear: bool = True) → None#

Draw the waveforms and data currently held internally by this class.

draw_entry(entry: int | list[int], append: bool = False, clear: bool = True, safe: bool = False) → None#

Draw specified entry in the current figure/axes.

Parameters:

  • entry (int | list[int]) – entry or list of entries to draw.

  • append (bool) – if True, do not clear previously drawn entries before drawing more.

  • clear (bool) – if True, clear previously drawn objects in the axes before drawing.

  • safe (bool) – if False, throw an exception for out of range entries.

draw_next(n_wfs: Optional[int] = None, append: bool = False, clear: bool = True) → tuple[int, int]#

Draw the next n_wfs waveforms (default self.n_drawn). See draw_next().

Return type:

tuple[int, int]

find_entry(entry: int | list[int], append: bool = True, safe: bool = False) → None#

Find the requested data associated with entry in input files and place store it internally without drawing it.

Parameters:

  • entry (int | list[int]) – index of entry or list of entries to find.

  • append (bool) – if False, clear previously found data before finding more.

  • safe (bool) – if False, throw an exception for out of range entries.

find_next(n_wfs: Optional[int] = None, append: bool = False) → tuple[int, int]#

Find the next n_wfs waveforms (default self.n_drawn). See find_entry().

Return type:

tuple[int, int]

new_figure() → None#

Create a new figure and draw in it.

reset() → None#

Reset to the start of the file for draw_next().

save_figure(f_out: str, *args, **kwargs) → None#

Write figure to file named f_out. See matplotlib.pyplot.savefig() for args and kwargs.

set_figure(fig: pygama.vis.waveform_browser.WaveformBrowser | matplotlib.figure.Figure, ax: Optional[Axes] = None) → None#

Use an already existing figure and axis.

Make sure to set clear=False when drawing if you don’t want to clear what’s already there! Can give a WaveformBrowser object to use the figure / axis from that.