Metrics

compute_ser(X_target, X_detected, axis=None)

Compute the Symbol Error Rate (SER) between the target and detected signals along the specified axis.

Parameters

X_targetndarray

The target signal array.

X_detectedndarray

The detected signal array after some transmission or processing.

axisint or None, optional

Axis along which to compute the SER. If None, the arrays are raveled into 1D arrays.

Returns

float or ndarray

The computed SER value. If axis is None, returns a float. Otherwise, returns an array.

Notes

The SER is computed using the formula:

\[\text{SER} = \frac{\|\mathbf{x}_{\text{tar}} - \mathbf{x}_{\text{est}}\|_0}{N}\]

compute_ber(X_target, X_detected, width, axis=None)

Compute the Bit Error Rate (BER) between target and detected symbols along the specified axis.

Parameters

X_targetndarray

The target symbols to be compared against. Should be convertible to a 1-D array.

X_detectedndarray

The detected symbols obtained from a transmission system or a decoder. Should be convertible to a 1-D array.

widthint

The number of bits used to represent each symbol.

axisint or None, optional

Axis along which to compute the BER. If None, the arrays are raveled into 1D arrays.

Returns

float or ndarray

The Bit Error Rate (BER), computed as the number of differing bits between s_target and s_detected divided by the total number of bits.

Notes

The function assumes that sym_2_bin is a predefined function that converts symbols to their binary representation. The formula for BER is:

\[ext{BER} = \frac{N_e}{N_b}\]

compute_evm(X_target, X_estimated, axis=None)

Compute the Error Vector Magnitude (EVM) between the target and estimated signals along the given axis.

Parameters

X_targetndarray

The target signal array.

X_estimatedndarray

The estimated signal array.

axisint or None, optional

Axis along which to compute the mean. If None, the mean is computed over all dimensions.

Returns

float or ndarray

The computed EVM value. If axis is None, returns a float. Otherwise, returns an array.

Notes

The EVM is computed using the formula:

\[\text{EVM} = \sqrt{\frac{\sum_{i} |x_{\text{target},i} - x_{\text{estimated},i}|^2}{\sum_{i} |x_{\text{target},i}|^2}}\]

where:

• \(x_{\text{target},i}\) is the ith element of the target signal.

• \(x_{\text{estimated},i}\) is the ith element of the estimated signal.

Examples

>>> X_target = np.array([1, 2, 3, 4])
>>> X_estimated = np.array([1.1, 2.1, 3.1, 3.9])
>>> compute_evm(X_target, X_estimated)
0.05057216690580728
>>> compute_evm(X_target, X_estimated, axis=0)
0.05057216690580728

compute_effective_SNR(X_target, X_estimated, sigma2_s=1, unit='natural')

Compute the effective Signal-to-Noise Ratio (SNR) between a target and an estimated signal.

Parameters

X_targetndarray

The target signal array.

X_estimatedndarray

The estimated signal array.

sigma2_sfloat, optional

The variance of the signal. The default is 1.

unitstr, optional

Unit of the output SNR. Can be “natural” (linear scale), “dB” (decibels), or “dBm” (decibel-milliwatts). The default is “natural”.

Returns

float

The effective SNR in the specified unit.

Raises

ValueError

If the specified unit is not one of “natural”, “dB”, or “dBm”.

Notes

• The effective SNR is calculated as the ratio of the signal variance to the mean squared error between the target and estimated signals.

• For “dB” unit, the SNR is converted using the formula: ( text{SNR}_{dB} = 10 log_{10}(text{SNR}) ).

• For “dBm” unit, the SNR is converted using the formula: ( text{SNR}_{dBm} = 10 log_{10}(text{SNR}) + 30 ).

compute_power(x, unit='natural')

Compute the mean power of an input array.

Parameters

xndarray

Input array containing the signal values.

unitstr, optional

Unit of the output power. Can be “natural” (Watts), “dB” (decibels), or “dBm” (decibel-milliwatts). The default is “natural”.

Returns

float

Mean power value in the specified unit.

Raises

ValueError

If the specified unit is not one of “natural”, “dB”, or “dBm”.

Notes

• The mean power is calculated as the average of the squared magnitudes of the input array.

• For “dB” and “dBm” units, the power is converted using the formula: ( P_{dB} = 10 log_{10}(P) ) and ( P_{dBm} = 10 log_{10}(P) + 30 ), respectively.

compute_ccdf(data, axis=-1)

Compute the Complementary Cumulative Distribution Function (CCDF) for a given dataset along a specified axis.

Parameters

dataarray-like

Input data for which the CCDF needs to be calculated.

axisint, optional

Axis along which to compute the CCDF. Default is the last axis.

Returns

sorted_datanp.ndarray

The input data sorted in ascending order along the specified axis.

ccdfnp.ndarray

The computed CCDF values corresponding to the sorted data.

Notes

The CCDF is computed using the formula:

\[\text{CCDF}(x) = 1 - \text{CDF}(x)\]

where the CDF is the cumulative distribution function.

Examples

>>> import numpy as np
>>> data = np.array([[1, 2, 3], [4, 5, 6]])
>>> sorted_data, ccdf = compute_ccdf(data, axis=1)
>>> sorted_data
array([[1, 2, 3],
       [4, 5, 6]])
>>> ccdf
array([[0.66666667, 0.33333333, 0.        ],
       [0.66666667, 0.33333333, 0.        ]])

calculate_acpr(signal, bandwidth, sampling_rate)

Calculate the Adjacent Channel Power Ratio (ACPR) of a given signal.

ACPR is a measure of spectral regrowth and quantifies the ratio between the power in the main transmission band and the power leaked into adjacent frequency bands. This function computes ACPR on both the left and right adjacent channels.

Parameters

signalnp.ndarray

The input time-domain signal.

bandwidthfloat

The bandwidth of the main signal in Hz.

sampling_ratefloat

The sampling rate of the signal in Hz.

Returns

acpr_rightfloat

ACPR value (in dB) for the right adjacent channel.

acpr_leftfloat

ACPR value (in dB) for the left adjacent channel.

class MetricRecorder(metric_fn: ~typing.Callable, params: ~typing.Dict[str, ~typing.Any] = <factory>, data: ~typing.Any = None, name: str = 'metric recorder')

A class to compute and record the result of a metric function applied to input data.

This class encapsulates a callable metric function with optional parameters. When the object is called with data, it evaluates the metric and stores the result in the data attribute, while returning the original input unchanged (for pipeline use).

Attributes

metric_fnCallable

The metric function to be applied. Must take the input X as first argument.

paramsdict

Optional keyword arguments to be passed to the metric function.

dataAny

The result of the metric function, stored after calling the object.

Example

>>> import numpy as np
>>> def mean_std(X, axis=0):
...     return {"mean": X.mean(axis=axis), "std": X.std(axis=axis)}
>>> X = np.array([[1, 2, 3], [4, 5, 6]])
>>> recorder = MetricRecorder(metric_fn=mean_std, params={"axis": 1})
>>> recorder(X)
array([[1, 2, 3],
       [4, 5, 6]])
>>> recorder.data
{'mean': array([2., 5.]), 'std': array([0.81649658, 0.81649658])}