Transforms¶

Transforms are applied to signals or samples to emulate transmitter and reciever effects, as well as tools for machine learning. There are three types of transforms, that differ in purpose and scope.

torchsig.transforms.transforms.Transform - may be applied to isolated signals from the signal builder (typically representing transmitter effects), or may be applied to samples, after isolated signals are placed onto a noise floor (typically represents receiver effects and other machine learning transforms).
torchsig.transforms.impairments.Impairments - special collections of Transforms that represent an environment.
Functionals - core logic of Transforms. Users can use for more fine-grained control of the transform.

Transforms ¶

Base Transforms ¶

Base and Utility Transforms

class torchsig.transforms.base_transforms.Compose(transforms: list[Transform], **kwargs)[source]¶

Bases: Transform

Composes several transforms together sequentially, in order.

This transform applies a sequence of transforms to the input signal.

transforms¶: List of Transform objects to be applied sequentially.

class torchsig.transforms.base_transforms.Lambda(func: callable, **kwargs)[source]¶

Bases: Transform

Apply a user-defined lambda as a transform.

Warning: Does not automatically update metadata.

func¶: Lambda/function to be used for transform.

Example

>>> from torchsig.transforms.base_transforms import Lambda
>>> transform = Lambda(lambda x: x**2)  # A transform that squares all inputs.

class torchsig.transforms.base_transforms.Normalize(norm: float | Literal['fro', 'nuc'] | None = 2, flatten: bool = False, **kwargs)[source]¶

Bases: Transform

Normalize an IQ data vector.

This transform normalizes the IQ data according to the specified norm.

norm¶: Order of the norm (refer to numpy.linalg.norm).

flatten¶: Specifies if the norm should be calculated on the flattened representation of the input tensor.

Example

>>> import torchsig.transforms as ST
>>> transform = ST.Normalize(norm=2) # normalize by l2 norm
>>> transform = ST.Normalize(norm=1) # normalize by l1 norm
>>> transform = ST.Normalize(norm=2, flatten=True) # normalize by l1 norm of the 1D representation

class torchsig.transforms.base_transforms.RandAugment(transforms: list[Transform], choose: int = 2, replace: bool = False, **kwargs)[source]¶

Bases: Transform

RandAugment transform loosely based on: `”RandAugment: Practical automated data augmentation with a reduced search space”

<https://arxiv.org/pdf/1909.13719.pdf>`_.

This transform randomly selects and applies a subset of transforms from a list.

transforms¶: List of Transforms to choose from.

choose¶: Number of Transforms to randomly choose. Defaults to 2.

replace¶: Allow replacement in random choose. Defaults to False.

class torchsig.transforms.base_transforms.RandomApply(transform, probability: float, **kwargs)[source]¶

Bases: Transform

Randomly applies transform with probability p.

This transform applies the specified transform with a given probability.

transform¶: Transform to randomly apply.

probability¶: Probability to apply transform in range [0., 1.].

class torchsig.transforms.base_transforms.Transform(required_metadata: list[str] = [], **kwargs)[source]¶

Bases: ABC, Seedable

Transform abstract class.

This is the base class for all transforms in TorchSig. All transforms should inherit from this class and implement the required methods.

Signal Transforms ¶

Transforms on Signal objects.

class torchsig.transforms.transforms.AWGN(noise_power_db: float, precise: bool = False, **kwargs)[source]¶

Bases: SignalTransform

Apply Additive White Gaussian Noise to signal.

This transform adds AWGN to the signal with specified power level.

noise_power_db¶: Noise AWGN power in dB (absolute).

precise¶: Measure and update SNR metadata. Default to False.

class torchsig.transforms.transforms.AddSlope(**kwargs)[source]¶

Bases: SignalTransform

Add the slope of each sample with its preceding sample to itself.

Creates a weak 0 Hz IF notch filtering effect.

class torchsig.transforms.transforms.AdditiveNoise(power_range: tuple = (0.01, 10.0), color: str = 'white', continuous: bool = True, precise: bool = False, **kwargs)[source]¶

Bases: SignalTransform

Adds noise with specified properties to signal.

This transform adds noise with configurable power, color, and continuity to the signal.

power_range¶: Range bounds for interference power level (W). Defaults to (0.01, 10.0).

power_distribution¶: Random draw of interference power.

color¶: Noise color, supports ‘white’, ‘pink’, or ‘red’ noise frequency spectrum types. Defaults to ‘white’.

continuous¶: Sets noise to continuous (True) or impulsive (False). Defaults to True.

precise¶: Measure and update SNR metadata. Default to False.

class torchsig.transforms.transforms.AdjacentChannelInterference(sample_rate: float = 1.0, power_range: tuple = (0.01, 10.0), center_frequency_range: tuple = (0.2, 0.3), phase_sigma_range: tuple = (0.0, 1.0), time_sigma_range: tuple = (0.0, 10.0), filter_weights: ndarray | None = None, **kwargs)[source]¶

Bases: SignalTransform

Apply adjacent channel interference to signal.

This transform adds interference from an adjacent channel with configurable parameters.

sample_rate¶: Sample rate (normalized). Defaults to 1.0.

power_range¶: Range bounds for interference power level (W). Defaults to (0.01, 10.0).

power_distribution¶: Random draw of interference power.

center_frequency_range¶: Range bounds for interference center frequency (normalized). Defaults to (0.2, 0.3).

center_frequency_distribution¶: Random draw of interference power.

phase_sigma_range¶: Range bounds for interference phase sigma. Defaults to (0.0, 1.0).

phase_sigma_distribution¶: Random draw of phase sigma.

time_sigma_range¶: Range bounds for interference time sigma. Defaults to (0.0, 10.0).

time_sigma_distribution¶: Random draw of time sigma.

filter_weights¶: Predefined baseband lowpass filter, fixed for all calls. Defaults to low_pass(0.125, 0.125, 1.0).

class torchsig.transforms.transforms.CarrierFrequencyDrift(drift_ppm: tuple[float, float] = (0.1, 10), **kwargs)[source]¶

Bases: SignalTransform

Apply carrier frequency drift to signal.

