Time series library

PYACS includes two main classes:

Gts objects are individual time series
- Gts allow to read, write, plot, detrend, filter individual time series
- gts_class: Gts structure description
- gts_methods: list of Gts methods available
- time_series: tutorial and jupyter notebooks to get started
Sgts objects are a list of Gts objects
- sgts_class: Gts structure description

Expert users can also use the tensor format ./pyacs.gts.tensor_ts.

Gts class API

Full reference: pyacs.gts.Gts.Gts

The Gts class holds NEU (or XYZ) time series with metadata (code, lon/lat/h, velocity, offsets, etc.). Below is a summary of available methods by category.

Summary of available methods

Read / write and format

Method	Description
`read()`	Read time series from file (format auto-detected or set by `fmt`).
`read_pos()`	Read GAMIT/GLOBK pos format.
`read_pride()`	Read PRIDE kinematics format.
`read_cats_file()`	Read CATS format.
`read_series()`	Read series format.
`write_pos()`	Write to pos format.
`write_cats()`	Write to CATS format.
`to_pandas_df()`	Convert to pandas DataFrame.
`to_pytrf()`	Convert to PyTRF time series object.
`get_unr()`	Fetch time series from UNR.
`force_daily()`	Force daily sampling.

Primitives (extract, merge, transform)

Method	Description
`copy()`	Return a copy of the time series.
`extract_periods()`	Extract one or more time periods.
`extract_dates()`	Extract data at given dates.
`exclude_periods()`	Exclude given periods from the series.
`substract_ts()`	Subtract another Gts (with date matching).
`add_obs()`	Add NEU observation at a date.
`xyz2neu()`	Convert XYZ data to NEU.
`neu2xyz()`	Convert NEU data to XYZ.
`reorder()`	Reorder by date.
`decimate()`	Decimate to a given time step.
`displacement()`	Compute displacement between periods.
`rotate()`	Rotate NEU components by an angle.
`insert_gts_data()`	Insert data from another Gts.
`interpolate()`	Interpolate to regular dates.
`set_zero_at_date()`	Set displacement to zero at a reference date.
`split()`	Split at given dates.
`get_coseismic()`	Get coseismic jump at a date.

Model and detrending

Method	Description
`detrend()`	Remove trend (velocity + optional offsets).
`detrend_annual()`	Remove annual signal.
`detrend_seasonal()`	Remove seasonal signal.
`detrend_median()`	Detrend using median filter.
`trajectory()`	Compute trajectory model.
`frame()`	Transform to another reference frame (Euler).
`make_model()`	Build parametric model.
`remove_pole()`	Remove pole from velocity field.
`detrend_pytrf()`	Detrend using PyTRF (realistic noise and sigmas).

Offsets

Method	Description
`find_offsets()`	Detect and estimate offsets.
`suspect_offsets()`	Propose candidate offset dates.
`apply_offsets()`	Apply offset corrections.
`test_offset_significance()`	Test significance of an offset at a date.
`find_offsets_t_scan()`	Find offsets using t-scan step detection.
`find_offsets_ivel()`	Find offsets using instantaneous velocity.

Outliers

Method	Description
`remove_outliers()`	Remove flagged outliers.
`find_outliers_simple()`	Detect outliers with threshold and window.
`find_outliers_vondrak()`	Detect outliers using Vondrak filter residuals.
`find_outliers_sliding_window()`	Detect outliers in sliding windows.
`find_outlier_around_date()`	Find outlier around a given date.

Noise and uncertainty

Method	Description
`realistic_sigma()`	Estimate realistic uncertainties (e.g. tsfit).
`wrms()`	Weighted RMS.
`sigma_vel_tsfit()`	Velocity sigma from time series fit.
`add_vel_sigma()`	Velocity sigma from white + flicker noise (Williams 2003).

Filters

Method	Description
`vondrak()`	Vondrak filter.
`wiener()`	Wiener filter.
`spline()`	Spline smoothing.
`median_filter()`	Median filter.
`edge_filter()`	Edge-preserving filter.
`disp2vel()`	Displacement to velocity (filtering).
`ivel()`	Instantaneous velocity.
`smooth()`	Smooth time series.

L1-trend (when Trendfilter is installed)

