Assured Signal: Examples

Each example is a verified run of a guided tour script from the shipped python/examples/ bundle (see PROGRESSION.md for the full 01→06 sequence). Run the guided tour first: it narrates the scenario, explains each metric, and shows when to trust the result. Use the production one-liner when wiring the same API call into your pipeline.

Beta release. Products in this catalog other than the SolvSRK family and SolvScout / SolvTune are beta — suitable for trials and evaluation; APIs and packaging may change before GA. Do not deploy beta builds in production programs without a signed agreement with Resonix. Activate a trial license before running examples — see Install and Licensing.

Journeys

Example 1: Journey 01 — First contact

Version, license, simplest successful call. Every support ticket starts with the package version. Machine-locked .lic files gate production use.

Walkthrough:

1. What you are doing — Confirm the native library loads, see your license state, and run the smallest API call that proves Assured Signal is alive: a noise-ratio estimate.

2. Version — Every support ticket starts with the package version.

   • version: 0.1.0
   • native: 0.1.0

3. License — Machine-locked .lic files gate production use.

   • license_valid: True

4. Simplest call — estimate_noise_ratio() is the discriminant the denoiser routes on. Feed it a noisy Lorenz-x series and read one number back - no config needed.

   • samples: 2000
   • noise_ratio: 0.491 — Higher noise_ratio -> noisier input. That single number drives the tier selection.

Guided tour output (from a verified run):

Version, license, simplest successful call

-- Act 1 - What you are doing --
  -> Confirm the native library loads, see your license state, and run the smallest API call that proves Assured Signal is alive: a noise-ratio estimate.

-- Act 2 - Version --
  -> Every support ticket starts with the package version.
  version: 0.1.0
  native: 0.1.0

-- Act 3 - License --
  -> Machine-locked .lic files gate production use.
  license_valid: True

-- Act 4 - Simplest call --
  -> estimate_noise_ratio() is the discriminant the denoiser routes on. Feed it a noisy Lorenz-x series and read one number back - no config needed.
  samples: 2000
  noise_ratio: 0.491
  -> Higher noise_ratio -> noisier input. That single number drives the tier selection.

-- Run complete --
  next_journey: 02_denoise_lorenz.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/01_first_contact.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a; print(a.__version__, a.license_valid())"

Example 2: Journey 02 — Denoise a noisy series

You logged a scalar channel from a deterministic system (here: Lorenz x). The sensor added white noise at ~5 dB SNR. You want the underlying signal back. denoise() picks a processing tier from the noise ratio and returns a DenoiseResult. Passing clean= lets it report SNR gain - clean is used ONLY for the diagnostics, never by the algorithm. Did it survive, which tier fired, and how much SNR did it buy?.

Walkthrough:

1. The scenario — You logged a scalar channel from a deterministic system (here: Lorenz x). The sensor added white noise at ~5 dB SNR. You want the underlying signal back.

   • samples: 4000
   • input_snr_db: 5.0

2. One call — denoise() picks a processing tier from the noise ratio and returns a DenoiseResult. Passing clean= lets it report SNR gain - clean is used ONLY for the diagnostics, never by the algorithm.

3. Read the result — Did it survive, which tier fired, and how much SNR did it buy?

   • survived: True
   • method: bse_dynamic
   • tier_selected: 1
   • noise_ratio: 0.4818
   • snr_improvement_db: 9.112
   • output_snr_db: 14.133
   • wall_s: 0.18 — res.denoised is the cleaned series (same length as the input) - that is what you ship downstream.

Guided tour output (from a verified run):

bse_dynamic on a 5 dB Lorenz-x channel

-- Act 1 - The scenario --
  -> You logged a scalar channel from a deterministic system (here: Lorenz x). The sensor added white noise at ~5 dB SNR. You want the underlying signal back.
  samples: 4000
  input_snr_db: 5.0

-- Act 2 - One call --
  -> denoise() picks a processing tier from the noise ratio and returns a DenoiseResult. Passing clean= lets it report SNR gain - clean is used ONLY for the diagnostics, never by the algorithm.

-- Act 3 - Read the result --
  -> Did it survive, which tier fired, and how much SNR did it buy?
  survived: True
  method: bse_dynamic
  tier_selected: 1
  noise_ratio: 0.4818
  snr_improvement_db: 9.112
  output_snr_db: 14.133
  wall_s: 0.18
  -> res.denoised is the cleaned series (same length as the input) - that is what you ship downstream.

