dspeed.vis package#

This subpackage implements utilities to visualize data.

Submodules#

dspeed.vis.waveform_browser module#

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] | LH5Iterator) – name of file or list of files to browse. Can use wildcards. Can also pass an LH5Iterator
lh5_group (str | list[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 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 (dict | 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 ProcessingChain.

_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: int | None = 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: int | None = 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: WaveformBrowser | Figure, ax: Axes | None = 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.