pytomoatt.src_rec
This content is for v0.3.0. Switch to the latest version for up-to-date documentation.
SrcRec
Section titled “SrcRec”I/O for source <–> receiver file
Parameters
| Name | Type | Description |
|---|---|---|
fname |
str |
Path to src_rec file |
src_only |
(bool, optional) |
Whether to read only source information, defaults to False (default: False) |
Constructor
__init__(fname: str, src_only=False)Attributes
Section titled “Attributes”SrcRec.rec_points
Section titled “SrcRec.rec_points”Return a DataFrame of all receivers
Returns
| Type | Description |
|---|---|
| `pandas.DataFrame |
Receivers contain 9 ~ 11 columns:
Common fields
Section titled “Common fields”================ =====================================================
Column Description
================ =====================================================
src_index Index of source recorded by the receiver
rec_index Index of receivers that recorded the same source
staname Name of the receiver
stla Latitude of the receiver
stlo Longitude of the receiver
stel Elevation of the receiver
phase Phase name
tt Travel time of the source receiver pair
weight Weight of the receiver applied on objective function
================ =====================================================
Optional fields
Section titled “Optional fields”================ ===========================================================================
Column Description
================ ===========================================================================
netname Name of the network (when name_net_and_sta=True in SrcRec.read)
dist_deg Epicentral distance in deg (when dist_in_data=True in SrcRec.read)
dist_km Epicentral distance in km
dist_3d_km Three-dimensional source–receiver distance in km
================ ===========================================================================` | All receivers |
SrcRec.rec_points_cr
Section titled “SrcRec.rec_points_cr”Return a DataFrame of all common receivers
Returns
| Type | Description |
|---|---|
| `pandas.DataFrame |
Common receivers contain 13 columns:
================ =====================================================
Column Description
================ =====================================================
src_index Index of source recorded by the receiver
rec_index Index of receivers that recorded the same source
staname Name of the receiver
stla Latitude of the receiver
stlo Longitude of the receiver
stel Elevation of the receiver
src_index2 Index of the source recorded by the receiver
event_id2 ID of the source
evla2 Latitude of the source
evlo2 Longitude of the source
evdp2 Focal depth
phase Phase name
tt Travel time of the source receiver pair
weight Weight of the receiver applied on objective function
================ =====================================================` | All common receivers |
SrcRec.rec_points_cs
Section titled “SrcRec.rec_points_cs”Return a DataFrame of all common sources
Returns
| Type | Description |
|---|---|
| `pandas.DataFrame |
Common sources contain 14 columns:
================ =====================================================
Column Description
================ =====================================================
src_index Index of source recorded by the receiver
rec_index1 Index of receivers that recorded the same source
staname1 Name of the receiver
stla1 Latitude of the receiver
stlo1 Longitude of the receiver
stel1 Elevation of the receiver
rec_index2 Index of the source recorded by the receiver
staname2 Name of the receiver
stla2 Latitude of the receiver
stlo2 Longitude of the receiver
stel2 Elevation of the receiver
phase Phase name
tt Travel time of the source receiver pair
weight Weight of the receiver applied on objective function
================ =====================================================` | All common sources |
SrcRec.src_points
Section titled “SrcRec.src_points”Return a DataFrame of all sources
Returns
| Type | Description |
|---|---|
| `pandas.DataFrame |
Sources contain 8 columns:
================ ===================================================
Column Description
================ ===================================================
origin_time Origin time of the source
evla Latitude of the source
evlo Longitude of the source
evdp Focal depth
mag Magnitude of the source
num_rec Number of receivers that recorded the source
event_id ID of the source
weight Weight of the source applied on objective function
================ ===================================================` | All sources |
Methods
Section titled “Methods”SrcRec.add_noise
Section titled “SrcRec.add_noise”SrcRec.add_noise(range_in_sec=0.1, mean_in_sec=0.0, shape='gaussian')Add random noise on travel time
Parameters
| Name | Type | Description |
|---|---|---|
mean_in_sec |
(float, optional) |
Mean of the noise in sec, defaults to 0.0 (default: 0.0) |
range_in_sec |
(float, optional) |
Maximun noise in sec, defaults to 0.1 (default: 0.1) |
shape |
str. options: gaussian | uniform |
shape of the noise distribution probability (default: 'gaussian') |
SrcRec.add_noise_to_source
Section titled “SrcRec.add_noise_to_source”SrcRec.add_noise_to_source(lat_pert=0.1, lon_pert=0.1, depth_pert=10, tau_pert=0.5)Add random noise on source location
Parameters
| Name | Type | Description |
|---|---|---|
lat_pert |
(float, optional) |
Maximum perturbation on latitude in degree, defaults to 0.1 (default: 0.1) |
lon_pert |
(float, optional) |
Maximum perturbation on longitude in degree, defaults to 0.1 (default: 0.1) |
depth_pert |
(float, optional) |
Maximum perturbation on depth in km, defaults to 10 (default: 10) |
tau_pert |
(float, optional) |
Maximum perturbation on origin time in sec, defaults to 0.0 (default: 0.5) |
SrcRec.append
Section titled “SrcRec.append”SrcRec.append(sr, **kwargs)Append another SrcRec object to the current one
For sources with the same event_id, keep the first one. For receivers (rec_points, rec_points_cs, rec_points_cr), merge all data under the same event_id and recalculate receiver counts.
Parameters
| Name | Type | Description |
|---|---|---|
sr |
SrcRec |
Another SrcRec object |
kwargs |
— |
Additional keyword arguments for updating duplicate receivers (default: {}) |
SrcRec.box_weighting
Section titled “SrcRec.box_weighting”SrcRec.box_weighting(d_deg: float, d_km: float | None = None, obj='both', dd_weight='average')Weighting sources and receivers by number in each subgrid
Parameters
| Name | Type | Description |
|---|---|---|
d_deg |
float |
grid size along lat and lon in degree |
d_km |
float | None |
Grid size along the depth axis in km. Required only when obj="src" or obj="both", defaults to None. (default: None) |
obj |
(str, optional) |
Object to be weighted, options: src, rec or both, defaults to both (default: 'both') |
dd_weight |
— |
Weighting method for double difference, options: average, multiply, defaults to average (default: 'average') |
SrcRec.calc_distaz
Section titled “SrcRec.calc_distaz”SrcRec.calc_distaz()Calculate distance and azimuth for each source–receiver pair.
dist_deg and dist_km are the epicentral distance in degrees
and kilometres, respectively. dist_3d_km is the three-dimensional
Euclidean distance calculated from dist_km and the vertical
separation. Source depth is in km and receiver elevation is converted
from m to km.
SrcRec.copy
Section titled “SrcRec.copy”SrcRec.copy()Return a copy of SrcRec object
Returns
| Type | Description |
|---|---|
SrcRec |
Copy of SrcRec object |
SrcRec.count_events_per_station
Section titled “SrcRec.count_events_per_station”SrcRec.count_events_per_station()count events per station
SrcRec.erase_duplicate_events
Section titled “SrcRec.erase_duplicate_events”SrcRec.erase_duplicate_events(thre_deg: float, thre_dep: float, thre_time_in_min: float, **kwargs)check and count how many events are duplicated, under given threshold of distance, depth, and time.
Parameters
| Name | Type | Description |
|---|---|---|
thre_deg |
float |
threshold of distance in degree |
thre_dep |
float |
threshold of distance in degree |
thre_time_in_min |
float |
hreshold of time in minutes |
SrcRec.erase_src_with_no_rec
Section titled “SrcRec.erase_src_with_no_rec”SrcRec.erase_src_with_no_rec()erase src_points with no rec_points
SrcRec.from_seispy
Section titled “SrcRec.from_seispy”SrcRec.from_seispy(rf_path: str)Read and convert source and station information from receiver function data calculated by Seispy
Parameters
| Name | Type | Description |
|---|---|---|
rf_path |
str |
Path to receiver functions calculated by Seispy |
Returns
| Type | Description |
|---|---|
SrcRec |
New instance of class SrcRec |
SrcRec.generate_double_difference
Section titled “SrcRec.generate_double_difference”SrcRec.generate_double_difference(type='cs', max_azi_gap=15, max_dist_gap=2.5, dd_weight='average', recalc_baz=False, same_phase=True, dis_type='dis_dif', **kwargs)Generate double difference data
Parameters
| Name | Type | Description |
|---|---|---|
type |
(str, optional) |
Type of double difference, options: cr, cs or both, defaults to cs (default: 'cs') |
max_azi_gap |
(float, optional) |
Maximum azimuthal gap for selecting events, defaults to 15 (default: 15) |
max_dist_gap |
(float, optional) |
Maximum distance gap in degrees for selecting pairs, defaults to 2.5 (default: 2.5) |
dd_weight |
— |
Weighting method for double difference, options: average, multiply, defaults to average (default: 'average') |
recalc_baz |
(bool, optional) |
Recalculate azimuth and back azimuth, defaults to False (default: False) |
same_phase |
(bool, optional) |
Only pair records with the same phase, defaults to True (default: True) |
dis_type |
`str, optional |
self.rec_points_cr | self.rec_points_cs are generated| Distance constraint type.“dis_dif”compares the difference between the two source--receiver epicentral distances.“dis_pair”compares the station--station separation for common-source pairs and event--event separation for common-receiver pairs, defaults to“dis_dif”. (default: ‘dis_dif’`) |
SrcRec.geo_weighting
Section titled “SrcRec.geo_weighting”SrcRec.geo_weighting(scale=0.5, obj='both', dd_weight='average')Calculate and assign normalized geographical weights.
Source and receiver weights are normalized so that the maximum of each calculated population is one before weights are propagated to absolute and double-difference records. Consequently, all generated weights are no greater than one.
Parameters
| Name | Type | Description |
|---|---|---|
scale |
(float, optional) |
Scale of reference distance parameter. See equation 22 in Ruan et al., (2019). The reference distance is given by scale* dis_average, defaults to 0.5 (default: 0.5) |
obj |
(str, optional) |
Object to be weighted, options: src, rec or both, defaults to both (default: 'both') |
dd_weight |
— |
Weighting method for double difference data, options: average or multiply, defaults to average (default: 'average') |
SrcRec.linear_regression
Section titled “SrcRec.linear_regression”SrcRec.linear_regression(phase=None, recalc_dist=False, distance='dist_3d_km')Fit travel time as a linear function of distance.
This method only computes regression parameters; it does not filter travel-time records. Non-finite distance/travel-time pairs are ignored by the fit.
Parameters
| Name | Type | Description |
|---|---|---|
phase |
str | None |
Fit only this phase. When None, all phases are used, defaults to None. (default: None) |
recalc_dist |
bool |
Recalculate distance fields even when the selected field exists, defaults to False. (default: False) |
distance |
str |
Independent variable used by the fit. Choose "dist_deg" for epicentral distance in degrees or "dist_km" for epicentral distance in km, or "dist_3d_km" for three-dimensional source–receiver distance in km, defaults to "dist_3d_km". (default: 'dist_3d_km') |
Returns
| Type | Description |
|---|---|
tuple of float |
(slope, intercept, residual_std). Slope is in s/degree for dist_deg or s/km for the kilometre fields; the other values are in s. |
SrcRec.plot
Section titled “SrcRec.plot”SrcRec.plot(color_by='depth', fname=None, **kwargs)Plot sources and receivers with source-depth sections.
Parameters
| Name | Type | Description |
|---|---|---|
color_by |
(str, optional) |
Source attribute used for color mapping; either "depth" or "weight", defaults to "depth" (default: 'depth') |
fname |
(str, optional) |
Path to output file, defaults to None (default: None) |
kwargs |
— |
Additional keyword arguments passed to Matplotlib’s Axes.scatter for source points, such as cmap, s, alpha, marker, vmin and vmax (default: {}) |
Returns
| Type | Description |
|---|---|
matplotlib.figure.Figure |
matplotlib figure |
SrcRec.plot_travel_time
Section titled “SrcRec.plot_travel_time”SrcRec.plot_travel_time(color=None, fname=None, fig=None, ylim='adaptive', distance='dist_3d_km', **kwargs)Plot absolute travel time against source–receiver distance.
If the selected distance field is unavailable, epicentral distance is
calculated before plotting.
The returned Matplotlib figure remains editable; use
figure.axes[0] to add lines, annotations, or other content.
Parameters
| Name | Type | Description |
|---|---|---|
distance |
(str, optional) |
Distance field used for the x-axis. Choose "dist_3d_km" for three-dimensional distance, "dist_deg" for epicentral distance in degrees, or "dist_km" for epicentral distance in km, defaults to "dist_3d_km". (default: 'dist_3d_km') |
color |
— |
Matplotlib-compatible point color. When None, the next color from the current axis color cycle is used. (default: None) |
fname |
(str, optional) |
Path to output file, defaults to None. (default: None) |
fig |
(matplotlib.figure.Figure, optional) |
Existing Matplotlib figure on which to draw, defaults to None. Its current axis is used, or one is created when necessary. (default: None) |
ylim |
— |
Y-axis scaling strategy. Use "adaptive" to derive limits from travel times at the minimum and maximum epicentral distances, "auto" for Matplotlib autoscaling, "inherit" to preserve the limits of an existing figure, or pass (min, max) explicitly. (default: 'adaptive') |
kwargs |
— |
Additional keyword arguments passed to Matplotlib’s Axes.scatter. (default: {}) |
Returns
| Type | Description |
|---|---|
matplotlib.figure.Figure |
Matplotlib figure. |
SrcRec.read
Section titled “SrcRec.read”SrcRec.read(fname: str, dist_in_data=False, name_net_and_sta=False, conflicting_receiver_action='error', **kwargs)Read source <–> receiver file to pandas.DataFrame
Source indices in the file are treated as local labels and may be
duplicated. Sources are reassigned consecutive src_index values
from zero in file order, and all receiver records are remapped to the
new indices using source blocks and unique event IDs.
Parameters
| Name | Type | Description |
|---|---|---|
fname |
str |
Path to src_rec file |
dist_in_data |
bool |
Whether distance is included in the src_rec file (default: False) |
name_net_and_sta |
bool |
Whether to include network and station name in the src_rec file (default: False) |
conflicting_receiver_action |
str |
How to handle a receiver name that has multiple coordinates/elevations. "error" lists every conflicting receiver location and stops reading; "remove" removes all observations involving those receiver names; "max_count" keeps the location with the highest occurrence count and removes observations at other locations; and "rename" keeps the locations and appends _A, _B, … to distinguish them. (default: 'error') |
Returns
| Type | Description |
|---|---|
SrcRec |
class of SrcRec |
SrcRec.remove_duplicate_rec_by_src
Section titled “SrcRec.remove_duplicate_rec_by_src”SrcRec.remove_duplicate_rec_by_src(mode='first')Remove duplicate receivers for the same source.
Parameters
| Name | Type | Description |
|---|---|---|
mode |
str |
Either “first” (keep only the first occurrence) or “mean” (average travel time tt and weight if present). (default: 'first') |
Raises
ValueError— If an unsupported mode is provided.
SrcRec.remove_rec_by_new_src
Section titled “SrcRec.remove_rec_by_new_src”SrcRec.remove_rec_by_new_src()remove rec_points by new src_points
SrcRec.remove_specified_recs
Section titled “SrcRec.remove_specified_recs”SrcRec.remove_specified_recs(rec_list, **kwargs)Remove specified receivers
Receiver observations are removed from absolute, common-source, and common-receiver records.
Parameters
| Name | Type | Description |
|---|---|---|
rec_list |
list |
List of receivers to be removed |
SrcRec.remove_src_by_duplicate_event_id
Section titled “SrcRec.remove_src_by_duplicate_event_id”SrcRec.remove_src_by_duplicate_event_id(keep='first')remove src_points by duplicated event_id
Parameters
| Name | Type | Description |
|---|---|---|
keep |
(str, optional) |
keep first or last duplicated event_id, defaults to “first” available options are “first” and “last” (default: 'first') |
SrcRec.remove_src_by_new_rec
Section titled “SrcRec.remove_src_by_new_rec”SrcRec.remove_src_by_new_rec()remove src_points by new receivers
SrcRec.reset_index
Section titled “SrcRec.reset_index”SrcRec.reset_index(start=0)Reset index of source and receivers.
SrcRec.rotate
Section titled “SrcRec.rotate”SrcRec.rotate(clat: float, clon: float, angle: float, reverse=False)Rotate sources and receivers around a center point
Parameters
| Name | Type | Description |
|---|---|---|
clat |
float |
Latitude of the center |
clon |
float |
Longitude of the center |
angle |
float |
anti-clockwise angle in degree |
SrcRec.select_by_azi_gap
Section titled “SrcRec.select_by_azi_gap”SrcRec.select_by_azi_gap(max_azi_gap: float, **kwargs)Select sources with azimuthal gap greater and equal than a number
Parameters
| Name | Type | Description |
|---|---|---|
azi_gap |
float |
threshold of minimum azimuthal gap |
SrcRec.select_by_box_region
Section titled “SrcRec.select_by_box_region”SrcRec.select_by_box_region(region, **kwargs)Select sources and station in a box region
Parameters
| Name | Type | Description |
|---|---|---|
region |
iterable |
Box region defined as [lon1, lon2, lat1, lat2] |
SrcRec.select_by_constant_velocity
Section titled “SrcRec.select_by_constant_velocity”SrcRec.select_by_constant_velocity(velocity, tt_res_range, distance='dist_km', recalc_dist=False, **kwargs)Select arrivals around a constant-velocity travel-time curve.
An arrival is retained when its travel-time residual satisfies
tt_res_range[0] < tt - distance / velocity < tt_res_range[1].
distance may be "dist_km" for epicentral distance or
"dist_3d_km" for three-dimensional distance. Both are measured in
kilometres. The residual bounds may be asymmetric. Non-finite
distances or travel times are removed.
Parameters
| Name | Type | Description |
|---|---|---|
velocity |
float |
Constant reference velocity in kilometres per second. |
tt_res_range |
list | tuple |
Exclusive travel-time residual range in seconds, (min_residual, max_residual). |
distance |
(str, optional) |
Distance used to calculate the reference travel time; either "dist_km" for epicentral distance or "dist_3d_km" for three-dimensional distance, defaults to "dist_km". (default: 'dist_km') |
recalc_dist |
bool |
Recalculate distance even when the selected distance column exists, defaults to False. (default: False) |
SrcRec.select_by_datetime
Section titled “SrcRec.select_by_datetime”SrcRec.select_by_datetime(time_range, **kwargs)select sources and station in a time range
Parameters
| Name | Type | Description |
|---|---|---|
time_range |
iterable |
Time range defined as [start_time, end_time] |
SrcRec.select_by_depth
Section titled “SrcRec.select_by_depth”SrcRec.select_by_depth(dep_min_max, **kwargs)Select sources in a range of depth
Parameters
| Name | Type | Description |
|---|---|---|
dep_min_max |
sequence |
limit of depth, [dep_min, dep_max] |
SrcRec.select_by_distance
Section titled “SrcRec.select_by_distance”SrcRec.select_by_distance(dist_min_max, recalc_dist=False, distance='dist_deg', **kwargs)Select source–receiver pairs in a range of distance.
Parameters
| Name | Type | Description |
|---|---|---|
dist_min_max |
list | tuple |
Distance limits, [dist_min, dist_max]. Their unit follows distance. |
recalc_dist |
bool |
Recalculate distance fields even when the selected field exists, defaults to False. (default: False) |
distance |
str |
Distance field used for selection. Choose "dist_deg" for degrees or "dist_km" for km, defaults to "dist_deg". (default: 'dist_deg') |
SrcRec.select_by_linear_regression
Section titled “SrcRec.select_by_linear_regression”SrcRec.select_by_linear_regression(std_multiplier=3.0, recalc_dist=False, separate_phase=True, distance='dist_3d_km', **kwargs)Select absolute travel times by linear-regression residual.
A straight line is fitted between the selected distance and travel
time. Records whose absolute residual is greater than std_multiplier
times the residual standard deviation are removed. By default each
phase is fitted separately so that phases with different apparent
velocities are not mixed.
Parameters
| Name | Type | Description |
|---|---|---|
std_multiplier |
float |
Multiplier applied to the residual standard deviation, defaults to 3. (default: 3.0) |
recalc_dist |
bool |
Recalculate distance fields even when the selected field exists, defaults to False. (default: False) |
separate_phase |
bool |
Fit each phase separately, defaults to True. (default: True) |
distance |
str |
Independent variable used by the fit. Choose "dist_deg" for epicentral distance in degrees or "dist_km" for epicentral distance in km, or "dist_3d_km" for three-dimensional source–receiver distance in km, defaults to "dist_3d_km". (default: 'dist_3d_km') |
Returns
| Type | Description |
|---|---|
dict |
Mapping from phase name to (slope, intercept, residual_std). When separate_phase=False, the key is "all". |
SrcRec.select_by_num_rec
Section titled “SrcRec.select_by_num_rec”SrcRec.select_by_num_rec(num_rec: int, **kwargs)select sources with recievers greater and equal than a number
Parameters
| Name | Type | Description |
|---|---|---|
num_rec |
int |
threshold of minimum receiver number |
SrcRec.select_by_phase
Section titled “SrcRec.select_by_phase”SrcRec.select_by_phase(phase_list, **kwargs)select interested phase and remove others
Parameters
| Name | Type | Description |
|---|---|---|
phase_list |
list of str |
List of phases for travel times used for inversion |
SrcRec.select_one_event_in_each_subgrid
Section titled “SrcRec.select_one_event_in_each_subgrid”SrcRec.select_one_event_in_each_subgrid(d_deg: float, d_km: float, **kwargs)select one event in each subgrid
Parameters
| Name | Type | Description |
|---|---|---|
d_deg |
float |
grid size along lat and lon in degree |
d_km |
float |
grid size along depth axis in km |
SrcRec.sort
Section titled “SrcRec.sort”SrcRec.sort(by='origin_time')Sort sources by given column
Parameters
| Name | Type | Description |
|---|---|---|
by |
(str, optional) |
Column to sort by, defaults to origin_time available columns are origin_time, evla, evlo, evdp, mag, num_rec, event_id, weight (default: 'origin_time') |
SrcRec.to_utm
Section titled “SrcRec.to_utm”SrcRec.to_utm(zone)Convert sources and receivers to UTM coordinates
Parameters
| Name | Type | Description |
|---|---|---|
zone |
int |
UTM zone number |
SrcRec.update
Section titled “SrcRec.update”SrcRec.update(mode='mean')Update SrcRec.src_points, SrcRec.rec_points,
SrcRec.rec_points_cr and SrcRec.rec_points_cs with procedures:
- remove receivers by new sources
- remove sources by new receivers
- update num_rec
- reset index
- update unique sources and receivers
- remove duplicate receivers by source
Parameters
| Name | Type | Description |
|---|---|---|
mode |
(str, optional) |
“first” to keep only the first occurrence of duplicate receivers, “mean” to average travel time, defaults to “mean” (default: 'mean') |
SrcRec.update_num_rec
Section titled “SrcRec.update_num_rec”SrcRec.update_num_rec()update num_rec in src_points by current rec_points
SrcRec.update_unique_src_rec
Section titled “SrcRec.update_unique_src_rec”SrcRec.update_unique_src_rec(conflicting_receiver_action='error')Update unique sources and receivers
The unique sources and receivers are stored
in SrcRec.sources and SrcRec.receivers respectively.
Parameters
| Name | Type | Description |
|---|---|---|
conflicting_receiver_action |
str |
How to handle receiver names with multiple coordinates/elevations. "error" raises a ValueError containing all conflicting locations; "remove" removes all observations involving those names; "max_count" keeps the location with the highest occurrence count and removes observations at other locations; and "rename" appends _A, _B, … to each distinct location. (default: 'error') |
SrcRec.write
Section titled “SrcRec.write”SrcRec.write(fname='src_rec_file')Write sources and receivers to ASCII file for TomoATT
Parameters
| Name | Type | Description |
|---|---|---|
fname |
(str, optional) |
Path to the src_rec file, defaults to ‘src_rec_file’ (default: 'src_rec_file') |
SrcRec.write_receivers
Section titled “SrcRec.write_receivers”SrcRec.write_receivers(fname: str)Write receivers to a txt file.
Parameters
| Name | Type | Description |
|---|---|---|
fname |
str |
Path to output txt file of receivers |
SrcRec.write_sources
Section titled “SrcRec.write_sources”SrcRec.write_sources(fname: str)Write sources to a txt file.
Parameters
| Name | Type | Description |
|---|---|---|
fname |
str |
Path to output txt file of sources |