# Utils¶

## Reference¶

PuPy.clear_empty_groups(pth)

Remove HDF5 groups with no datasets from pth. Return a list of removed groups.

class PuPy.Normalization(pth=None)

Bases: object

Supply normalization routines for sensor data. The normalization parameters (per sensor) are loaded from the pth file. See py:meth:load_normalization for the file syntax.

Todo

Doesn’t work with zero-mean and unit variance data. (There was a bug...).

The normalization takes two parameters, an offset ($o$) and scale ($s$). Data is normalized according to

$x' = \frac{ x - o }{ s }$

and denormalized

$x = s * x' + o$

The normalization parameters offset and scale must be set such that the desired mapping is achieved.

denormalize_epoch(epoch)

Denormalize all values in the dict epoch, where the key is regarded as sensor name.

denormalize_value(sensor, value)

Return the denormalized value, with respect to sensor.

get(sensor)

Return the normalization parameters of sensor. The order is (offset, scale). A valid result is returned in any case. If the sensor was not configured, the identity mapping is returned, i.e.

>>> nrm = Normalization()
>>> nrm.set('unknown_sensor', *nrm.get('unknown_sensor'))
>>> nrm.normalize_value('unknown_sensor', value) == value
True


However, a warning will be issued.

Load normalization parameters from a JSON file at pth.

The file structure must be like so:

{
"<sensor name>" : [<offset>, <scale>],
}


For example:

{
"hip0"   : [0.9678, 3.141],
"touch0" : [-0.543, 1e3],
"trg0"   : [1e-2, 8]
}
`

Note

This routine is only available, if the json module is installed.

normalize_epoch(epoch)

Normalize all values in the dict epoch, where the key is regarded as sensor name.

normalize_value(sensor, value)

Return the normalized value, with respect to sensor.

params_stat(data, sensor=None)

Find parameters offset and scale of data, such that normalized data has zero mean and unit variance.

If not None, the parameters will be attached to sensor.

The normalization parameters can be computed straight-forward: The offset is the mean, the scale the standard deviance.

params_unit(data, sensor=None)

Find parameters offset and scale of data, such that data is mapped to [-1.0, 1.0].

If not None, the parameters will be attached to sensor.

With $$o = \min \text{data}$$ and $$s = \max \text{data} - \min \text{data}$$, the normalization to [-1, 1] becomes

$x' = 2 \frac{x - o }{ s } - 1$

Since the normalization is is done differently (see Normalization), this has to be reformulated:

$\begin{eqnarray*} x' &=& 2 \frac{ x - o }{ s } - 1 \\ &=& \frac{2}{s} (x - o) - \frac{ 2/s }{ 2/s } \\ &=& \frac{2}{s} \left[ x - o - \frac{ 1 }{ 2/s } \right] \\ &=& \frac{2}{s} \left[ x - \left( o + \frac{ s }{ 2 } \right) \right] \\ \end{eqnarray*}$

So, the effective normalization parameters are

$\begin{eqnarray*} \text{scale} &=& \frac{s}{2} \\ \text{offset} &=& o + \frac{s}{2} \end{eqnarray*}$
save(pth)

Store the normalization parameters in a JSON file at pth.

set(sensor, offset, scale)

Set the normalization parameters offset and scale for a specific sensor.

The normalization computes the following:

x’ = ( x - offset ) / scale

Control

Examples