Package `sprit`

This module enables analysis of ambient seismic data using the Horizontal to Vertical Spectral Ratio (HVSR) technique.

Sub-modules

sprit.sprit_calibration: This module will be used for calibration of the ambient HVSR data acquired near wells to derive a relation between the resonant frequency and the …
sprit.sprit_cli: This module/script is used to run sprit from the command line …
sprit.sprit_hvsr: This module is the main SpRIT module that contains all the functions needed to run HVSR analysis …
sprit.sprit_jupyter_UI: Functions to create jupyter notebook widget UI
sprit.sprit_plot
sprit.sprit_streamlit_ui: This file contains the code to run the SpRIT app (via streamlit) both locally and on the web.
sprit.sprit_tkinter_ui: This script contains all the functions, classes, etc. to create a tkinter app for graphical user interface.
sprit.sprit_utils

Functions

def batch_data_read(batch_data, batch_type='table', param_col=None, batch_params=None, verbose=False, **readcsv_getMeta_fetch_kwargs)

Function to read data in data as a batch of multiple data files. This is best used through sprit.fetch_data(args, source='batch', *other_kwargs).

Parameters

batch_data : filepath or list: Input data information for how to read in data as batch. Can be filepath or list of filepaths/stream objects. If filepath, should point to .csv (or similar that can be read by pandas.read_csv()) with batch data information.
batch_type : str, optional: Type of batch read, only 'table' and 'filelist' accepted. If 'table', will read data from a file read in using pandas.read_csv(), by default 'table'
param_col : None or str, optional: Name of parameter column from batch information file. Only used if a batch_type='table' and single parameter column is used, rather than one column per parameter (for single parameter column, parameters are formatted with = between keys/values and , between item pairs), by default None
batch_params : list, dict, or None, default = None: Parameters to be used if batch_type='filelist'. If it is a list, needs to be the same length as batch_data. If it is a dict, will be applied to all files in batch_data and will combined with extra keyword arguments caught by **readcsv_getMeta_fetch_kwargs.
verbose : bool, optional: Whether to print information to terminal during batch read, by default False
**readcsv_getMeta_fetch_kwargs: Keyword arguments that will be read into pandas.read_csv(), sprit.input_params, sprit.get_metadata(), and/or sprit.fetch_data()

Returns

hvsrBatch: HVSRBatch object with each item representing a different HVSRData object

Raises

IndexError: description

def calculate_azimuth(hvsr_data, azimuth_angle=45, azimuth_type='multiple', azimuth_unit='degrees', show_az_plot=False, verbose=False, **plot_azimuth_kwargs)

Function to calculate azimuthal horizontal component at specified angle(s). Adds each new horizontal component as a radial component to obspy.Stream object at hvsr_data['stream']

Parameters

hvsr_data : HVSRData: Input HVSR data
azimuth_angle : int, default=10: If azimuth_type='multiple', this is the angular step (in unit azimuth_unit) of each of the azimuthal measurements. If azimuth_type='single' this is the angle (in unit azimuth_unit) of the single calculated azimuthal measruement. By default 10.
azimuth_type : str, default='multiple': What type of azimuthal measurement to make, by default 'multiple'. If 'multiple' (or {'multi', 'mult', 'm'}), will take a measurement at each angular step of azimuth_angle of unit azimuth_unit. If 'single' (or {'sing', 's'}), will take a single azimuthal measurement at angle specified in azimuth_angle.
azimuth_unit : str, default='degrees': Angular unit used to specify azimuth_angle parameter. By default 'degrees'. If 'degrees' (or {'deg', 'd'}), will use degrees. If 'radians' (or {'rad', 'r'}), will use radians.
show_az_plot : bool, default=False: Whether to show azimuthal plot, by default False.
verbose : bool, default=False: Whether to print terminal output, by default False

Returns

HVSRData: Updated HVSRData object specified in hvsr_data with hvsr_data['stream'] attribute containing additional components (EHR-***), with *** being zero-padded (3 digits) azimuth angle in degrees.

def calculate_depth(freq_input, depth_model='ISGS_All', freq_col='Peak', calculate_depth_in_feet=False, calculate_elevation=True, show_depth_curve=True, surface_elevation_data='Elevation', bedrock_elevation_column='BedrockElevation', depth_column='BedrockDepth', verbose=False, export_path=None, swave_velocity=563.0, decimal_places=3, depth_model_in_latex=False, fig=None, ax=None, **kwargs)

Calculate depth(s) based on a frequency input (usually HVSRData or HVSRBatch oject) and a frequency-depth depth_model (usually a power law relationship).

Parameters

freq_input : HVSRData, HVSRBatch, float, int, or filepath, optional: Input with frequency information, by default {sprit_hvsr.HVSRData, sprit_hvsr.HVSRBatch, float, os.PathLike}
depth_model : str, tuple, list, or dict, optional: Model describing a relationship between frequency and depth, by default "ISGS_All"
calculate_depth_in_feet : bool, optional: Whether to calculate depth in feet (in addition to meters, which is done by default)
freq_col : str, optional: Name of the column containing the frequency information of the peak, by default "Peak" (per HVSRData.Table_Report output)
calculate_elevation : bool, optional: Whether or not to calculate elevation, by default True
surface_elevation_data : str or numeric, optional: The name of the column or a manually specified numeric value to use for the surface elevation value, by default "Elevation"
bedrock_elevation_column : str, optional: The name of the column in the TableReport for the bedrock elevation of the point. This can be either the name of a column in a table (i.e., Table_Report) or a numeric value, by default "BedrockElevation"
depth_column : str, optional: description, by default "BedrockDepth"
verbose : bool, optional: Whether or not to print information about the processing to the terminal, by default False
export_path : _type_, optional: description, by default None
swave_velocity : float, optional: Shear wave velocity to use for depth calculations in meters/second, if using the quarter wavelength shear wave velocity method, by default 563.0
decimal_places : int, optional: Number of decimal places to round depth results, by default 3

Returns

HVSRBatch or list if those are input; otherwise, HVSRData object: The returns are the same type as freq_input, except filepath which returns pandas.DataFrame

def calibrate(calib_filepath, calib_type='power', peak_freq_col='PeakFrequency', calib_depth_col='Bedrock_Depth', outlier_radius=None, xcoord_col='xcoord', ycoord_col='ycoord', bedrock_type=None, show_calibration_plot=True)

The calibrate function allows input of table with f0 and known depths to generate a power-law regression relationship.

Parameters

calib_filepath : pathlike object: Path to file readable by pandas.read_csv() with a column for frequencies and a column for depths.
calib_type : str, optional: Which calibration to use. Currently only power-law is supported, by default "power"
outlier_radius : None or float, optional: Radius (in CRS of coordinates) within which to use the points for calibration, by default None. Not currently supported.
bedrock_type : str or None, optional: Bedrock type by which to select which points to use for calibration, by default None. Not currently supported.
peak_freq_col : str, optional: Which column in calib_filepath to use for fundamental frequency values, by default "PeakFrequency"
calib_depth_col : str, optional: Which column in calib_filepath to use for depth values, by default "Bedrock_Depth"
show_calibration_plot : bool, optional: Whether to show the calibration plot, by default True

Returns

tuple: Tuple (a, b) containing the parameters used for calibration regression.

def check_peaks(hvsr_data, hvsr_band=[0.1, 50], peak_selection='max', peak_freq_range=[0.1, 50], azimuth='HV', verbose=False)

Function to run tests on HVSR peaks to find best one and see if it passes SESAME quality checks

Parameters

hvsr_data : dict: Dictionary containing all the calculated information about the HVSR data (i.e., hvsr_out returned from process_hvsr)
hvsr_band : tuple or list, default=[0.1, 50]: 2-item tuple or list with lower and upper limit of frequencies to analyze
peak_selection : str or numeric, default='max': How to select the "best" peak used in the analysis. For peak_selection="max" (default value), the highest peak within peak_freq_range is used. For peak_selection='scored', an algorithm is used to select the peak based in part on which peak passes the most SESAME criteria. If a numeric value is used (e.g., int or float), this should be a frequency value to manually select as the peak of interest.
peak_freq_range : tuple or list, default=[0.1, 50];: The frequency range within which to check for peaks. If there is an HVSR curve with multiple peaks, this allows the full range of data to be processed while limiting peak picks to likely range.
verbose : bool, default=False: Whether to print results and inputs to terminal.

Returns

hvsr_data : HVSRData or HVSRBatch object: Object containing previous input data, plus information about peak tests

def create_jupyter_ui()

Function that generates the user interface for Jupyter Notebooks.

This interface uses ipywidgets, plotly, and IPython to create a user interface for processing data in a Jupyter notebook.

As of version 2.6.5, this is broken but there are plans to fix in the near future.

def export_data(hvsr_data, data_export_path, data_export_format='mseed', starttime=None, endtime=None, tzone=None, export_edited_stream=False, site=None, project=None, verbose=False, **kwargs)

Export data stream to file

Parameters

hvsr_data : HVSRData, HVSRBatch, obspy.Stream, obspy.Trace: Input stream or HVSR object
data_export_path : pathlike-object: Filepath at which to format data. If directory (recommended), filename will be generated automatically.
data_export_format : str, optional: Format of data, should be file format supported by obspy.write(), by default 'mseed'
starttime : str, UTCDateTime, or datetime.datetime, optional: Starttime of stream, if trimming is desired, by default None
endtime : str, UTCDateTime, or datetime.datetime, optional: Endtime of stream, if trimming is desired, by default None
tzone : str, zoneinfo.Zoneinfo, optional: String readable by zoneinfo.Zoneinfo() or Zoneinfo object, by default None
export_edited_stream : bool, optional: Whether to export the raw stream or edited stream in HVSRData object, by default False
site : str, optional: Site name, to be used in filename generation, by default None
project : str, optional: Project or county name, to be used in filename generation, by default None
verbose : bool, optional: Whether to print information to terminal, by default False

Returns

obspy.Stream: Stream object exported

Raises

TypeError: hvsr_data must be of type HVSRData, HVSRBatch, obspy.Stream, or obspy.Trace

def export_hvsr(hvsr_data, hvsr_export_path=None, ext='hvsr', verbose=False)

Export data into pickle format that can be read back in using import_data(). Intended so data does not need to be processed each time it needs to be used. Default extension is .hvsr but it is still a pickled file that can be read in using pickle.load().

Parameters

hvsr_data : HVSRData or HVSRBatch: Data to be exported
hvsr_export_path : str or filepath object, default = None: String or filepath object to be read by pathlib.Path() and/or a with open(hvsr_export_path, 'wb') statement. If None, defaults to input input_data directory, by default None
ext : str, default = 'hvsr': Filepath extension to use for data file, by default 'hvsr'

def export_report(hvsr_results, report_export_path=None, report_export_format=['pdf'], azimuth='HV', csv_handling='rename', show_report=True, verbose=False)

Function to export reports to disk. Exportable formats for report_export_format include: * 'table': saves a pandas DataFrame as a csv) * 'plot': saves the matplotlib or plotly plot figure (depending on what is designated via plot_engine) as an image (png by default) * 'print': saves the print report as a .txt file * 'html': saves the html report as a .html file * 'pdf': saves the pdf report as a .pdf file

