UTS_SBD

Self-Supervised Blind Denoiser (SSB Denoiser) for 1D time-series, plus an optional wrapper (UTS_SBD) that first performs unsupervised time-series segmentation to obtain quasi-stationary segments before denoising.

• Core focus: using SelfSupervisedDenoiser to denoise signals without clean targets.
• Optional: UTSSBD adds a pre-segmentation step to split nonstationary signals; this segmentation feature is experimental and not yet fully polished.

Why SSB Denoiser

• Self-supervised denoising via masked/inpainted objectives, no clean labels needed.
• Searches across a bank of invariant denoisers (DFT / WT / EMD / VMD / EWT) and hyperparameters.
• Selects the best configuration using robust loss-selection strategies (kmeans_bins*, time2clean*).
• Works on 1D signals (single array or batched 2D arrays).

Quick Start — SSB Denoiser (Recommended)

import numpy as np
from UTS_SBD.SSB_denoisers import SelfSupervisedDenoiser
from UTS_SBD.SSB_denoisers.base.interpolator import INTERPOLATOR_DICT
from UTS_SBD.SSB_denoisers.base.masker import MASKER_DICT
from UTS_SBD.SSB_denoisers.base.loss_factory import LOSS_FACTORY_DICT
from UTS_SBD.SSB_denoisers.base.loss_selector import LOSS_SELECTOR_DICT

# Configure components
interpolator = INTERPOLATOR_DICT['cubic_spline']()
masker = MASKER_DICT['global'](blind_spot_size=1)
loss_factory = LOSS_FACTORY_DICT['all'](eval_loss='inv_post')
loss_selector = LOSS_SELECTOR_DICT['kmeans_binsE4'](eval_loss='inv_post')

denoiser_map = {
    'DFT': {},
    'WT': {},
    'EMD': {},
    'VMD': {},
    'EWT': {},
}

ssd = SelfSupervisedDenoiser(
    denoiser_map=denoiser_map,
    interpolator=interpolator,
    masker=masker,
    loss_factory=loss_factory,
    loss_selector=loss_selector,
    use_parallel=True,
)

x = np.random.randn(4096)  # your 1D signal
ssd.fit(x)                 # optionally: ssd.fit(x, y) with a reference if available
denoised = ssd.transform(x)

Notes:

• SelfSupervisedDenoiser also supports 2D input (shape [n_samples, length]).
• Passing y (a reference/clean-like signal) is optional and only used for internal evaluation/records.

Optional Wrapper — UTSSBD (Unsupervised Segmentation + SSB)

UTSSBD wraps SSB by inserting an unsupervised change-point detection step to split the signal into quasi-stationary segments. Each segment is then denoised by SSB and merged back.

• Segmentation methods: ClaSP, PELT, Ruptures (RPT), MovingWindow.
• The segmentation step is experimental and not yet fully refined; APIs and results may change.

Example:

from UTS_SBD.UTS_SBD import UTSSBD

model = UTSSBD(
    denoiser_map=denoiser_map,
    interpolator=interpolator,
    masker=masker,
    loss_factory=loss_factory,
    loss_selector=loss_selector,
    segment_feature_type='x',
    segment_method='ClaSP',
    segment_kwargs={},
    use_parallel=True,
)
denoised = model.fit_transform(x)

Prefer using SelfSupervisedDenoiser directly if your signal is already (quasi-)stationary or if you handle segmentation yourself.

Components (SSB Denoiser)

• denoiser_map: which invariant denoisers to search (keys: DFT, WT, EMD, VMD, EWT).
• interpolator: masked sample inpainting (random, mean, cubic_spline).
• masker: blind-spot mask generator (e.g., global with blind_spot_size).
• loss_factory: self-supervised objectives to compute (e.g., inv_post, time2clean_*, jinv*, rec, rev).
• loss_selector: rule for picking the best run (kmeans_bins*, time2clean*, time2clean_eval).
• use_parallel: parallel evaluation across denoiser families.

Installation

Prerequisites:

• Python 3.10+
• A working C/C++ toolchain may be required for some scientific packages.

Install dependencies (typical set used across the modules):

pip install numpy pandas matplotlib scikit-learn joblib xarray ruptures sktime skchange ydata-profiling optuna tqdm scipy

Notes:

• sktime may require specific versions of numba/numpy; consult sktime docs if installation fails.
• skchange is used for change detection; ensure it’s available for your platform.

Data (Optional)

If you want to reproduce example experiments, loaders exist for NetCDF Lidar-like signals, e.g. UTS_SBD/utils/load_data/load_hefei.py. Update file paths or place data under UTS_SBD/data/ as referenced in code.

Experiments (Optional)

• Config-driven experiments live under UTS_SBD/src with YAML config files in UTS_SBD/config/ and outputs in UTS_SBD/_result/.
• These are helpful for batch runs and plotting but are not required to use SelfSupervisedDenoiser.

Troubleshooting

• Installation issues with the scientific Python stack (especially sktime): pin compatible numpy/numba versions per sktime docs.
• If segmentation assertions trigger in UTSSBD, review your change-point method and parameters.

License

No explicit license file is included. If you plan to use or distribute this project, please coordinate with the repository owner.