-- Run complete --
  next_journey: 03_noise_ratio.py
  survived: True
  snr_gain_db: 9.11

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_denoise_lorenz.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a, numpy as np; r=a.denoise(np.random.default_rng(0).standard_normal(2000)); print(r.survived, r.tier_selected)"

Example 3: Journey 03 — Noise-ratio estimate

One number that tells you how hard the denoise will be. The same clean series is corrupted at several input SNRs. The noise ratio should climb as the SNR drops - low ratio == clean, high ratio == noisy. Monotone rise confirms the discriminant tracks noise, not signal content. Use a threshold on this value to gate/alert before denoising.

Walkthrough:

1. Why it matters — estimate_noise_ratio() is a cheap pre-flight check. It returns the same discriminant denoise() routes on, so you can gauge input quality before committing to a full pass - and monitor drift in a production feed.

2. Sweep the SNR — The same clean series is corrupted at several input SNRs. The noise ratio should climb as the SNR drops - low ratio == clean, high ratio == noisy.

   • noise_ratio: 0.0561
   • noise_ratio: 0.1743
   • noise_ratio: 0.2993
   • noise_ratio: 0.4848
   • noise_ratio: 0.6966

3. Interpretation — Monotone rise confirms the discriminant tracks noise, not signal content. Use a threshold on this value to gate/alert before denoising.

   • monotone_increasing: True

Guided tour output (from a verified run):

One number that tells you how hard the denoise will be

-- Act 1 - Why it matters --
  -> estimate_noise_ratio() is a cheap pre-flight check. It returns the same discriminant denoise() routes on, so you can gauge input quality before committing to a full pass - and monitor drift in a production feed.

-- Act 2 - Sweep the SNR --
  -> The same clean series is corrupted at several input SNRs. The noise ratio should climb as the SNR drops - low ratio == clean, high ratio == noisy.
  noise_ratio: 0.0561
  noise_ratio: 0.1743
  noise_ratio: 0.2993
  noise_ratio: 0.4848
  noise_ratio: 0.6966

-- Act 3 - Interpretation --
  -> Monotone rise confirms the discriminant tracks noise, not signal content. Use a threshold on this value to gate/alert before denoising.
  monotone_increasing: True

-- Run complete --
  next_journey: 04_config_methods.py
  monotone: True

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_noise_ratio.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a, numpy as np; print(a.estimate_noise_ratio(np.random.default_rng(0).standard_normal(2000)))"

Example 4: Journey 04 — Methods and configuration

METHODS registry, AsigConfig, and per-method behaviour. Fix a 5 dB Lorenz-x series and denoise it with every method. Passing clean= gives an apples-to-apples SNR gain per method. config_defaults() returns a populated AsigConfig you can inspect; denoise() also takes keyword overrides (embed_dim, delay, timeout_s, ...) so you rarely build the struct by hand.

Walkthrough:

1. The method registry — METHODS maps a friendly name to the C tier code. bse_dynamic (the default) auto-selects a tier; the others let you pin a specific algorithm.

   • methods: ['bse_adaptive', 'bse_dynamic', 'bse_enhanced', 'iterative_lp', 'lp_wavelet', 'vanilla_lp', 'wavelet_bse']

2. Compare methods on one series — Fix a 5 dB Lorenz-x series and denoise it with every method. Passing clean= gives an apples-to-apples SNR gain per method.

   • survived: True
   • tier: 0
   • snr_gain_db: 9.047
   • survived: True
   • tier: 1
   • snr_gain_db: 9.28
   • survived: True
   • tier: 0
   • snr_gain_db: 9.28
   • survived: True
   • tier: 0
   • snr_gain_db: 1.485
   • survived: True
   • tier: 0
   • snr_gain_db: 5.769
   • survived: True
   • tier: 0
   • snr_gain_db: 0.683
   • survived: True
   • tier: 0
   • snr_gain_db: 4.503

3. Hand-tune with AsigConfig — config_defaults() returns a populated AsigConfig you can inspect; denoise() also takes keyword overrides (embed_dim, delay, timeout_s, ...) so you rarely build the struct by hand.

   • default_embed_dim: 0
   • default_delay: 0
   • default_timeout_s: 0.0
   • tuned_embed_dim_used: 5
   • tuned_delay_used: 2
   • tuned_snr_gain_db: 9.64

Guided tour output (from a verified run):

