# PhaseSanitizer Configuration Options: Complete Guide to WiFi DensePose Phase Sanitization

> Explore PhaseSanitizer configuration options for WiFi DensePose. Learn about unwrapping_method, outlier_threshold, smoothing_window, and over 6 optional settings for phase sanitization.

- Repository: [rUv/wifi-densepose](https://github.com/ruvnet/wifi-densepose)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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`](https://github.com/ruvnet/wifi-densepose/blob/main/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`](https://github.com/ruvnet/wifi-densepose/blob/main/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`](https://github.com/ruvnet/wifi-densepose/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/ruvnet/wifi-densepose/blob/main/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.