scale_range_soft_clip

selfeeg.utils.utils.scale_range_soft_clip(x: ArrayLike, Range: float = 200, asintote: float = 1.2, scale: str = 'mV', exact: bool = True) → ArrayLike[source]

soft version of the range scaler.

The function will rescale the data in the following way:

  1. values in Range will be rescaled in the range [-1,1] linearly

  2. values outside the range will be either clipped or soft clipped with an exponential saturating curve with first derivative in -1 and 1 preserved and horizontal asintote (the saturating point) given by the user.

To provide faster computation, this function can also approximate its behaviour with a sigmoid function which scales the given input using the specified range and asintote. To check the difference in those functions see the geogebra file provided in the extra folder of the github repository.

Parameters:

  • x (ArrayLike) – The array or tensor to rescale. Rescaling can be perfomed along the last dimension. Tensors can also be placed in a GPU. Computation in this case is much faster

  • Range (float, optional) –

    The range of values to rescale given in microVolt. It rescale linearly the values in [-range, range] to [-1, 1]. Must be a positive value. The list [-range, range] is created internally.

    Default = 200

  • asintote (float, optional) –

    The horizontal asintote of the soft clipping part. Must be a value bigger than 1.

    Default = 1.2

  • scale (str, optional) –

    The scale of the EEG Samples. It can be:

    • ’mV’ for milliVolt

    • ’uV’ for microVolt

    • ’nV’ for nanoVolt

    Default = ‘mV’

  • exact (bool, optional) – Whether to approximate the composed function (linear + exponential function) with a sigmoid. It will make the rescaling much faster but will not preserve the linearity in the range [-1, 1].

Returns:

x_scaled (ArrayLike) – The rescaled array.

Example

>>> import selfeeg.utils
>>> import torch
>>> x = torch.zeros(16,32,1024) + torch.sin(torch.linspace(0, 8*torch.pi,1024))*500
>>> x_scaled = utils.scale_range_soft_clip(x, 200, 2.5, 'uV' )
>>> print( x.max()<=2.5 and x.min()>=-2.5) # should return False
>>> print( x_scaled.max()<=2.5 and x_scaled.min()>=-2.5) # should return True