fix #472

[tapyu]

Problem

Signal metadata written to the HDF5 dataset (_lower_frequency/_upper_frequency) can end up mirrored to the wrong side of 0 Hz relative to the signal's actual center_freq — for a subset of signals, the bounding box lands on the opposite side of baseband from where the signal's energy actually is.

Reproduced with a minimal FM dataset (Impairments(level=0), 200 signals): 140/200 (70%) of emitter records had _lower_frequency/_upper_frequency values inconsistent with their own center_freq — specifically, avg(_lower_frequency, _upper_frequency) ≈ -center_freq.

Root cause

_lower_frequency/_upper_frequency are cached side effects of reading the upper_freq/lower_freq properties (signals/signal_types.py) — they get computed from center_freq/bandwidth and written back into the metadata dict at read time, but nothing invalidates that cache when center_freq/bandwidth are mutated afterward via direct item assignment.

In practice:

• datasets/dataset_utils.py::frequency_shift_signal is the only call site that ever reads .upper_freq/.lower_freq (populating the cache), right after the initial random RF placement — before the anti-aliasing-filter branch, which can then overwrite center_freq/bandwidth again without refreshing the cache.
• ChannelSwap, SpectralInversion, TimeReversal, and Doppler (transforms/transforms.py) all mutate signal["center_freq"] (and, for Doppler, bandwidth) directly — including on component_signals — without touching the cache either.
• At write time, utils/file_handlers/hdf5.py::populate_hdf5_group_with_metadata serializes every raw key in the metadata dict verbatim, so whatever stale value happens to be cached is what lands on disk.

Fix

• signals/signal_types.py: add SignalMetadataObject.sync_frequency_bounds(), which force-refreshes _lower_frequency/_upper_frequency from the current center_freq/bandwidth.
• datasets/dataset_utils.py: call it in frequency_shift_signal after the anti-aliasing-filter branch.
• transforms/transforms.py: call it in ChannelSwap, SpectralInversion, TimeReversal, and Doppler, for both the signal and each of its component_signals, right after they mutate center_freq/bandwidth.
• utils/file_handlers/hdf5.py: as a backstop, force a refresh in populate_hdf5_group_with_metadata immediately before serializing, so the written values are correct regardless of which code path touched center_freq/bandwidth last.

Testing

Regenerated a 200-signal FM dataset (Impairments(level=0)) before and after the fix and checked every emitter's _lower_frequency/_upper_frequency against center_freq/bandwidth for consistency:

	mismatched records
before	131 / 200 (70%)
after	0 / 200

Fixes #472

[tapyu]

Here is the code you can check this fix

import h5py

from torchsig.datasets.datasets import TorchSigIterableDataset
from torchsig.utils.data_loading import WorkerSeedingDataLoader
from torchsig.signals.builders.fm import FMSignalGenerator
from torchsig.utils.writer import DatasetCreator, default_collate_fn
from torchsig.transforms.impairments import Impairments

dataset_metadata = {
    "num_iq_samples_dataset": 108_032,
    "fft_size": 512,
    "num_signals_min": 1,
    "num_signals_max": 1,
    "sample_rate": 20e6,
    "noise_power_db": 0,
    "snr_db_min": 50,
    "snr_db_max": 50,
    "signal_duration_min": 0.00378112,
    "signal_duration_max": 0.00378112,
    "bandwidth_min": 500e3,
    "bandwidth_max": 1e6,
    "signal_duration_in_samples_min": 75622,
    "signal_duration_in_samples_max": 75622,
    "frequency_min": -10e6,
    "frequency_max": 10e6,
    "signal_center_freq_min": -9e6,
    "signal_center_freq_max": 9e6,
    "class_list": "fm",
    "class_distribution": "1",
    "fft_stride": 512,
    "cochannel_overlap_probability": 0,
}


def get_dataset():

    impairments = Impairments(level=0)  # noiseless channel

    iter_dataset = TorchSigIterableDataset(
        signal_generators=[FMSignalGenerator(**dataset_metadata)],
        metadata=dataset_metadata,
        transforms=[impairments.dataset_transforms],
        component_transforms=[impairments.signal_transforms],
        target_labels=['class_name', 'start_in_samples', 'duration_in_samples', 'lower_freq', 'upper_freq', 'snr_db'],
        seed=14,
    )

    dataloader = WorkerSeedingDataLoader(
        iter_dataset,
        seed=14,
        batch_size=8,
        num_workers=10,
        collate_fn=default_collate_fn,
    )

    dataset_creator = DatasetCreator(
        dataset_length=200,
        dataloader=dataloader,
        root='dataset',
        overwrite=True,
        multithreading=True,
    )
    dataset_creator.create()
    print(f"Dataset created at {dataset_creator.root}")


def count_mismatched_metadata(rel_tol: float = 1e-6) -> tuple[int, int]:
    """Checks every signal metadata record in the generated dataset for
    internal consistency between `center_freq`/`bandwidth` and the derived
    `_lower_frequency`/`_upper_frequency` fields.

    A record is "mismatched" when either:
      - avg(_lower_frequency, _upper_frequency) != center_freq, or
      - (_upper_frequency - _lower_frequency) != bandwidth

    beyond a small numerical tolerance. This is the bug signature: TorchSig
    caches `_lower_frequency`/`_upper_frequency` as a side effect of reading
    the `upper_freq`/`lower_freq` properties, but nothing refreshes that
    cache when `center_freq`/`bandwidth` are mutated afterward (e.g.
    anti-aliasing clipping, ChannelSwap, SpectralInversion, TimeReversal,
    Doppler) -- so the cached values can go stale and end up inconsistent,
    including fully mirrored to the opposite side of 0 Hz.

    Returns:
        tuple[int, int]: (number of mismatched records, total records checked)
    """
    n_records = 0
    n_mismatched = 0

    required_fields = ("center_freq", "bandwidth", "_lower_frequency", "_upper_frequency")

    with h5py.File("dataset/data.h5", "r") as f:
        metadata = f["metadata"]
        for key in metadata.keys():
            record = metadata[key]
            if not all(field in record for field in required_fields):
                continue

            center_freq = record["center_freq"][()]
            bandwidth = record["bandwidth"][()]
            lower_freq = record["_lower_frequency"][()]
            upper_freq = record["_upper_frequency"][()]

            n_records += 1

            tol = max(1.0, rel_tol * max(abs(bandwidth), abs(center_freq)))
            center_mismatch = abs((lower_freq + upper_freq) / 2 - center_freq) > tol
            bandwidth_mismatch = abs((upper_freq - lower_freq) - bandwidth) > tol

            if center_mismatch or bandwidth_mismatch:
                n_mismatched += 1

    print(f"Mismatched metadata records: {n_mismatched} / {n_records}")
    return n_mismatched, n_records


def main():
    get_dataset()
    count_mismatched_metadata()


if __name__ == "__main__":
    main()