This transform simulates frequency drift in the carrier signal.

drift_ppm_range¶: Drift in parts per million (ppm). Default (0.1,1).

drift_ppm_distribution¶: Random draw from drift_ppm_range distribution.

class torchsig.transforms.transforms.CarrierPhaseNoise(phase_noise_degrees: tuple[float, float] = (0.25, 1), **kwargs)[source]¶

Bases: SignalTransform

Apply Carrier phase noise to signal.

This transform simulates phase noise in the carrier signal.

phase_noise_degrees¶: Range for phase noise (in degrees). Defaults to (0.25, 1).

phase_noise_degrees_distribution¶: Random draw from phase_noise_degrees distribution.

class torchsig.transforms.transforms.CarrierPhaseOffset(phase_offset_range: tuple[float, float] = (0, 6.283185307179586), **kwargs)[source]¶

Bases: SignalTransform

Apply a randomized carrier phase offset to signal.

The randomized phase offset is of the form exp(j * phi) where phi is in the range of 0 to 2pi radians. Real world effects such as time delays as a signal transits the air and others can cause such randomized phase offsets. The transform does not usually require any arguments due to its simplicity. It is generally unrealistic to have a randomized phase offset of a range less than 0 to 2pi.

phase_offset_range¶: Range bounds for phase offset (radians).

phase_offset_distribution¶: Random draw from phase offset distribution.

class torchsig.transforms.transforms.ChannelSwap(**kwargs)[source]¶

Bases: SignalTransform

Swaps the I and Q channels of complex input data.

class torchsig.transforms.transforms.ClockDrift(drift_ppm: tuple[float, float] = (1, 10), **kwargs)[source]¶

Bases: SignalTransform

Simulates a clock drift effect, which applies a random error to the sampling rate.

class torchsig.transforms.transforms.ClockJitter(jitter_ppm: tuple[float, float] = (1, 10), **kwargs)[source]¶

Bases: SignalTransform

Simulates a clock jitter effect, which applies a random error to the sampling phase.

class torchsig.transforms.transforms.CoarseGainChange(gain_change_db: tuple[float, float] = (-20, 20), **kwargs)[source]¶

Bases: SignalTransform

Apply a randomized instantaneous jump in signal magnitude to model an abrupt receiver gain change.

gain_change_db_range¶: Sets the (min, max) gain change in dB.

gain_change_db_distribution¶: Random draw from gain_change_db distribution.

class torchsig.transforms.transforms.CochannelInterference(power_range: tuple = (0.01, 10.0), filter_weights: ndarray | None = None, color: str = 'white', continuous: bool = True, **kwargs)[source]¶

Bases: SignalTransform

Apply cochannel interference to signal.

This transform adds interference that shares the same channel as the signal.

power_range¶: Range bounds for interference power level (W). Default (0.01, 10.0).

power_distribution¶: Random draw of interference power.

filter_weights¶: Predefined baseband lowpass filter, fixed for all calls. Default low_pass(0.125, 0.125, 1.0).

noise_color¶: Base noise color, supports ‘white’, ‘pink’, or ‘red’ noise frequency spectrum types. Default ‘white’.

continuous¶: Sets noise to continuous (True) or impulsive (False). Default True.

precise¶: Measure and update SNR metadata. Default to False.

class torchsig.transforms.transforms.ComplexTo2D(**kwargs)[source]¶

Bases: SignalTransform

Converts IQ data to two channels (real and imaginary parts).

class torchsig.transforms.transforms.CutOut(duration=(0.01, 0.2), cut_type: list[str] = ['zeros', 'ones', 'low_noise', 'avg_noise', 'high_noise'], **kwargs)[source]¶

Bases: SignalTransform

Applies the CutOut transform operation in the time domain.

The cut_dur input specifies how long the cut region should be, and the cut_fill input specifies what the cut region should be filled in with. Options for the cut type include: zeros, ones, low_noise, avg_noise, and high_noise. Zeros fills in the region with zeros; ones fills in the region with 1+1j samples; low_noise fills in the region with noise with -100dB power; avg_noise adds noise at power average of input data, effectively slicing/removing existing signals in the most RF realistic way of the options; and high_noise adds noise with 40dB power. If a list of multiple options are passed in, they are randomly sampled from. This transform is loosely based on “Improved Regularization of Convolutional Neural Networks with Cutout”.

duration¶: cut_dur sets the duration of the region to cut out * If float, cut_dur is fixed at the value provided. * If list, cut_dur is any element in the list. * If tuple, cut_dur is in range of (tuple[0], tuple[1]).

duration_distribution¶: Random draw from duration distribution.

cut_type¶: cut_fill sets the type of data to fill in the cut region with from the options: zeros, ones, low_noise, avg_noise, and high_noise * If list, cut_fill is any element in the list. * If str, cut_fill is fixed at the method provided.

cut_type_distribution¶: Random draw from cut_type distribution.

class torchsig.transforms.transforms.DigitalAGC(initial_gain_db: tuple[float] = (0, 0), alpha_smooth: tuple[float] = (1e-07, 1e-06), alpha_track: tuple[float] = (1e-06, 1e-05), alpha_overflow: tuple[float] = (0.1, 0.3), alpha_acquire: tuple[float] = (1e-06, 1e-05), track_range_db: tuple[float] = (0.5, 2), **kwargs)[source]¶

Bases: SignalTransform

Automatic Gain Control performing sample-by-sample AGC algorithm.

initial_gain_db¶: Inital gain value in dB.

alpha_smooth¶: Alpha for averaging the measure signal level level_n = level_n * alpha + level_n-1(1-alpha)

alpha_track¶: Amount to adjust gain when in tracking state.

alpha_overflow¶: Amount to adjust gain when in overflow state [level_db + gain_db] >= max_level.

alpha_acquire¶: Amount to adjust gain when in acquire state.

track_range_db¶: dB range for operating in tracking state.

class torchsig.transforms.transforms.Doppler(velocity_range: tuple[float, float] = (0.0, 10.0), propagation_speed: float = 299790000.0, **kwargs)[source]¶

Bases: SignalTransform

Apply a wideband Doppler effect to signal.