Parameters

hvsr_results : HVSRData object: HVSRData object containing the HVSR data
report_export_path : path-like object, optional: The path to where the report should be exported. If this is None (default), this is written to the home directory. If this is a True, uses the same directory as the input data, but generates a filename. If this is a directory, generates a filename. If filename is specified and the extension does not match the report type, the extension is adjusted. Otherwise, this is the output file or , by default None
csv_handling : {'rename', 'append', 'overwrite', 'keep'}, optional: If table is the report type, this can prevent overwriting data, by default 'rename'. * "rename" (or "keep"): renames the new file to prevent overwrite, appends a digit to the end of filename * "append": appends the new data to the existing file * "overwrite": overwrites the existing file
report_export_format : str or list, optional: The format (or a list of formats) to export the report, by default ['pdf'].
show_report : bool, optional: Whether to show the designated reports that were chosen for export, by default True
verbose : bool, optional: Whether to print progress and other information to terminal, by default False

Returns

HVSRData: An HVSRData object that is the same as hvsr_results, but with any additionally generated reports.

def export_settings(hvsr_data, export_settings_path='default', export_settings_type='all', include_location=False, verbose=True)

Save processing settings to json file.

Parameters

export_settings_path : str, default="default": Where to save the json file(s) containing the settings, by default 'default'. If "default," will save to sprit package resources. Otherwise, set a filepath location you would like for it to be saved to. If 'all' is selected, a directory should be supplied. Otherwise, it will save in the directory of the provided file, if it exists. Otherwise, defaults to the home directory.
export_settings_type : str, {'all', 'instrument', 'processing'}: What kind of settings to save. If 'all', saves all possible types in their respective json files. If 'instrument', save the instrument settings to their respective file. If 'processing', saves the processing settings to their respective file. By default 'all'
include_location : bool, default=False, input CRS: Whether to include the location parametersin the exported settings document.This includes xcoord, ycoord, elevation, elev_unit, and input_crs
verbose : bool, default=True: Whether to print outputs and information to the terminal

def fetch_data(params, source='file', data_export_path=None, data_export_format='mseed', detrend='spline', detrend_options=2, filter_type=None, filter_options={}, update_metadata=True, plot_input_stream=False, plot_engine='matplotlib', show_plot=True, verbose=False, **kwargs)

Fetch ambient seismic data from a source to read into obspy stream.

Parameters

params : dict
Dictionary containing all the necessary params to get data.
Parameters defined using input_params() function.
source : str,
String indicating where/how data file was created. For example, if raw data, will need to find correct channels.
'raw' finds raspberry shake data, from raw output copied using scp directly from Raspberry Shake, either in folder or subfolders;
'dir' is used if the day's 3 component files (currently Raspberry Shake supported only) are all 3 contained in a directory by themselves.
'file' is used if the params['input_data'] specified in input_params() is the direct filepath to a single file to be read directly into an obspy stream.
'batch' is used to read a list or specified set of seismic files.
Most commonly, a csv file can be read in with all the parameters. Each row in the csv is a separate file. Columns can be arranged by parameter.
data_export_path : None or str or pathlib obj, default=None: If None (or False), data is not trimmed in this function. Otherwise, this is the directory to save trimmed and exported data.
data_export_format : str='mseed': If data_export_path is not None, this is the format in which to save the data
detrend : str or bool, default='spline': If False, data is not detrended. Otherwise, this should be a string accepted by the type parameter of the obspy.core.trace.Trace.detrend method: https://docs.obspy.org/packages/autogen/obspy.core.trace.Trace.detrend.html
detrend_options : int, default=2: If detrend parameter is 'spline' or 'polynomial', this is passed directly to the order parameter of obspy.core.trace.Trace.detrend method.
filter_type : None, str: Type of filter to use on raw data. This should either be None or any of {'bandpass', 'bandstop', 'lowpass', 'highpass', 'lowpass_cheby_2', 'lowpass_fir', 'remez_fir'}. This passes filter_type to the type parameter and **filter_options to the **options parameter of the obspy.Stream filter() method. See here for more information: https://docs.obspy.org/packages/autogen/obspy.core.stream.Stream.filter.html If None, no filtering is done on the input seismic data.
filter_options : dict: Dictionary that will be unpacked into the **options parameter of the filter() method of the obspy.Stream class. This should fit the parameters of whichever filter type is specifed by filter_type. Example options for the 'bandpass' filter_type might be: filter_options={'freqmin': 0.1, 'freqmax':50, 'df':100, 'corners':4, 'zerophase':True}. See here for more information: https://docs.obspy.org/packages/autogen/obspy.core.stream.Stream.filter.html
update_metadata : bool, default=True: Whether to update the metadata file, used primarily with Raspberry Shake data which uses a generic inventory file.
plot_input_stream : bool, default=False: Whether to plot the raw input stream. This plot includes a spectrogram (Z component) and the raw (with decimation for speed) plots of each component signal.
plot_engine : str, default='matplotlib': Which plotting library/engine to use for plotting the Input stream. Options are 'matplotlib', 'plotly', or 'obspy' (not case sensitive).
verbose : bool, default=False: Whether to print outputs and inputs to the terminal
**kwargs: Keywords arguments, primarily for 'batch' and 'dir' sources

Returns

params : HVSRData or HVSRBatch object: Same as params parameter, but with an additional "stream" attribute with an obspy data stream with 3 traces: Z (vertical), N (North-south), and E (East-west)

def generate_psds(hvsr_data, window_length=30.0, overlap_pct=0.5, window_type='hann', window_length_method='length', remove_response=False, skip_on_gaps=True, num_freq_bins=512, obspy_ppsds=False, azimuthal_psds=False, verbose=False, plot_psds=False, **obspy_ppsd_kwargs)

Calculate Power Spectral Density (PSD) curves for each channel. Uses the scipy.signal.welch() function to generate PSDs by default, or can use Obspy's PPSD class. Info on Obspy PPSD creation here (if obspy_ppsds=True): https://docs.obspy.org/packages/autogen/obspy.signal.spectral_estimation.PPSD.html

Parameters

hvsr_data : dict, HVSRData object, or HVSRBatch object: Data object containing all the parameters and other data of interest (stream and paz, for example)
window_length : float: Length of the window, in seconds, to use for each PSD calculation. Defaults to 30.0.
overlap_pct : float: Percentage (should be 0-1) for overlapping each window used for PSD calculation. Defaults to 0.5.
window_type : str: Type of window to use. This is passed to the window parameter of the scipy.signal.welch function
window_length_method : str = {'length', 'number'}: Whether the window length should be a measure of length in seconds or number of windows. If number of windows uses integer value.
remove_response : bool, default=False: Whether to remove the instrument response from the data traces before calculating PSD data. If True, the appropriate metadata (i.e., obspy.Inventory object) must be attached to the stream and should be stored in the 'inv' attribute of hvsr_data.
skip_on_gaps : bool, default=True: Whether to skip data gaps when processing windows. This is passed to the skip_on_gaps parameter of the Obspy PPSD class.
num_freq_bins : int, default=512: Number of frequency bins to use. When using the default (i.e., scipy.signal.welch) PSD function, the frequency bins are created manually for processing.
obspy_ppsds : bool, default=False: Whether to use the Obspy PPSD class.
azimuthal_psds : bool, default=False: Whether to generate PPSDs for azimuthal data
verbose : bool, default=True: Whether to print inputs and results to terminal
plot_psds : bool, default=False: Whether to show a plot of the psds here.
**obspy_ppsd_kwargs : dict: Dictionary with keyword arguments that are passed directly to obspy.signal.PPSD. If the following keywords are not specified, their defaults are amended in this function from the obspy defaults for its PPSD function. Specifically: - ppsd_length defaults to 30 (seconds) here instead of 3600 - skip_on_gaps defaults to True instead of False - period_step_octaves defaults to 0.03125 instead of 0.125

Returns

ppsds : HVSRData object
    Dictionary containing entries with ppsds for each channel

Parameters

params : dict: Dictionary containing all the input and other parameters needed for processing Ouput from input_params() function
write_path : str: String with output filepath of where to write updated inventory or metadata file If not specified, does not write file
update_metadata : bool: Whether to update the metadata file itself, or just read as-is. If using provided raspberry shake metadata file, select True.
source : str, default=None: This passes the source variable value to _read_RS_metadata. It is expected that this is passed directly from the source parameter of sprit.fetch_data()

Returns

params : dict: Modified input dictionary with additional key:value pair containing paz dictionary (key = "paz")

def get_report(hvsr_results, report_formats=['print', 'table', 'plot', 'html', 'pdf'], azimuth='HV', plot_type='HVSR p ann COMP+ p ann SPEC p ann', plot_engine='matplotlib', show_print_report=True, show_table_report=False, show_plot_report=False, show_html_report=False, show_pdf_report=True, suppress_report_outputs=False, show_report_outputs=False, csv_handling='append', report_export_format=None, report_export_path=None, verbose=False, **kwargs)

Generate and/or print and/or export a report of the HVSR analysis in a variety of formats.

Formats include: * 'print': A (monospace) text summary of the HVSR results * 'table': A pandas.DataFrame summary of the HVSR Results. This is useful for copy/pasting directly into a larger worksheet. * 'plot': A plot summary of the HVSR results, generated using the plot_hvsr() function. * 'html': An HTML document/text of the HVSR results. This includes the table, print, and plot reports in one document. * 'pdf': A PDF document showing the summary of the HVSR Results. The PDF report is simply the HTML report saved to an A4-sized PDF document.

Parameters

hvsr_results : dict: Dictionary containing all the information about the processed hvsr data
report_formats : {'table', 'print', plot}: Format in which to print or export the report. The following report_formats return the following items in the following attributes: - 'plot': hvsr_results['Print_Report'] as a str - 'print': hvsr_results['HV_Plot'] - matplotlib.Figure object - 'table': hvsr_results['Table_Report']- pandas.DataFrame object - list/tuple - a list or tuple of the above objects, in the same order they are in the report_formats list - 'html': hvsr_results['HTML_Report'] - a string containing the text for an HTML document - 'pdf': currently does not save to the HVSRData object itself, can only be saved to the disk directly
plot_type : str, default = 'HVSR p ann C+ p ann Spec p ann': What type of plot to plot, if 'plot' part of report_formats input
azimuth : str, default = 'HV': Which azimuth to plot, by default "HV" which is the main "azimuth" combining the E and N components
csv_handling : str, {'append', 'overwrite', 'keep/rename'}: How to handle table report outputs if the designated csv output file already exists. By default, appends the new information to the end of the existing file.
suppress_report_outputs : bool, default=False: If True, only reads output to appropriate attribute of data class (ie, print does not print, only reads text into variable). If False, performs as normal.
report_export_format : list or str, default=['pdf']: A string or list of strings indicating which report formats should be exported to disk.
report_export_path : None, bool, or filepath, default = None: If None or False, does not export; if True, will export to same directory as the input_data parameter in the input_params() function. Otherwise, it should be a string or path object indicating where to export results. May be a file or directory. If a directory is specified, the filename will be "-". The extension/suffix defaults to png for report_formats="plot", csv for 'table', txt for 'print', html for 'html', and pdf for 'pdf.'
verbose : bool, default=True: Whether to print the results to terminal. This is the same output as report_formats='print', and will not repeat if that is already selected

