Package {rLifting}

rLifting: High-Performance Wavelet Lifting Transforms

Description

A unified framework for Wavelet Transforms using the Lifting Scheme. It provides robust tools for offline signal analysis and functional data analysis (FDA), while also enabling high-performance causal processing for real-time applications via a specialized 'C++' core.

Author(s)

Maintainer: Moises da Silva moisesdff8@gmail.com

See Also

Useful links:

• https://github.com/mkyou/rLifting

• Report bugs at https://github.com/mkyou/rLifting/issues

Warn if a scheme has no irregular-grid support for any predict step.

Description

Warn if a scheme has no irregular-grid support for any predict step.

Usage

.check_irregular_scheme(scheme)

Generate standard signals for wavelet testing (Donoho-Johnstone Benchmark)

Description

Creates synthetic classic signals used for wavelet validation. Formulas are based on Donoho and Johnstone and Liu et al.

Usage

.generate_signal(type, n = 512)

Arguments

Value

Numeric vector.

Implements factorizations based on Daubechies and Sweldens (1998).

Description

Implements factorizations based on Daubechies and Sweldens (1998).

Usage

.get_wavelet_config(name)

adlift Benchmark Results

Description

MSE and timing statistics for the adlift package (adaptive lifting on irregular grids) on the four Donoho-Johnstone signals. 7-quartile summaries over 1000 simulations per configuration. Used as a reference baseline in the irregular-grid benchmark vignette.

Usage

data(benchmark_adlift)

Format

A data frame with 384 rows and 19 columns:

Signal

Donoho-Johnstone test signal.

Pkg

Always "adlift".

Wavelet

Predictor family: "AdaptPred", "CubicPred", "LinearPred", or "QuadPred".

Boundary

Encoded combination of adlift::fwtnp options (neighbours, interpolation, closest-point, mean/median predictor).

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Reconstruction MSE statistics.

Time_min, Time_q1, Time_median, Time_mean, Time_q3, Time_max, Time_se

Wall-time statistics (seconds).

Source

data-raw/generate_adlift_benchmark.R

adlift Irregular-Grid Benchmark Results

Description

MSE and timing statistics for the adlift package on seven irregular-grid test signals: three physically motivated (linear_phys, trend_events, blocks_gapped) and four Donoho-Johnstone classics re-sampled on irregular grids (blocks_dj_irr, bumps_dj_irr, doppler_dj_irr, heavisine_dj_irr). 7-quartile summaries over 1000 simulations per configuration. Companion to benchmark_nlt_irregular and benchmark_rlifting_irregular; used by the irregular-grid benchmark vignette.

Usage

data(benchmark_adlift_irregular)

Format

A data frame with 672 rows and 20 columns:

Signal

One of the seven irregular-grid test signals (see Description).

Pkg

Always "adlift".

Wavelet

Predictor family: "AdaptPred", "CubicPred", "LinearPred", or "QuadPred".

Boundary

Encoded combination of adlift::fwtnp options.

NoiseSd

Per-signal Gaussian noise standard deviation (e.g. 0.15 for linear_phys/trend_events, 0.30 for the DJ-irregular signals, 0.50 for blocks_gapped).

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Reconstruction MSE statistics.

Time_min, Time_q1, Time_median, Time_mean, Time_q3, Time_max, Time_se

Wall-time statistics (seconds).

Source

data-raw/generate_adlift_irregular_benchmark.R

nlt Benchmark Results

Description

MSE and timing statistics for the nlt package (nondecimated lifting transform) on the four Donoho-Johnstone signals. 7-quartile summaries over 1000 simulations per configuration. Used as a reference baseline in the irregular-grid benchmark vignette.

Usage

data(benchmark_nlt)

Format

A data frame with 384 rows and 19 columns:

Signal

Donoho-Johnstone test signal.

Pkg

Always "nlt".

Wavelet

Predictor family inherited from adlift.

Boundary

Encoded combination of nlt/adlift options.

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Reconstruction MSE statistics.

Time_min, Time_q1, Time_median, Time_mean, Time_q3, Time_max, Time_se

Wall-time statistics (seconds).

Source

data-raw/generate_nlt_benchmark.R

nlt Irregular-Grid Benchmark Results

Description

MSE and timing statistics for the nlt package on seven irregular-grid test signals (see benchmark_adlift_irregular for the signal set). 7-quartile summaries over 1000 simulations per configuration. Used by the irregular-grid benchmark vignette as a reference baseline.

Usage

data(benchmark_nlt_irregular)

Format

A data frame with 672 rows and 20 columns:

Signal

One of the seven irregular-grid test signals.

Pkg

Always "nlt".

Wavelet

Predictor family inherited from adlift: "AdaptPred", "CubicPred", "LinearPred", or "QuadPred".

Boundary

Encoded combination of nlt/adlift options.

NoiseSd

Per-signal Gaussian noise standard deviation.

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Reconstruction MSE statistics.

Time_min, Time_q1, Time_median, Time_mean, Time_q3, Time_max, Time_se

Wall-time statistics (seconds).

Source

data-raw/generate_nlt_irregular_benchmark.R

rLifting Offline/Causal Benchmark Results

Description

MSE and timing statistics for rLifting denoising across the four Donoho-Johnstone signals, three modes (offline / causal-batch / stream), multiple wavelets, boundary modes, threshold rules, and shrinkage methods. Reported as 7-quartile summaries (min / q1 / median / mean / q3 / max / se) over 1000 simulations per configuration. Used by vignette("v02-thresholding-and-tuning") and vignette("v03-causal-stream").

Usage

data(benchmark_rlifting)

Format

A data frame with 3600 rows and 40 columns:

Signal

Donoho-Johnstone test signal: "blocks", "bumps", "doppler", or "heavisine".

Pkg

Always "rLifting".

Mode

"offline", "causal", or "stream".

Wavelet

Lifting scheme: "haar", "cdf53", etc.

Boundary

Boundary extension mode.

Method

Composite label combining threshold rule and shrinkage.

ThresholdMethod

Threshold rule: "universal" or "sure".

Shrinkage

Shrinkage rule: "hard", "soft", "semisoft", or "scad".

AlphaUsed, BetaUsed

Threshold-recursion parameters used.

Version

Generator version tag ("v2" for current).

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Mean-squared-error statistics against the noise-free signal.

MSE_settled_min, MSE_settled_q1, MSE_settled_median, MSE_settled_mean, MSE_settled_q3, MSE_settled_max, MSE_settled_se

MSE statistics computed after dropping the warm-up window (causal/stream modes only).

Time_total_min, Time_total_q1, Time_total_median, Time_total_mean, Time_total_q3, Time_total_max, Time_total_se

Total wall time per call (seconds).

Per_sample_us_min, Per_sample_us_q1, Per_sample_us_median, Per_sample_us_mean, Per_sample_us_q3, Per_sample_us_max, Per_sample_us_se

Per-sample time (microseconds), i.e. Time_total / signal length.

Source

data-raw/generate_rlifting_benchmark_v2.R

rLifting Irregular-Grid Benchmark Results

Description

MSE and timing statistics for rLifting denoising on seven irregular-grid test signals (see benchmark_adlift_irregular for the signal set), covering all three modes (offline, causal, stream), six built-in wavelets, five boundary modes, and twelve threshold/shrinkage method combinations (universal/sure x hard/soft/semisoft/scad, with and without tune_alpha_beta where applicable). 7-quartile summaries over 1000 simulations per configuration. Companion to benchmark_adlift_irregular and benchmark_nlt_irregular; used by the irregular-grid benchmark vignette.

Usage

data(benchmark_rlifting_irregular)

Format

A data frame with 7560 rows and 47 columns:

Signal

One of the seven irregular-grid test signals.

Pkg

Always "rLifting".

Mode

"offline", "causal", or "stream".

Wavelet

Lifting scheme: "haar", "db2", "cdf53", "cdf97", "dd4", or "lazy".

Boundary

Boundary extension mode: "symmetric", "periodic", "zero", "local_linear", or "one_sided".

Method

Composite label combining threshold rule, shrinkage, and tuned/untuned status (e.g. "universal_tuned_soft").

ThresholdMethod

Threshold rule: "universal" or "sure".

Shrinkage

Shrinkage rule: "hard", "soft", "semisoft", or "scad".

AlphaUsed, BetaUsed

Threshold-recursion parameters used (post-tuning when applicable).

NoiseSd

Per-signal Gaussian noise standard deviation.

N

Number of simulations per configuration (1000).

MSEpos_min, MSEpos_q1, MSEpos_median, MSEpos_mean, MSEpos_q3, MSEpos_max, MSEpos_se

MSE statistics with position-aware processing.

MSEfix_min, MSEfix_q1, MSEfix_median, MSEfix_mean, MSEfix_q3, MSEfix_max, MSEfix_se

MSE statistics with position-ignoring processing (offline only; NA for causal/stream).

Ratio_min, Ratio_q1, Ratio_median, Ratio_mean, Ratio_q3, Ratio_max, Ratio_se

Per-simulation ratio MSEpos / MSEfix summarised over the 1000 simulations (offline only).

Timepos_min, Timepos_q1, Timepos_median, Timepos_mean, Timepos_q3, Timepos_max, Timepos_se

Wall-time statistics with position-aware processing (seconds).

Timefix_min, Timefix_q1, Timefix_median, Timefix_mean, Timefix_q3, Timefix_max, Timefix_se

Wall-time statistics with position-ignoring processing (offline only).

Details

Each configuration is run twice in offline mode: with position-aware processing (t = t_phys passed in, irregular path active) and position-ignoring (t = NULL, uniform-grid treatment). The Ratio_* columns report MSEpos / MSEfix per simulation as a direct measure of the value of irregular handling for that configuration. Causal and stream modes report only position-aware results (MSEpos_*/Timepos_*); the position-ignoring columns are NA for those rows.

Source

data-raw/generate_rlifting_irregular_benchmark.R

wavethresh Benchmark Results

Description

MSE and timing statistics for the wavethresh package on the four Donoho-Johnstone signals, across its native wavelets and boundary/threshold combinations. 7-quartile summaries over 1000 simulations per configuration. Used as a reference baseline in the offline benchmark vignette.

Usage

data(benchmark_wavethresh)

Format

A data frame with rows per (Signal, Wavelet, Boundary) and 19 columns:

Signal

Donoho-Johnstone test signal.

Pkg

Always "wavethresh".

Wavelet

Daubechies filter family identifier (e.g. "co1" for Daubechies-extremal-phase order 1).

Boundary

Combination of wavethresh threshold policy and shrinkage rule (e.g. "BayesThresh_soft", "cv_hard").

N

Number of simulations per configuration (1000).

MSE_min, MSE_q1, MSE_median, MSE_mean, MSE_q3, MSE_max, MSE_se

Reconstruction MSE statistics.

Time_min, Time_q1, Time_median, Time_mean, Time_q3, Time_max, Time_se

Wall-time statistics (seconds).

Source

data-raw/generate_wavethresh_benchmark.R

Calculate Adaptive Threshold (Universal / Recursive)

Description

Estimates the per-level noise threshold from the finest-level detail coefficients and applies the recursive Liu et al. (2014) decay across levels. This is the step-by-step entry point for the universal threshold rule.

Usage

compute_adaptive_threshold(lwt_obj, alpha = 0.3, beta = 1.2)

Arguments

Details

To use SureShrink instead, call denoise_signal_offline() or the causal/stream functions with threshold_method = "sure" — the SURE branch lives in the C++ engine and is not exposed as a standalone R routine. For automatic selection of alpha and beta, see tune_alpha_beta.

Value

Object of class adaptive_thresholds (a list of thresholds).

References

Donoho, D. L., & Johnstone, I. M. (1994). Ideal spatial adaptation by wavelet shrinkage. Biometrika, 81(3), 425–455.

Liu, Z., Mi, Y., & Mao, Y. (2014). Improved real-time denoising method based on lifting wavelet transform. Measurement Science Review, 14(3), 152–159. doi:10.2478/msr-2014-0020

Create a custom wavelet

Description

Wrapper to create a lifting_scheme object from manual steps.

Usage

custom_wavelet(name, steps, norm = c(1, 1))

Arguments

Value

An object of class lifting_scheme.

Examples

p1 = lift_step("predict", c(1), position = "center")
u1 = lift_step("update", c(0.5), position = "center")
w = custom_wavelet("HaarManual", list(p1, u1), c(1.41, 0.707))

Causal Batch Denoising (Turbo Simulation)

Description

Processes a complete signal simulating the sequential arrival of data. Uses the specialized 'C++' class WaveletEngine to perform causal filtering efficiently on a historical dataset.

Usage

denoise_signal_causal(
  signal,
  scheme,
  levels = 1,
  window_size = 256,
  alpha = 0.3,
  beta = 1.2,
  threshold_method = "universal",
  shrinkage = NULL,
  a = 3.7,
  method = NULL,
  extension = "symmetric",
  update_freq = 1,
  t = NULL,
  ll_k = 4L
)

Arguments

Value

Filtered vector (same length as input).

Offline Denoising (Global Batch)

Description

Performs denoising on the entire signal at once using a non-causal approach. Uses global statistics for recursive threshold calculation (Eq. 9). This function is fully optimized in 'C++' (Zero-Allocation).

Usage

denoise_signal_offline(
  signal,
  scheme,
  alpha = 0.3,
  beta = 1.2,
  levels = 3,
  threshold_method = "universal",
  shrinkage = NULL,
  a = 3.7,
  method = NULL,
  extension = "symmetric",
  t = NULL,
  ll_k = 4L
)

Arguments

Value

Filtered numeric vector (same length as input).

Complete Wavelet Diagnosis

Description

Runs a battery of physical and mathematical tests on a wavelet.

Usage

diagnose_wavelet(wavelet_name, config, verbose = TRUE, plot = TRUE)

Arguments

Value

An object of class wavelet_diagnosis (S3), which is a list containing the results of each test. The object has a dedicated print method.

Noisy Doppler Signal Example

Description

Synthetic Doppler signal contaminated with Gaussian noise. Used in vignette("v01-introduction") and the boundary-mode comparison.

Usage

data(doppler_example)

Format

A data frame with 2048 rows and 3 columns:

index

Time index (1..2048).

original

The pure Doppler signal.

noisy

The signal with added Gaussian noise (sd = 0.5).

Inverse Lifting Wavelet Transform ('C++' Accelerated)

Description

Reconstructs the original signal from wavelet coefficients. Optimized with 'C++' backend.

Usage

ilwt(lwt_obj, scheme = NULL)

Arguments

Value

Numeric vector containing the reconstructed signal.

Examples

s = c(1, 2, 3, 4)
sch = lifting_scheme("haar")
fwd = lwt(s, sch)
rec = ilwt(fwd)
print(rec)

Create an individual Lifting Step

Description

Helper function to create prediction (P) or update (U) steps, abstracting the complexity of index management.

Usage

lift_step(
  type = c("predict", "update"),
  coeffs,
  start_idx = NULL,
  position = "center",
  degree = NULL
)

Arguments

Value

A list list(type, coeffs, start_idx, degree) formatted for the internal lifting engine.

Lifting Scheme Constructor

Description

Creates an S3 object containing the prediction (P) and update (U) steps required for the Lifting Transform.

Usage

lifting_scheme(wavelet = "haar", custom_steps = NULL, custom_norm = NULL)

Arguments

Value

An object of class lifting_scheme.

Lifting Wavelet Transform (Forward)

Description

Performs the Forward Wavelet Transform using the Lifting Scheme. Optimized with 'C++' backend.

Usage

lwt(signal, scheme, levels = 1, extension = "symmetric", t = NULL, ll_k = 4L)

Arguments

Value

An object of class lwt. It is a list containing coeffs (list of details d1..dn and approximation an), scheme (the scheme object used), levels, original_len, extension, ll_k, and t.

Examples

data = c(1, 2, 3, 4, 5, 6, 7, 8)
sch = lifting_scheme("haar")
res = lwt(data, sch, levels = 2)
print(res)

Create an Adaptive Wavelet Stream Processor ('C++' Core)

Description

Generates a stateful function backed by a high-performance 'C++' Ring Buffer engine. It implements Sliding Window + Lifting Decomposition + Adaptive Thresholding in highly efficient time per sample.

Usage

new_wavelet_stream(
  scheme,
  window_size = 256,
  levels = 1,
  alpha = 0.3,
  beta = 1.2,
  threshold_method = "universal",
  shrinkage = NULL,
  a = 3.7,
  method = NULL,
  extension = "symmetric",
  update_freq = 1,
  irregular = FALSE,
  ll_k = 4L
)

Arguments

Value

A closure processor(new_sample, t_val = NULL) that accepts one sample (and optionally its time position) and returns the filtered value.

Plot method for Adaptive Thresholds

Description

Plot method for Adaptive Thresholds

Usage

## S3 method for class 'adaptive_thresholds'
plot(x, ...)

Arguments

Value

Invisibly returns NULL.

Plot method for Lifting Scheme

Description

Plot method for Lifting Scheme

Usage

## S3 method for class 'lifting_scheme'
plot(x, ...)

Arguments

Value

Invisibly returns NULL.

Plot method for LWT Decomposition

Description

Plot method for LWT Decomposition

Usage

## S3 method for class 'lwt'
plot(x, ...)

Arguments

Value

Invisibly returns NULL.

Print method for Adaptive Thresholds

Description

Print method for Adaptive Thresholds

Usage

## S3 method for class 'adaptive_thresholds'
print(x, ...)

Arguments

Value

Invisibly returns x.

Print method

Description

Print method

Usage

## S3 method for class 'lifting_scheme'
print(x, ...)

Arguments

Value

Invisibly returns NULL. Called for side effects (printing).

Print method for LWT

Description

