pyacs.gts.Sgts module

Super class for a collection of geodetic time series (Sgts).

Sgts holds multiple Gts instances and provides methods to operate on them collectively.

class pyacs.gts.Sgts.Sgts(ts_dir='.', add_key='', verbose=True, name_filter='', read=True, sites=[], lexclude=[], type=None, xyz=True)[source]

Bases: object

add_offsets_dates(dates, verbose=False): add_offsets_dates to every Gts in current Sgts

append(gts)

Append a Gts to this Sgts (in-place).

Parameters:: gts (Gts) – Gts instance to append (key = gts.code).
Return type:: None

apply_coseismic(date, coseismic_en_gmt_file=None, coseismic_up_gmt_file=None, verbose=False, add=True)

Apply coseismic offsets from GMT psvelo files.

Parameters:

date (float) – Coseismic date in decimal year.
coseismic_en_gmt_file (str, optional) – GMT psvelo file with East-North displacement (mm). Default is None.
coseismic_up_gmt_file (str, optional) – GMT psvelo file with Up displacement (mm). Default is None.
verbose (bool, optional) – Verbose mode. Default is False.
add (bool, optional) – True = add offset, False = subtract. Default is True.

Returns:

New Sgts with coseismic offsets applied.

Return type:

Sgts

common_mode(lref=[], detrend_method='detrend_median', method='median', center=True, verbose=True)

Compute and remove common mode from time series.

Parameters:

lref (list, optional) – Site codes for reference (common mode). Default is [].
detrend_method (str, optional) – ‘detrend_median’ or ‘detrend’ for reference series. Default is ‘detrend_median’.
method (str, optional) – ‘median’ or ‘mean’ for common mode. Default is ‘median’.
center (bool, optional) – If True, center the stack. Default is True.
verbose (bool, optional) – Verbose mode. Default is True.

Returns:

New Sgts with filtered series and _CMM for the common mode.

Return type:

Sgts

Notes

Assumes daily time series.

compute_common_mode_l1trend(already_ivel=True, max_ivel=40)

This approach estimates a common mode from instantaneous velocity

parameter already_ivel: boolean, if True ts_ref are already results from l1trend

copy()

Return a deep copy of this Sgts.

Returns:: New Sgts instance.
Return type:: Sgts

correct_offsets_from_file(offset_file, fill_offsets_dates=False)

Read offsets from a text file and apply them to the time series.

Parameters:

offset_file (str) – Path to the offset file.
fill_offsets_dates (bool, optional) – If True, fill the offsets_dates attribute of each Gts. Default False.

Returns:

Copy of the current Sgts with offsets applied (one Gts per site that appears in the file and in the collection).

Return type:

Sgts

Notes

Offset file is whitespace-separated; lines starting with # are ignored. Expected columns: lon, lat, de, dn, du, sde, sdn, sdu, code, offset_date, offset_info. Displacements (de, dn, du, sde, sdn, sdu) are in mm in the file. Example:

#      lon        lat       de       dn       du      sde      sdn      sdu    code       offset_date        offset_info
  -79.1000     0.1000  -103.51     3.67     0.00     2.37     2.60     0.00    ARSH  2016-04-16T23:58  Mw7.8/-80.25/-0.12/22

dates(unit='decyear')

Return start and end dates of this Sgts.

Parameters:: unit (str, optional) – ‘decyear’ or ‘datetime’. Default is ‘decyear’.
Returns:: (start_date, end_date) in the chosen unit.
Return type:: tuple

delnone()

Remove all series with .data is None.

Returns:: New Sgts without None-data series.
Return type:: Sgts

delts(code)

Remove one time series from this Sgts (in-place).

Parameters:: code (str) – Site code to remove.
Return type:: None

frame(frame=None, euler=None, w=None, verbose=False)

Rotate time series according to an Euler pole.

Provide exactly one of: frame, euler, or w.

Parameters:

frame (str, optional) – Named frame: ‘soam’, ‘nas’, ‘nazca’, ‘inca’, ‘nas_wrt_soam’, ‘inca_wrt_soam’.
euler (str or list or numpy.ndarray, optional) – Euler pole: string ‘lon/lat/w’, list [lon,lat,w], or 1D array.
w (str or list or numpy.ndarray, optional) – Rotation rate (rad/yr): string ‘wx/wy/wz’, list [wx,wy,wz], or 1D array.

Returns:

New Sgts in the chosen frame.

Return type:

Sgts

Notes

Frame values from Nocquet et al., Nat. Geosci., 2014.

get_dates(fmt='isoformat')

Return start and end dates of all time series in this Sgts.

Parameters:: fmt (str, optional) – Output format: ‘isoformat’, ‘datetime’, ‘decyear’, ‘mjd’, ‘dayno’, ‘cal’. Default is ‘isoformat’.
Returns:: (start_date, end_date) in the requested format.
Return type:: tuple

Notes

Formats: isoformat (ISO 8601), datetime, decyear, mjd, dayno (dayno, year), cal (day, month, year).

get_unr(lcode=[], center=None, radius=None)

Download time series from UNR and append to this Sgts.

Parameters:

lcode (list, optional) – Site codes to download. Default is [].
center (list, optional) – [lon, lat] in decimal degrees for center of search.
radius (list, optional) – [min_radius, max_radius] in km.

Returns:

Time series are appended to self (in-place).

Return type:

None

gts(method, *args, **kwargs)

Apply a Gts method to every series in this Sgts.

Parameters:

method (str) – Name of the Gts method (e.g. ‘detrend’, ‘copy’).
*args (tuple) – Positional arguments for the method.
**kwargs (dict) – Keyword arguments for the method.

Returns:

New Sgts with results (or self for in-place methods).

Return type:

Sgts

Examples

>>> ts.gts('detrend', periods=[2010.0, 2013.0])

gts_mp(method, *args, **kwargs)

Apply a Gts method to each series in parallel (ProcessPoolExecutor).

Parameters:

method (str) – Gts method name (e.g. ‘detrend’).
*args (tuple) – Positional arguments for the method.
**kwargs (dict) – Keyword arguments; ncpu (int) sets number of CPUs (default 4).

Returns:

New Sgts with processed Gts instances.

Return type:

Sgts

has_ts(code)

Check if a time series with the given code exists in this Sgts.

Parameters:: code (str) – 4-character site code.
Returns:: True if code is in Sgts, False otherwise.
Return type:: bool

info(): Basic informations about time series included in the Gts instance.

lGts(lexclude=[], linclude=[])

Return list of Gts instances in this Sgts (after optional filters).

Parameters:

lexclude (list, optional) – Site codes to exclude. Default is [].
linclude (list, optional) – If non-empty, only these codes are included. Default is [].

Returns:

List of Gts instances (sorted by code).

Return type:

list

lcode(lexclude=[], linclude=[], min_obs=None, max_obs=None, min_duration=None, force_4_digit=False)

Return list of Gts codes in this Sgts (with optional filters).

Parameters:

lexclude (list, optional) – Site codes to exclude. Default is [].
linclude (list, optional) – If non-empty, only these codes are included. Default is [].
min_obs (int, optional) – Minimum number of epochs per site. Default is None.
max_obs (int, optional) – Maximum number of epochs per site. Default is None.
min_duration (float, optional) – Minimum duration in decimal year. Default is None.
force_4_digit (bool, optional) – If True, keep only 4-character code. Default is False.

Returns:

Site codes.

Return type:

list

make_distance_matrix_from_sgts()

Compute XYZ distance matrix (km) between all sites in this Sgts.

Returns:: Distance matrix in km (same order as sorted lcode()).
Return type:: numpy.ndarray

medvel(outdir=None, verbose=False)

Automatic velocity estimates using median estimator (MIDAS-style, Blewitt et al., 2016).

Fills the velocity attribute of every Gts. Optionally writes results to outdir.

Parameters:

outdir (str, optional) – Output directory for results. Default is None.
verbose (bool, optional) – Verbose mode. Default is False.

Returns:

Modified Sgts (velocity set for each Gts).

Return type:

Sgts

References

Blewitt et al. (2016), J. Geophys. Res. Solid Earth, 121(3), 2054-2068.

n(lexclude=[], linclude=[])

Return the number of Gts in this Sgts (after optional filters).

Parameters:

lexclude (list, optional) – Site codes to exclude. Default is [].
linclude (list, optional) – If non-empty, only these codes are counted. Default is [].

Returns:

Number of time series.

Return type:

int

nearest(site, n=1)

Return the n nearest sites to the given site.

Parameters:

site (str) – Site code to search from.
n (int, optional) – Number of nearest sites to return. Default is 1.

Returns:

List of site codes (nearest first), or None if site not in Sgts.

Return type:

list

plot_component(component='E', lorder=[], shift=10.0, Hshift={}, title=None, loffset=True, loutliers=True, verbose=False, date=[], yaxis=None, min_yaxis=None, yupaxis=None, xticks_minor_locator=1, error_scale=1.0, lperiod=[[]], lvline=[], save_dir_plots='.', save=None, show=True, unit='mm', date_unit='cal', date_ref=0.0, set_zero_at_date=None, superimposed=None, lcolor=[], label=None, legend=0.2, grid=True, plot_size=None, xlabel_fmt=None, **kwargs)

Plot one component for multiple time series using Matplotlib.

Coordinates in meters; default display unit mm (unit=’m’ for meters).

Parameters:

component (str, optional) – Component to plot (‘N’, ‘E’, ‘U’). Default is ‘E’.
lorder (list, optional) – Site code order (top to bottom). Default is [].
shift (float, optional) – Vertical shift between series in mm. Default is 10.
Hshift (dict, optional) – Per-code offset {‘code’: offset}. Default is {}.
title (str, optional) – Plot title. Default is None.
loffset (bool, optional) – Draw offset lines. Default is True.
loutliers (bool, optional) – Plot outliers. Default is True.
verbose (bool, optional) – Verbose mode. Default is False.
date (list, optional) – [sdate, edate] for range. Default is [].
yaxis (list, optional) – Y-axis limits; auto if not set.
min_yaxis (list, optional) – Y-axis limits; auto if not set.
yupaxis (list, optional) – Y-axis limits; auto if not set.
xticks_minor_locator (float or str, optional) – Minor tick spacing. Default is 1.
error_scale (float, optional) – Error bar scale (0 = none). Default is 1.0.
lperiod (list, optional) – Background periods. Default is [[]].
lvline (list, optional) – Dates for vertical lines. Default is [].
save_dir_plots (str, optional) – Save directory. Default is ‘.’.
save (bool or str, optional) – Save figure. Default is None.
show (bool, optional) – Show plot. Default is True.
unit (str, optional) – ‘m’, ‘cm’, ‘mm’. Default is ‘mm’.
date_unit (str, optional) – ‘decyear’, ‘cal’, ‘days’. Default is ‘cal’.
date_ref (float, optional) – Reference date. Default is 0.0.
set_zero_at_date (float, optional) – Date to align series. Default is None.
superimposed (Gts, optional) – Overlay Gts. Default is None.
lcolor (list, optional) – Colors for superimposed. Default is [].
label (str, optional) – Legend label. Default is None.
legend (float, optional) – Legend space (e.g. 0.2 = 20%). Default is 0.2.
grid (bool, optional) – Draw grid. Default is True.
plot_size (tuple, optional) – Figure size. Default is None.
xlabel_fmt (str, optional) – X-axis label format. Default is None.
**kwargs (dict, optional) – Passed to matplotlib.pyplot.errorbar.

Return type:

None

plot_data_sum(period=None)

generate an interactive plot showing available/missing data

param period: period used to checkk data availability. Uses pandas syntax. See examples. return self .. rubric:: Examples

