Modules

This section includes modules that are used in this project.

database.py

The core module for communicating with the database.

class tsprocess.database.DataBase(dbname, cache_size)

DataBase class (singleton pattern)

close_db()

Commits changes to the database, closes the database, clears the cache.

delete_value(key)

Deletes the key, and its value from both in-memory dictionary and on-disk database. If the key is not found, simply ignores it.

Inputs:

key: hash value (generated by the package)

get_nested_container(key)

Returns the value of the nested container, directly from database.

Inputs:

key: container key

Outputs:

If found, value, else returns None.

get_value(key)

Returns the value in the following order:

1) It will look for the value in the cache and return it, if not found

2) will look for the value in the disk and return it, if not found

3) will return None.

Inputs:

key: hash value (generated by the package)

Outputs:

If found, value, else returns None.

remove_nested_container(key1, key2)

Removes key2 from tracking inside key1 container. Not implemented.

set_value(key, value)

Sets the key and given value in the database. If the key exists, it will override the value. In that case, it will remove the key from the in-memory dictionary. It will be loaded again with the get_value command if needed.

Inputs:

key: hash value (generated by the package)

value: Seismic Record object

update_nested_container(key1, key2, value, append=True)

Updates nested container

Inputs:

key1 is the key for the contaier.

key2 is the key inside the container.

value is the value of key2

db_tracker.py

The core module for the DatabaseTracker class.

class tsprocess.db_tracker.DataBaseTracker(name, project, buffer_capacity=3)

DatabaseTracker Class

start_tracking_incident(incident_name)

creates an empty list for a new incident.

project.py

The core module for the project class.

class tsprocess.project.Project(name)

Project Class p1 = Project(‘myproject’)

classmethod _connect_to_database()

Creates and connects to a database.

_extract_records(list_inc, list_process, list_filters)

Extracts the requested records. Loop through all available stations and choose them based on list_filters. For a list of incidents with N incidents, each station will return a list of N records, corresponding to the list of incidents. If for some stations there is no record for that incident, it should return None.

_is_incident_valid(list_incidents)

Checks if the requested processing label is a valid label

_is_processing_label_valid(list_process)

Checks if the requested processing label is a valid lable

Input:

list_process: List of processing labels

_is_station_filter_valid(list_filters)

Checks if the requested station filter is a valid filter

Input:

list_filters: List of station filters

_load_incident(incident_folder, incident_description)

load incidents into the project’s incidents dictionary

Inputs:

incident_folder: path to incident folder

incident_description: dictionary of incident’s description

classmethod _make_output_dir()

Makes output_tsprocess directory in the working path.

static _read_incident_description(incident_folder)

Extract incident descriptions

Inputs:

incident_folder: path to incident folder.

add_incident(incident_folder)

Adds a new incident to the project.

Inputs:

incident_folder: absolute or relative path to the incident folder.

add_processing_label(label_name, label_type, hyper_parameters)

Creates a processing label

add_source_hypocenter(lat, lon, depth)

Adds earthquake hypocenter to the project.

Inputs:

lat: latitude (-90,90)

lon: longitude (-180, 180)

depth: in meters (positive toward earth interior)

add_station_filter(station_filter_name, station_filter_type, hyper_parameters)

Adds a new filter for selecting stations

close_database()

Terminating the connection to the database.

compare_incidents(ls_inc, only_differences=False)

compares the incidents’ meta data

Inputs:

ls_inc: list of incident names

only_differerences: True or False

database_summary()

Returns a summary of database

list_of_incidents()

Returns a list of incidents.

list_of_processing_labels()

Returns a list of available processing labels

list_of_station_filters()

Returns a list of available processing labels

plot_acceleration_records(list_inc, list_process, list_filters, opt_params)

Plots 3 acceleration timeseries one page per station and their response spectra plots

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

zoom_in_time : [tmin, tmax] in seconds

Horizontal zoom in time axis for better presentation. Data is not modified.

zoom_in_rsp : [period_min, period_max] in seconds