This transform simulates the Doppler effect caused by relative motion between transmitter and receiver.

velocity_range¶: Relative velocity bounds in m/s. Default (0.0, 10.0)

velocity_distribution¶: Random draw from velocity distribution.

propagation_speed¶: Wave speed in medium. Default 2.9979e8 m/s.

class torchsig.transforms.transforms.Fading(coherence_bandwidth=(0.01, 0.1), power_delay_profile: tuple | list | ndarray = (1, 1), **kwargs)[source]¶

Bases: SignalTransform

Apply a channel fading model to signal.

Note, currently only performs Rayleigh fading:: A Rayleigh fading channel can be modeled as an FIR filter with Gaussian distributed taps which vary over time. The length of the filter determines the coherence bandwidth of the channel and is inversely proportional to the delay spread. The rate at which the channel taps vary over time is related to the coherence time and this is inversely proportional to the maximum Doppler spread. This time variance is not included in this model.

coherence_bandwidth¶: Coherence bandwidth sampling parameters. Defaults to (0.01, 0.1).

coherence_bandwidth_distribution¶: Random draw from coherence bandwidth distribution.

power_delay_profile¶: A list of positive values assigning power to taps of the channel model. When the number of taps exceeds the number of items in the provided power_delay_profile, the list is linearly interpolated to provide values for each tap of the channel. Defaults to (1, 1).

class torchsig.transforms.transforms.IQImbalance(amplitude_imbalance=(-1.0, 1.0), phase_imbalance=(-0.03490658503988659, 0.03490658503988659), dc_offset_db=(0, 3), dc_offset_rads=(0, 6.283185307179586), **kwargs)[source]¶

Bases: SignalTransform

Apply a set of I/Q imbalance effects to a signal: amplitude, phase, and DC offset.

amplitude_imbalance¶: Range bounds of IQ amplitude imbalance (dB).

amplitude_imbalance_distribution¶: Random draw from amplitude imbalance distribution.

phase_imbalance¶: Range bounds of IQ phase imbalance (radians).

phase_imbalance¶: Random draw from phase imbalance distribution.

dc_offset_db¶: Range bounds for DC offset in relative power.

dc_offset_db_distribution¶: Random draw from dc_offset_db distribution.

dc_offset_phase_rads¶: Range bounds for phase of DC offset

dc_offset_phase_rads_distribution¶: Random draw from dc_offset_phase_rads distribution.

class torchsig.transforms.transforms.InterleaveComplex(**kwargs)[source]¶

Bases: SignalTransform

Transforms a complex-valued array into a real-valued array of interleaved IQ values.

class torchsig.transforms.transforms.IntermodulationProducts(model_order: list[int] = [3, 5], coeffs_range: tuple[float, float] = (0.0001, 0.1), **kwargs)[source]¶

Bases: SignalTransform

Apply simulated basebanded intermodulation products to a signal.

model_order¶: The choices model order, 3rd or 5th order. Defaults to [3,5].

coeffs_range¶: Range bounds for each intermodulation coefficient. Defaults to (0., 1.).

class torchsig.transforms.transforms.NonlinearAmplifier(gain_range: tuple[float, float] = (1.0, 1.0), psat_backoff_range: tuple[float, float] = (5.0, 20.0), phi_max_range: tuple[float, float] = (-0.05, 0.05), phi_slope_range: tuple[float, float] = (-0.1, 0.1), auto_scale: bool = True, **kwargs)[source]¶

Bases: SignalTransform

Apply a memoryless nonlinear amplifier model to a signal.

gain_range¶: Small-signal gain range (linear). Defaults to (1.0, 4.0).

gain_distribution¶: Random draw from gain distribution.

psat_backoff_range¶: Psat backoff factor (linear) reflecting saturated power level (Psat) relative to input signal mean power. Defaults to (5.0, 20.0).

psat_backoff_distribution¶: Random draw from psat_backoff distribution.

phi_max_range¶: Maximum signal relative phase shift at saturation power level (radians). Defaults to (-0.05, 0.05).

phi_max_distribution¶: Random draw from phi_max distribution.

phi_slope_range¶: Slope of relative phase shift response (W/radians). Defaults to (-0.1, 0.01).

phi_slope_distribution¶: Random draw from phi_max distribution.

auto_scale¶: Automatically rescale output power to match full-scale peak input power prior to transform, based on peak estimates. Default True.

class torchsig.transforms.transforms.PassbandRipple(max_ripple_db: tuple[float] = (1, 2), num_taps: list[int] = [2, 3], coefficient_decay_rate: tuple[float] = (1, 5), **kwargs)[source]¶

Bases: SignalTransform

Models analog filter passband ripple response for a signal.

max_ripple_db¶: Range for maximum allowable ripple to simulate. Defaults to (1,2).

num_taps¶: List of number of taps in simulated filter. Defaults to [2,3].

coefficient_decay_rate¶: Range for the rate at which the simulated impulse response goes to zero. Defaults to (1, 5).

class torchsig.transforms.transforms.PatchShuffle(patch_size=(3, 10), shuffle_ratio=(0.01, 0.05), **kwargs)[source]¶

Bases: SignalTransform

Randomly shuffle multiple local regions of samples.

Transform is loosely based on “PatchShuffle Regularization”.

patch_size¶

patch_size sets the size of each patch to shuffle * If int or float, patch_size is fixed at the value provided. * If list, patch_size is any element in the list. * If tuple, patch_size is in range of (tuple[0], tuple[1]).

patch_size_distribution: Random draw from patch_size distribution. shuffle_ratio: shuffle_ratio sets the ratio of the patches to shuffle

If int or float, shuffle_ratio is fixed at the value provided.

If list, shuffle_ratio is any element in the list.

If tuple, shuffle_ratio is in range of (tuple[0], tuple[1]).

shuffle_ratio_distribution: Random draw from shuffle_ratio distribution.

class torchsig.transforms.transforms.Quantize(num_bits: tuple[int, int] = (6, 18), ref_level_adjustment_db: tuple[float, float] = (-10, 3), rounding_mode: list[str] = ['floor', 'ceiling'], **kwargs)[source]¶

