Inspect and audit a dataset¶

Use rfgen inspect to run a read-only audit before training, publication, or Phase 2 annotation. The command reads stored metadata, not IQ samples, and prints one JSON object containing the audit report and a bounded metadata sample.

When to use this¶

Run the inspection after a local smoke run, production generation run, resume, or export. Run it again after changing the requested class distribution, SNR grid, overlap rate, or spectral occupancy target.

Inspect a local dataset¶

Pass the dataset URI or path. The default storage backend is zarr_local, and the default metadata sample contains three records.

rfgen inspect ./out/local-smoke

Choose a different shipped or plugin-provided storage backend with --backend:

rfgen inspect gs://rf-fm-datasets-synth/wideband/v0.5.0 \
  --backend zarr_gcs

Set --sample-size 0 when only the aggregate report is needed. Valid sample sizes range from 0 through 100.

rfgen inspect ./out/local-smoke --sample-size 0
rfgen inspect ./out/local-smoke --sample-size 10

The command opens the store in read mode and never modifies its contents.

Read the output¶

The command emits a JSON object with two top-level keys:

report contains the aggregate audit fields.
records contains at most sample_size metadata-only stored records.

The report includes:

Field	Interpretation
`record_count`	Number of metadata records inspected.
`snr_db`	Realized SNR minimum, maximum, mean, and approximate p10, p50, and p90.
`class_histogram`	Realized emitter count by canonical class name.
`cochannel_overlap_rate`	Mean realized cochannel-overlap rate.
`spectral_occupancy`	Mean realized spectral occupancy.
`emitter_count_histogram`	Realized record count by emitter count.
`requested_emitter_count_histogram`	Requested record count by emitter count when requested metadata is present.
`quantile_method`	The deterministic bottom-hash reservoir method used for SNR quantiles.
`quantile_sample_size`	Number of SNR observations retained for quantiles, at most `10_000`.
`snr_bucket_count`	Number of requested-SNR buckets compared.

SNR count, minimum, maximum, and mean accumulation is exact. The three quantiles are deterministic approximations from at most 10_000 retained SNR observations, so do not treat them as exact percentiles for larger datasets.

Understand audit failures¶

When requested targets are present in stored metadata, the audit compares them with realized values. The default tolerances are:

Comparison	Default tolerance
Mean realized SNR per requested-SNR bucket	`0.5 dB` absolute error
Realized class distribution	`0.05` KL divergence
Mean cochannel-overlap rate	`0.02` absolute error
Mean spectral occupancy	`0.05` absolute error

Exceeding a tolerance raises a structured ValidationError with a per-metric breakdown. Records without the corresponding requested target do not participate in that comparison.

Configure audit bounds¶

AuditConfig prevents unbounded audit state. Its default limits are:

Field	Default
`max_records`	`1_000_000`
`max_class_cardinality`	`10_000`
`max_snr_bucket_cardinality`	`10_000`
`max_emitter_count_cardinality`	`10_000`

Exceeding a bound raises a structured ValidationError. Raise a limit only when the dataset size, taxonomy, requested SNR grid, or emitter-count range intentionally requires it. The current CLI uses the defaults; call audit_dataset(store, config=AuditConfig(...)) from Python to supply custom thresholds or bounds.

AuditConfig bounds metadata cardinality as well as record count. The Python and Hydra field names are max_class_cardinality, max_snr_bucket_cardinality, and max_emitter_count_cardinality; each defaults to 10_000. A dataset exceeding any bound fails with a structured ValidationError instead of allowing an unbounded histogram or SNR-bucket map to grow in memory. Raise a bound only when the dataset taxonomy or requested SNR grid intentionally requires it.

Troubleshoot¶

Symptom	Fix
Missing records	Re-run the same generation command; completed shards are skipped.
Unexpected class balance	Inspect the resolved generation config and requested class distribution.
SNR threshold failure	Compare the reported bucket error with the requested SNR metadata and channel configuration.
Cardinality-bound failure	Check for malformed or unexpectedly unique class, SNR, or emitter-count values before raising the bound.
Too much record detail in output	Set `--sample-size 0` or a smaller value.