Horizontal zoom in period axis for better presentation. Data is not modified.

plot_displacement_records(list_inc, list_process, list_filters, opt_params)

Plots 3 displacement timeseries one page per station and their fft amplitude spectra plots

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

zoom_in_time : [tmin, tmax] in seconds

Horizontal zoom in time axis for better presentation. Data is not modified.

zoom_in_freq : [freq_min, freq_max] in Hertz

Horizontal zoom in period axis for better presentation. Data is not modified.

plot_peak_velocity_vs_distance(list_inc, list_process, list_filters, opt_params)

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Outputs:

plot_record_section(list_inc, list_process, list_filters, opt_params)

Plots seismic record section

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

zoom_in_time : [tmin, tmax] in seconds

Horizontal zoom in time axis for better presentation. Data is not modified.

plot_records_orientation(list_inc, list_process, list_filters, opt_params)

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Outputs:

plot_velocity_records(list_inc, list_process, list_filters, opt_params)

Plots 3 velocity timeseries one page per station and their fft amplitude spectra plots

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

zoom_in_time : [tmin, tmax] in seconds

Horizontal zoom in time axis for better presentation. Data is not modified.

zoom_in_freq : [freq_min, freq_max] in Hertz

Horizontal zoom in period axis for better presentation. Data is not modified.

remove_incident(incident_name)

Removes incident from the project.

show_stations_on_map(list_inc, list_process, list_filters, opt_params)

Returns an interactive map of source and stations, use only in Jupyter Notebooks.

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

show_stations_on_map2(list_inc, list_process, list_filters, opt_params)

Returns a map including the source and stations

Inputs:

list_inc: list of incidents (supports one incident)

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

save_figure: True, False

llrtlatlon: lower_left then upper_right lat and lon

stations_joint_table(list_inc, list_process, list_filters, opt_params)

Returns a joint table that shows stations’ location and corresponding station name at different incidents.

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Outputs:

stations_joint_table: as a pandas dataframe

summary()

prints out a summary of the project.

valid_processing_labels()

Returns a list of valid processing labels

valid_station_filter_type()

Returns a list of valid filters for selecting stations.

which_records(list_inc, list_process, list_filters, opt_params)

Print outs all records that pass the given filters

Inputs:

list_inc: list of incidents

list_process: list of processes, one list per incident

list filters: list of filters defined for stations

opt_params: optional parameters (dictionary)

Optional parameters:

incident.py

The core module for the Incident class.

class tsprocess.incident.Incident(folder_path, incident_description)

Incident Class

_extract_input_parameters()

Extracts input parameters from the incident folder. Stores the results in the metadata attribute.

_extract_seismic_source_data()

extracts seismic source details.

_extract_station_name_location()

Extracts stations’ name and location from the incident folder.

timeseries.py

The core module for the TimeSeries class.

class tsprocess.timeseries.Acc(value, dt, t_init_point)

Acc Class

_compute_response_spectra()

Computes response spectra

compute_integral()

Returns Vel instance

class tsprocess.timeseries.Disp(value, dt, t_init_point)

Disp Class

compute_diff()

Returns Vel instance

class tsprocess.timeseries.Raw(raw_value, dt, t_init_point, poles, zeros, constant)

Raw Class

to_velocity()

Returns Vel instance

class tsprocess.timeseries.TimeSeries

TimeSeries Abstract Class

classmethod _add_processing_label(label_name, label_type, argument_dict)

Adds new processing label to the timeseries class.

Inputs:

label_name: optional processing label name

label_type: should be one of the valid label types

argument_dict: dictionary of arguments that is required for that processing label type.

_apply(label_name)

Applies the requested label_name on the timeseries

Input:

label_name: processing label name

Output:

processed timeseries

_bandpass_filter(fcs, N=4)

Returns a bandpass filtered (the Butterworth filter) signal value.

Inputs:

fc: corner frequencies (Hz)

N: filter order (default value = 4)

_compute_fft_value()

Computes FFT value by calling FAS function.