ts.plot_data_sum(period=’2008’) willl show a summary for the whole year 2008 ts.plot_data_sum(period=[‘2008-01-15’,’2011-01-01’]) willl show a summary for the period Dispay will include all time series in ts. Combine with ts selection to obtain more specific behaviour. ts.sub(linclude=[‘XXXX’,’YYYY’]).plot_data_sum(period=’2008’) will plot data availability only for ‘XXXX’ and ‘YYYY’ ts.sel_radius(‘XXXX’,[0,50]).sel_period([2008,2015],min_data=1000).plot_data_sum(period=’2008’) will show data availability for year 2008, only for sites less than 50 km from XXXX and having a minimum of 1000 days between 2008 and 2015.

read_gmt(gmt=True, verbose=False, vel=False)

Read GMT psvelo file and set lon/lat (and optionally velocity) for each Gts.

Parameters:

gmt (bool or str, optional) – True = read ‘../stat/pyacs_void.gmt’; str = path to GMT file. Default is True.
verbose (bool, optional) – Verbose mode. Default is False.
vel (bool, optional) – If True, fill .velocity from file. Default is False.

Returns:

Modifies self in place.

Return type:

None

Notes

Always in-place.

read_gts_conf(gts_conf_file, verbose=False): Reads a gts_conf_file implemented commands in the file are: #todo add_break [site] [date] # date is either [decyear] [doy year] [mday month year] apply_offset [site] [offset_north,offset_east,offset_up] [date] # offset applied is in mm, date is either [decyear] [doy year] [mday month year] remove_offset [site] [offset_north,offset_east,offset_up] [date] # offset removed is in mm, date is either [decyear] [doy year] [mday month year] #todo extract_periods [site] [date1,date2] # date is either [decyear] [doy year] [mday month year] #todo exclude_periods [site] [date1,date2] # date is either [decyear] [doy year] [mday month year] #todo remove_day [site] [date]

read_soln(soln, verbose=True)

Read IGS soln file and set offsets_dates from solution (P) changes.

Parameters:

soln (str) – Path to IGS soln.snx file.
verbose (bool, optional) – Verbose mode. Default is True.

Returns:

Modifies self in place.

Return type:

None

Notes

In-place: populates offsets_dates for each Gts from soln discontinuities.

read_ts(ts_dir='.', verbose=True, name_filter='', add_key='', sites=[], lexclude=[], type=None, xyz=True)

Read time series from directory; format is auto-detected or set by type.

Supported formats: pos, kenv, mb_file, cats, txyz (pyacs), track (NEU), pride, pck.

Parameters:

ts_dir (str, optional) – Directory of time series files. Default is ‘.’.
verbose (bool, optional) – If True, print progress. Default is True.
name_filter (str, optional) – Filter on time series name (’name_filter’).
add_key (str, optional) – String to add before site code.
sites (list, optional) – If non-empty, only these site codes are read.
lexclude (list, optional) – Site codes to exclude from reading.
type (str, optional) – Format: ‘pos’, ‘kenv’, ‘mb_file’, ‘cats’, ‘txyz’, ‘track’, ‘pride’, ‘pck’.
xyz (bool, optional) – For pos files, read XYZ rather than dNEU. Default is True.

Returns:

Time series are appended to this Sgts instance (in-place).

Return type:

None

remove_observations(observations_to_remove, date_tolerance=0.25, verbose=False)

Remove observations given as (code, date) pairs.

Parameters:

observations_to_remove (list of tuple) – (code, date) with date in decimal year.
date_tolerance (float, optional) – Date matching tolerance in days. Default is 0.25.
verbose (bool, optional) – Verbose mode. Default is False.

Returns:

New Sgts with specified observations removed.

Return type:

Sgts

Notes

Date matching uses the same tolerance as other pyacs methods.

same_site(dc=10, in_place=True, verbose=False)

Check that all gts in the current Sgts are actually the same site. If a given time series is found to be of two separate sites, then a new gts is added to the return Sgts instance.