Bases: SignalTransform

Quantize signal I/Q samples into specified levels with a rounding method.

num_levels¶: Number of quantization levels.

num_levels_distribution¶: Random draw from num_levels distribution.

rounding_mode¶: Quantization rounding method. Must be ‘floor’ or ‘ceiling’.

rounding_mode_distribution¶: Random draw from rounding_mode distribution.

class torchsig.transforms.transforms.RandomDropSamples(drop_rate=(0.01, 0.05), size=(1, 10), fill: list[str] = ['ffill', 'bfill', 'mean', 'zero'], **kwargs)[source]¶

Bases: SignalTransform

Randomly drop IQ samples from the input data of specified durations and with specified fill techniques:

ffill (front fill): replace drop samples with the last previous value.

bfill (back fill): replace drop samples with the next value.

mean: replace drop samples with the mean value of the full data.

zero: replace drop samples with zeros.

Transform is based off of the TSAug Dropout Transform.

drop_rate¶: drop_rate sets the rate at which to drop samples * If int or float, drop_rate is fixed at the value provided. * If list, drop_rate is any element in the list. * If tuple, drop_rate is in range of (tuple[0], tuple[1]).

drop_rate_distribution¶: Random draw from drop_rate distribution.

size¶: size sets the size of each instance of dropped samples * If int or float, size is fixed at the value provided. * If list, size is any element in the list. * If tuple, size is in range of (tuple[0], tuple[1]).

size_distribution¶: Random draw from size distribution.

fill¶: fill sets the method of how the dropped samples should be filled * If list, fill is any element in the list. * If str, fill is fixed at the method provided.

fill_distribution¶: Random draw from fill distribution.

class torchsig.transforms.transforms.Shadowing(mean_db_range: tuple[float, float] = (0.0, 4.0), sigma_db_range: tuple[float, float] = (2.0, 6.0), **kwargs)[source]¶

Bases: SignalTransform

Apply channel shadowing effect across entire signal.

This transform models RF shadowing effects by applying lognormal fading to the input data.

mean_db_range¶: Mean value range in dB. Defaults to (0.0, 4.0).

mean_db_distribution¶: Random draw from mean_db distribution.

sigma_db_range¶: Sigma value range in dB. Defaults to (2.0, 6.0).

sigma_db_distribution¶: Random draw from sigma_db distribution.

Bases: Transform

Base class for performing transforms on Signal objects.

This class provides the foundation for all signal transforms, including: - Signal validation before applying transforms - Transform application - Metadata updates - Data type enforcement

data_dtype¶: Data type to enforce after transform (None for no enforcement)

precise¶: Enable precise (but slower) signal metadata updates

class torchsig.transforms.transforms.SpectralInversion(**kwargs)[source]¶

Bases: SignalTransform

Inverts spectrum of complex signal data.

This transform performs spectral inversion by complex conjugation of the input data.

class torchsig.transforms.transforms.Spectrogram(fft_size: int, **kwargs)[source]¶

Bases: SignalTransform

Computes the spectogram of I/Q data.

This transform computes the spectrogram by applying the Short-Time Fourier Transform (STFT) to the input IQ data.

fft_size¶: The FFT size (number of bins) in the spectrogram.

class torchsig.transforms.transforms.SpectrogramDropSamples(drop_rate=(0.001, 0.005), size=(1, 10), fill: list[str] = ['ffill', 'bfill', 'mean', 'zero', 'low', 'min', 'max', 'ones'], **kwargs)[source]¶

Bases: SignalTransform

Randomly drop samples from the input data of specified durations and with specified fill techniques.

Supported Fill Techniques:

ffill (front fill): replace drop samples with the last previous value
bfill (back fill): replace drop samples with the next value
mean: replace drop samples with the mean value of the full data
zero: replace drop samples with zeros
low: replace drop samples with low power samples
min: replace drop samples with the minimum of the absolute power
max: replace drop samples with the maximum of the absolute power
ones: replace drop samples with ones

Transform is based off of the TSAug Dropout Transform.

drop_rate¶: drop_rate sets the rate at which to drop samples * If int or float, drop_rate is fixed at the value provided. * If list, drop_rate is any element in the list. * If tuple, drop_rate is in range of (tuple[0], tuple[1]).

drop_rate_distribution¶: Random draw from drop_rate distribution.

size¶: size sets the size of each instance of dropped samples * If int or float, size is fixed at the value provided. * If list, size is any element in the list. * If tuple, size is in range of (tuple[0], tuple[1]).

size_distribution¶: Random draw from size distribution.

fill¶: fill sets the method of how the dropped samples should be filled * If list, fill is any element in the list. * If str, fill is fixed at the method provided.

fill_distribution¶: Random draw from fill distribution.

class torchsig.transforms.transforms.SpectrogramImage(fft_size: int, black_hot: bool = True, **kwargs)[source]¶

Bases: SignalTransform

Transforms signal to a spectrogram image.

This transform computes the spectrogram and converts it to a grayscale image.

class torchsig.transforms.transforms.Spurs(num_spurs: tuple[int] = (1, 4), relative_power_db: tuple[float] = (0, 30), **kwargs)[source]¶

Bases: SignalTransform

Simulates spurs by adding tones into the receive signal.

This transform adds spurious signals (tones) at specified frequencies with specified power levels.

num_spurs¶: The range of numbers of spurs to add. Defaults to (1,4).

relative_power_db¶: The range of relative power for the spurs. The power is relative to the noise floor. Defaults to (5,15).

class torchsig.transforms.transforms.TimeReversal(allow_spectral_inversion: bool | float = True, **kwargs)[source]¶

Bases: SignalTransform

Apply a time reversal to the input.

Note that applying a time reversal inherently also applies a spectral inversion. If a time-reversal without spectral inversion is desired, the undo_spectral_inversion argument can be set to True. By setting this value to True, an additional, manual spectral inversion is applied to revert the time-reversal’s inversion effect.

allow_spectral_inversion¶: Whether to allow spectral inversion as a time reversal side effect (True) or not (False). Defaults to True. * If bool, applied to all signals. * If float, applied as probability to add signals.

class torchsig.transforms.transforms.TimeVaryingNoise(noise_power_low=(-80.0, -60.0), noise_power_high=(-40.0, -20.0), inflections=[0, 10], random_regions: list | bool = True, **kwargs)[source]¶

Bases: SignalTransform

Add time-varying noise to signal regions.

This transform adds noise with power levels that vary over time, with specified minimum and maximum power levels and number of inflection points.

noise_power_low¶: Range bounds for minimum noise power in dB.

noise_power_low_distribution¶: Random draw from noise_power_low distribution.

noise_power_high¶: Range bounds for maximum noise power in dB.

noise_power_high_distribution¶: Random draw from noise_power_high distribution.

inflections¶: Number of inflection points over IQ data.

inflections_distribution¶: Random draw from inflections distribution.

random_regions¶: Inflections points spread randomly (True) or evenly (False).

random_regions_distribution¶: Random draw from random_regions distribution.

Impairments ¶

Dataset Transform/Impairment class

Impairments are transforms applied to Signal objects, after the Signal Builder generates an isolated signal. Transforms are applied to Signal objects, after isolated signals are placed on an IQ cut of noise.

class torchsig.transforms.impairments.Impairments(level: int, **kwargs)[source]¶

Bases: Transform

Applies signal and dataset transformations at specific impairment levels.

This class applies a set of signal and dataset transforms based on a given impairment level. The impairment level must be between 0 and 2, where each level corresponds to different sets of transformations for signals and datasets.

Level 0: Perfect (no impairments)
Level 1: Cabled environment (transmit impairments only)
Level 2: Wireless environment (transmit impairments + channel models)

Parameters:

level – The impairment level (must be between 0 and 2).
**kwargs – Additional keyword arguments passed to the parent class Transform.

Raises:

ValueError – If the provided impairment level is outside the valid range (0, 1, 2).

level¶: The specified impairment level.

signal_transforms¶: The composed signal transformations corresponding to the given impairment level.

dataset_transforms¶: The composed dataset transformations corresponding to the given impairment level.

get_signal_transforms() → list[Transform][source]¶

Get the signal transforms for this impairment level.

Returns:: List of signal transforms configured for the current impairment level.

get_dataset_transforms() → list[Transform][source]¶

Get the dataset transforms for this impairment level.

Returns:: List of dataset transforms configured for the current impairment level.

Functional Transforms ¶

Functional transforms for reuse and custom fine-grained control.

torchsig.transforms.functional.add_slope(data: ndarray) → ndarray[source]¶

Add slope between each sample and its preceding sample is added to every sample.

Augmentation has the effect of amplifying high frequency component more than lower frequency components.

Parameters:: data – IQ data.
Returns:: IQ data with added slope.

torchsig.transforms.functional.additive_noise(data: ndarray, power: float = 1.0, color: str = 'white', continuous: bool = True, rng: Generator | None = None) → ndarray[source]¶

Additive complex noise with specified parameters.

Parameters:

data – Complex valued IQ data samples.
power – Desired noise power (linear, positive). Defaults to 1.0 W (0 dBW).
color – Noise color, supports ‘white’, ‘pink’, or ‘red’ noise frequency spectrum types. Defaults to ‘white’.
continuous – Sets noise to continuous (True) or impulsive (False). Defaults to True.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with complex noise samples with specified power added.

torchsig.transforms.functional.adjacent_channel_interference(data: ndarray, sample_rate: float = 4.0, power: float = 1.0, center_frequency: float = 0.2, filter_weights: ndarray | None = None, phase_sigma: float = 1.0, time_sigma: float = 0.0, rng: Generator | None = None) → ndarray[source]¶

Adds adjacent channel interference to the baseband data at a specified center frequency and power level.

The adjacent channel signal is a filtered, frequency-offset, randomly block time-shifted, randomly phase-perturbed baseband copy that has similar bandwidth and modulation properties, but degrades phase and time coherence with the original baseband signal.

Parameters:

data – Complex valued IQ data samples.
sample_rate – Sampling rate (Fs). Default 4.0
power – Adjacent interference signal power (linear, positive). Default 1.0 W (0 dBW).
center_frequency – Adjacent interference signal center frequency (normalized relative to Fs). Default 0.2.
filter_weights – Lowpass filter weights applied to baseband signal data to band limit prior to creating adjacent signal. Default low_pass(0.25,0.25,4.0).
phase_sigma – Standard deviation of Gaussian phase noise. Default 1.0.
time_sigma – Standard deviation of Gaussian block time shift in samples. Default 0.0.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with added adjacent interference.

torchsig.transforms.functional.awgn(data: ndarray, noise_power_db: float, rng: Generator | None = None) → ndarray[source]¶

Adds zero-mean complex additive white Gaussian noise with power of noise_power_db.

Parameters:

data – (batch_size, vector_length, …)-sized data.
noise_power_db – Defined as 10*log10(E[|n|^2]).
random_generator – Random Generator to use. Defaults to None (new generator created internally).

Returns:

Data with added noise.

torchsig.transforms.functional.carrier_frequency_drift(data: ndarray, drift_ppm: float = 1, rng: Generator | None = None) → ndarray[source]¶

Carrier frequency drift from a Local Oscillator (LO), with drift modeled as accumulated gaussian random phase.

Parameters:

data – Complex valued IQ data samples.
drift_ppm – Drift in parts per million (ppm). Default 1.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with LO drift applied.

torchsig.transforms.functional.carrier_phase_noise(data: ndarray, phase_noise_degrees: float = 1.0, rng: Generator | None = None) → ndarray[source]¶

Carrier phase noise from a Local Oscillator (LO) with the noise modeled as a Gaussian RV.

Parameters:

data – Complex valued IQ data samples.
phase_noise_degrees – Phase noise in degrees. Used as standard deviation for Gaussian distribution. Defaults to 1.0.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data mixed with noisy LO.

torchsig.transforms.functional.channel_swap(data: ndarray) → ndarray[source]¶

Swap I and Q channels of IQ data.

Parameters:: data – IQ data.
Returns:: IQ data with channels swapped.