_highpass_filter(fc, N=4)

Returns a highpass filtered (the Butterworth filter) signal value.

Inputs:

fc: corner frequency (Hz)

N: filter order (default value = 4)

_lowpass_filter(fc, N=4)

Returns a lowpass filtered (the Butterworth filter) signal value.

Inputs:

fc: corner frequency (Hz)

N: filter order (default value = 4)

_scale(factor)

Returns a scaled signal.

Inputs:

factor: scaling factor (e.g., 2 for doubling amplitude)

class tsprocess.timeseries.Unitless

Unitless Class

class tsprocess.timeseries.Vel(value, dt, t_init_point)

Vel Class

compute_diff()

Returns ACC instance

compute_integral()

Returns Disp instance

record.py

The core module for the Record class.

class tsprocess.record.Record(time_vec, disp_h1, disp_h2, disp_ver, vel_h1, vel_h2, vel_ver, acc_h1, acc_h2, acc_ver, station, source_params, hc_or1, hc_or2, ver_or, unit)

Record Class

static _add_proc_key(record, hash_val)

Includes the hash value of the new processed record of this record into record’s processed attribute. It also updates the record on the database.

classmethod _add_processing_label(label_name, label_type, argument_dict)

Adds new processing label to the Record class.

Inputs:

label_name: optional processing label name

label_type: should be one of the valid label types

argument_dict: dictionary of arguments that is required for that processing label type.

static _apply(record, label_name)

Applies the requested processing label on the record. Returns a new Record object representing the processed record.

_compute_record_unique_ids()

Assigns two randomly generated 16 char id to each record.

_compute_source_dependent_params()

Computes parameters that are dependent to the distance and azimuth between source and the station.

static _from_cesmdv2(r_data, r_metadata, station_obj, source_hypocenter, st_name)

Loads an instance of Hercules simulation results at one station. Returns a Record object.

Inputs:

r_data: nested list of data. See ts_utils.read_smc_v2 funtions first return value

r_metadata: dictionary of metadata regarding the loaded record. See ts_utils.read_smc_v2 functions second return value

station_obj: a station object corresponding that filename

source_hypocenter: project source location

st_name: station name

Outputs:

Record object

static _from_hercules(filename, station_obj, source_hypocenter, hr_or1, hr_or2, ver_or, inc_unit)

Loads an instance of Hercules simulation results at one station. Returns a Record object.

Inputs:

filename: station file name (e.g., station.10)

station_obj: a station object corresponding that filename

source_hypocenter: project source location

hr_or1: first horizontal component’s orientation

hr_or2: second horizontal component’s orientation

ver_or: vertical component’s orientation

inc_unit: Incident unit

Outputs:

Record object

static _get_processed_record(incident_name, record, list_process)

Returns the processed records based on hash value of the record and the processing label. Developers should call this function only by original record.

static generate_uid()

generates 16 chars random combination from string and numbers

static get_record(station_obj, incident_metadata, list_process)

Returns final processed reocord based on station, incident, and required list of processes. If the record is found in database, it will be returned, otherwise, it will be processed and will be returned. The processed record will be stored in the database for future use.

Inputs:

station_obj: a station object

incident_metadata: a dictionary of incidance metadata

list_process: list of required processes

Output:

record object

seismicsource.py

The core module for the SeismicSource class.

class tsprocess.seismicsource.SeismicSource(source_directory, incident_type)

SeismicSource Class

station.py

The core module for the Station class.

class tsprocess.station.Station(lat, lon, depth)

Class Station

ts_utils.py

The core module for timeseries helper functions.

tsprocess.ts_utils.FAS(data, dt, points, fmin, fmax, s_factor)

Calculates the FAS of the input array using NumPy’s fft Library

Inputs:

data - input array

dt - delta t for the input array

points - length of the transformed axis in the fft output

fmin - min frequency for results

fmax - max frequency for results

s_factor - smooth factor to be used for the smooth function

Outputs:

freq - frequency array

