Experimental Notice

There are currently three versions of a graphical user interface (GUI).

This includes:

• A browser-based web app that is hosted by streamlit (THIS IS THE CURRENTLY RECOMMENDED GUI)
• A windowed application that runs in its own window (uses tkinter)
• An ipywidget application that runs in Jupyter notebooks, where supported

The streamlit app can be run on any device with a browser and internet connection, though its formatting is intended for laptop/desktop use The windowed application contains plots and charts and needs no coding to run. The second GUI is a set of widgets intended to be run in a Jupyter notebook. Using ipywidgets, it allows you to run the underlying HVSR code, with no coding (except the code needed to start the GUI: sprit.gui(kind="notebook") or sprit.gui("nb")). This uses the plotly package to create plots. These plots are interactive, and values of the plotted data can be accessed by hovering over the plot. These plots can be exported as .png files using the camera icon on each plot:

The windowed graphical user interface (GUI) has been tested on several Windows and Linux systems, but has had issues on some Linux systems, since tkinter is not installed with python by default. It has not been tested on iOS systems. Check the Troubleshooting page if you run into issues to see if it is addressed there. The notebook version of the GUI has been tested and works in a Visual Studio Code notebook environment and in Google Colab. The Google Colab environment only allows limited use of this version (no graphing capacity) and only in playground mode.

There is a plan to make the graphical user interface accessible as an executable file without a python installation, but that has not yet been implemented.

Introduction

A graphical user interface (GUI) is an application with a window with buttons, text entries, etc. that can be operated with a mouse and keyboard. For sprit, it enables use of the package without any coding.

The default GUI is a locally hosted version of the browser app (mentioned above). This creates a GUI in a webbrowser on your local system (no internet needed). This can be access from both the code and command line interfaces:

Python:

sprit.gui() # or sprit.gui(kind='browser')

Command Line:

sprit gui

The windowed graphical user interface (GUI) uses the tkinter module, part of the python standard library. The GUI can be started from both the code and command line interfaces:

Python:

sprit.gui(kind='windowed')

The jupyter notebook GUI uses ipywidgets. It is currently experimental and may not work fully as intended. Run the following code form within a Jupyter notebook to access the widgets.

Python:

sprit.gui(kind='widget') # you may also use kind='notebook', kind='nb', kind='jupyter'

Sample Data

To access the sample data in the GUI, simply type "sample" or "sample1" "sample2"..."sample6" in the Data filepath box in the Input tab. This is the default in the notebook version. This will read sample data (there are 6 sample files. "sample" defaults to "sample1". Select "Batch" for the Source type radio button at the 5op of the Input tab to do analysis on all 6 files at once in batch mode).

Usage

The GUI has several tabs and menus. Each tab allows manipulation of the parameters for the different functions necessary for the HVSR analysis. The tabs include:

• Input Params: parameters for sprit.input_params() and sprit.fetch_data()
• Preview: displays the information for the seismic data stream that has been read in (blank until either the Read or Run button is selected).
• Noise: parameters for excluding data and ppsd time windows from HVSR analysis. (parameters for sprit.remove_noise())
• Settings: parameters to adjust for the HVSR processing functions (sprit.generate_ppsds(), sprit.process_hvsr(), and slrit.check_peaks())
• Log: a printed log of all analysis steps carried out during current session (since the GUI window has been opened). This is similar to the output from verbose=True in most of the functions.
• Results: peak analysis and plot results are displayed. In batch mode, the different sites can be selected and displayed in this tab as well.

Each tab shows the equivalent python call for the settings and parameters you have selected.

At the bottom of most of the tabs are buttons for processing data. On the Input tab, there is a Read Data button and Run button. The Read Data button performs the sprit.input_params() and sprit.fetch_data() functions with the parameters you have selected on that tab. This will take you to the Preview tab where you can preview the data you have read in. You may then choose to go to the Noise tab to do noise removal via the sprit.remove_noise() function or to click the Run button to perform the rest of the HVSR analysis (sprit.generate_ppsds() --> sprit.process_hvsr --> sprit.check_peaks(). Selecting the Run button will take you to the Results tab.

Input tab

The Input tab contains the parameters for inputting into the rest of the processing algorithm. Specifically, it enables selection of parameters for sprit.input_params() and sprit.fetch_data()

The notebook version is below. The accordions are the boxes with the arrows point to the left. Clicking any of those will reveal more available options. Notably, the Instrument Metadata accordion/section contains an option to read in the Instrument Settings file (.inst) created using sprit.export_settings() and the IO/Parameters accordion/section contains an option to read in a Processing Settings file (.proc), also created with sprit.export_settings(). The Read button simply reads in the data without processing it (sprit.input_params() and sprit.fetch_data()). The Run button runs the full processing algorithm for HVSR.

Preview tab

The Preview tab is intended to allow a visual inspection of the data before proceeding with processing steps. This is where you will land if you select the "Read Data" button on the Input tab.

The notebook version of the Preview tab is divided into two subtabs: Data Preview and Noise Removal. The Data Preview tab simply shows a chart of the raw data. The Noise Removal tab has options for removing noisy data. The Update Noise Windows applies the settings from the Noise Removal subtab. The Run button runs the full processing algorithm for HVSR.

Noise tab

The Noise tab allows you to carry out noise removal via sprit.remove_noise() before moving to the next stages of analysis. The main chart in this tab has a spectrogram of the "Z" component of the data, as well as a raw stream of all three components below it.

You may select parameters and then push the "Update Noise Windows." Additionally, you can manually select windows to remove by clicking on the chart area (You can click on any of the four charts). Left-click to begin a window (a line will draw where you clicked). Left click to end that window and your window will appear. All data within that window will be removed from later analysis. To delete a window, right click anywhere in the window you have created.

If there are gaps in the input data, they will show up as red bars on all four plots.

The Noise tab is a subtab of the Preview tab in the notebook version.

Settings tab

The settings tab contains multiple sub-tabs for selecting settings and parameters for various aspects of the sprit package.

PPSD Settings subtab

The PPSD Settings subtab contains parameters and settings to be adjusted for the sprit.generate_ppsds() function. Since this function calls the obspy.signal.spectral_estimation.PPSD() class, it also includes the parameters to read into that class instance.

The notebook version:

Outlier Settings subtab

This is currently only implemented in the notebook version. This enables the removal of windows where either the PPSD curve or the H/V curve is an outlier. Outliers can be removed using the Root Square Mean Error (RMSE) against the median curve value.

HVSR Settings subtab

The HVSR Settings subtab contains parameters and settings to be adjusted for the sprit.process_hvsr() and sprit.check_peaks() functions. The default values are filled in for you. The actual python calls are displayed on the bottom half of the tab.

The notebook version:

Plot Settings subtab

The Plot Settings subtab contains settings for updating the plot in the Results tab. This is the equivalent of changing parameters for the sprit.plot_hvsr() function. The actual python call for the sprit.plot_hvsr() function is displayed on the bottom part of the tab.

The notebook version:

Log tab

The Log tab contains the information for all actions performed during the current session, which is since you've opened the gooey window. This is roughly equivalent to including verbose=True as an argument to many of the function calls. It also contains the print output of the report for data that is processed (i.e., sprit.get_report(*args, report_format='print', **kwargs)

The notebook version:

Results tab

The Results tab contains a modified version of the print report and the plot report. A CSV report can also be exported from here (future feature).

The notebook version contains three subtabs for each time of report type: plot ("Plot"), print ("Peak Tests"), and csv ("Peak Table"). Plot:

Print:

CSV: Note that the csv table can be exported to the path specified in the text field, or which can be selected using a file selection dialog, if available on your system.