torchsig.transforms.functional.clock_drift(data: ndarray, drift_ppm: float = 10, rng: Generator | None = None) → ndarray[source]¶

Clock drift from a Local Oscillator (LO), modeled as accumulated gaussian random noise impacting the sampling rate.

The drift applies a randomness to the sampling rate, and by accumulating the gaussian RV over time it will slightly increase or decrease the sampling rate of the data, and thereby changing the number of samples by a very small number.

Parameters:

data – Complex valued IQ data samples.
drift_ppm – Clock drift in parts per million (ppm). Default 10.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with LO drift applied.

torchsig.transforms.functional.clock_jitter(data: ndarray, jitter_ppm: float = 10, rng: Generator | None = None) → ndarray[source]¶

Clock jitter from a Local Oscillator (LO), modeled as gaussian random noise impacting the sampling phase.

The jitter applies a randomness to the sampling phase, applying a slight increment or decrement to the sampling phase and therefore potentially changing the number of samples by a very small number.

Parameters:

data – Complex valued IQ data samples.
jitter_ppm – Jitter in parts per million (ppm). Default 10.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with LO drift applied.

torchsig.transforms.functional.coarse_gain_change(data: ndarray, gain_change_db: float, start_idx: int) → ndarray[source]¶

Implements a large instantaneous jump in receiver gain.

Parameters:

data – IQ data.
gain_change_db – Gain value to change in dB.
start_idx – Start index for IQ data.

Returns:

IQ data with instantaneous gain change applied.

torchsig.transforms.functional.cochannel_interference(data: ndarray, power: float = 1.0, filter_weights: ndarray | None = None, color: str = 'white', continuous: bool = True, rng: Generator | None = None) → ndarray[source]¶

Applies uncorrelated co-channel interference to the baseband data, modeled as shaped noise with specified parameters.

Parameters:

data – Complex valued IQ data samples.
power – Interference power (linear, positive). Default 1.0 W (0 dBW).
filter_weights – Lowpass interference shaping filter weights. Default low_pass(0.25, 0.25, 4.0).
color – Base noise color, supports ‘white’, ‘pink’, or ‘red’ noise frequency spectrum types. Default ‘white’.
continuous – Sets noise to continuous (True) or impulsive (False). Default True.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with added uncorrelated co-channel interference.

torchsig.transforms.functional.complex_to_2d(data: ndarray) → ndarray[source]¶: Converts IQ data to two channels (real and imaginary parts).

torchsig.transforms.functional.cut_out(data: ndarray, cut_start: float, cut_duration: float, cut_type: str, rng: Generator | None = None) → ndarray[source]¶

Performs CutOut: replacing values with fill.

Parameters:

data – IQ data
cut_start – Normalized start of cut region [0.0, 1.0)
cut_duration – Normalized duration of cut region (0.0, 1.0)
cut_type – Type of data to fill cut region. * zeros * ones * low_noise * avg_noise * high_noise
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Raises:

ValueError – Invalid cut_type.

Returns:

CutOut IQ data.

torchsig.transforms.functional.digital_agc(data: ndarray, initial_gain_db: float = 0.0, alpha_smooth: float = 0.0001, alpha_track: float = 0.001, alpha_overflow: float = 0.1, alpha_acquire: float = 0.001, ref_level_db: float = 0.0, track_range_db: float = 1.0, low_level_db: float = -80, high_level_db: float = 10) → ndarray[source]¶

Automatic Gain Control algorithm (deterministic).

Parameters:

data – IQ data samples.
initial_gain_db – Inital gain value in dB.
alpha_smooth – Alpha for avergaing the measure signal level level_n = level_n * alpha + level_n-1(1-alpha)
alpha_track – Amount to adjust gain when in tracking state.
alpha_overflow – Amount to adjust gain when in overflow state [level_db + gain_db] >= max_level.
alpha_acquire – Amount to adjust gain when in acquire state.
ref_level_db – Reference level goal for algorithm to achieve, in dB units.
track_range_db – dB range for operating in tracking state.
low_level_db – minimum magnitude value (dB) to perform any gain control adjustment.
high_level_db – magnitude value (dB) to enter overflow state.

Returns:

IQ data adjusted sample-by-sample by the AGC algorithm.

torchsig.transforms.functional.doppler(data: ndarray, velocity: float = 10.0, propagation_speed: float = 299792458.0) → ndarray[source]¶

Applies wideband Doppler effect through time scaling.

Parameters:

data – Complex valued IQ data samples.
velocity – Relative velocity in m/s (positive = approaching). Default 10 m/s.
propagation_speed – Wave speed in medium. Default 2.9979e8 m/s (speed_of_light).

Returns:

Data with wideband Doppler.

torchsig.transforms.functional.drop_samples(data: ndarray, drop_starts: ndarray, drop_sizes: ndarray, fill: str) → ndarray[source]¶

Drop samples at given locations/durations with fill technique.

Supported Fill Techniques:: ffill: Forward Fill. Use value at sample one before start. bfill: Backwards Fill. Use value at sample one after end. mean: Mean Fill. Use data mean. zero: Zero Fill. Use 0.

Parameters:

data – IQ data.
drop_starts – Start indicies of drops.
drop_sizes – Durations for each start index.
fill – Drop sample replacement method.

Raises:

ValueError – Invalid fill type.

Returns:

data array with fill values during drops.

torchsig.transforms.functional.fading(data: ndarray, coherence_bandwidth: float, power_delay_profile: ndarray, rng: Generator) → ndarray[source]¶

Apply fading channel to signal. Currently only does Rayleigh fading.

Taps are generated by interpolating and filtering Gaussian taps.

Parameters:

data – IQ data.
coherence_bandwidth – coherence bandwidth relative to sample rate [0, 1.0].
power_delay_profile – power delay profile assign to channel.
rng – Random Generator to use. Defaults to None (new generator created internally).

Returns:

IQ data with fading applied.

torchsig.transforms.functional.interleave_complex(data: ndarray) → ndarray[source]¶

Converts complex vectors into real interleaved IQ vector.

Parameters:: data – Input array of complex samples
Returns:: Real-valued array of interleaved IQ samples

