Caution

You're reading the documentation for a development version. For the latest released version, please have a look at 0.10.2.

# librosa.util.normalize

librosa.util.normalize(S, *, norm=inf, axis=0, threshold=None, fill=None)[source]

Normalize an array along a chosen axis.

Given a norm (described below) and a target axis, the input array is scaled so that:

```norm(S, axis=axis) == 1
```

For example, `axis=0` normalizes each column of a 2-d array by aggregating over the rows (0-axis). Similarly, `axis=1` normalizes each row of a 2-d array.

This function also supports thresholding small-norm slices: any slice (i.e., row or column) with norm below a specified `threshold` can be left un-normalized, set to all-zeros, or filled with uniform non-zero values that normalize to 1.

Note: the semantics of this function differ from `scipy.linalg.norm` in two ways: multi-dimensional arrays are supported, but matrix-norms are not.

Parameters:
Snp.ndarray

The array to normalize

norm{np.inf, -np.inf, 0, float > 0, None}
• np.inf : maximum absolute value

• -np.inf : minimum absolute value

• 0 : number of non-zeros (the support)

• floatcorresponding l_p norm

See `scipy.linalg.norm` for details.

• None : no normalization is performed

axisint [scalar]

Axis along which to compute the norm.

thresholdnumber > 0 [optional]

Only the columns (or rows) with norm at least `threshold` are normalized.

By default, the threshold is determined from the numerical precision of `S.dtype`.

fillNone or bool

If None, then columns (or rows) with norm below `threshold` are left as is.

If False, then columns (rows) with norm below `threshold` are set to 0.

If True, then columns (rows) with norm below `threshold` are filled uniformly such that the corresponding norm is 1.

Note

`fill=True` is incompatible with `norm=0` because no uniform vector exists with l0 “norm” equal to 1.

Returns:
S_normnp.ndarray [shape=S.shape]

Normalized array

Raises:
ParameterError

If `norm` is not among the valid types defined above

If `S` is not finite

If `fill=True` and `norm=0`

Notes

This function caches at level 40.

Examples

```>>> # Construct an example matrix
>>> S = np.vander(np.arange(-2.0, 2.0))
>>> S
array([[-8.,  4., -2.,  1.],
[-1.,  1., -1.,  1.],
[ 0.,  0.,  0.,  1.],
[ 1.,  1.,  1.,  1.]])
>>> # Max (l-infinity)-normalize the columns
>>> librosa.util.normalize(S)
array([[-1.   ,  1.   , -1.   ,  1.   ],
[-0.125,  0.25 , -0.5  ,  1.   ],
[ 0.   ,  0.   ,  0.   ,  1.   ],
[ 0.125,  0.25 ,  0.5  ,  1.   ]])
>>> # Max (l-infinity)-normalize the rows
>>> librosa.util.normalize(S, axis=1)
array([[-1.   ,  0.5  , -0.25 ,  0.125],
[-1.   ,  1.   , -1.   ,  1.   ],
[ 0.   ,  0.   ,  0.   ,  1.   ],
[ 1.   ,  1.   ,  1.   ,  1.   ]])
>>> # l1-normalize the columns
>>> librosa.util.normalize(S, norm=1)
array([[-0.8  ,  0.667, -0.5  ,  0.25 ],
[-0.1  ,  0.167, -0.25 ,  0.25 ],
[ 0.   ,  0.   ,  0.   ,  0.25 ],
[ 0.1  ,  0.167,  0.25 ,  0.25 ]])
>>> # l2-normalize the columns
>>> librosa.util.normalize(S, norm=2)
array([[-0.985,  0.943, -0.816,  0.5  ],
[-0.123,  0.236, -0.408,  0.5  ],
[ 0.   ,  0.   ,  0.   ,  0.5  ],
[ 0.123,  0.236,  0.408,  0.5  ]])
```
```>>> # Thresholding and filling
>>> S[:, -1] = 1e-308
>>> S
array([[ -8.000e+000,   4.000e+000,  -2.000e+000,
1.000e-308],
[ -1.000e+000,   1.000e+000,  -1.000e+000,
1.000e-308],
[  0.000e+000,   0.000e+000,   0.000e+000,
1.000e-308],
[  1.000e+000,   1.000e+000,   1.000e+000,
1.000e-308]])
```
```>>> # By default, small-norm columns are left untouched
>>> librosa.util.normalize(S)
array([[ -1.000e+000,   1.000e+000,  -1.000e+000,
1.000e-308],
[ -1.250e-001,   2.500e-001,  -5.000e-001,
1.000e-308],
[  0.000e+000,   0.000e+000,   0.000e+000,
1.000e-308],
[  1.250e-001,   2.500e-001,   5.000e-001,
1.000e-308]])
>>> # Small-norm columns can be zeroed out
>>> librosa.util.normalize(S, fill=False)
array([[-1.   ,  1.   , -1.   ,  0.   ],
[-0.125,  0.25 , -0.5  ,  0.   ],
[ 0.   ,  0.   ,  0.   ,  0.   ],
[ 0.125,  0.25 ,  0.5  ,  0.   ]])
>>> # Or set to constant with unit-norm
>>> librosa.util.normalize(S, fill=True)
array([[-1.   ,  1.   , -1.   ,  1.   ],
[-0.125,  0.25 , -0.5  ,  1.   ],
[ 0.   ,  0.   ,  0.   ,  1.   ],
[ 0.125,  0.25 ,  0.5  ,  1.   ]])
>>> # With an l1 norm instead of max-norm
>>> librosa.util.normalize(S, norm=1, fill=True)
array([[-0.8  ,  0.667, -0.5  ,  0.25 ],
[-0.1  ,  0.167, -0.25 ,  0.25 ],
[ 0.   ,  0.   ,  0.   ,  0.25 ],
[ 0.1  ,  0.167,  0.25 ,  0.25 ]])
```