Returns

HVSRData

def gui(kind: str = 'browser')

Function to open a graphical user interface (gui)

Parameters

kind : str, optional: What type of gui to open: * "browser" or "default" opens browser interface (using streamlit) * "widget" opens jupyter widget (using ipywidgets) * "window" opens windowed gui (using tkinter)

def import_data(import_filepath, data_format='pickle', show_data=False)

Function to import .hvsr (or other extension) data exported using export_hvsr() function

Parameters

import_filepath : str or path object: Filepath of file created using export_hvsr() function. This is usually a pickle file with a .hvsr extension
data_format : str, default='pickle': Type of format data is in. Currently, only 'pickle' supported. Eventually, json or other type may be supported, by default 'pickle'.

Returns

HVSRData or HVSRBatch object

def import_settings(settings_import_path, settings_import_type='instrument', verbose=False)

Function to import settings, intended for use with settings saved to disk using export_settings

Parameters

settings_import_path : pathlike object: Filepath to exported settings document
settings_import_type : str, optional: What type of settings to export (can be 'instrument' or 'all'), by default 'instrument'
verbose : bool, optional: Whether to print information to terminal, by default False

Returns

dict: A dictionary containing the function names as keys of internal dictionaries, with key:value pairs for each parameter name:value in that function.

def input_params(input_data, site='HVSRSite', project=None, network='AM', station='NONE', location='00', channels=['EHZ', 'EHN', 'EHE'], acq_date=None, starttime=None, endtime=None, tzone='UTC', xcoord=-88.229, ycoord=40.101, elevation=225, input_crs='EPSG:4326', output_crs=None, elev_unit='meters', depth=0, instrument='Seismometer', metapath=None, hvsr_band=[0.1, 50], peak_freq_range=[0.1, 50], processing_parameters={}, verbose=False)

Function for designating input parameters for reading in and processing data

Parameters

input_data : str or pathlib.Path object: Filepath of data. This can be a directory or file, but will need to match with what is chosen later as the source parameter in fetch_data()
site : str, default="HVSR Site": Site name as designated by user for ease of reference. Used for plotting titles, filenames, etc.
project : str, default=None: A prefix that may be used to create unique identifiers for each site. The identifier created is saved as the ['HVSR_ID'] attribute of the HVSRData object, and is equivalent to the following formatted string: f"{project}-{acq_date.strftime("%Y%m%d")}-{starttime.strftime("%H%M")}-{station}".
network : str, default='AM': The network designation of the seismometer. This is necessary for data from Raspberry Shakes. 'AM' is for Amateur network, which fits Raspberry Shakes.
station : str, default='RAC84': The station name of the seismometer. This is necessary for data from Raspberry Shakes.
location : str, default='00': Location information of the seismometer.
channels : list, default=['EHZ', 'EHN', 'EHE']: The three channels used in this analysis, as a list of strings. Preferred that Z component is first, but not necessary
acq_date : str, int, date object, or datetime object: If string, preferred format is 'YYYY-MM-DD'. If int, this will be interpreted as the time_int of year of current year (e.g., 33 would be Feb 2 of current year) If date or datetime object, this will be the date. Make sure to account for time change when converting to UTC (if UTC is the following time_int, use the UTC time_int).
starttime : str, time object, or datetime object, default='00:00:00.00': Start time of data stream. This is necessary for Raspberry Shake data in 'raw' form, or for trimming data. Format can be either 'HH:MM:SS.micros' or 'HH:MM' at minimum.
endtime : str, time obejct, or datetime object, default='23:59:99.99': End time of data stream. This is necessary for Raspberry Shake data in 'raw' form, or for trimming data. Same format as starttime.
tzone : str or int, default = 'UTC': Timezone of input data. If string, 'UTC' will use the time as input directly. Any other string value needs to be a TZ identifier in the IANA database, a wikipedia page of these is available here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. If int, should be the int value of the UTC offset (e.g., for American Eastern Standard Time: -5). This is necessary for Raspberry Shake data in 'raw' format.
xcoord : float, default=-88.2290526: Longitude (or easting, or, generally, X coordinate) of data point, in Coordinate Reference System (CRS) designated by input_crs. Currently only used in table output, but will likely be used in future for mapping/profile purposes.
ycoord : float, default=40.1012122: Latitute (or northing, or, generally, X coordinate) of data point, in Coordinate Reference System (CRS) designated by input_crs. Currently only used in table output, but will likely be used in future for mapping/profile purposes.
input_crs : str or other format read by pyproj, default='EPSG:4326': Coordinate reference system of input data, as used by pyproj.CRS.from_user_input()
output_crs : str or other format read by pyproj, default='EPSG:4326': Coordinate reference system to which input data will be transformed, as used by pyproj.CRS.from_user_input()
elevation : float, default=755: Surface elevation of data point. Not currently used (except in table output), but will likely be used in the future.
depth : float, default=0: Depth of seismometer. Not currently used, but will likely be used in the future.
instrument : str {'Raspberry Shake', "Tromino"}: Instrument from which the data was acquired.
metapath : str or pathlib.Path object, default=None: Filepath of metadata, in format supported by obspy.read_inventory. If default value of None, will read from resources folder of repository (only supported for Raspberry Shake).
hvsr_band : list, default=[0.1, 50]: Two-element list containing low and high "corner" frequencies (in Hz) for processing. This can specified again later.
peak_freq_range : list or tuple, default=[0.1, 50]: Two-element list or tuple containing low and high frequencies (in Hz) that are used to check for HVSR Peaks. This can be a tigher range than hvsr_band, but if larger, it will still only use the hvsr_band range.
processing_parameters={} : dict or filepath, default={}
If filepath, should point to a .proc json file with processing parameters (i.e, an output from sprit.export_settings()).
Note that this only applies to parameters for the functions: 'fetch_data', 'remove_noise', 'generate_psds', 'process_hvsr', 'check_peaks', and 'get_report.'
If dictionary, dictionary containing nested dictionaries of function names as they key, and the parameter names/values as key/value pairs for each key.
If a function name is not present, or if a parameter name is not present, default values will be used.
For example:
{ 'fetch_data' : {'source':'batch', 'data_export_path':"/path/to/trimmed/data", 'data_export_format':'mseed', 'detrend':'spline', 'plot_input_stream':True, 'verbose':False, kwargs:{'kwargskey':'kwargsvalue'}} }
verbose : bool, default=False: Whether to print output and results to terminal

Returns

params : HVSRData: sprit.HVSRData class containing input parameters, including data file path and metadata path. This will be used as an input to other functions. If batch processing, params will be converted to batch type in fetch_data() step.

def parse_plot_string(plot_string)

Function to parse a plot string into a list readable by plotting functions

Parameters

plot_string : str: Plot string used by sprit.plot_hvsr to define results plot

Returns

list: A list readable by various sprit plotting functions to show what to include in the results plot.

def plot_azimuth(hvsr_data, fig=None, ax=None, show_azimuth_peaks=False, interpolate_azimuths=True, show_azimuth_grid=False, show_plot=True, **plot_azimuth_kwargs)

Function to plot azimuths when azimuths are calculated

Parameters

hvsr_data : HVSRData or HVSRBatch: HVSRData that has gone through at least the sprit.fetch_data() step, and before sprit.generate_psds()
show_azimuth_peaks : bool, optional: Whether to display the peak value at each azimuth calculated on the chart, by default False
interpolate_azimuths : bool, optional: Whether to interpolate the azimuth data to get a smoother plot. This is just for visualization, does not change underlying data. It takes a lot of time to process the data, but interpolation for vizualization can happen fairly fast. By default True.
show_azimuth_grid : bool, optional: Whether to display the grid on the chart, by default False

Returns

matplotlib.Figure, matplotlib.Axis: Figure and axis of resulting azimuth plot

def plot_cross_section(hvsr_data, title=None, fig=None, ax=None, use_elevation=True, show_feet=False, primary_unit='m', show_curves=True, annotate_curves=False, curve_alignment='peak', grid_size='auto', orientation='WE', interpolation_type='cloughtocher', interpolate_log_values=True, surface_elevations=None, show_peak_points=True, smooth_bedrock_surface=False, depth_limit=150, minimum_elevation=None, show_bedrock_surface=True, return_data_batch=True, show_cross_section=True, verbose=False, **kwargs)

Functio to plot a cross section given an HVSRBatch or similar object

Parameters

hvsr_data : HVSRBatch, list, or similar: HVSRBatch (intended usage) object with HVSRData objects to show in profile/cross section view
title : str, optional: Title to use for plot, by default None
fig : matplotlib.Figure, optional: Figure to use for plot, by default None
ax : matplotlib.Axis, optional: Axis to use for plot, by default None
use_elevation : bool, optional: Whether to use elevation (if True) or depth (if False), by default True
show_feet : bool, optional: Whether to show feet (if True) or meters (if False), by default False
primary_unit : str, optional: Primary unit to use ('m' or 'ft'), by default 'm'
show_curves : bool, optional: Whether to also show curves on plot, by default True
annotate_curves : bool, optional: Whether to annotate curves by plotting site names next to them, by default False
curve_alignment : str, optional: How to horizontally align the curve. If "peak" the curve will be aligned so that the peak is at the correct latitude or longitude. If "max" will align the maximum point of the curve to the correct location. If any other value, will align at the surface (i.e., highest frequency). By default 'peak'.
grid_size : list, optional: Two item list with height and width of grid for interpolation. If "auto" this will be calculated based on the data, by default 'auto'.
orientation : str, optional: The orientation of the cross section. Should be either "WE", "EW", "NS", or "SN", by default 'WE'.
interpolation_type : str, optional: Interpolation type to use. Uses scipy.interpolation. Options include: 'cloughtocher', 'nearest neighbor', 'linear', or 'radial basis function', by default 'cloughtocher'.
interpolate_log_values : bool, optional: Whether to use log values of the H/V curve for interpolation (can be useful for better normalizing data)
surface_elevations : shapely.LineString, optional: A shapely.LineString object containing surface elevation coordinates along cross section path. If None, uses elevation data in HVSRBatch specified by hvsr_data, by default None.
show_peak_points : bool, optional: Whether to plot small triangles where peaks were picked, by default True
smooth_bedrock_surface : bool, optional: Whether to smooth the bedrock surface when plotting, by default False
depth_limit : int, optional: Depth limit for the plot, by default 150
minimum_elevation : _type_, optional: Minimum elevation of the plot, by default None
show_bedrock_surface : bool, optional: Whether to show the bedrock surface, by default True
return_data_batch : bool, optional: Whether to return the HVSRBatch object, by default True
show_cross_section : bool, optional: Whether to show the cross section plot, by default True
verbose : bool, optional: Whether to print information about the process to terminal, by default False

Returns

figure: Currently only matplotlib figure supported

def plot_depth_curve(hvsr_results, use_elevation=True, show_feet=False, normalize_curve=True, depth_limit=250, max_elev=None, min_elev=None, annotate=True, depth_plot_export_path=None, fig=None, ax=None, show_depth_curve=True)

