pyacs.gts.lib.filters.l1trend module

L1-trend filtering 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: - l1trend -> pyacs.gts.lib.l1trend.l1trendi - get_stats_l1_model -> pyacs.gts.lib.l1trend.statistics - pre_process_test, pre_process_ts -> pyacs.gts.lib.l1trend.preprocessing - best_l1trend_golden, best_l1trend_custom -> pyacs.gts.lib.l1trend.optimization

Please import from the new location:

from pyacs.gts.lib.l1trend import l1trendi, get_stats_l1_model, pre_process_test, etc.

pyacs.gts.lib.filters.l1trend.best_l1trend_custom(x, y, criterion_idx, logger=None, component_mask=None)[source]

Find the optimal hyperparameter alpha in l1trend using a custom search algorithm.

Parameters:

  • x (numpy.ndarray) – Input time array

  • y (numpy.ndarray) – Input data array

  • criterion_idx (int) – Index of the criterion to use (-1 for BIC, -2 for AICc, -3 for Cp)

  • logger (logging.Logger, optional) – Logger instance for logging messages

Returns:

(optimal filtered data, history dictionary, optimal alpha)

Return type:

tuple

pyacs.gts.lib.filters.l1trend.best_l1trend_golden(x, y, criterion_idx, bounds=[-2, 1], tol=0.01, logger=None, component_mask=None)[source]

Find the optimal hyperparameter alpha in l1trend using golden section search algorithm.

Parameters:

  • x (numpy.ndarray) – Input time array

  • y (numpy.ndarray) – Input data array

  • criterion_idx (int) – Index of the criterion to use (-1 for BIC, -2 for AICc, -3 for Cp)

  • bounds (list) – Bounds for the search [lower, upper]

  • tol (float) – Tolerance for convergence

  • logger (logging.Logger, optional) – Logger instance for logging messages

Returns:

Optimally filtered data

Return type:

numpy.ndarray

pyacs.gts.lib.filters.l1trend.get_stats_l1_model(x, y, fy, alpha, component_mask=None)[source]

Calculate statistics for L1-trend model evaluation.

Parameters:

  • x (numpy.ndarray) – Input time as 1D array

  • y (numpy.ndarray) – Input raw data as 1D array

  • fy (numpy.ndarray) – Input l1trend filtered data as 1D array

  • alpha (float) – Hyperparameter used for l1 filtering

  • component_mask (numpy.ndarray, optional) – Boolean mask indicating which data points should be considered for statistics. If None, all points are considered.

Returns:

(alpha, cchi2, sigma, cp, cchi2_probability, Cp, AICc, BIC)

Return type:

tuple

pyacs.gts.lib.filters.l1trend.l1trend(self, alpha='auto', ndays_mf=1, criterion='BIC', lcomponent='ENU', algo='golden', pre_process=4500, bounds=[-2, 1], tol=0.01, refine=True, min_samples_per_segment=5, threshold_bias_res_detect=5, threshold_vel=3, min_sample_segment_refinement=1, norm='L2', verbose=False, log_dir=None, component=None)

Performs l1 trend filter on GPS time series. For each component, optimal filter parameter is searched using specified criterion. Uses https://pypi.org/project/trendfilter/

Parameters:

  • alpha (float or str) – Either hyperparameter as float or ‘auto’ to find optimal filtering using criterion

  • ndays_mf (int) – Parameter for a median filter to be applied prior to l1-trend filtering

  • criterion (str) – Criterion to select automatic optimal l1-trend filtering. Options: ‘BIC’ (default), ‘AICc’, ‘Cp’

  • lcomponent (str) – List of components to be filtered. Other components will remain unchanged

  • algo (str) – Algorithm to find optimal alpha. Options: ‘golden’ (default) or ‘custom’

  • pre_process (float) – Pre-process time series to avoid convergence problems in l1trend. It corrects for unrealistically large velocity using the threshold provided (mm/yr). Correction is then added again after l1_trend. Default is 3600 (3.6 m/yr)

  • bounds (list) – Bounds for golden section search algorithm. Default is [-2, 1]

  • tol (float) – Tolerance for golden section search algorithm. Default is 0.01

  • refine (bool) – If True, will run refinement after l1 trend filtering

  • min_samples_per_segment (int) – Minimum number of samples per segment for refinement

  • threshold_bias_res_detect (float) – Threshold for bias detection in refinement

  • threshold_vel (float) – Threshold for velocity detection in refinement

  • min_sample_segment_refinement (int) – Minimum number of samples per segment in refinement

  • norm (str) – Norm to use for refinement. Options: ‘L2’ (default)

  • verbose (bool) – Enable verbose output for debugging

  • log_dir (str or None) – If provided, directory where the log file will be created. The log file will be named ‘SITE_l1trendi.log’ where SITE is the site code. If None, no file logging is performed.

  • component (str or None) – Components to process (‘N’, ‘E’, ‘U’, ‘NE’, ‘EN’, ‘NU’, ‘UN’, ‘EU’, ‘UE’, ‘NEU’, etc.). If None, uses lcomponent parameter. Used for component-specific statistics calculation.

Returns:

l1-trend filtered time series as new Gts instance

Return type:

Gts

Raises:

  • ValueError – If invalid parameters are provided

  • RuntimeError – If processing fails

pyacs.gts.lib.filters.l1trend.pre_process_test(gts, component, threshold=5000.0, logger=None)[source]

Pre-process. Test whether a large offset is present in the time series. Find the largest offset exceeding threshold found in the time series. Returns the index in the time series immediately after the largest offset or a void list if no offset is found

Parameters:

  • gts (Gts) – Input time series

  • component (str) – Component to test (‘E’, ‘N’, or ‘U’)

  • threshold (float) – Threshold for offset detection

  • logger (logging.Logger, optional) – Logger instance for logging messages

Returns:

List of indices where offsets are found

Return type:

list

pyacs.gts.lib.filters.l1trend.pre_process_ts(self, threshold=5000.0)[source]

Pre-process a time series to avoid convergence problems in l1trend. It performs change point detection analysis, correct for unrealistically large velocity and return a cleaned time series