pyrocko.gui.snuffler.snuffling

Snuffling infrastructure

This module provides the base class Snuffling for user-defined snufflings and some utilities for their handling.

Classes

Choice(name, ident, default, choices)	Definition of a string choice for the snuffling.
Param(name, ident, default, minimum, maximum)	Definition of an adjustable floating point parameter for the snuffling.
Snuffling()	Base class for user snufflings.
SnufflingModule(path, name, handler)	Utility class to load/reload snufflings from a file.
Switch(name, ident, default)	Definition of a boolean switch for the snuffling.

Exceptions

MissingStationInformation	Raised when station information is missing.
NoTracesSelected	This exception is raised, when no traces have been selected in the viewer and we cannot fallback to using the current view.
NoViewerSet	This exception is raised, when no viewer has been set on a Snuffling.
SnufflingCallFailed	This exception is raised, when Snuffling.fail() is called from Snuffling.call().
SnufflingError	Base exception for Snuffling errors.
UserCancelled	This exception is raised, when the user has cancelled a snuffling dialog.

class Param(name, ident, default, minimum, maximum, low_is_none=None, high_is_none=None, low_is_zero=False, tracking=True, type=<class 'float'>)

Bases: object

Definition of an adjustable floating point parameter for the snuffling. The snuffling may display controls for user input for such parameters.

Parameters:

• name – labels the parameter on the snuffling’s control panel

• ident – identifier of the parameter

• default – default value

• minimum – minimum value for the parameter

• maximum – maximum value for the parameter

• low_is_none – if True: parameter is set to None at lowest value of parameter range (optional)

• high_is_none – if True: parameter is set to None at highest value of parameter range (optional)

• low_is_zero – if True: parameter is set to value 0 at lowest value of parameter range (optional)

class Switch(name, ident, default)

Bases: object

Definition of a boolean switch for the snuffling. The snuffling may display a checkbox for such a switch.

Parameters:

• name – labels the switch on the snuffling’s control panel

• ident – identifier of the parameter

• default – default value

class Choice(name, ident, default, choices)

Bases: object

Definition of a string choice for the snuffling. The snuffling may display a menu for such a choice.

Parameters:

• name – labels the menu on the snuffling’s control panel

• ident – identifier of the parameter

• default – default value

• choices – tuple of other options

class Snuffling

Bases: object

Base class for user snufflings.

Snufflings are plugins for snuffler (and other applications using the PileViewer class defined in pile_viewer.py). They can be added, removed and reloaded at runtime and should provide a simple way of extending the functionality of snuffler.

A snuffling has access to all data available in a pile viewer, can process this data and can create and add new traces and markers to the viewer.

setup()

Setup the snuffling.

This method should be implemented in subclass and contain e.g. calls to set_name() and add_parameter().

module_dir()

Returns the path of the directory where snufflings are stored.

The default path is $HOME/.snufflings.

init_gui(viewer, panel_parent, menu_parent, reloaded=False)

Set parent viewer and hooks to add panel and menu entry.

This method is called from the PileViewer object. Calls setup_gui().

setup_gui(reloaded=False)

Create and add gui elements to the viewer.

This method is initially called from init_gui(). It is also called, e.g. when new parameters have been added or if the name of the snuffling has been changed.

set_force_panel(bool=True)

Force to create a panel.

Parameters:

bool – if True will create a panel with Help, Clear and Run button.

delete_gui()

Remove the gui elements of the snuffling.

This removes the panel and menu entry of the widget from the viewer and also removes all traces and markers added with the add_traces() and add_markers() methods.

set_name(name)

Set the snuffling’s name.

The snuffling’s name is shown as a menu entry and in the panel header.

get_name()

Get the snuffling’s name.

enable_pile_changed_notifications()

Get informed when pile changed.

When activated, the pile_changed() method is called on every update in the viewer’s pile.

disable_pile_changed_notifications()

Stop getting informed about changes in viewer’s pile.

pile_changed()

Called when the connected viewer’s pile has changed.

Must be activated with a call to enable_pile_changed_notifications().

reset_gui(reloaded=False)

Delete and recreate the snuffling’s panel.

show_message(kind, message)

Display a message box.

Parameters:

• kind – string defining kind of message

• message – the message to be displayed

error(message)

Show an error message box.

Parameters:

message – specifying the error

warn(message)

Display a warning message.

Parameters:

message – specifying the warning

fail(message, action='error')

Show an error message box and raise SnufflingCallFailed exception.

Parameters:

message – specifying the error

pylab(name=None, get='axes', figure_cls=None)

Create a pyrocko.gui.util.FigureFrame and return either the frame, a matplotlib.figure.Figure instance or a matplotlib.axes.Axes instance.

Parameters:

• name – labels the figure frame’s tab

• get – ‘axes’|’figure’|’frame’ (optional)

figure(name=None)

Returns a matplotlib.figure.Figure instance.

Force drawing of the figure by calling fig.canvas.draw() on the returned object fig.

Parameters:

name – labels the tab of the figure

axes(name=None)

Returns a matplotlib.axes.Axes instance.

Parameters:

name – labels the tab of axes

figure_frame(name=None, figure_cls=None)

Create a pyrocko.gui.util.FigureFrame.

Parameters:

name – labels the tab figure frame

smartplot_frame(name, *args, plot_cls=None, **kwargs)

Create a pyrocko.gui.util.SmartplotFrame.

Parameters:

• name – labels the tab

• *args – passed to pyrocko.plot.smartplot.Plot

• *kwargs – passed to pyrocko.plot.smartplot.Plot

• plot_cls – if given, subclass to be used instead of pyrocko.plot.smartplot.Plot

pixmap_frame(filename=None, name=None)

Create a pyrocko.gui.util.PixmapFrame.

Parameters:

• name – labels the tab

• filename – name of file to be displayed

web_frame(url=None, name=None)

Creates a WebKitFrame which can be used as a browser within Snuffler.

Parameters:

• url – url to open

• name – labels the tab

vtk_frame(name=None, actors=None)

Create a pyrocko.gui.util.VTKFrame to render interactive 3D graphics.

Parameters:

• actors – list of VTKActors

• name – labels the tab

Initialize the interactive rendering by calling the frames’ :py:meth`initialize` method after having added all actors to the frames renderer.

Requires installation of vtk including python wrapper.

tempdir()

Create a temporary directory and return its absolute path.

The directory and all its contents are removed when the Snuffling instance is deleted.

set_live_update(live_update)

Enable/disable live updating.

When live updates are enabled, the call() method is called whenever the user changes a parameter. If it is disabled, the user has to initiate such a call manually by triggering the snuffling’s menu item or pressing the call button.

add_parameter(param)

Add an adjustable parameter to the snuffling.

Parameters:

param – object of type Param, Switch, or Choice.

For each parameter added, controls are added to the snuffling’s panel, so that the parameter can be adjusted from the gui.

add_trigger(name, method)

Add a button to the snuffling’s panel.

Parameters:

• name – string that labels the button

• method – method associated with the button

get_parameters()

Get the snuffling’s adjustable parameter definitions.

Returns a list of objects of type Param.

get_parameter(ident)

Get one of the snuffling’s adjustable parameter definitions.

Parameters:

ident – identifier of the parameter

Returns an object of type Param or None.

set_parameter(ident, value)

Set one of the snuffling’s adjustable parameters.

Parameters:

• ident – identifier of the parameter

• value – new value of the parameter

Adjusts the control of a parameter without calling call().

set_parameter_range(ident, vmin, vmax)

Set the range of one of the snuffling’s adjustable parameters.

Parameters:

• ident – identifier of the parameter

• vmin,vmax – new minimum and maximum value for the parameter

Adjusts the control of a parameter without calling call().

set_parameter_choices(ident, choices)

Update the choices of a Choice parameter.

Parameters:

• ident – identifier of the parameter

• choices – list of strings

get_parameter_value(ident)

Get the current value of a parameter.

Parameters:

ident – identifier of the parameter

get_settings()

Returns a dictionary with identifiers of all parameters as keys and their values as the dictionaries values.

get_viewer()

Get the parent viewer.