METHODS registry, AsigConfig, and per-method behaviour

-- Act 1 - The method registry --
  -> METHODS maps a friendly name to the C tier code. bse_dynamic (the default) auto-selects a tier; the others let you pin a specific algorithm.
  methods: ['bse_adaptive', 'bse_dynamic', 'bse_enhanced', 'iterative_lp', 'lp_wavelet', 'vanilla_lp', 'wavelet_bse']

-- Act 2 - Compare methods on one series --
  -> Fix a 5 dB Lorenz-x series and denoise it with every method. Passing clean= gives an apples-to-apples SNR gain per method.
  survived: True
  tier: 0
  snr_gain_db: 9.047
  survived: True
  tier: 1
  snr_gain_db: 9.28
  survived: True
  tier: 0
  snr_gain_db: 9.28
  survived: True
  tier: 0
  snr_gain_db: 1.485
  survived: True
  tier: 0
  snr_gain_db: 5.769
  survived: True
  tier: 0
  snr_gain_db: 0.683
  survived: True
  tier: 0
  snr_gain_db: 4.503

-- Act 3 - Hand-tune with AsigConfig --
  -> config_defaults() returns a populated AsigConfig you can inspect; denoise() also takes keyword overrides (embed_dim, delay, timeout_s, ...) so you rarely build the struct by hand.
  default_embed_dim: 0
  default_delay: 0
  default_timeout_s: 0.0
  tuned_embed_dim_used: 5
  tuned_delay_used: 2
  tuned_snr_gain_db: 9.64

-- Run complete --
  next_journey: 05_diagnostics.py
  best_method: bse_dynamic
  best_snr_gain_db: 9.28

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/04_config_methods.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a; print(sorted(a.METHODS))"

Example 5: Journey 05 — Diagnostics and Session

Every DenoiseResult field, plus a reusable Session. For many series of the same max length, Session reuses the native work buffers instead of allocating per call. Use it as a context manager. Session results match the one-shot API exactly - it is purely a performance wrapper, not a different algorithm.

Walkthrough:

1. Full result surface — A single denoise() returns rich diagnostics. Log these to explain WHY a pass behaved the way it did - tier, embedding used, timing, and (with clean=) SNR.

   • survived: True
   • failure_mode: ok
   • method: bse_dynamic
   • tier_selected: 2
   • embed_dim_used: 5
   • delay_used: 71
   • noise_ratio: 0.3714
   • est_input_snr_db: 7.958
   • input_snr_db: 7.98
   • output_snr_db: 16.234
   • snr_improvement_db: 8.254
   • wall_s: 0.126
   • denoised_len: 4000

2. Batch with a Session — For many series of the same max length, Session reuses the native work buffers instead of allocating per call. Use it as a context manager.

   • n_max: 4000
   • survived: True
   • tier: 1
   • snr_gain_db: 9.112
   • survived: True
   • tier: 2
   • snr_gain_db: 8.21
   • survived: True
   • tier: 3
   • snr_gain_db: 5.575

3. One-shot vs Session parity — Session results match the one-shot API exactly - it is purely a performance wrapper, not a different algorithm.

   • identical: True

Guided tour output (from a verified run):

Every DenoiseResult field, plus a reusable Session

-- Act 1 - Full result surface --
  -> A single denoise() returns rich diagnostics. Log these to explain WHY a pass behaved the way it did - tier, embedding used, timing, and (with clean=) SNR.
  survived: True
  failure_mode: ok
  method: bse_dynamic
  tier_selected: 2
  embed_dim_used: 5
  delay_used: 71
  noise_ratio: 0.3714
  est_input_snr_db: 7.958
  input_snr_db: 7.98
  output_snr_db: 16.234
  snr_improvement_db: 8.254
  wall_s: 0.126
  denoised_len: 4000

-- Act 2 - Batch with a Session --
  -> For many series of the same max length, Session reuses the native work buffers instead of allocating per call. Use it as a context manager.
  n_max: 4000
  survived: True
  tier: 1
  snr_gain_db: 9.112
  survived: True
  tier: 2
  snr_gain_db: 8.21
  survived: True
  tier: 3
  snr_gain_db: 5.575

-- Act 3 - One-shot vs Session parity --
  -> Session results match the one-shot API exactly - it is purely a performance wrapper, not a different algorithm.
  identical: True

-- Run complete --
  next_journey: 06_limits.py
  survived: True

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/05_diagnostics.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a, numpy as np; r=a.denoise(np.random.default_rng(0).standard_normal(2000)); print(r.tier_selected, r.embed_dim_used, round(r.wall_s,4))"

Example 6: Journey 06 — Limits and non-goals

Where Assured Signal fits - and where it does not. Not a general audio/DSP suite: no FFT filter bank, EQ, resampling, codec, or perceptual audio pipeline. Not a multi-channel / spectrogram tool: denoise() takes ONE 1-D series. Not a forecaster: it cleans an observed series, it does not extrapolate. clean= is diagnostics-only - never required, never used by the algorithm. Bad inputs raise ValueError; too-short or ill-posed series come back with survived=False and a named failure_mode instead of a silent bad answer.

Walkthrough:

1. What it IS — A denoiser for scalar time series drawn from a deterministic dynamical system (sensor channels, telemetry, physical processes). It reconstructs the low-dimensional attractor structure the noise obscures.

2. What it is NOT — Not a general audio/DSP suite: no FFT filter bank, EQ, resampling, codec, or perceptual audio pipeline. Not a multi-channel / spectrogram tool: denoise() takes ONE 1-D series. Not a forecaster: it cleans an observed series, it does not extrapolate. clean= is diagnostics-only - never required, never used by the algorithm.

3. Honest failure modes — Bad inputs raise ValueError; too-short or ill-posed series come back with survived=False and a named failure_mode instead of a silent bad answer.

   • 2-D array: ValueError: noisy must be a 1-D array (got shape (4, 4))
   • unknown method: ValueError: unknown method 'nope'; choose from ['bse_adaptive', 'bse_dynamic', 'bse_enhanced', 'iterative_lp', 'lp_wavelet', 'vanilla_lp', 'wavelet_bse']
   • mismatched clean: ValueError: clean length 50 != noisy length 200

4. Graceful survived=False — A tiny series is handled without an exception - inspect survived / failure_mode and decide downstream.

   • survived: True
   • failure_mode: ok
   • failure_msg: (none)

5. Right-sized use — Give it a few hundred+ samples from a real dynamical channel (like the Lorenz-x journeys) and it delivers measurable SNR gain with full diagnostics.

   • survived: True
   • tier: 1

Guided tour output (from a verified run):

Where Assured Signal fits - and where it does not

-- Act 1 - What it IS --
  -> A denoiser for scalar time series drawn from a deterministic dynamical system (sensor channels, telemetry, physical processes). It reconstructs the low-dimensional attractor structure the noise obscures.

-- Act 2 - What it is NOT --
  -> Not a general audio/DSP suite: no FFT filter bank, EQ, resampling, codec, or perceptual audio pipeline. Not a multi-channel / spectrogram tool: denoise() takes ONE 1-D series. Not a forecaster: it cleans an observed series, it does not extrapolate. clean= is diagnostics-only - never required, never used by the algorithm.

-- Act 3 - Honest failure modes --
  -> Bad inputs raise ValueError; too-short or ill-posed series come back with survived=False and a named failure_mode instead of a silent bad answer.
  2-D array: ValueError: noisy must be a 1-D array (got shape (4, 4))
  unknown method: ValueError: unknown method 'nope'; choose from ['bse_adaptive', 'bse_dynamic', 'bse_enhanced', 'iterative_lp', 'lp_wavelet', 'vanilla_lp', 'wavelet_bse']
  mismatched clean: ValueError: clean length 50 != noisy length 200

-- Act 4 - Graceful survived=False --
  -> A tiny series is handled without an exception - inspect survived / failure_mode and decide downstream.
  survived: True
  failure_mode: ok
  failure_msg: (none)

-- Act 5 - Right-sized use --
  -> Give it a few hundred+ samples from a real dynamical channel (like the Lorenz-x journeys) and it delivers measurable SNR gain with full diagnostics.
  survived: True
  tier: 1

-- Run complete --
  review: You have completed the Assured Signal journeys.

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_limits.py
 
# Production one-liner — same API call you ship:
python -c "import assured_signal as a, numpy as np; print(a.denoise(np.arange(8,dtype=float)).failure_mode)"

Example bundle

Every journey is a domain scenario with narrated acts — run the guided tour first to see what each number means, then copy the production one-liner into your pipeline.

Guided journeys

Run from the python/ directory after install and license activation. Set ASSURED_SIGNAL_QUIET=1 only when you want silent CLI runs (no narration).