velocity_check

Provides VelocityCheckRunner — the class that ProcessedDataset.apply_velocity_check() delegates to. Use it directly for finer control over individual checks or to inspect per-check statistics.

VelocityCheckRunner

import pyadps
from pyadps.processing.velocity_check import VelocityCheckRunner

ds = pyadps.read('deployment.000')
runner = VelocityCheckRunner(ds)

QC Check Methods

All methods return self for chaining.

Method	Default	Description
`magnetic_correction(declination, lat, lon, year, use_api)`	—	Rotate U/V to correct for magnetic declination
`threshold(cutoff_u=2500, cutoff_v=2500, cutoff_w=500)`	mm/s	Flag cells exceeding per-component velocity limits
`despike(kernel_size=13, cutoff=3.0)`	σ=3	Flag transient spikes using a median-filter approach
`flatline(kernel_size=4, cutoff=1.0)`	1 mm/s	Flag constant-value segments (frozen sensor)

Control and Output Methods

Method	Description
`reset()`	Restore working dataset to original state
`finalize()`	Return processed `xarray.Dataset`
`apply_pipeline(checks, order)`	Apply multiple checks from a configuration dict

Statistics Methods

Method	Description
`get_statistics()`	Dict of `QCCheckStats` keyed by check name
`get_modifications()`	Dict of `DataModificationStats` for data corrections
`print_statistics()`	Print formatted QC summary table
`get_pipeline_report()`	Return `QCPipelineReport` for `ProcessedDataset`

Usage

runner = VelocityCheckRunner(ds)
ds_qc = (runner
    .magnetic_correction(declination=-5.0)
    .threshold(cutoff_u=2500, cutoff_v=2500, cutoff_w=500)
    .despike(kernel_size=13, cutoff=3.0)
    .flatline(kernel_size=4, cutoff=1.0)
    .finalize())

runner.print_statistics()

Non-Obvious Behaviors

magnetic_correction() modifies data values, not the mask. It rotates U and V to true geographic coordinates. Apply it before any QC checks so that thresholds apply to geographically-correct velocities.

Declination sources. Provide declination directly, or supply lat, lon, and year to calculate it from local COF files. Set use_api=True for NOAA online lookup.

# Known declination
runner.magnetic_correction(declination=-5.0)

# Calculate from position (requires pygeomag)
runner.magnetic_correction(lat=40.0, lon=-74.0, year=2023.5)

W threshold is asymmetric by design. Vertical velocities are physically 5–10× smaller than horizontal, so the default cutoff_w=500 mm/s is already more restrictive than the horizontal defaults of 2500 mm/s.

Beam 3 is a combined flag. After every check, beam 3 in the mask is set to the OR of beams 0, 1, and 2 — a cell is flagged in beam 3 if any velocity component fails.