torchsig.transforms.functional.intermodulation_products(data: ndarray, coeffs: ndarray | None = None) → ndarray[source]¶

Pass IQ data through an optimized memoryless nonlinear response model that creates local intermodulation distortion (IMD) products.

Note that since only odd-order IMD products effectively fall in spectrum near the first-order (original) signal, only these are calculated.

Parameters:

data – Complex valued IQ data samples.
coeffs – coefficients of memoryless IMD response such that y(t) = coeffs[0]*x(t) + coeffs[1]*(x(t)**2) + coeffs[2]*(x(t)**3) + … Defaults to a third-order model: np.array([1.0, 1.0, 1.0]).

Returns:

IQ data with local IMD products.

torchsig.transforms.functional.iq_imbalance(data: ndarray, amplitude_imbalance: float, phase_imbalance: float, dc_offset_db: float, dc_offset_phase_rads: float, noise_power_db: float | None = None) → ndarray[source]¶

Applies IQ imbalance to IQ data.

Parameters:

data – IQ data.
amplitude_imbalance – IQ amplitude imbalance in dB.
phase_imbalance – IQ phase imbalance in radians [-pi, pi].
dc_offset_db – Relative power of additive DC offset in dB.
dc_offset_phase_rads – Phase of additive DC offset in radians.
noise_power_db – Noise floor power in dB. Estimated internally if not provided. Defaults to None.

Returns:

IQ data with IQ Imbalance applied.

torchsig.transforms.functional.nonlinear_amplifier(data: ndarray, gain: float = 1.0, psat_backoff: float = 10.0, phi_max: float = 0.1, phi_slope: float = 0.01, auto_scale: bool = True) → ndarray[source]¶

A memoryless AM/AM, AM/PM nonlinear amplifier function-based model using a hyperbolic tangent output power response defined by gain and saturation power, and a hyperbolic tangent phase response defined by maximum relative phase shift.

Parameters:

data – Complex valued IQ data samples.
gain – Small-signal linear gain. Default 1.0.
psat_backoff – Saturated output power factor relative to the input signal mean power. That is, Psat = psat_backoff * Pavg. For example, operating at a 2.0 psat_backoff factor with a 1 W mean power signal has saturation power level at 2.0 W. Default 10.0.
phi_max – Signal maximum relative phase shift in saturation (radians). Default 0.1.
phi_slope – Absolute slope of relative phase linear response region (W/radian). Default 0.01.
auto_scale – Automatically rescale output power to match full-scale peak input power prior to transform, based on peak estimates. Default True.

Returns:

Nonlinearly distorted IQ data.

torchsig.transforms.functional.nonlinear_amplifier_table(data: ndarray, p_in: ndarray | None = None, p_out: ndarray | None = None, phi: ndarray | None = None, auto_scale: bool = False) → ndarray[source]¶

A nonlinear amplifier (AM/AM, AM/PM) memoryless model that distorts an input complex signal to simulate an amplifier response, based on interpolating a table of provided power input, power output, and phase change data points.

Default very small model parameters depict a 10 dB gain amplifier with P1dB = 9.0 dBW.: p_in = 10**((np.array([-100., -20., -10., 0., 5., 10. ]) / 10)) p_out = 10**((np.array([ -90., -10., 0., 9., 9.9, 10. ]) / 10)) phi = np.deg2rad(np.array([0., -2., -4., 7., 12., 23.]))

Parameters:

data – Complex valued IQ data samples.
p_in – Model signal power input points. Assumes sorted ascending linear values (Watts).
p_out – Model power out corresponding to p_in points (Watts).
phi – Model output phase shift values (radians) corresponding to p_in points.
auto_scale – Automatically rescale output power to match full-scale peak input power prior to transform, based on peak estimates. Default False.

Raises:

ValueError – If model array arguments are not the same size.

Returns:

Nonlinearly distorted IQ data.

torchsig.transforms.functional.normalize(data: ndarray, norm_order: float | Literal['fro', 'nuc'] | None = 2, flatten: bool = False) → ndarray[source]¶

Scale data so that a specified norm computes to 1.

For detailed information, see numpy.linalg.norm.()

For norm=1, norm = max(sum(abs(x), axis=0)) (sum of the elements)
for norm=2, norm = sqrt(sum(abs(x)^2), axis=0) (square-root of the sum of squares)
for norm=np.inf, norm = max(sum(abs(x), axis=1)) (largest absolute value)

Parameters:

data – (batch_size, vector_length, …)-sized data to be normalized.
norm_order – norm order to be passed to np.linalg.norm. Defaults to 2.
flatten – boolean specifying if the input array’s norm should be calculated on the flattened representation of the input data. Defaults to False.

Returns:

Normalized complex array data.

torchsig.transforms.functional.passband_ripple(data: ndarray, num_taps: int = 2, max_ripple_db: float = 2.0, coefficient_decay_rate: float = 1, rng: Generator | None = None) → ndarray[source]¶

Functional for passband ripple transforms.

This function applies a passband ripple effect to the input data by designing a filter with specified ripple characteristics and applying it to the data.

Parameters:

data – Complex valued IQ data samples.
num_taps – Number of taps in simulated filter. Defaults to 2.
max_ripple_db – Maximum allowed ripple in the simulated filter (in dB). Defaults to 2.0.
coefficient_decay_rate – The decay rate of the exponential weighting in the filter. Defaults to 1.0.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Raises:

ValueError – When filter cannot meet ripple spec within a set number of iterations.

Returns:

Filtered data with passband ripple applied.

torchsig.transforms.functional.patch_shuffle(data: ndarray, patch_size: int, patches_to_shuffle: ndarray, rng: Generator | None = None) → ndarray[source]¶

Apply shuffling of patches specified by num_patches.

This function divides the input data into patches of specified size and shuffles the data within each patch according to the provided indices.

Parameters:

data – (batch_size, vector_length, …)-sized data.
patch_size – Size of each patch to shuffle.
patches_to_shuffle – Index of each patch of size patch_size to shuffle.
rng – Random Generator to use. Defaults to None (new generator created internally).

Returns:

Data that has undergone patch shuffling.

