pyacs.gts.lib.filters.refine_l1trend module
L1-trend refinement functions have been moved to pyacs.gts.lib.l1trend package.
This file has been refactored into a modular structure for better organization and maintainability.
The functions have been distributed as follows: - refine_l1trend -> pyacs.gts.lib.l1trend.refinement - check_l1_trend -> pyacs.gts.lib.l1trend.check_trend - l1trend_to_breakpoints -> pyacs.gts.lib.l1trend.breakpoints - clean_l1trend -> pyacs.gts.lib.l1trend.cleaning - simplify_l1trend -> pyacs.gts.lib.l1trend.simplification - optimal_pwlf_refinement, optimal_pwlf_refinement_fast -> pyacs.gts.lib.l1trend.optimal_refinement
- Please import from the new location:
from pyacs.gts.lib.l1trend import refine_l1trend, check_l1_trend, l1trend_to_breakpoints, etc.
- pyacs.gts.lib.filters.refine_l1trend.check_l1_trend(ts, l1ts, component='ENU', min_samples_per_segment=4, threshold_bias_res_detect=40, threshold_vel=8, plot=False)[source]
Inspect the result from l1trend model of a time series. Returns a list periods ([sdate,edate]) where bad modelling is suspected.
- Parameters:
ts (pyacs.gts.Gts.Gts) – Raw time series
l1ts (pyacs.gts.Gts.Gts) – L1-trend time series
component (str) – Components to be analyzed. Default: ‘EN’
min_samples_per_segment (int) – Minimum number of samples for a segment to be inspected (default: 6)
threshold_bias_res_detect (float) – Threshold to detect bias residuals (default: 40)
threshold_vel (float) – Instantaneous velocity threshold for a segment to be considered in detection (default: 8 mm/yr)
plot (bool) – Plot the results (default: False)
- Returns:
(H_period, H_cp, H_cp_pb) - H_period: Dictionary of suspicious periods for each component - H_cp: Dictionary of breakpoint indices for each component - H_cp_pb: Dictionary of problematic breakpoint indices for each component
- Return type:
tuple
- pyacs.gts.lib.filters.refine_l1trend.clean_l1trend(self, raw_gts, threshold='auto')[source]
Cleans breakpoints from an already L1-trend filtered time series. Removes breakpoints that are too close in value (<0.5 mm/yr). Returns a new Gts object interpolated on the dates from l1trend_gts.
- Parameters:
raw_gts (pyacs.gts.Gts.Gts) – Original (position) time series.
threshold (float or 'auto') – Threshold for cleaning. If ‘auto’, computed from median difference.
- Returns:
Cleaned/interpolated Gts object.
- Return type:
- pyacs.gts.lib.filters.refine_l1trend.l1trend_to_breakpoints(self, tol='auto', threshold=[1.0, 1.0, 5.0])[source]
Convert a Gts resulting from a L1-trend-filtering to a dictionary of breakpoints. The breakpoints are computed by looking for significant changes in the slope of the time series.
- Parameters:
tol (float or 'auto') – Tolerance for detecting breakpoints in mm/yr. If ‘auto’, finds the greatest tol such that the max difference between interpolated breakpoints and the time series is below a threshold for each component.
threshold (list of floats) – List of thresholds in mm for each component (‘N’, ‘E’, ‘U’) to determine the best tolerance if tol is ‘auto’. Default is [1., 1., 5.] for ‘N’, ‘E’, and ‘U’ respectively. If tol is a float, this parameter is ignored.
- Returns:
bp – Dictionary with keys as component names (‘E’, ‘N’, ‘U’) and dates/values as bp[component][0], H_bp[component][1]
- Return type:
- pyacs.gts.lib.filters.refine_l1trend.optimal_pwlf_refinement(t, y, y0, yn, nbp, weights=None)[source]
Find the optimal piecewise linear function with nbp breakpoints fitting y.
The function finds the optimal piecewise linear function (opwlf) fitting y with nbp breakpoints according to the weighted L2 norm. The obtained optimal piecewise linear function verifies opwlf[0]=y0 and opwlf[-1]=yn, that is end and starting point of y are kept fixed.
The problem is applied to small dimension (n<=6), so that a systematic search can be performed and does not require complex optimization approaches.
For large time series (>100 points), preprocessing is applied to decimate the data while preserving essential structure.
- Parameters:
t (numpy.ndarray) – Time array expressed in integer seconds
y (numpy.ndarray) – Values of the function to fit
y0 (float) – Value of the function at t[0] (fixed)
yn (float) – Value of the function at t[-1] (fixed)
nbp (int) – Number of breakpoints (excluding start and end points)
weights (numpy.ndarray, optional) – Weights for each data point. If None, all weights are set to 1.0.
- Returns:
(optimal_breakpoints, optimal_values, min_error) - optimal_breakpoints: array of breakpoint times - optimal_values: array of function values at breakpoints - min_error: minimum weighted L2 error achieved
- Return type:
tuple
- pyacs.gts.lib.filters.refine_l1trend.optimal_pwlf_refinement_fast(t, y, y0, yn, weights=None)[source]
Fast version of optimal_pwlf_refinement using l1trendi with criterion AICc.
- Parameters:
t (numpy.ndarray) – Time array expressed in integer seconds
y (numpy.ndarray) – Values of the function to fit
y0 (float) – Value of the function at t[0] (fixed)
yn (float) – Value of the function at t[-1] (fixed)
weights (numpy.ndarray, optional) – Weights for each data point. If None, all weights are set to 1.0.
- Returns:
(optimal_breakpoints, optimal_values, min_error)
- Return type:
tuple
- pyacs.gts.lib.filters.refine_l1trend.refine_l1trend(self, rawts, lcomponent='ENU', min_samples_per_segment=10, threshold_bias_res_detect=10, threshold_vel=8, min_sample_segment_refinement=1, norm='L2', output='ts')[source]
Refine results from l1trend by optimizing the date of breakpoints for suspected periods. The algorithm first identifies periods where the l1trend model might be improved. For every candidate period, the algorithm checks different metrics to decide if the model should be refined. Finally, for the selected periods, it optimizes the date of breakpoints.
- Parameters:
rawts (pyacs.gts.Gts.Gts) – Raw time series, originally processed by l1trend
lcomponent (str) – Component to refine (default: ‘ENU’)
min_samples_per_segment (int) – Minimum number of samples for a segment to be considered as a candidate for improvement (default: 10)
threshold_bias_res_detect (float) – Threshold to detect bias residuals (default: 10)
threshold_vel (float) – Threshold to detect high velocities (default: 8)
min_sample_segment_refinement (int) – Minimum number of samples for a segment in the refined model (default: 1)
norm (str) – Norm to be minimized for improvement (default: ‘L2’)
output (str) – Output type ‘ts’ for the refined Gts, ‘info’ for the periods suspected, ‘both’ for both (default: ‘ts’)
- Returns:
Refined Gts object or information about suspected periods
- Return type:
pyacs.gts.Gts.Gts or tuple
- pyacs.gts.lib.filters.refine_l1trend.simplify_l1trend(self, tolerance=0.5, components='ENU')[source]
Remove unnecessary breakpoints from an L1-trend filtered time series.
This function iteratively removes breakpoints and tests if the simplified model still fits the original time series within a specified tolerance.
- Parameters:
tolerance (float) – Maximum allowed difference (in mm) between original and simplified model. Default is 0.5 mm.
components (str) – Components to process. Default is ‘ENU’.
- Returns:
Simplified Gts object with unnecessary breakpoints removed.
- Return type: