PhaseSanitizer Configuration Options: Complete Guide to WiFi DensePose Phase Sanitization

The PhaseSanitizer class accepts a configuration dictionary with three required parameters (unwrapping_method, outlier_threshold, smoothing_window) and six optional boolean or numeric settings that control phase unwrapping, outlier removal, smoothing, and noise filtering.

The PhaseSanitizer class in the ruvnet/wifi-densepose repository manages WiFi CSI phase data cleaning through a flexible configuration system. Understanding the available PhaseSanitizer configuration options is essential for tuning the sanitization pipeline to your specific signal processing requirements. All configuration validation occurs in the constructor via the _validate_config method defined in v1/src/core/phase_sanitizer.py.

Required PhaseSanitizer Configuration Parameters

Three configuration keys are mandatory when instantiating the PhaseSanitizer. The constructor raises ValueError if any are missing or invalid.

unwrapping_method

The unwrapping_method parameter selects the algorithm used by unwrap_phase to resolve phase discontinuities.

• Type: String
• Accepted values: "numpy", "scipy", "custom"
• Effect: Determines whether _unwrap_numpy, _unwrap_scipy, or _unwrap_custom handles the unwrapping logic
• Validation: Invalid values trigger ValueError at lines 66-68 in phase_sanitizer.py

outlier_threshold

This parameter controls the sensitivity of outlier detection in the _detect_outliers method.

• Type: Positive float (Z-score cutoff)
• Constraint: Must be greater than 0
• Effect: Values with Z-scores exceeding this threshold are flagged as outliers for interpolation
• Validation: Checked at lines 71-75 in the source

smoothing_window

The smoothing_window sets the kernel size for the moving average smoother applied by _apply_moving_average.

• Type: Positive integer
• Behavior: Even values are automatically converted to odd numbers internally
• Effect: Larger windows produce smoother phase curves but may reduce temporal resolution

Optional PhaseSanitizer Configuration Parameters

Six additional boolean and numeric settings fine-tune pipeline behavior. All optional parameters include sensible defaults.

enable_outlier_removal

Controls whether the remove_outliers method processes data or returns inputs unchanged.

• Type: Boolean
• Default: True
• Effect: When False, outlier detection and interpolation are skipped entirely

enable_smoothing

Determines if smooth_phase applies the moving average filter.

• Type: Boolean
• Default: True
• Effect: When disabled, phase data passes through without windowed averaging

enable_noise_filtering

Activates low-pass Butterworth filtering via filter_noise.

• Type: Boolean
• Default: False
• Effect: When True, applies frequency-domain filtering to suppress high-frequency noise components

noise_threshold

Specifies the cutoff frequency for the Butterworth filter as a fraction of the Nyquist frequency.

• Type: Float
• Range: 0 < threshold ≤ 0.5
• Default: 0.05
• Effect: Lower values create stricter low-pass filters, removing more high-frequency content

phase_range

Defines valid bounds for phase values checked by validate_phase_data.

• Type: Tuple of two floats
• Default: (-np.pi, np.pi)
• Effect: Values outside this range raise PhaseSanitizationError during validation

Configuration Validation in PhaseSanitizer

The constructor enforces configuration integrity through the private _validate_config method located at lines 59-75 in v1/src/core/phase_sanitizer.py.

The validation sequence performs three critical checks:

1. Presence verification: Ensures all three required keys (unwrapping_method, outlier_threshold, smoothing_window) exist in the configuration dictionary (lines 59-66)
2. Algorithm validation: Confirms unwrapping_method belongs to the allowed set {'numpy','scipy','custom'} (lines 66-68)
3. Numeric constraints: Verifies that outlier_threshold and smoothing_window are positive numbers (lines 71-75)

Any validation failure immediately raises ValueError, preventing instantiation with invalid parameters.

How Configuration Affects the Sanitization Pipeline

The sanitize_phase method orchestrates the complete processing workflow, with each configuration option controlling specific stages:

Phase Unwrapping: The unwrapping_method parameter determines which algorithm resolves 2π discontinuities. The selection occurs in unwrap_phase, which delegates to _unwrap_numpy, _unwrap_scipy, or _unwrap_custom accordingly.

Outlier Processing: When enable_outlier_removal is True, remove_outliers executes _detect_outliers using the Z-score threshold defined by outlier_threshold, followed by _interpolate_outliers to fill gaps.

Smoothing: The smooth_phase method applies _apply_moving_average with a window size of smoothing_window only when enable_smoothing is enabled.

Noise Filtering: If enable_noise_filtering is True, filter_noise invokes _apply_low_pass_filter using the noise_threshold as the normalized cutoff frequency.

Range Validation: Throughout the pipeline, validate_phase_data ensures all values remain within phase_range, raising PhaseSanitizationError for out-of-bound data.

Practical PhaseSanitizer Configuration Examples

Minimal Required Configuration

Instantiate PhaseSanitizer with only the mandatory parameters:

import numpy as np
from src.core.phase_sanitizer import PhaseSanitizer

# Minimal required config

basic_cfg = {
    "unwrapping_method": "numpy",
    "outlier_threshold": 3.0,
    "smoothing_window": 5,
}

sanitizer = PhaseSanitizer(config=basic_cfg)

# Example raw CSI phase matrix (2 antennas × 100 samples)

raw_phase = np.random.uniform(-np.pi, np.pi, (2, 100))

# Full pipeline

clean_phase = sanitizer.sanitize_phase(raw_phase)
print(clean_phase.shape)   # (2, 100)

Full Configuration with All Optional Features

Enable advanced processing options for noisy environments:

full_cfg = {
    "unwrapping_method": "custom",
    "outlier_threshold": 2.5,
    "smoothing_window": 7,
    "enable_outlier_removal": True,
    "enable_smoothing": True,
    "enable_noise_filtering": True,
    "noise_threshold": 0.1,
    "phase_range": (-np.pi, np.pi),
}
sanitizer = PhaseSanitizer(config=full_cfg)

Monitoring Sanitization Statistics

Access processing metrics after running the pipeline:

stats = sanitizer.get_sanitization_statistics()
print(stats)

# {'total_processed': 1, 'outliers_removed': 0, 'sanitization_errors': 0,

#  'outlier_rate': 0.0, 'error_rate': 0.0}

Summary

The PhaseSanitizer class in ruvnet/wifi-densepose provides nine configuration options that control WiFi CSI phase data processing:

• Three required parameters: unwrapping_method (algorithm selection), outlier_threshold (Z-score cutoff), and smoothing_window (moving average size)
• Six optional toggles: Boolean flags for enabling outlier removal, smoothing, and noise filtering, plus numeric settings for noise threshold and valid phase ranges
• Strict validation: The _validate_config method enforces type checking and value constraints during instantiation, raising ValueError for invalid configurations
• Pipeline integration: Each setting directly controls specific methods in the sanitization workflow, from phase unwrapping to Butterworth filtering

Frequently Asked Questions

What happens if I omit a required configuration key in PhaseSanitizer?

The constructor raises a ValueError immediately during instantiation. The _validate_config method checks for the presence of unwrapping_method, outlier_threshold, and smoothing_window at lines 59-66 in v1/src/core/phase_sanitizer.py, preventing the object from being created with incomplete settings.

Can I disable specific processing stages without modifying the source code?

Yes. Set enable_outlier_removal, enable_smoothing, or enable_noise_filtering to False in your configuration dictionary. These boolean flags make remove_outliers, smooth_phase, and filter_noise return data unchanged, effectively bypassing those pipeline stages while preserving the method interfaces.

What is the difference between outlier_threshold and noise_threshold?

The outlier_threshold is a required Z-score cutoff (positive float) used in _detect_outliers to identify and interpolate anomalous phase samples. The noise_threshold is an optional normalized frequency cutoff (0 < value ≤ 0.5) used by _apply_low_pass_filter to configure the Butterworth filter's passband, defaulting to 0.05 when enable_noise_filtering is True.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}