param dc: critical distance to decide to split the time series param in_place: if True modify current Sgts, False retuen a new Sgts param verbose: verbose mode

return: a new Sgts instance

save_velocity(vel_file='../stat/vel', en=True, up=True)

Save horizontal and up velocities in GMT psvelo format from .velocity attributes.

Parameters:

vel_file (str, optional) – Output basename (e.g. ‘../stat/vel’ -> _en.gmt, _up.gmt). Default is ‘../stat/vel’.
en (bool, optional) – If True, write East & North velocity. Default is True.
up (bool, optional) – If True, write Up velocity. Default is True.

Returns:

self.

Return type:

Sgts

sel_from_grid(grid, depth_range=[0, 200])

Select sites above a grid (e.g. slab2) within a depth range.

Parameters:

grid (str) – Path to NetCDF grid file.
depth_range (list, optional) – [depth_min_km, depth_max_km]. Default is [0, 200].

Returns:

New Sgts with selected time series.

Return type:

Sgts

sel_period(period, min_data=2, verbose=True)

Select time series that have data in the given period.

Parameters:

period (list) – [start, end] in decimal years.
min_data (int, optional) – Minimum number of points required to keep a series. Default is 2.
verbose (bool, optional) – Verbose mode. Default is True.

Returns:

New Sgts instance.

Return type:

Sgts

sel_radius(center, range, verbose=True)

Select time series for sites within a radius range around center.

Parameters:

center (list or str) – [lon, lat] in decimal degrees, or site code.
range (list or float) – [min_radius_km, max_radius_km], or single max_radius_km, or site code.
verbose (bool, optional) – Verbose mode. Default is True.

Returns:

New Sgts instance.

Return type:

Sgts

sel_radius_eq(eq, time=None, verbose=True)

Select time series potentially impacted by an earthquake.

Parameters:

eq (list) – [lon, lat, magnitude]; epicenter in decimal degrees.
time (float, optional) – Earthquake time in decimal year. Default is None.
verbose (bool, optional) – If True, print progress. Default is True.

Returns:

New Sgts with offset_dates set at eq time.

Return type:

Sgts

Notes

Radius from NGL formula: radius = 10**(magnitude/2 - 0.79).

sel_rectangle(bounds, verbose=True)

Select time series for sites inside a rectangular bounds.

Parameters:

bounds (list) – [lon_min, lon_max, lat_min, lat_max] in decimal degrees.
verbose (bool, optional) – Verbose mode. Default is True.

Returns:

New Sgts instance.

Return type:

Sgts

show_ivel_map_gmt(day, topo=False, projection='M10', region=None, eq_lon_lat=None, scale_gps=0.1, gps_scale=0.01, no_clip=True, show='external', save_dir=None)

Make a map of instantaneous velocity (ivel) using pygmt.

Parameters: day (tuple, datetime, float, or list): Day to read. Can be (day, month, year) tuple, datetime object, decimal year, or a list of these. topo (bool): If True, shaded topography will be shown in the background. Default is False. projection (str): Projection type for the map. Default is “M10”. region (list): List defining the region to plot [min_lon, max_lon, min_lat, max_lat]. If None, it will be determined from data. eq_lon_lat (tuple): Tuple of earthquake longitude and latitude to plot. Default is None. scale_gps (float): Scale for GPS vectors. Default is 0.1. gps_scale (float): Scale for GPS uncertainty vectors. Default is 0.01. no_clip (bool): If True, vectors will not be clipped at the map boundaries. Default is True. show (str): ‘external’ or ‘notebook’ to show the plot. Anything else will not show the plot. Default is ‘external’. save_dir (str): Directory to save the plot. If None, the plot will not be saved. Default is None.

Returns: None

show_map(bounds=None, resolution='l', highlight=[], tile=False, tile_provider='OpenTopoMap', figsize=(7, 9), show=True, save=False, velocity=False, title=None)

Show map of Sgts sites (optionally with velocity).

Parameters:

bounds (list, optional) – [min_lon, max_lon, min_lat, max_lat]. Default is None (auto).
resolution (str, optional) – ‘c’, ‘l’, ‘i’, ‘h’, ‘f’. Default is ‘l’.
highlight (list, optional) – Site codes to highlight. Default is [].
tile (bool, optional) – If True, use tile_provider (requires internet). Default is False.
tile_provider (str, optional) – ‘OpenTopoMap’ or ‘OpenStreetMap.Mapnik’. Default is ‘OpenTopoMap’.
figsize (tuple, optional) – Figure size. Default is (7, 9).
show (bool, optional) – If True, show plot. Default is True.
save (bool, optional) – If True, save figure. Default is False.
velocity (bool, optional) – If True, plot velocities. Default is False.
title (str, optional) – Plot title. Default is None.

Return type:

self

stat_site(lsite=[], lsite_file=None, verbose=False, save_dir=None, save_file=None, display=True)

Compute basic statistics for each time series.

Parameters:

lsite (list, optional) – Site codes to include. Default is [].
lsite_file (str, optional) – File listing site codes. Default is None.
verbose (bool, optional) – Verbose mode. Default is False.
save_dir (str, optional) – Directory for output files. Default is None.
save_file (str, optional) – Single file for all statistics. Default is None.
display (bool, optional) – Print to screen. Default is True.

Return type:

None

sub(lexclude=[], linclude=None)

Return new Sgts with subset by exclude/include lists.

Parameters:

lexclude (list, optional) – Site codes to exclude. Default is [].
linclude (list, optional) – If not None, only these codes are kept; default None means linclude is ignored.

Returns:

New Sgts instance.

Return type:

Sgts

to_displacement(verbose=True, base_name='vel', wdir='.', up=False): print displacements every dates as gmt psvelo files

to_kml(kml_file)

Write a KML file with site locations.

Parameters:: kml_file (str) – Output KML file path.
Return type:: self

to_obs_tensor(rounding='day', verbose=False)

Return ENU data as a 3D tensor and site code array.

Parameters:

rounding (str, optional) – ‘day’, ‘hour’, or ‘second’ for date rounding. Default is ‘day’.
verbose (bool, optional) – Verbose mode. Default is False.

Returns:

(T_OBS, np_names, np_date_s); T_OBS[k,i,0] = East at date k, site i (mm).

Return type:

tuple

Notes

T_OBS is 3D (dates x sites x components), values in mm.

to_tsnpz(ofile, rounding='day', verbose=False)

Write Sgts to an npz file.

Arrays saved: T_OBS (3D, mm), np_names_t_obs (site codes), np_obs_date_s (pyacs seconds), np_coo (lon, lat, height per site).

Parameters:

ofile (str) – Output file path (.npz).
rounding (str, optional) – ‘day’, ‘hour’, or ‘second’ for date rounding. Default is ‘day’.
verbose (bool, optional) – Verbose mode. Default is False.

Return type:

None

to_tspck(rounding='day', save=None, verbose=False)

returns a pickle with the following numpy array

T_OBS: observation array of dim 3. T_OBS[k,i,0] returns the East value at the k_th date for site i in mm np_names_t_obs: np_names_t_obs[i] is the code of site i np_obs_date_s: time series dates in pyacs seconds np_coo: for site i, np_coo[i,0] is longitude, np_coo[i,1] latitude and np_coo[i,1] ellipsoidal height

Parameters:

sgts – Sgts instance
rounding – ‘day’,’hour’,’second’. all dates will be rounded to the nearest chosen day, hour or second. default is ‘day’
save – output file name for writing. Extension is .tspck
verbose – boolean for verbose mode

Returns:

object

Note:

tspck file to be read with read_tspck

write_pck(outfile, verbose=True)

Write this Sgts to a pickle (.pck) file.

Parameters:

outfile (str) – Output file path (.pck added if no extension).
verbose (bool, optional) – Verbose mode. Default is True.

Return type:

None