afs - fas

tsprocess.ts_utils.cal_acc_response(period, data, delta_t)

Returns the response for acceleration only. First tries fortran extenstion, if not found, uses python implementation, which is slower.

Inputs:

period: osilator’s period

data: acceleration input signal

delta_ts: time step

tsprocess.ts_utils.compute_azimuth(lat1, lon1, lat2, lon2)

Computes azimuth from point one to point2.

Inputs:

lat and lon for point 1 and point 2

Outputs:

azimuth from point1 to point2.

Examples:

>>> p1 = [37.577019, -112.561856]
>>> p2 = [37.214750, -117.545706]
>>> az = compute_azimuth(p1[0], p1[1], p2[0], p2[1])
>>> print(f"{az :0.5f}")
266.28959

tsprocess.ts_utils.compute_rotation_angle(a, b)

Computes angle to align vector b on to vector a. North toward East is considered as a positive orientation (N10E = 10.) All inputs should be positive. (N10W = 350) The order of orientations are not important. Inputs:

a: [hr1, hr2] current orientation

b: [hr1, hr2] target orientation

Outputs:

rotation_angle: returns rotation angle

tsprocess.ts_utils.get_period(tmin, tmax)

Return an array of period T

>>> a = get_period(0.1,10)
>>> print(f"{a[2] :.8f}")
0.16237767

tsprocess.ts_utils.haversine(lat1, lon1, lat2, lon2)

Computes distance of two geographical points.

Inputs:

lat and lon for point 1 and point 2

Outputs:

distance betwee two points in km.

tsprocess.ts_utils.is_depth_valid(depth)

Controls if depth is a valid number. Depth is considered positive towards the earth interior.

Inputs:

depth: depth in km

Output:

True or False

Example:

>>> is_depth_valid('twenty')
False

tsprocess.ts_utils.is_incident_description_valid(inc_des, valid_incidents, current_incidents, valid_vertical_orientation, valid_incident_unit)

checks incident description and if it follows incident description format, returns True, otherwise returns False.

Inputs:

inc_des: Incident description key-value dictionary

valid_incidents: List of valid incidents type

current_incidents: List of current incidents name

valid_vertical_orientation: valid vertical orientation

valid_incident_unit: valid units for incidents

Outputs:

True or False

tsprocess.ts_utils.is_lat_valid(lat)

Controls if latitude is in a valide range.

Inputs:

lat: latitude in degrees

Output:

True or False

Example:

>>> is_lat_valid(-130)
False

tsprocess.ts_utils.is_lon_valid(lon)

Controls if longitude is in a valide range.

Inputs:

lat: latitude in degrees

Output:

True or False

Example:

>>> is_lon_valid(122)
True

tsprocess.ts_utils.list2message(lst)

converts list of processing details into string message details include: | file_name, list_inc, list_processing, list_station_filter, station_incident dictionary

tsprocess.ts_utils.max_osc_response(acc, dt, csi, period, ini_disp, ini_vel)

Returns maximum values of displacement, velocity, and acceleration.

Inputs:

acc: accleration input signal

dt: time step

csi: damping ratio

period: oscilator’s period

ini_disp: initial displacement

ini_vel: initial velocity

Originial version is writting by: Leonardo Ramirez-Guzman

Fortran kernel extension is added for speed up.

tsprocess.ts_utils.query_opt_params(opt_params, key)

Returns the provided key in optional parameters dictionayr. Returns None if not found.

tsprocess.ts_utils.read_data(signal)

The function is to convert signal data into an numpy array of float numbers

Inputs:

string of numbers

Outputs:

numpy array of numbers

tsprocess.ts_utils.read_smc_v2(input_file)

Reads and processes a COSMOS V2 file

Inputes:

input_file: Input file path

Outputs:

record_list: Includes list of records. Each item in this list includes

number of samples, delta t, orientation, and [disp, vel, acc] records.

station_metadata: Please see the end of this function for keys in the

metadata attribute.

tsprocess.ts_utils.rotate_record(record, rotation_angle)