Returns a reference to an object of type PileViewer, which is the main viewer widget.

If no gui has been initialized for the snuffling, a NoViewerSet exception is raised.

get_pile()

Get the pile.

If a gui has been initialized, a reference to the viewer’s internal pile is returned. If not, the make_pile() method (which may be overloaded in subclass) is called to create a pile. This can be utilized to make hybrid snufflings, which may work also in a standalone mode.

get_active_event_and_stations(trange=(-3600.0, 3600.0), missing='warn')

Get event and stations with available data for active event.

Parameters:

• trange – (begin, end), time range around event origin time to query for available data

• missing – string, what to do in case of missing station information: 'warn', 'raise' or 'ignore'.

Returns:

(event, stations)

get_stations()

Get all stations known to the viewer.

get_markers()

Get all markers from the viewer.

get_event_markers()

Get all event markers from the viewer.

get_selected_markers()

Get all selected markers from the viewer.

get_selected_event_markers()

Get all selected event markers from the viewer.

get_active_event_and_phase_markers()

Get the marker of the active event and any associated phase markers

get_viewer_trace_selector(mode='inview')

Get currently active trace selector from viewer.

Parameters:

mode – set to 'inview' (default) to only include selections currently shown in the viewer, 'visible' to include all traces not currenly hidden by hide or quick-select commands, or ``'all' to disable any restrictions.

chopper_selected_traces(fallback=False, marker_selector=None, mode='inview', main_bandpass=False, progress=None, responsive=False, *args, **kwargs)

Iterate over selected traces.

Shortcut to get all trace data contained in the selected markers in the running snuffler. For each selected marker, pyrocko.pile.Pile.chopper() is called with the arguments tmin, tmax, and trace_selector set to values according to the marker. Additional arguments to the chopper are handed over from *args and **kwargs.

Parameters:

• fallback – If True, if no selection has been marked, use the content currently visible in the viewer.

• marker_selector – If not None a callback to filter markers.

• mode – Set to 'inview' (default) to only include selections currently shown in the viewer (excluding traces accessible through vertical scrolling), 'visible' to include all traces not currently hidden by hide or quick-select commands (including traces accessible through vertical scrolling), or 'all' to disable any restrictions.

• main_bandpass – If True, apply main control high- and lowpass filters to traces. Note: use with caution. Processing is fixed to use 4th order Butterworth highpass and lowpass and the signal is always demeaned before filtering. FFT filtering, rotation, demean and bandpass settings from the graphical interface are not respected here. Padding is not automatically adjusted so results may include artifacts.

• progress – If given a string a progress bar is shown to the user. The string is used as the label for the progress bar.

• responsive – If set to True, occasionally allow UI events to be processed. If used in combination with progress, this allows the iterator to be aborted by the user.

get_selected_time_range(fallback=False)

Get the time range spanning all selected markers.

Parameters:

fallback – if True and no marker is selected return begin and end of visible time range

panel_visibility_changed(bool)

Called when the snuffling’s panel becomes visible or is hidden.

Can be overloaded in subclass, e.g. to perform additional setup actions when the panel is activated the first time.

make_pile()

Create a pile.

To be overloaded in subclass. The default implementation just calls pyrocko.pile.make_pile() to create a pile from command line arguments.

make_panel(parent)

Create a widget for the snuffling’s control panel.

Normally called from the setup_gui() method. Returns None if no panel is needed (e.g. if the snuffling has no adjustable parameters).

make_helpmenuitem(parent)

Create the help menu item for the snuffling.

make_menuitem(parent)

Create the menu item for the snuffling.

This method may be overloaded in subclass and return None, if no menu entry is wanted.

output_filename(caption='Save File', dir='', filter='', selected_filter=None)

Query user for an output filename.

This is currently a wrapper to QFileDialog.getSaveFileName. UserCancelled exception is raised if the user cancels the dialog.

input_directory(caption='Open Directory', dir='')

Query user for an input directory.

This is a wrapper to QFileDialog.getExistingDirectory. A UserCancelled exception is raised if the user cancels the dialog.

input_filename(caption='Open File', dir='', filter='', selected_filter=None)

