dspeed.vis package

This subpackage implements utilities to visualize data.

Submodules

dspeed.vis.waveform_browser module

class dspeed.vis.waveform_browser.WaveformBrowser(raw_in, lh5_group='', base_path='', entry_list=None, entry_mask=None, dsp_config=None, database=None, aux_values=None, lines=None, styles=None, legend=None, legend_opts=None, n_drawn=1, x_unit=None, x_lim=None, y_lim=None, norm=None, align=None, buffer_len=128, block_width=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:

  • raw_in (str | Collection[str] | LH5Iterator | Table) – raw data with waveforms. Can be a file or list of lh5 files (requires use of lh5_group argument), an LH5Iterator

  • lh5_group (str | Collection[str]) – HDF5 base group(s) to read containing a LGDO table that contains the waveforms. If a list is provided for both lh5_files and group, they must be the same size. If a file is wild-carded, the same group will be assigned to each file found

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

  • entry_list (Collection[int] | Collection[Collection[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 (Collection[bool] | Collection[Collection[bool]]) – 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 | Mapping) – name of DSP config JSON file containing a list of processors that can be applied to waveforms.

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

  • aux_values (Mapping[np.ndarray]) – table of auxiliary values that are one-to-one with the input waveforms that can be drawn or placed in the legend.

  • lines (str | Collection[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 (Mapping[str, Collection] | 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 | Collection[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 (Mapping) – dictionary containing additional keyword arguments for matplotlib.legend.

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

  • x_lim (Collection[float | str | 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 (Collection[float | str | 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 (str | Unit) – 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 ProcessingChain.

_update_auto_limit(x, y)
clear_data()

Reset the currently stored data.

draw_current(clear=True)

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

draw_entry(entry, append=False, clear=True, safe=False)

Draw specified entry in the current figure/axes.

Parameters:

  • entry (int | Collection[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=None, append=False, clear=True)

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

Return type:

tuple[int, int]

find_entry(entry, append=True, safe=False)

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

Parameters:

  • entry (int | Collection[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=None, append=False)

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

Return type:

tuple[int, int]

new_figure()

Create a new figure and draw in it.

reset()

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

save_figure(f_out, *args, **kwargs)

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

set_figure(fig, ax=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.