Rotates a given record instance by rotation angle

Input:

record: instance of Record class rotation_angle: rotation angle in degrees

Output:

rotated record instane

tsprocess.ts_utils.seism_appendzeros(flag, t_diff, m, timeseries, delta_t)

Adds zeros in the front or at the end of an numpy array, applies taper before adding zeros.

Inputs:

flag - ‘front’ or ‘end’ - tapering flag passed to the taper function

t_diff - how much time to add (in seconds)

m - number of samples for tapering

ts_vec - Input timeseries

Outputs:

timeseries - zero-padded timeseries.

tsprocess.ts_utils.seism_cutting(flag, t_diff, m, timeseries, delta_t)

Cuts data in the front or at the end of an numpy array apply taper after cutting

Inputs:

flag - ‘front’ or ‘end’ - flag to indicate from where to cut samples

t_diff - how much time to cut (in seconds)

m - number of samples for tapering

timeseries - Input timeseries

Outputs:

timeseries - Output timeseries after cutting

tsprocess.ts_utils.smooth(data, factor)

Smooth the data in the input array

Inputs:

data - input array

factor - used to calculate the smooth factor

Outputs:

data - smoothed array

tsprocess.ts_utils.taper(flag, m, ts_vec)

Returns a Kaiser window created by a Besel function

Inputs:

flag - set to ‘front’, ‘end’, or ‘all’ to taper at the beginning, at the end, or at both ends of the timeseries

m - number of samples for tapering

window - Taper window

tsprocess.ts_utils.unit_convention_factor(r_unit, inc_unit)

controls requested and incident units and returns multiplicaiton factor that converts the incident’s or record’s unit into the requested unit. Only m(meter) anc cm(centimeter) are supported.

Inputs:

r_unit: The requested conventional unit

inc_unit: Incident or record unit

Output:

multiplication factor

Example: >>> unit_convention_factor(“cm”, “cm”) 1 >>> unit_convention_factor(“m”, “cm”) 0.01 >>> unit_convention_factor(“cm”, “m”) 100

ts_plot_utils.py

The core module for timeseries plot helper functions.

tsprocess.ts_plot_utils.plot_acceleration_helper(record, color_code, opt_params, list_inc, list_process, list_filters)

Plots acceleration timeseries and corresponding response spectra amplitude for 3 components. It is an internal function for plot_acceleration_records methods in the Project class. should not be directly used by the end users.

tsprocess.ts_plot_utils.plot_displacement_helper(record, color_code, opt_params, list_inc, list_process, list_filters)

Plots displacement timeseries and corresponding frequency spectra amplitude for 3 components. It is an internal function for plot_displacement_records methods in the Project class. should not be directly used by the end users.

tsprocess.ts_plot_utils.plot_peak_velocity_vs_distance_helper(st_records, list_inc)

Plots scatter data points for comparing peak ground velocity vs distance.

Inputs:

st_records: nested list, each nested list contains one station’s location. First elemenet is distance, second, third, fourth elements are peak ground velocity of h1, h2, and ver. There is one list for each incident provided in list_inc.

list_inc: list of incidents.

Outputs:

fig: matplotlib figure handle.

tsprocess.ts_plot_utils.plot_records_orientation_helper(st_item)

tsprocess.ts_plot_utils.plot_recordsection_helper(records, color_code, opt_params, list_inc, list_process, list_filters)

Plots seismic record section. It is an internal function for plot_record_section methods in the Project class. should not be directly used by the end users.

tsprocess.ts_plot_utils.plot_scatter_on_basemap(llcrnrlatlon, urcrnrlatlon, data)

Plots scatter datapoints provided by data on the basemap plot.

tsprocess.ts_plot_utils.plot_velocity_helper(record, color_code, opt_params, list_inc, list_process, list_filters)

Plots velocity timeseries and corresponding frequency spectra amplitude for 3 components. It is an internal function for plot_velocity_records methods in the Project class. should not be directly used by the end users.