Print method for LWT

Usage

## S3 method for class 'lwt'
print(x, ...)

Arguments

Value

Invisibly returns NULL. Called for side effects (printing).

Print method for Wavelet Diagnosis

Description

Print method for Wavelet Diagnosis

Usage

## S3 method for class 'wavelet_diagnosis'
print(x, ...)

Arguments

Value

Invisibly returns x.

Print method for Wavelet Stream Processor

Description

Print method for Wavelet Stream Processor

Usage

## S3 method for class 'wavelet_stream'
print(x, ...)

Arguments

Value

Invisibly returns x.

General Thresholding Wrapper

Description

General Thresholding Wrapper

Usage

threshold(x, lambda, method = "soft", a = 3.7)

Arguments

Value

Numeric vector of the same length as x with thresholded coefficients.

Hard Thresholding

Description

Sets coefficients below the threshold to zero, keeping others unchanged. Known as the "keep or kill" policy.

Usage

threshold_hard(x, lambda)

Arguments

Value

Processed vector.

SCAD Shrinkage (Antoniadis & Fan, 2001)

Description

Smoothly Clipped Absolute Deviation shrinkage. Three-region rule with continuity at lambda, 2lambda and alambda. Identity above a*lambda eliminates the bias that soft thresholding imposes on large coefficients, while keeping sparsity in the zero region.

Usage

threshold_scad(x, lambda, a = 3.7)

Arguments

Value

Processed vector.

Semisoft Shrinkage (Hyperbolic)

Description

Implementation based on Liu et al. (2014). Combines the stability of Soft Thresholding with the amplitude precision of Hard Thresholding. Function: sign(x) * sqrt(x^2 - lambda^2) for values above lambda.

Usage

threshold_semisoft(x, lambda)

Arguments

Value

Processed vector.

References

Liu, Z., Mi, Y., & Mao, Y. (2014). Improved real-time denoising method based on lifting wavelet transform. Measurement Science Review, 14(3), 152–159. doi:10.2478/msr-2014-0020

Soft Thresholding

Description

Sets coefficients below the threshold to zero and shrinks others towards zero. Reduces noise variance but introduces amplitude bias.

Usage

threshold_soft(x, lambda)

Arguments

Value

Processed vector.

Tune Adaptive Threshold Parameters via SURE

Description

Selects the recursive-threshold parameters alpha and beta that minimise Stein's Unbiased Risk Estimate (SURE) for soft thresholding applied to the wavelet detail coefficients of the supplied signal.

Usage

tune_alpha_beta(
  signal,
  scheme,
  levels = 3,
  extension = "symmetric",
  ll_k = 4L,
  alpha_range = c(0, 10),
  beta_range = c(0.5, 3)
)

Arguments

Details

SURE is computed under the soft-threshold estimator assumption (Donoho & Johnstone, 1995). The chosen parameters are typically usable with shrinkage = "soft", "semisoft", "hard", or "scad", since all four share the same threshold location.

Value

A list with components alpha, beta, sure (the minimised SURE value), and converged (logical).

Validate Compact Support (FIR Compliance)

Description

Verifies if the impulse response is finite (FIR Filter).

Usage

validate_compact_support(scheme, max_width)

Arguments

Value

List with status and number of active taps.

Validate Orthogonality (Energy Conservation)

Description

Verifies Parseval's Theorem. Only applicable for orthogonal wavelets.

Usage

validate_orthogonality(scheme, expected = TRUE, tol = 1e-09)

Arguments

Value

List with status and energy ratio (Out/In).

Validate Perfect Reconstruction (Stress Test)

Description

Verifies wavelet invertibility against a battery of signals.

Usage

validate_perfect_reconstruction(scheme, tol = 1e-09)

Arguments

Value

List with global status and maximum error found.

Validate Shift Sensitivity (Shift Variance)

Description

Decimated wavelets are not translation invariant. This test quantifies the variation in detail energy when shifting the input signal by 1 sample.

Usage

validate_shift_sensitivity(scheme)

Arguments

Value

List with status and percentage variation.

Validate Vanishing Moments

Description

Verifies if the wavelet cancels polynomials of a specific degree.

Usage

validate_vanishing_moments(scheme, degree = 0, tol = 1e-09)

Arguments

Value

List with status and residual energy.

Visualize Basis Functions (Scaling and Wavelet)

Description

Plots the waveform by iterating the reconstruction over several levels.

Usage

visualize_wavelet_basis(scheme, plot = TRUE, levels = 8)

Arguments

Value

Invisibly returns NULL. Called for side effects (plotting).