API Reference#

The Application Programming Interface (API) of PyNetDesign is composed of the following modules:

Modelling: algorithms for modelling related to microseismic network design
- Core: high-level drivers for magnitude sensitivity
- Homogeneous: algorithms for a homogeneous velocity model
- Geometry generators: synthetic geometry generators
- Input / output: reading and writing geometry and velocity files
- Classes: parameter containers
- Modelling utilities: wave modes, radiation patterns, amplitudes and grid helpers
Visualization: plotting of results and input
- Geometry: receiver geometry
- Sensitivity: magnitude sensitivity results
- Visualization utilities: general utility functions for visualization

Modelling#

`get_mag_sensitivity`(grid_coords, ...[, ...])	Computes detectable magnitude sensitivity for input geometry, velocity and parameters.
`get_mag_sensitivity_local`(grid_coords, ...)	Computes magnitude sensitivity using mag_sensitivity_grid for input local geometry, velocity and parameters.

`mag_sensitivity_grid`(grid_coords, velocity_df)	Computes magnitude sensitivity - the minimum moment magnitude (Mw) of a microseismic event which will theoretically produce particle velocity amplitudes (of P and/or S waves) on stations necessary for event detection assuming 3D elastic homogeneous medium with attenuation.
`calculate_M0`(density, v, Q, rad_pattern, r, amps)	Calculates the seismic moment \(M_0\) in a homogeneous medium given the density \(\rho\), wave velocity \(v\), distance from the source \(r\) and the displacement amplitude spectrum \(\left\|U(f)\right\|\) using:
`calculate_fpeak`(v, Q, r[, fcorner])	Calculates the peak frequency \(f_{peak}\) for particle velocity in a homogeneous medium given the wave velocity \(v\), the attenuation factor \(Q\), and the distance from a source \(r\) using:
`validate_parameters`(density, v_p, v_s, Q_p, ...)	Validates the input parameters.

`generate_geometry`(mode[, center_x, ...])	Generate a DAS geometry file in PyNetDesign tab-delimited format.
`generate_borehole_geometry`(center_x, ...)	Generate borehole DAS channel coordinates.
`generate_surface_geometry`(center_x, ...)	Generate surface DAS channel coordinates.
`generate_darkfiber_geometry`(center_x, ...[, ...])	Generate a continuous dark-fiber cable path.

`read_geometry`(file_path)	Read geometry data from a whitespace-delimited CSV (ASCII) file and return a DataFrame.
`save_geometry`(geometry, file_path)	Save geometry to disk in a format compatible with `read_geometry`.
`read_velocity`(file_path)	Read velocity model data from a whitespace-delimited CSV (ASCII) file and return a DataFrame.
`combine_geometry`(*dataframes[, names])	Combine an arbitrary number of pandas DataFrames with geometries into one while retaining the ability to distinguish and recover the original DataFrames.
`is_combined_geometry`(df)	Check if the given DataFrame is a combined geometry DataFrame created by combine_geometry.
`decimate_geometry`(geometry_df, step)	Decimate a non-combined geometry by keeping every `step`-th station.
`global2local`(latY, lonX[, refLat, refLon])	Converts global latitude and longitude coordinates to Cartesian coordinates under a simple spherical Earth approximation.

DetectionParameters(min_SNR_p, min_SNR_s, ...)

Container for the parameters controlling event detection.

`normalize_wave_mode`(wave_mode)	Return the canonical form of a wave mode.
`wave_mode_phases`(wave_mode)	Expand a wave mode into the physical phases that must be evaluated.
`wave_mode_has_p`(wave_mode)	Return whether `wave_mode` includes the P branch.
`wave_mode_has_s`(wave_mode)	Return whether `wave_mode` includes any S-family branch.
`wave_mode_s_phases`(wave_mode)	Return the S-family phases included in `wave_mode`.
`phase_radiation_pattern`(phase)	Return the root-mean-square radiation-pattern magnitude of a phase.
`resolve_radiation_pattern`(phase[, ...])	Resolve the radiation-pattern magnitude to use for a phase.

`calculate_Mw`(M0)	Calculates the moment magnitude \(M_w\) according to Kanamori (1977) using formula
`calculate_seismic_moment`(Mw)	Calculates the seismic moment \(M_0\) from moment magnitude \(M_w\) according to Kanamori (1977)
`get_scaling_displacement`(amps_type, f)	Get scaling coefficient(s) to convert to the amplitudes to displacement provided the type of original amplitudes and the frequency (or array of frequencies).
`retrieve_min_amps`(geometry_df, SNR_p, SNR_s)	Retrieve minimum amplitudes for P and S waves from geometry data, scaled based on noise type.

`mag_detectable`(Mw_min_stations[, ...])	Computes detectable minimum magnitudes from magnitude sensitivities for individual stations with respect to number of stations necessary for event detection using P and/or S waves.
`check_min_stations`(min_stations_p, ...[, ...])	Check that the minimum numbers of stations required for detection are valid.
`compute_free_surface_coefficients`(...[, ...])	Compute free surface amplification coefficients for each station and grid point.
`get_phase_station_directionality`(...[, ...])	Derive receiver projection coefficients for P, SV and SH polarizations.
`geometry_requires_receiver_projection`(...)	Return whether a geometry needs receiver-component projection.
`get_ray_station_directionality`(...[, ...])	Derive directionality coefficients for P and S waves along a cable.

`generate_grid`(x, y, z)	From the grid vectors x,y,z generates an array of grid point coordinates of size (nxnynz,3).
`reshape_grid`(grid_array, nx, ny, nz)	Reshape a flat grid array into a multidimensional array based on the provided grid vectors.
`reshape_data`(data, x, y)	Reshape data to 2D array using axes vectors.
`get_slice_coordinates`(grid_points, ...)	From the array of grid point coordinates of size (nxnynz,3) retrieve coordinates of the slice plane at a given slice coordinate in a given slice dimension.
`are_points_inside`(grid_coords1, grid_coords2)	Check if all points in `grid_coords1` are inside `grid_coords2`.
`find_indices_of_points`(grid_coords1, ...)	Find indices of points in `grid_coords1` that are inside `grid_coords2`.
`nth_minimum`(arr, n)	Find the n-th minimum value in each row of a given 2D numpy array.
`check_zero_values`(a[, ErrorMessage])	Check if the input value is close to zero and raise an error if true.
`contains_only_numeric`(seq)	Check if a sequence (tuple, list, or numpy array) contains only numeric values.
`compute_gcd_of_floats`(rx, ry, rz)	Computes the greatest common divisor (GCD) of three positive float values.

plot_stations_view(df[, view, x_offset, ...])

Plots either a map view or side view of stations as filled triangles with name labels.

plot_sensitivity_slice(sens_data[, xi, yi, ...])

Plots magnitude sensitivity in map or side view with stations plotted as non-filled triangles with name labels.

`generate_colorscale`(cmap, ncolors)	Generate a colorscale from a colormap and number of colors.
`is_notebook`()	Check if code is run in a notebook.
`check_spyder`()	Check if code is run inside Spyder.