def plot_hvsr(hvsr_data, plot_type='HVSR p ann COMP+ p ann SPEC p ann', azimuth='HV', use_subplots=True, fig=None, ax=None, return_fig=False, plot_engine='matplotlib', save_dir=None, save_suffix='', show_legend=False, show_plot=True, close_figs=False, clear_fig=True, **kwargs)

Function to plot HVSR data

Parameters

hvsr_data : dict: Dictionary containing output from process_hvsr function
plot_type : str or list, default = 'HVSR ann p C+ ann p SPEC ann p': The plot_type of plot(s) to plot. If list, will plot all plots listed - 'HVSR' - Standard HVSR plot, including standard deviation. Options are included below: - 'p' shows a vertical dotted line at frequency of the "best" peak - 'ann' annotates the frequency value of of the "best" peak - 'all' shows all the peaks identified in check_peaks() (by default, only the max is identified) - 't' shows the H/V curve for all time windows - 'tp' shows all the peaks from the H/V curves of all the time windows - 'fr' shows the window within which SpRIT will search for peak frequencies, as set by peak_freq_range - 'test' shows a visualization of the results of the peak validity test(s). Examples: - 'tests' visualizes the results of all the peak tests (not the curve tests) - 'test12' shows the results of tests 1 and 2. - Append any number 1-6 after 'test' to show a specific test result visualized - 'COMP' - plot of the PPSD curves for each individual component ("C" also works) - '+' (as a suffix in 'C+' or 'COMP+') plots C on a plot separate from HVSR (C+ is default, but without + will plot on the same plot as HVSR) - 'p' shows a vertical dotted line at frequency of the "best" peak - 'ann' annotates the frequency value of of the "best" peak - 'all' shows all the peaks identified in check_peaks() (by default, only the max is identified) - 't' shows the H/V curve for all time windows - 'SPEC' - spectrogram style plot of the H/V curve over time - 'p' shows a horizontal dotted line at the frequency of the "best" peak - 'ann' annotates the frequency value of the "best" peak - 'all' shows all the peaks identified in check_peaks() - 'tp' shows all the peaks of the H/V curve at all time windows - 'AZ' - circular plot of calculated azimuthal HV curves, similar in style to SPEC plot. - 'p' shows a point at each calculated (not interpolated) azimuth peak - 'g' shows grid lines at various angles - 'i' interpolates so that there is an interpolated azimuth at each degree interval (1 degree step) This is the default, so usually 'i' is not needed. - '-i' prohibits interpolation (only shows the calculated azimuths, as determined by azimuth_angle (default = 30))
azimuth : str, default = 'HV': What 'azimuth' to plot, default being standard N E components combined
use_subplots : bool, default = True: Whether to output the plots as subplots (True) or as separate plots (False)
fig : matplotlib.Figure, default = None: If not None, matplotlib figure on which plot is plotted
ax : matplotlib.Axis, default = None: If not None, matplotlib axis on which plot is plotted
return_fig : bool: Whether to return figure and axis objects
plot_engine : str, default='Matplotlib': Which engine to use for plotting. Both "matplotlib" and "plotly" are acceptable. For shorthand, 'mpl', 'm' also work for matplotlib; 'plty' or 'p' also work for plotly. Not case sensitive.
save_dir : str or None: Directory in which to save figures
save_suffix : str: Suffix to add to end of figure filename(s), if save_dir is used
show_legend : bool, default=False: Whether to show legend in plot
show_plot : bool: Whether to show plot
close_figs : bool, default=False: Whether to close figures before plotting
clear_fig : bool, default=True: Whether to clear figures before plotting
**kwargs : keyword arguments: Keyword arguments for matplotlib.pyplot

Returns

fig, ax : matplotlib figure and axis objects: Returns figure and axis matplotlib.pyplot objects if return_fig=True, otherwise, simply plots the figures

def plot_input_stream(hv_data, stream=None, input_fig=None, plot_engine='plotly', spectrogram_component='Z', decimate=True, show_plot=True, return_fig=False, **kwargs)

Function to plot input stream using plotly.

Parameters

hv_data : HVSRData
stream : obspy.stream.Stream: Can explictly specify stream instead of using hv_data object.
input_fig : plotly.Figure: Plotly figure to plot input stream on. If None, creates new one. Default is None.
spectrogram_component : str, default='Z': Which component to use for the spectrogram
show_plot : bool, default=True: Whether to show plot or just generate it.
return_fig : bool, default=False: Whether to return figure

Returns

plotly figure: Only returned if return_fig is True

def plot_outlier_curves(hvsr_data, plot_engine='plotly', plotly_module='go', remove_outliers_during_plot=False, rmse_thresh=0.98, use_percentile=True, use_hv_curve=False, from_roc=False, show_plot=True, verbose=False, discarded_curves=None)

Functio to plot outlier curves, including which have been excluded

Parameters

hvsr_data : HVSRData: Input data object
plot_engine : str = {'plotly', 'matplotlib'}: Which plotting library to use, by default 'plotly'
plotly_module : str = {'go', 'px'}: Which plotly module to use if applicable, by default 'go'
remove_outliers_during_plot : bool, optional: Whether curves should also be removed when plotted. During sprit.run(), removal happens separately, so this is False.
rmse_thresh : float, optional: RMSE threshold (for removing outliers), by default 0.98
use_percentile : bool, optional: Whether to use percentile or raw value, by default True
use_hv_curve : bool, optional: Whether to perform analysis on HV curves (if True) or PSD curves (if False), by default False
from_roc : bool, optional: Helper parameter to determine if this is being called from sprit.remove_outlier_curves function, by default False
show_plot : bool, optional: Whether to show plot, by default True
verbose : bool, optional: Whether to print information to terminal, by default False

Returns

plotly figure: Figure type depends on plotly_module

def plot_results(hv_data, plot_string='HVSR p ann C+ p SPEC ann', azimuth='HV', results_fig=None, results_graph_widget=None, use_figure_widget=False, return_fig=False, show_results_plot=False, html_plot=False, verbose=False)

Function to plot results using plotly

Parameters

hv_data : HVSRData: Data object to use for plotting
plot_string : str, optional: String for designating what to include in plot(s), by default 'HVSR p ann C+ p SPEC ann'
results_fig : pyplot figure, optional: Which pyplot figure to plot data onto. If None, makes new figure, by default None.
results_graph_widget : plotly graph object widget, optional: Which pyplot figure to plot data onto. If None, makes new widget, if applicable, by default None.
use_figure_widget : bool, optional: Whether to use figure widget, by default False
return_fig : bool, optional: Whether to return figure, by default False
show_results_plot : bool, optional: Wheather to show plot, by default False
html_plot : bool, optional: Whether to create an HTML version of the plot, by default False
verbose : bool, optional: Whether to print information to terminal, by default False

Returns

plotly figure: Only if return_fig is True.

def process_hvsr(hvsr_data, horizontal_method=None, smooth=True, freq_smooth='konno ohmachi', f_smooth_width=40, resample=True, outlier_curve_rmse_percentile=False, azimuth=None, verbose=False)

Process the input data and get HVSR data

This is the main function that uses other (private) functions to do the bulk of processing of the HVSR data and the data quality checks.

Parameters

hvsr_data : HVSRData or HVSRBatch

Data object containing all the parameters input and generated by the user (usually, during sprit.input_params(), sprit.fetch_data(), sprit.generate_psds() and/or sprit.remove_noise()).

horizontal_method : int or str, default=3

Method to use for combining the horizontal components. Default is 3) Geometric Mean

0) (not used)

1) 'Diffuse field assumption' H = √( (eie_E + eie_N) / eie_Z), eie = equal interval energy

2) 'Arithmetic Mean' H ≡ (HN + HE)/2

3) 'Geometric Mean' H ≡ √(HN · HE), recommended by the SESAME project (2004)

4) 'Vector Summation' H ≡ √(HN^2 + HE^2)

5) 'Quadratic Mean' H ≡ √(HN^2 + HE^2)/2

6) 'Maximum Horizontal Value' H ≡ max

7) 'Minimum Horizontal Valey' H ≡ min

8) 'Single Azimuth' H = H2·cos(az) + H1·sin(az)

smooth : bool, default=True

bool or int may be used.

If True, default to smooth H/V curve to using savgoy filter with window length of 51 (works well with default resample of 1000 pts)

If int, the length of the window in the savgoy filter.

freq_smooth : str {'konno ohmachi', 'constant', 'proportional'}

Which frequency smoothing method to use. By default, uses the 'konno ohmachi' method. - The Konno & Ohmachi method uses the obspy.signal.konnoohmachismoothing.konno_ohmachi_smoothing() function: https://docs.obspy.org/packages/autogen/obspy.signal.konnoohmachismoothing.konno_ohmachi_smoothing.html - The constant method uses a window of constant length f_smooth_width - The proportional method uses a window the percentage length of the frequncy steps/range (f_smooth_width now refers to percentage) See here for more information: https://www.geopsy.org/documentation/geopsy/hv-processing.html

f_smooth_width : int, default = 40

For 'konno ohmachi': passed directly to the bandwidth parameter of the konno_ohmachi_smoothing() function, determines the width of the smoothing peak, with lower values resulting in broader peak. Must be > 0.
For 'constant': the size of a triangular smoothing window in the number of frequency steps
For 'proportional': the size of a triangular smoothing window in percentage of the number of frequency steps (e.g., if 1000 frequency steps/bins and f_smooth_width=40, window would be 400 steps wide)

resample : bool, default = True

bool or int.

If True, default to resample H/V data to include 1000 frequency values for the rest of the analysis

If int, the number of data points to interpolate/resample/smooth the component psd/HV curve data to.

outlier_curve_rmse_percentile : bool, float, default = False

If False, outlier curve removal is not carried out here. If True, defaults to 98 (98th percentile). Otherwise, float of percentile used as rmse_thresh of remove_outlier_curve().

azimuth : float, default = None

The azimuth angle to use when method is single azimuth.

verbose : bool, defualt=False

Whether to print output to terminal

Returns

hvsr_out    : dict
    Dictionary containing all the information about the data, including input parameters

def read_tromino_files(input_data, struct_format='H', tromino_model=None, sampling_rate=None, set_record_duration=None, start_byte=24576, verbose=False, **kwargs)

Function to read data from tromino. Specifically, this has been lightly tested on Tromino 3G+ and Blue machines

Parameters

input_data : str: Falseilepath to .trc file
struct_format : str, optional: This is the format used in the struct module. Usually should not be changed, by default 'H'
tromino_model : str, optional: Which tromino model is being read. Currently only "Yellow" and "Blue" are supported. If None, assumes "Yellow", by default None.
sampling_rate : int, optional: Sampling rate (samples per second) used during acquisition. This may later be detected automatically. If None, 128 used, by default None
set_record_duration : int, optional: Duration of record to set manually in minutes, by default None
start_byte : int, optional: Used internally, by default 24576
verbose : bool, optional: Whether to print information to terminal, by default False

Returns

obspy.stream.Stream: Obspy Stream object with Tromino data

def remove_noise(hvsr_data, remove_method=None, processing_window=None, sat_percent=0.995, noise_percent=0.8, sta=2, lta=30, stalta_thresh=[8, 16], std_ratio_thresh=2.0, std_window_size=20.0, min_std_win=5.0, warmup_time=0, cooldown_time=0, min_win_size=1, remove_raw_noise=False, show_stalta_plot=False, verbose=False)