Method	Description
`l1trendi()`	L1 trend filtering.
`refine_l1trend()`	Refine breakpoint dates from L1 trend.
`clean_l1trend()`	Clean L1 trend (remove spurious breakpoints).
`simplify_l1trend()`	Simplify L1 trend (merge segments).
`l1trend_to_breakpoints()`	Export L1 trend breakpoints.
`l1trend_optimal_workflow()`	Full L1-trend workflow.

Metadata and I/O

Method	Description
`info()`	Print or return summary info.
`save_velocity()`	Save velocity to file.
`save_offsets()`	Save offsets to file.
`plot()`	Plot the time series.

Full API

Individual geodetic time series (Gts) class and helpers.

The Gts class holds NEU (or XYZ) time series with metadata. Key attributes: data (2D: dec_year, N, E, U, S_N, S_E, S_U, S_NE, S_NU, S_EU), code, lon/lat/h, X0,Y0,Z0,t0, data_xyz, outliers, offsets_*, velocity, annual, semi_annual, ifile, log, metadata. Units: dates in decimal year, coordinates in m, phases in radians.

Each method in the summary tables above links to its own page under gts_methods/ (e.g. read() → gts_methods/read.html).

Sgts class API

Full reference: pyacs.gts.Sgts.Sgts

The Sgts class holds a collection of Gts (geodetic time series) and provides methods to load, select, and operate on them collectively. Below is a summary of available methods by category.

Summary of available methods

Read and load

Method	Description
`read_ts()`	Load time series from a directory (or list of files).
`read_gmt()`	Read GMT-style time series files.
`read_soln()`	Read from a solution directory.
`read_gts_conf()`	Read time series using a configuration file.

Selection and filtering

Method	Description
`sel_period()`	Keep time series overlapping a given period.
`sel_radius()`	Select sites within a radius of a center point.
`sel_rectangle()`	Select sites inside a rectangular bounds.
`sel_from_grid()`	Select sites from a grid with depth range.
`sel_radius_eq()`	Select sites within radius of an earthquake.
`sub()`	Subset by including or excluding site codes.
`lGts()`	Return list of Gts (optionally filtered).
`n()`	Number of time series (optionally filtered).
`has_ts()`	Check if a site code is in the collection.
`same_site()`	Keep only one time series per site.
`nearest()`	Return the n nearest sites to a given site.

Collection and modification

Method	Description
`append()`	Append a Gts to the collection.
`copy()`	Return a copy of the Sgts.
`delts()`	Remove time series by site code.
`delnone()`	Remove entries with no data.
`add_offsets_dates()`	Add offset dates to time series from a file.
`correct_offsets_from_file()`	Apply offsets from a file to matching time series.
`remove_observations()`	Remove specified observations from all time series.

Frame and apply Gts methods

Method	Description
`frame()`	Transform all time series to another reference frame (Euler).
`gts()`	Call a Gts method on each time series in the collection.
`gts_mp()`	Call a Gts method on each time series in parallel.

Common mode and coseismic

Method	Description
`common_mode()`	Remove common mode signal from the collection.
`compute_common_mode_l1trend()`	Compute common mode using L1-trend approach.
`apply_coseismic()`	Apply coseismic corrections from GMT files.

Export and write

Method	Description
`save_velocity()`	Save velocities to file.
`write_pck()`	Write to PCK format.
`to_obs_tensor()`	Convert to observation tensor.
`to_displacement()`	Export displacement time series.
`to_kml()`	Export to KML.
`to_tsnpz()`	Save to compressed NumPy archive.
`to_tspck()`	Save to TSPCK format.

Info, dates and statistics

Method	Description
`info()`	Print or return summary info for the collection.
`dates()`	Return dates (e.g. decimal year) for the collection.
`get_dates()`	Get dates in requested format.
`lcode()`	List of site codes (optionally filtered).
`medvel()`	Median velocity estimation for the collection.
`stat_site()`	Site statistics (e.g. velocity, RMS).
`make_distance_matrix_from_sgts()`	Build distance matrix between sites.

Plot and map

Method	Description
`show_map()`	Display a map of the sites.
`plot_component()`	Plot a component for all or selected time series.
`plot_data_sum()`	Plot stacked or summary of time series data.
`show_ivel_map_gmt()`	Show instantaneous velocity map (GMT).

Data

Method	Description
`get_unr()`	Fetch time series from UNR for sites in the collection.

Sgts full API

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