Query user for an input filename.

This is currently a wrapper to QFileDialog.getOpenFileName. A UserCancelled exception is raised if the user cancels the dialog.

input_dialog(caption='', request='', directory=False)

Query user for a text input.

This is currently a wrapper to QInputDialog.getText. A UserCancelled exception is raised if the user cancels the dialog.

modified_snuffling_panel(value, iparam)

Called when the user has played with an adjustable parameter.

The default implementation sets the parameter, calls the snuffling’s call() method and finally triggers an update on the viewer widget.

switch_on_snuffling_panel(ident, state)

Called when the user has toggled a switchable parameter.

choose_on_snuffling_panel(ident, state)

Called when the user has made a choice about a choosable parameter.

menuitem_triggered(arg)

Called when the user has triggered the snuffling’s menu.

The default implementation calls the snuffling’s call() method and triggers an update on the viewer widget.

call_button_triggered()

Called when the user has clicked the snuffling’s call button.

The default implementation calls the snuffling’s call() method and triggers an update on the viewer widget.

clear_button_triggered()

Called when the user has clicked the snuffling’s clear button.

This calls the cleanup() method and triggers an update on the viewer widget.

help()

Get help text in html/markdown.

help_button_triggered()

Creates a QLabel which contains the documentation as given in the snufflings help().

live_update_toggled(on)

Called when the checkbox for live-updates has been toggled.

add_traces(traces)

Add traces to the viewer.

Parameters:

traces – list of objects of type pyrocko.trace.Trace

The traces are put into a pyrocko.pile.MemTracesFile and added to the viewer’s internal pile for display. Note, that unlike with the traces from the files given on the command line, these traces are kept in memory and so may quickly occupy a lot of ram if a lot of traces are added.

This method should be preferred over modifying the viewer’s internal pile directly, because this way, the snuffling has a chance to automatically remove its private traces again (see cleanup() method).

add_trace(tr)

Add a trace to the viewer.

See add_traces().

add_markers(markers)

Add some markers to the display.

Takes a list of objects of type pyrocko.gui.snuffler.marker.Marker and adds these to the viewer.

add_marker(marker)

Add a marker to the display.

See add_markers().

cleanup()

Remove all traces and markers which have been added so far by the snuffling.

call()

Main work routine of the snuffling.

This method is called when the snuffling’s menu item has been triggered or when the user has played with the panel controls. To be overloaded in subclass. The default implementation does nothing useful.

get_tpad()

Return current amount of extra padding needed by live processing hooks.

pre_destroy()

Called when the snuffling instance is about to be deleted.

Can be overloaded to do user-defined cleanup actions. The default implementation calls cleanup() and deletes the snuffling`s tempory directory, if needed.

exception SnufflingError

Bases: Exception

Base exception for Snuffling errors.

exception NoViewerSet

Bases: SnufflingError

This exception is raised, when no viewer has been set on a Snuffling.

exception MissingStationInformation

Bases: SnufflingError

Raised when station information is missing.

exception NoTracesSelected

Bases: SnufflingError

This exception is raised, when no traces have been selected in the viewer and we cannot fallback to using the current view.

exception UserCancelled

Bases: SnufflingError

This exception is raised, when the user has cancelled a snuffling dialog.

exception SnufflingCallFailed

Bases: SnufflingError

This exception is raised, when Snuffling.fail() is called from Snuffling.call().

class SnufflingModule(path, name, handler)

Bases: object

Utility class to load/reload snufflings from a file.

The snufflings are created by user modules which have the special function __snufflings__ which return the snuffling instances to be exported. The snuffling module is attached to a handler class, which makes use of the snufflings (e.g. PileViewer from pile_viewer.py). The handler class must implement the methods add_snuffling() and remove_snuffling() which are used as callbacks. The callbacks are utilized from the methods load_if_needed() and remove_snufflings() which may be called from the handler class, when needed.

load_if_needed()

Called by Snuffler to check whether it has to reload the module.

add_snuffling(snuffling, reloaded=False)

Called by load_if_needed() to add a snuffling.

remove_snufflings()

Called by load_if_needed() to remove all snufflings.