Function to remove noisy windows from data, using various methods.

Methods include - Manual window selection (by clicking on a chart with spectrogram and stream data), - Auto window selection, which does the following two in sequence (these can also be done indepently): - A sta/lta "antitrigger" method (using stalta values to automatically remove triggered windows where there appears to be too much noise) - A noise threshold method, that cuts off all times where the noise threshold equals more than (by default) 80% of the highest amplitude noise sample for the length specified by lta (in seconds) - A saturation threshold method, that cuts off all times where the noise threshold equals more than (by default) 99.5% of the highest amplitude noise sample.

Parameters

hvsr_data : dict, obspy.Stream, or obspy.Trace: Dictionary containing all the data and parameters for the HVSR analysis
remove_method : str, {'auto', 'manual', 'stalta'/'antitrigger', 'saturation threshold', 'noise threshold', 'warmup'/'cooldown'/'buffer'/'warm_cool'}: The different methods for removing noise from the dataset. A list of strings will also work, in which case, it should be a list of the above strings. See descriptions above for what how each method works. By default 'auto.' If remove_method='auto', this is the equivalent of remove_method=['noise threshold', 'antitrigger', 'saturation threshold', 'warm_cool']
processing_window : list, tuple, or None: A list/tuple of two items [s, e] or a list/tuple of two-item lists/tuples [[s0, e0], [s1,e1],…[sn, en]] with start and end time(s) for windows to keep for processing. Data outside of these times will be excluded from processing. Times should be obspy.UTCDateTime objects to ensure precision, but time strings ("13:05") will also work in most cases (excpetions may be when the data stream starts/ends on different UTC days)
sat_percent : float, default=0.995: Percentage (between 0 and 1), to use as the threshold at which to remove data. This is used in the saturation method. By default 0.995. If a value is passed that is greater than 1, it will be divided by 100 to obtain the percentage.
noise_percent : float, default = 0.8: Percentage (between 0 and 1), to use as the threshold at which to remove data, if it persists for longer than time (in seconds (specified by min_win_size)). This is used in the noise threshold method. By default 0.8. If a value is passed that is greater than 1, it will be divided by 100 to obtain the percentage.
sta : int, optional: Short term average (STA) window (in seconds), by default 2. For use with sta/lta antitrigger method.
lta : int, optional: Long term average (STA) window (in seconds), by default 30. For use with sta/lta antitrigger method.
stalta_thresh : list, default=[0.5,5]: Two-item list or tuple with the thresholds for the stalta antitrigger. The first value (index [0]) is the lower threshold, the second value (index [1] is the upper threshold), by default [0.5,5]
std_ratio_thresh : float, optional: The ratio to use as a threshold for removal of noise. The ratio represents the standard deviation value for a rolling window (the size of which is determined by the std_window_size parameter) divided by the standard deviation calculated for the entire trace. This rolling window standard deviation method is similar to the default noise removal method used by the Grilla HVSR software.
std_window_size : float, optional: The length of the window (in seconds) to use for calculating the rolling/moving standard deviation of a trace for the rolling standard deviation method.
min_std_win : float, optional: The minimum size of "window" that will be remove using the rolling standard deviation method.
warmup_time : int, default=0: Time in seconds to allow for warmup of the instrument (or while operator is still near instrument). This will renove any data before this time, by default 0.
cooldown_time : int, default=0: Time in seconds to allow for cooldown of the instrument (or for when operator is nearing instrument). This will renove any data before this time, by default 0.
min_win_size : float, default=1: The minumum size a window must be over specified threshold (in seconds) for it to be removed
remove_raw_noise : bool, default=False: If remove_raw_noise=True, will perform operation on raw data ('input_stream'), rather than potentially already-modified data ('stream').
verbose : bool, default=False: Whether to print status of remove_noise

Returns

output : dict: Dictionary similar to hvsr_data, but containing modified data with 'noise' removed

def remove_outlier_curves(hvsr_data, rmse_thresh=98, use_percentile=True, use_hv_curve=False, plot_engine='matplotlib', show_outlier_plot=False, generate_outlier_plot=True, verbose=False, **kwargs)

Function used to remove outliers curves using Root Mean Square Error to calculate the error of each windowed Probabilistic Power Spectral Density (PPSD) curve against the median PPSD value at each frequency step for all times. It calculates the RMSE for the PPSD curves of each component individually. All curves are removed from analysis.

Some abberant curves often occur due to the remove_noise() function, so this should be run some time after remove_noise(). In general, the recommended workflow is to run this immediately following the generate_psds() function.

Parameters

hvsr_data : dict: Input dictionary containing all the values and parameters of interest
rmse_thresh : float or int, default=98: The Root Mean Square Error value to use as a threshold for determining whether a curve is an outlier. This averages over each individual entire curve so that curves with very abberant data (often occurs when using the remove_noise() method), can be identified. Otherwise, specify a float or integer to use as the cutoff RMSE value (all curves with RMSE above will be removed)
use_percentile : float, default=True: Whether rmse_thresh should be interepreted as a raw RMSE value or as a percentile of the RMSE values.
use_hv_curve : bool, default=False: Whether to use the calculated HV Curve or the individual components. This can only be True after process_hvsr() has been run.
show_plot : bool, default=False: Whether to show a plot of the removed data
verbose : bool, default=False: Whether to print output of function to terminal

Returns

hvsr_data : dict: Input dictionary with values modified based on work of function.

def run(input_data=None, source='file', azimuth_calculation=False, noise_removal=False, outlier_curves_removal=False, verbose=False, **kwargs)

The sprit.run() is the main function that allows you to do all your HVSR processing in one simple step (sprit.run() is how you would call it in your code, but it may also be called using sprit.sprit_hvsr.run())

The input_data parameter of sprit.run() is the only required parameter (if nothing entered, it will run sample data). This can be either a single file, a list of files (one for each component, for example), a directory (in which case, all obspy-readable files will be added to an HVSRBatch instance), a Rasp. Shake raw data directory, or sample data.

Notes

The sprit.run() function calls the following functions. This is the recommended order/set of functions to run to process HVSR using SpRIT. See the API documentation for these functions for more information: - input_params(): The input_data parameter of input_params() is the only required variable, though others may also need to be called for your data to process correctly. - fetch_data(): the source parameter of fetch_data() is the only explicit variable in the sprit.run() function aside from input_data and verbose. Everything else gets delivered to the correct function via the kwargs dictionary - remove_noise(): by default, the kind of noise removal is remove_method='auto'. See the remove_noise() documentation for more information. If remove_method is set to anything other than one of the explicit options in remove_noise, noise removal will not be carried out. - calculate_azimuth(): calculate one or several azimuths. Single azimuth can be a way to combine H components too. - generate_psds(): generates ppsds for each component, which will be combined/used later. Any parameter of obspy.signal.spectral_estimation.PPSD() may also be read into this function. - remove_outlier_curves(): removes any outlier ppsd curves so that the data quality for when curves are combined will be enhanced. See the remove_outlier_curves() documentation for more information. - process_hvsr(): this is the main function processing the hvsr curve and statistics. See process_hvsr() documentation for more details. The hvsr_band parameter sets the frequency spectrum over which these calculations occur. - check_peaks(): this is the main function that will find and 'score' peaks to get a best peak. The parameter peak_freq_range can be set to limit the frequencies within which peaks are checked and scored. - get_report(): this is the main function that will print, plot, and/or save the results of the data. See the get_report() API documentation for more information. - export_hvsr(): this function exports the final data output as a pickle file (by default, this pickle object has a .hvsr extension). This can be used to read data back into SpRIT without having to reprocess data.

Parameters