torchsig.transforms.functional.phase_offset(data: ndarray, phase: float) → ndarray[source]¶

Applies a phase rotation to data.

This function multiplies the input data by a complex exponential to apply a phase rotation.

Parameters:

data – IQ data.
phase – phase to rotate sample in [-pi, pi].

Returns:

Data that has undergone a phase rotation.

torchsig.transforms.functional.quantize(data: ndarray, num_bits: int, ref_level_adjustment_db: float = 0.0, rounding_mode: str = 'floor') → ndarray[source]¶

Quantize input to number of levels specified.

This function quantizes the input data to a specified number of bits, with options for reference level adjustment and rounding mode.

Default implementation is ceiling.

Parameters:

data – IQ data.
num_bits – Number of bits to simulate.
ref_level_adjustment_db – Changes the relative scaling of the input. For example, ref_level_adjustment_db = 3.0, the average power is now 3 dB above full scale and into saturation. For ref_level_adjustment_db = -3.0, the average power is now 3 dB below full scale and simulates a loss of dynamic range. Default is 0.
rounding_mode – Represents either rounding to ‘floor’ or ‘ceiling’. Default is ‘floor’.

Raises:

ValueError – Invalid round type.
TypeError – If num_bits is not an integer.

Returns:

Quantized IQ data.

torchsig.transforms.functional.shadowing(data: ndarray, mean_db: float = 4.0, sigma_db: float = 2.0, rng: Generator | None = None) → ndarray[source]¶

Applies RF shadowing to the data, assuming the channel obstructions’ loss are lognormal.

This function models RF shadowing effects by applying lognormal fading to the input data.

Refer to T.S. Rappaport, Wireless Communications, Prentice Hall, 2002.

Parameters:

data – Complex valued IQ data samples.
mean_db – Mean value of shadowing in dB. Default 4.0.
sigma_db – Shadowing standard deviation. Default 2.0.
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

Data with shadowing applied.

torchsig.transforms.functional.spectral_inversion(data: ndarray) → ndarray[source]¶

Applies a spectral inversion to input data.

This function performs spectral inversion by complex conjugation of the input data.

Parameters:: data – IQ data.
Returns:: Spectrally inverted data.

torchsig.transforms.functional.spectrogram(data: ndarray, fft_size: int, fft_stride: int) → ndarray[source]¶

Computes spectrogram from IQ data.

This function computes the spectrogram by applying the Short-Time Fourier Transform (STFT) to the input IQ data.

Directly uses compute_spectrogram inside of utils/dsp.py.

Parameters:

data – IQ samples.
fft_size – The FFT size (number of bins) in the spectrogram.
fft_stride – The number of data points to move or “hop” over when computing the next FFT.

Returns:

Spectrogram computed from IQ data.

torchsig.transforms.functional.spectrogram_drop_samples(data: ndarray, drop_starts: ndarray, drop_sizes: ndarray, fill: str) → ndarray[source]¶

Drop samples at given locations/durations with fill technique.

This function drops samples at specified locations and fills them with the specified technique.

Supported Fill Techniques:: ffill: Forward Fill. Use value at sample one before start. bfill: Backwards Fill. Use value at sample one after end. mean: Mean Fill. Use data mean. zero: Zero Fill. Use 0. min: Minimum observed value fill. max: Maximum observed value fill low: Fixed low value fill. Use np.ones * 1e-3. ones: Ones fill. Use np.ones.

Parameters:

data – IQ data.
drop_starts – Start indices of drops.
drop_sizes – Durations for each start index.
fill – Drop sample replacement method.

Raises:

ValueError – Invalid fill type.

Returns:

Data array with fill values during drops.

torchsig.transforms.functional.spectrogram_image(data: ndarray, fft_size: int, fft_stride: int, black_hot: bool = True) → ndarray[source]¶

Creates spectrogram from IQ samples.

This function computes the spectrogram and converts it to a grayscale image.

Parameters:

data – IQ samples.
fft_size – The FFT size (number of bins) in the spectrogram.
fft_stride – The number of data points to move or “hop” over when computing the next FFT.
black_hot – Toggles black hot spectrogram. Defaults to True (black hot).

Returns:

Spectrogram image in BGR format.

torchsig.transforms.functional.spurs(data: ndarray, sample_rate: float = 1, center_freqs=[0.25], relative_power_db=[3], noise_power_db: float | None = None) → ndarray[source]¶

Adds spurs to the input data.

This function adds spurious signals (tones) at specified frequencies with specified power levels.

Parameters:

data – IQ data samples.
sample_rate – Sample rate associated with the samples. Defaults to 1.
center_freqs – Center frequencies for the spurs. Defaults to [0.25].
relative_power_db – Relative power of spurs in dB to noise floor. Defaults to [3].
noise_power_db – Noise floor power in dB. Estimated internally if not provided. Defaults to None.

Returns:

IQ data with spurs (tones) added.

Raises:

ValueError – If center_freqs are outside the valid range or if lengths don’t match.

torchsig.transforms.functional.time_reversal(data: ndarray) → ndarray[source]¶

Applies time reversal to data (flips horizontally).

This function reverses the time axis of the input data.

Parameters:: data – IQ data.
Returns:: Time flipped IQ data.

torchsig.transforms.functional.time_varying_noise(data: ndarray, noise_power_low: float, noise_power_high: float, inflections: int, random_regions: bool, rng: Generator | None = None) → ndarray[source]¶

Adds time-varying complex additive white Gaussian noise.

This function adds noise with power levels that vary over time, with specified minimum and maximum power levels and number of inflection points.

Parameters:

data – IQ data.
noise_power_low – Minimum noise power in dB.
noise_power_high – Maximum noise power in dB.
inflections – Number of inflection points over IQ data.
random_regions – Inflection points spread randomly (True) or evenly (False).
rng – Random number generator. Defaults to np.random.default_rng(seed=None).

Returns:

IQ data with time-varying noise added.

Transforms¶

Transforms¶

Base Transforms¶

Signal Transforms¶

Impairments¶

Functional Transforms¶

Transforms ¶

Base Transforms ¶

Signal Transforms ¶

Impairments ¶

Functional Transforms ¶