input_data : str or filepath object that can be read by obspy: Filepath to data to be processed. This may be a file or directory, depending on what kind of data is being processed (this can be specified with the source parameter). For sample data, The following can be specified as the input_data parameter: - Any integer 1-6 (inclusive), or the string (e.g., input_data="1" or input_data=1 will work) - The word "sample" before any integer (e.g., input_data="sample1") - The word "sample" will default to "sample1" if source='file'. - If source='batch', input_data should be input_data='sample' or input_data='batch'. In this case, it will read and process all the sample files using the HVSRBatch class. Set verbose=True to see all the information in the sample batch csv file.
source : str, optional: description, by default 'file'
azimuth_calculation : bool, optional: Whether to perform azimuthal analysis, by default False.
noise_removal : bool, default=False: Whether to remove noise (before processing PPSDs)
outlier_curves_removal : bool, default=False: Whether to remove outlier curves from HVSR time windows
show_plot : bool, default=True: Whether to show plots. This does not affect whether the plots are created (and then inserted as an attribute of HVSRData), only whether they are shown.
verbose : bool, optional: description, by default False
**kwargs: Keyword arguments for the functions listed above. The keyword arguments are unique, so they will get parsed out and passed into the appropriate function.
input_params : function name (not an actual parameter): Function for designating input parameters for reading in and processing data See API documentation: input_params()
input_data : any, default = '<no default>': See API documentation at link above or at help(input_params()) for specifics.
site : any, default = 'HVSRSite': See API documentation at link above or at help(input_params()) for specifics.
project : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
network : any, default = 'AM': See API documentation at link above or at help(input_params()) for specifics.
station : any, default = 'NONE': See API documentation at link above or at help(input_params()) for specifics.
location : any, default = '00': See API documentation at link above or at help(input_params()) for specifics.
channels : any, default = ['EHZ', 'EHN', 'EHE']: See API documentation at link above or at help(input_params()) for specifics.
acq_date : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
starttime : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
endtime : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
tzone : any, default = 'UTC': See API documentation at link above or at help(input_params()) for specifics.
xcoord : any, default = -88.229: See API documentation at link above or at help(input_params()) for specifics.
ycoord : any, default = 40.101: See API documentation at link above or at help(input_params()) for specifics.
elevation : any, default = 225: See API documentation at link above or at help(input_params()) for specifics.
input_crs : any, default = 'EPSG:4326': See API documentation at link above or at help(input_params()) for specifics.
output_crs : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
elev_unit : any, default = 'meters': See API documentation at link above or at help(input_params()) for specifics.
depth : any, default = 0: See API documentation at link above or at help(input_params()) for specifics.
instrument : any, default = 'Seismometer': See API documentation at link above or at help(input_params()) for specifics.
metapath : any, default = None: See API documentation at link above or at help(input_params()) for specifics.
hvsr_band : any, default = [0.1, 50]: See API documentation at link above or at help(input_params()) for specifics.
peak_freq_range : any, default = [0.1, 50]: See API documentation at link above or at help(input_params()) for specifics.
processing_parameters : any, default = {}: See API documentation at link above or at help(input_params()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(input_params()) for specifics.
fetch_data : function name (not an actual parameter): Fetch ambient seismic data from a source to read into obspy stream. See API documentation: fetch_data()
params : any, default = '<output of previous function>': See API documentation at link above or at help(fetch_data()) for specifics.
source : any, default = 'file': See API documentation at link above or at help(fetch_data()) for specifics.
data_export_path : any, default = None: See API documentation at link above or at help(fetch_data()) for specifics.
data_export_format : any, default = 'mseed': See API documentation at link above or at help(fetch_data()) for specifics.
detrend : any, default = 'spline': See API documentation at link above or at help(fetch_data()) for specifics.
detrend_options : any, default = 2: See API documentation at link above or at help(fetch_data()) for specifics.
filter_type : any, default = None: See API documentation at link above or at help(fetch_data()) for specifics.
filter_options : any, default = {}: See API documentation at link above or at help(fetch_data()) for specifics.
update_metadata : any, default = True: See API documentation at link above or at help(fetch_data()) for specifics.
plot_input_stream : any, default = False: See API documentation at link above or at help(fetch_data()) for specifics.
plot_engine : any, default = 'matplotlib': See API documentation at link above or at help(fetch_data()) for specifics.
show_plot : any, default = True: See API documentation at link above or at help(fetch_data()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(fetch_data()) for specifics.
kwargs : any, default = {}: See API documentation at link above or at help(fetch_data()) for specifics.
calculate_azimuth : function name (not an actual parameter): Function to calculate azimuthal horizontal component at specified angle(s). See API documentation: calculate_azimuth()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(calculate_azimuth()) for specifics.
azimuth_angle : any, default = 45: See API documentation at link above or at help(calculate_azimuth()) for specifics.
azimuth_type : any, default = 'multiple': See API documentation at link above or at help(calculate_azimuth()) for specifics.
azimuth_unit : any, default = 'degrees': See API documentation at link above or at help(calculate_azimuth()) for specifics.
show_az_plot : any, default = False: See API documentation at link above or at help(calculate_azimuth()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(calculate_azimuth()) for specifics.
plot_azimuth_kwargs : any, default = {}: See API documentation at link above or at help(calculate_azimuth()) for specifics.
remove_noise : function name (not an actual parameter): Function to remove noisy windows from data, using various methods. See API documentation: remove_noise()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(remove_noise()) for specifics.
remove_method : any, default = None: See API documentation at link above or at help(remove_noise()) for specifics.
processing_window : any, default = None: See API documentation at link above or at help(remove_noise()) for specifics.
sat_percent : any, default = 0.995: See API documentation at link above or at help(remove_noise()) for specifics.
noise_percent : any, default = 0.8: See API documentation at link above or at help(remove_noise()) for specifics.
sta : any, default = 2: See API documentation at link above or at help(remove_noise()) for specifics.
lta : any, default = 30: See API documentation at link above or at help(remove_noise()) for specifics.
stalta_thresh : any, default = [8, 16]: See API documentation at link above or at help(remove_noise()) for specifics.
std_ratio_thresh : any, default = 2.0: See API documentation at link above or at help(remove_noise()) for specifics.
std_window_size : any, default = 20.0: See API documentation at link above or at help(remove_noise()) for specifics.
min_std_win : any, default = 5.0: See API documentation at link above or at help(remove_noise()) for specifics.
warmup_time : any, default = 0: See API documentation at link above or at help(remove_noise()) for specifics.
cooldown_time : any, default = 0: See API documentation at link above or at help(remove_noise()) for specifics.
min_win_size : any, default = 1: See API documentation at link above or at help(remove_noise()) for specifics.
remove_raw_noise : any, default = False: See API documentation at link above or at help(remove_noise()) for specifics.
show_stalta_plot : any, default = False: See API documentation at link above or at help(remove_noise()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(remove_noise()) for specifics.
generate_psds : function name (not an actual parameter): Calculate Power Spectral Density (PSD) curves for each channel. See API documentation: generate_psds()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(generate_psds()) for specifics.
window_length : any, default = 30.0: See API documentation at link above or at help(generate_psds()) for specifics.
overlap_pct : any, default = 0.5: See API documentation at link above or at help(generate_psds()) for specifics.
window_type : any, default = 'hann': See API documentation at link above or at help(generate_psds()) for specifics.
window_length_method : any, default = 'length': See API documentation at link above or at help(generate_psds()) for specifics.
remove_response : any, default = False: See API documentation at link above or at help(generate_psds()) for specifics.
skip_on_gaps : any, default = True: See API documentation at link above or at help(generate_psds()) for specifics.
num_freq_bins : any, default = 512: See API documentation at link above or at help(generate_psds()) for specifics.
obspy_ppsds : any, default = False: See API documentation at link above or at help(generate_psds()) for specifics.
azimuthal_psds : any, default = False: See API documentation at link above or at help(generate_psds()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(generate_psds()) for specifics.
plot_psds : any, default = False: See API documentation at link above or at help(generate_psds()) for specifics.
obspy_ppsd_kwargs : any, default = {}: See API documentation at link above or at help(generate_psds()) for specifics.
process_hvsr : function name (not an actual parameter): Process the input data and get HVSR data See API documentation: process_hvsr()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(process_hvsr()) for specifics.
horizontal_method : any, default = None: See API documentation at link above or at help(process_hvsr()) for specifics.
smooth : any, default = True: See API documentation at link above or at help(process_hvsr()) for specifics.
freq_smooth : any, default = 'konno ohmachi': See API documentation at link above or at help(process_hvsr()) for specifics.
f_smooth_width : any, default = 40: See API documentation at link above or at help(process_hvsr()) for specifics.
resample : any, default = True: See API documentation at link above or at help(process_hvsr()) for specifics.
outlier_curve_rmse_percentile : any, default = False: See API documentation at link above or at help(process_hvsr()) for specifics.
azimuth : any, default = None: See API documentation at link above or at help(process_hvsr()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(process_hvsr()) for specifics.
remove_outlier_curves : function name (not an actual parameter): Function used to remove outliers curves using Root Mean Square Error to calculate the error of each See API documentation: remove_outlier_curves()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(remove_outlier_curves()) for specifics.
rmse_thresh : any, default = 98: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
use_percentile : any, default = True: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
use_hv_curve : any, default = False: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
plot_engine : any, default = 'matplotlib': See API documentation at link above or at help(remove_outlier_curves()) for specifics.
show_outlier_plot : any, default = False: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
generate_outlier_plot : any, default = True: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
kwargs : any, default = {}: See API documentation at link above or at help(remove_outlier_curves()) for specifics.
check_peaks : function name (not an actual parameter): Function to run tests on HVSR peaks to find best one and see if it passes SESAME quality checks See API documentation: check_peaks()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(check_peaks()) for specifics.
hvsr_band : any, default = [0.1, 50]: See API documentation at link above or at help(check_peaks()) for specifics.
peak_selection : any, default = 'max': See API documentation at link above or at help(check_peaks()) for specifics.
peak_freq_range : any, default = [0.1, 50]: See API documentation at link above or at help(check_peaks()) for specifics.
azimuth : any, default = 'HV': See API documentation at link above or at help(check_peaks()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(check_peaks()) for specifics.
get_report : function name (not an actual parameter): Generate and/or print and/or export a report of the HVSR analysis in a variety of formats. See API documentation: get_report()
hvsr_results : any, default = '<output of previous function>': See API documentation at link above or at help(get_report()) for specifics.
report_formats : any, default = ['print', 'table', 'plot', 'html', 'pdf']: See API documentation at link above or at help(get_report()) for specifics.
azimuth : any, default = 'HV': See API documentation at link above or at help(get_report()) for specifics.
plot_type : any, default = 'HVSR p ann COMP+ p ann SPEC p ann': See API documentation at link above or at help(get_report()) for specifics.
plot_engine : any, default = 'matplotlib': See API documentation at link above or at help(get_report()) for specifics.
show_print_report : any, default = True: See API documentation at link above or at help(get_report()) for specifics.
show_table_report : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
show_plot_report : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
show_html_report : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
show_pdf_report : any, default = True: See API documentation at link above or at help(get_report()) for specifics.
suppress_report_outputs : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
show_report_outputs : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
csv_handling : any, default = 'append': See API documentation at link above or at help(get_report()) for specifics.
report_export_format : any, default = None: See API documentation at link above or at help(get_report()) for specifics.
report_export_path : any, default = None: See API documentation at link above or at help(get_report()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(get_report()) for specifics.
kwargs : any, default = {}: See API documentation at link above or at help(get_report()) for specifics.
export_hvsr : function name (not an actual parameter): Export data into pickle format that can be read back in using import_data(). See API documentation: export_hvsr()
hvsr_data : any, default = '<output of previous function>': See API documentation at link above or at help(export_hvsr()) for specifics.
hvsr_export_path : any, default = None: See API documentation at link above or at help(export_hvsr()) for specifics.
ext : any, default = 'hvsr': See API documentation at link above or at help(export_hvsr()) for specifics.
verbose : any, default = False: See API documentation at link above or at help(export_hvsr()) for specifics.

Returns

hvsr_results : HVSRData or HVSRBatch object: If a single file/data point is being processed, a HVSRData object will be returned. Otherwise, it will be a HVSRBatch object. See their documention for more information.

Classes

class HVSRBatch (*args, **kwargs)

HVSRBatch is the data container used for batch processing. It contains several HVSRData objects (one for each site). These can be accessed using their site name, either square brackets (HVSRBatchVariable["SiteName"]) or the dot (HVSRBatchVariable.SiteName) accessor.

The dot accessor may not work if there is a space in the site name.

All of the functions in the sprit package are designed to perform the bulk of their operations iteratively on the individual HVSRData objects contained in the HVSRBatch object, and do little with the HVSRBatch object itself, besides using it determine which sites are contained within it.

Expand source code

class HVSRBatch:
    """HVSRBatch is the data container used for batch processing. 
    It contains several HVSRData objects (one for each site). 
    These can be accessed using their site name, 
    either square brackets (HVSRBatchVariable["SiteName"]) or the dot (HVSRBatchVariable.SiteName) accessor.
    
    The dot accessor may not work if there is a space in the site name.
    
    All of the  functions in the sprit package are designed to perform the bulk of their operations iteratively
    on the individual HVSRData objects contained in the HVSRBatch object, and do little with the HVSRBatch object itself, 
    besides using it determine which sites are contained within it.
    
    """
    @check_instance
    def __init__(self, batch_input, batch_ext=None, batch_use=None, df_as_read=None):
        """HVSR Batch initializer

        Parameters
        ----------
        batch_input : dict, list, tuple, HVSRData, or filepath(s)
            If:

            * dict, dictionary containing Key value pairs with {sitename: HVSRData object}.
            * list or tuple, assumed to be dicts, HVSRData objects, or filepaths to processed .hvsr files or seismic data to be processed.
            * HVSRData object, will transform into HVSRBatch object with single HVSRData object. The add() or append() methods, or using square brackes can be used to add additional sites.
            * filepaths, if:
                * If directory, will use `batch_ext` as the input to a `glob()` function to get all files in that directory and add them to batch. Defaults to '.hvsr' files if `batch_ext` not specified.
                * Filepath, will make a HVSRBatch object importing that single file, or if readable by pandas.read_csv() will use in conjunction with `batch_use` (see below)
        batch_ext : str or None
            Filepath extension to use in `glob()` function for filetypes to import, if batch_input is a filepath.
        batch_use : {dict, list, tuple, None}
            Intended to be used as dict with keys "site", "filepath", and "batch". 
            In this case, should be {'site':"name_of_df_col_with_sitenames", 'filepath':"name_of_df_col_with_filepaths_to_data", 'batch':values_to_include}.
            values_to_include can be a value (or list of values) in a column called "batch" to specify that that row should be included in the HVSRBatch object or
            a dictionary where they keys are column names and the values are the values to look for in each column name for inclusion in HVSRBatch object.
            If not specified, defaults to None and uses all rows in dataframe.

        df_as_read : {None, pd.DataFrame}
            Used in various sprit functions to allow original DataFrame used to create HVSRBatch object to be carried through.        
        """

        # Just return it as-is if it's already Batch object
        if isinstance(batch_input, HVSRBatch):
            return batch_input
        
        self._batch_input = batch_input
        self.batch_input = self._batch_input
        
        self._batch_dict = self.batch_dict = {}

        self._input_df = df_as_read
        self.input_df = self._input_df
        
        self.batch = True
        
        if isinstance(batch_input, (list, tuple,)):
            # This is for a list/tuple with the following structure:
            # batch_input = [HVSRData, HVSRData, HVSRData]
            # or batch_input = ['/file/path1.hvsr', '/file/path2.hvsr']
            # Can also be mixed: [HVSRData, '/file/path3/.hvsr']
            siteNo = 0
            zfilldigs = len(str(len(batch_input)))
            
            for hvdata in batch_input:
                if isinstance(hvdata, (dict, HVSRData)):
                    if hasattr(hvdata, 'site'):
                        sitename = hvdata.site
                    elif hasattr(hvdata, 'Table_Report') and 'Site Name' in hvdata.Table_Report.columns:
                        sitename = hvdata.Table_Report['Site Name'][0]
                    else:
                        sitename = f"HVSRSite{str(siteNo).zfill(zfilldigs)}"
                        siteNo += 1
                    self.batch_dict[sitename] = hvdata
                elif pathlib.Path(hvdata).exists():
                    def _get_sitename(proposed_sitename, batch_dict):
                        # Get unique site name based on stem
                        j = 0
                        if proposed_sitename in batch_dict.keys():
                            # 100 is limit
                            for index in range(100):
                                if len(proposed_sitename.split('_')) <= index:
                                    if proposed_sitename.split('_')[-1].isdigit():
                                        j = int(proposed_sitename.split('_')[-1]) + 1
                                        sitenameList = proposed_sitename.split('_')
                                        sitenameList[-1] = str(j)
                                        proposed_sitename = '_'.join(sitenameList)
                                        break
                                    else:
                                        proposed_sitename = proposed_sitename+'_'+str(j)
                                        break
                                    j += 1
                                else:
                                    proposed_sitename = '_'.join(proposed_sitename.split('_')[:index+1])
                        return proposed_sitename

                    if 'hvsr' in pathlib.Path(hvdata).suffix:
                        sitename = pathlib.path(hvdata).stem
                        sitename = _get_sitename(sitename, batch_dict)

                        self.batch_dict[sitename] = hvdata
                    elif pathlib.Path(hvdata).suffix.upper()[1:] in OBSPY_FORMATS:
                        if verbose:
                            print(f"Site specified for inclusion in HVSRBatch has not been processed. Processing. ({hvdata})")
                        sitename = pathlib.Path(hvdata).stem
                        sitename = _get_sitename(sitename, batch_dict)
                        self.batch_dict[sitename] = run(pathlib.Path(hvdata).as_posix())
                    else:
                        print(f"Could not parse Batch input. Excluding from HVSRBatch object: {hvdata}")
        elif isinstance(batch_input, dict):
            # This is for a dictionary with the following structure:
            # batch_input = {"SiteName1":HVSRData, "Sitename2":HVSRData}
            self.batch_dict = batch_input
        elif isinstance(batch_input, HVSRData):
            # If iniitializing HVSRBatch with single HVSRData
            self.batch_dict[batch_input['site']] = batch_input
        elif pathlib.Path(batch_input).exists():
            # This is intended for filepaths
            if pathlib.Path(batch_input).is_dir():
                if batch_ext is not None:
                    batchfileglob = pathlib.Path(batch_input).glob("*."+batch_ext)
                    batchfiledict = {}
                    #if 'hvsr' in batch_ext:
                    for hvfile in batchfileglob:
                        currhvfile = import_data(hvfile)
                        batchfiledict[currhvfile['site']] = currhvfile
                    self.batch_dict = self._batch_dict = batchfiledict
                else:
                    # Assume it is .hvsr file you wish to import
                    batchfileglob = []
                    batchfiledict = {}

                    batchfileglob = pathlib.Path(batch_input).glob("*")
                    for hvfile in batchfileglob:
                        if hvfile.as_posix().lower().endswith('hvsr'):
                            currhvfile = import_data(hvfile.as_posix())
                            batchfiledict[currhvfile['site']] = currhvfile
                    self.batch_dict = self._batch_dict = batchfiledict           
            else:
                if '.hvsr' in pathlib.Path(batch_input).suffix:
                    # In this case, assume this is alreayd a batch file and import/return it
                    return import_data(batch_input)
                else:
                    # For reading in a csv and specifying column map
                    batch_df = pd.read_csv(batch_input)

                    # Convert columns to lowercase
                    batch_df.columns = [c.lower() for c in batch_df.columns]

                    # This is for if dictionary mapping is not specified
                    snList = ['site', 'sitename', 'sites', 'sitenames', 
                                'identifier', 'batch', 'profile', 'crosssection', 'group']
                    pathList = ['hvsr_export_path', 'import_filepath', 'batch_input', 'filepath', 'input_data',
                                'path', 'filepath', 'filename', 'file', 'hvsrdata', 'hvsr', 'data']

                    siteCol = batch_df.columns[0]
                    for sn in snList:
                        if sn in snList:
                            siteCol = sn
                            break

                    pathCol = batch_df.columns[1]
                    for pa in pathList:
                        if pa in pathList:
                            pathCol = pa
                            break

                    def _read_data_into_batch(batch_df_row, site_col, path_col):
                        if '.hvsr' in str(batch_df_row[path_col]):
                            dataObj = import_data(str(batch_df_row[path_col]))
                        elif pathlib.Path(batch_df_row[path_col]).suffix.upper()[1:] in OBSPY_FORMATS:
                            dataObj = run(pathlib.Path(batch_df_row[path_col]).as_posix())
                        else:
                            warnings.Warn(f"Batch input specified as site {batch_df_row[site_col]} cannot be read, skipping: {batch_df_row[path_col]}")
                            dataObj = None
                        
                        return dataObj

                    if isinstance(batch_use, dict):
                        # Dictionary of {'site':"site_col", 'filepath':'path_col', 'batch':values_in_batch_col_to_include}
                        if len(list(batch_use.keys())) != 3:
                            warnMsg = f"batch_use dict should have three keys called 'site', 'filepath', and 'batch' (not {len(list(batch_use.keys()))}: {list(batch_use.keys())}). \n\t'batch' may be changed to name of column you are using to specify inclusion in HVSRBatch object, or input DataFrame should have column called 'batch'"
                            warnings.Warn(warnMsg)

                        # Should be site and filepath, but just in case
                        for k in batch_use.keys():
                            if str(k).lower() in snList:
                                siteCol = batch_use[k]
                                siteKey = k

                            if str(k).lower() in pathList:
                                pathCol = batch_use[k]
                                pathKey = k

                            if str(k).lower() not in snList and str(k).lower() not in pathList:
                                includeMe = batch_use[k]
                                batchKey = k
    
                        # Get subset df with only rows that we want
                        #includeMe = batchCol#batch_use[batchCol]
                        if isinstance(includeMe, (list, tuple)):
                            sites_df = batch_df[batch_df[batchKey].isin(includeMe)]
                        elif isinstance(includeMe, dict):
                            sitesDFList = []
                            for batchCol, includeValue in includeMe.items():
                                sitesDFList.append(batch_df[batch_df[batchCol]==includeValue])
                            sites_df = pd.concat(sitesDFList, ignore_index=True)
                        else:
                            sites_df = batch_df[batch_df[batchKey]==includeMe]

                        # Import, process, or otherwise read data into batch object
                        for i, row in sites_df.iterrows():
                            dataObj = _read_data_into_batch(row, siteCol, pathCol)
                            if dataObj is not None:
                                self.batch_dict[str(row[siteCol])] = dataObj

                    elif isinstance(batch_use, (list, tuple)):
                        # This should be list/tuples of site names
                        sites_df = batch_df[batch_df[siteCol].isin(batch_use)]
                        for i, row in sites_df.iterrows():
                            dataObj = _read_data_into_batch(row, siteCol, pathCol)
                            if dataObj is not None:
                                self.batch_dict[str(row[siteCol])] = dataObj
                    
                    else:
                        # Use all rows (as possible)
                        print(f"**NOTE**: All data specified will be read into batch object, from: {batch_input}")
                        for i, row in batch_df.iterrows():
                            dataObj = _read_data_into_batch(row, siteCol, pathCol)

                            if dataObj is not None:
                                self.batch_dict[str(row[siteCol])] = dataObj
        else:
            raise TypeError(f"The batch_input parameter of the HVSRBatch class must be a dict of parameters, list or tuple of HVSRData obejcts, or an HVSRData object itself. {type(batch_input)}")


        self._batch_dict = self.batch_dict
        for sitename, hvsrdata in self.batch_dict.items():
            setattr(self, sitename, hvsrdata)
            self[sitename]['batch'] = True
        self.sites = list(self.batch_dict.keys())


    # METHODS
    def __to_json(self, filepath):
        """Not yet implemented, but may allow import/export to json files in the future, rather than just .hvsr pickles

        Parameters
        ----------
        filepath : filepath object
            Location to save HVSRBatch object as json
        """
        # open the file with the given filepath
        with open(filepath, 'w') as f:
            # dump the JSON string to the file
            json.dump(self, f, default=lambda o: o.__dict__, sort_keys=True, indent=4)


    def add(self, hvsr_data):
        """Function to add HVSRData objects to existing HVSRBatch objects"""
        if isinstance(hvsr_data, (dict, HVSRData)):
            hvsr_data = [hvsr_data]

        if isinstance(hvsr_data, (list, tuple,)):
            siteNo = 0
            zfilldigs = len(str(len(hvsr_data)))

            for hvdata in hvsr_data:
                sitename = f"HVSRSite{str(siteNo).zfill(zfilldigs)}"

                if hasattr(hvdata, 'site'):
                    sitename = hvdata.site
                elif hasattr(hvdata, 'Table_Report') and 'Site Name' in hvdata.Table_Report.columns:
                    sitename = hvdata.Table_Report['Site Name'][0]
                elif isinstance(hvdata, dict):
                    if 'site' in hvdata.keys():
                        sitename = hvdata['site']

                self[sitename] = hvsr_data
        

    def append(self, hvsr_data):
        """Alias of add()"""
        add(self, hvsr_data)
        

    def export(self, hvsr_export_path=True, ext='hvsr'):
        """Method to export HVSRData objects in HVSRBatch container to indivdual .hvsr pickle files.

        Parameters
        ----------
        hvsr_export_path : filepath, default=True
            Filepath to save file. Can be either directory (which will assign a filename based on the HVSRData attributes). By default True. If True, it will first try to save each file to the same directory as input_data, then if that does not work, to the current working directory, then to the user's home directory, by default True
        ext : str, optional
            The extension to use for the output, by default 'hvsr'. This is still a pickle file that can be read with pickle.load(), but will have .hvsr extension.
        """
        export_hvsr(hvsr_data=self, hvsr_export_path=hvsr_export_path, ext=ext)


    def keys(self):
        """Method to return the "keys" of the HVSRBatch object. For HVSRBatch objects, these are the site names. Functions similar to dict.keys().

        Returns
        -------
        dict_keys
            A dict_keys object listing the site names of each of the HVSRData objects contained in the HVSRBatch object
        """
        return self.batch_dict.keys()


    def items(self):
        """Method to return both the site names and the HVSRData object as a set of dict_items tuples. Functions similar to dict.items().

        Returns
        -------
        _type_
            _description_
        """
        return self.batch_dict.items()


    def copy(self, type='shallow'):
        """Make a copy of the HVSRBatch object. Uses python copy module.
        
        Parameters
        ----------
        type : str {'shallow', 'deep'}
            Based on input, creates either a shallow or deep copy of the HVSRBatch object. Shallow is equivalent of copy.copy(). Input of 'deep' is equivalent of copy.deepcopy() (still experimental). Defaults to shallow.
    
        """
        if type.lower()=='deep':
            return HVSRBatch(copy.deepcopy(self._batch_dict), df_as_read=self._input_df)
        else:
            return HVSRBatch(copy.copy(self._batch_dict), df_as_read=self._input_df)


    #Method wrapper of sprit.plot_hvsr function
    def plot(self, **kwargs):
        """Method to plot data, based on the sprit.plot_hvsr() function. 
        
        All the same kwargs and default values apply as plot_hvsr().
        For return_fig, returns it to the 'Plot_Report' attribute of each HVSRData object

        Returns
        -------
        _type_
            _description_

        See Also
        --------
        plot_hvsr
        """
        for sitename in self:
            if 'return_fig' in kwargs.keys() and kwargs['return_fig']:
                self[sitename]['Plot_Report'] = plot_hvsr(self[sitename], **kwargs)
            else:
                plot_hvsr(self[sitename], **kwargs)

        return self
    
    def get_report(self, **kwargs):
        """Method to get report from processed data, in print, graphical, or tabular format.

        Returns
        -------
        Variable
            May return nothing, pandas.Dataframe, or pyplot Figure, depending on input.

        See Also
        --------
        get_report
        """
        if 'report_formats' in kwargs.keys():
            if 'table' == kwargs['report_formats']:
                for sitename in self:
                    rowList = []
                    rowList.append(get_report(self[sitename], **kwargs))
                return pd.concat(rowList, ignore_index=True)
            elif 'plot' == kwargs['report_formats']:
                plotDict = {}
                for sitename in self:
                    if 'return_fig' in kwargs.keys() and kwargs['return_fig']:
                        plotDict[sitename] = get_report(self[sitename], **kwargs)
                    else:
                        get_report(self[sitename], **kwargs)
                return plotDict
            
        #Only report_formats left is print, doesn't return anything, so doesn't matter if defalut or not
        for sitename in self:
            get_report(self[sitename], **kwargs)
        return

    def report(self, **kwargs):
        """Wrapper of get_report()
        
        See Also
        --------
        get_report
        """
        return self.get_report(**kwargs)

    def export_settings(self, site_name=None, export_settings_path='default', export_settings_type='all', include_location=False, verbose=True):
        """Method to export settings from HVSRData object in HVSRBatch object. 
        
        Simply calls sprit.export_settings() from specified HVSRData object in the HVSRBatch object. 
        See sprit.export_settings() for more details.

        Parameters
        ----------
        site_name : str, default=None
            The name of the site whose settings should be exported. If None, will default to the first site, by default None.
        export_settings_path : str, optional
            Filepath to output file. If left as 'default', will save as the default value in the resources directory. If that is not possible, will save to home directory, by default 'default'
        export_settings_type : str, {'all', 'instrument', 'processing'}, optional
            They type of settings to save, by default 'all'
        include_location : bool, optional
            Whether to include the location information in the instrument settings, if that settings type is selected, by default False
        verbose : bool, optional
            Whether to print output (filepath and settings) to terminal, by default True
        
        
        See Also
        --------
        export_settings
        """
        #If no site name selected, use first site
        if site_name is None:
            site_name = self.sites[0]
            
        export_settings(hvsr_data=self[site_name], 
                        export_settings_path=export_settings_path, export_settings_type=export_settings_type, include_location=include_location, verbose=verbose)

    def __iter__(self):
        return iter(self._batch_dict.keys())

    def __setitem__(self, key, value):
        setattr(self, key, value)

    def __getitem__(self, key):
        return getattr(self, key)

Methods

def add(self, hvsr_data)

Function to add HVSRData objects to existing HVSRBatch objects

def append(self, hvsr_data)

Alias of add()

def copy(self, type='shallow')

Make a copy of the HVSRBatch object. Uses python copy module.

Parameters

type : str {'shallow', 'deep'}: Based on input, creates either a shallow or deep copy of the HVSRBatch object. Shallow is equivalent of copy.copy(). Input of 'deep' is equivalent of copy.deepcopy() (still experimental). Defaults to shallow.

def export(self, hvsr_export_path=True, ext='hvsr')

Method to export HVSRData objects in HVSRBatch container to indivdual .hvsr pickle files.

Parameters

hvsr_export_path : filepath, default=True: Filepath to save file. Can be either directory (which will assign a filename based on the HVSRData attributes). By default True. If True, it will first try to save each file to the same directory as input_data, then if that does not work, to the current working directory, then to the user's home directory, by default True
ext : str, optional: The extension to use for the output, by default 'hvsr'. This is still a pickle file that can be read with pickle.load(), but will have .hvsr extension.

def export_settings(self, site_name=None, export_settings_path='default', export_settings_type='all', include_location=False, verbose=True)

Method to export settings from HVSRData object in HVSRBatch object.

Simply calls sprit.export_settings() from specified HVSRData object in the HVSRBatch object. See sprit.export_settings() for more details.

Parameters

site_name : str, default=None: The name of the site whose settings should be exported. If None, will default to the first site, by default None.
export_settings_path : str, optional: Filepath to output file. If left as 'default', will save as the default value in the resources directory. If that is not possible, will save to home directory, by default 'default'
export_settings_type : str, {'all', 'instrument', 'processing'}, optional: They type of settings to save, by default 'all'
include_location : bool, optional: Whether to include the location information in the instrument settings, if that settings type is selected, by default False
verbose : bool, optional: Whether to print output (filepath and settings) to terminal, by default True

Returns

Variable: May return nothing, pandas.Dataframe, or pyplot Figure, depending on input.

Returns

_type_: description

def keys(self)

Method to return the "keys" of the HVSRBatch object. For HVSRBatch objects, these are the site names. Functions similar to dict.keys().

Returns

dict_keys: A dict_keys object listing the site names of each of the HVSRData objects contained in the HVSRBatch object

def plot(self, **kwargs)

Method to plot data, based on the sprit.plot_hvsr() function.

All the same kwargs and default values apply as plot_hvsr(). For return_fig, returns it to the 'Plot_Report' attribute of each HVSRData object

Returns

_type_: description

Returns

bool: True if HVSRData object is part of HVSRBatch object, otherwise, False

Expand source code

@property
def batch(self):
    """Whether this HVSRData object is part of an HVSRBatch object. This is used throughout the code to help direct the object into the proper processing pipeline.

    Returns
    -------
    bool
        True if HVSRData object is part of HVSRBatch object, otherwise, False
    """
    return self._batch

prop params

Dictionary containing the parameters used to process the data

Returns

dict: Dictionary containing the process parameters

Expand source code

@property
def params(self):
    """Dictionary containing the parameters used to process the data

    Returns
    -------
    dict
        Dictionary containing the process parameters
    """
    return self._params

prop ppsds

Dictionary copy of the class object obspy.signal.spectral_estimation.PPSD(). The dictionary copy allows manipulation of the data in PPSD, whereas that data cannot be easily manipulated in the original Obspy object.

Returns

dict: Dictionary copy of the PPSD information from generate_psds()

Expand source code

@property
def ppsds(self):
    """Dictionary copy of the class object obspy.signal.spectral_estimation.PPSD(). The dictionary copy allows manipulation of the data in PPSD, whereas that data cannot be easily manipulated in the original Obspy object.

    Returns
    -------
    dict
        Dictionary copy of the PPSD information from generate_psds()
    """
    return self._ppsds

prop ppsds_obspy

The original ppsd information from the obspy.signal.spectral_estimation.PPSD(), so as to keep original if copy is manipulated/changed.

Expand source code

@property
def ppsds_obspy(self):
    """The original ppsd information from the obspy.signal.spectral_estimation.PPSD(), so as to keep original if copy is manipulated/changed."""        
    return self._ppsds_obspy

Methods

def copy(self, copy_type='shallow')

Make a copy of the HVSRData object. Uses python copy module.

Parameters

copy_type : str {'shallow', 'deep'}: Based on input, creates either a shallow or deep copy of the HVSRData object. Shallow is equivalent of copy.copy(). Input of copy_type='deep' is equivalent of copy.deepcopy() (still experimental). Defaults to shallow.

def export(self, hvsr_export_path=None, ext='hvsr')

Method to export HVSRData objects to .hvsr pickle files.

Parameters

hvsr_export_path : filepath, default=True: Filepath to save file. Can be either directory (which will assign a filename based on the HVSRData attributes). By default True. If True, it will first try to save each file to the same directory as input_data, then if that does not work, to the current working directory, then to the user's home directory, by default True
ext : str, optional: The extension to use for the output, by default 'hvsr'. This is still a pickle file that can be read with pickle.load(), but will have .hvsr extension.

Parameters

export_settings_path : str, optional: Filepath to output file. If left as 'default', will save as the default value in the resources directory. If that is not possible, will save to home directory, by default 'default'
export_settings_type : str, {'all', 'instrument', 'processing'}, optional: They type of settings to save, by default 'all'
include_location : bool, optional: Whether to include the location information in the instrument settings, if that settings type is selected, by default False
verbose : bool, optional: Whether to print output (filepath and settings) to terminal, by default True

def get_report(self, **kwargs)

Method to get report from processed data, in print, graphical, or tabular format.

Returns

Variable: May return nothing, pandas.Dataframe, or pyplot Figure, depending on input.

Returns

dict_items: A dict_items object of the HVSRData objects attributes, parameters, etc.

def keys(self)

Method to return the "keys" of the HVSRData object. For HVSRData objects, these are the attributes and parameters of the object. Functions similar to dict.keys().

Returns

dict_keys: A dict_keys object of the HVSRData objects attributes, parameters, etc.

def plot(self, **kwargs)

Method to plot data, wrapper of sprit.plot_hvsr()

Returns

matplotlib.Figure, matplotlib.Axis (if return_fig=True)

Sub-modules

Functions

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Raises

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

See Also

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

See Also

Classes

Methods

Parameters

Parameters

Parameters

See Also

Returns

See Also

Returns

Returns

Returns

See Also

See Also

Instance variables

Returns

Returns

Returns

Methods