[FEATURE] Audio normalization

[Gautzilla]

⚠️ Obsolete description, see the updated comment below

🐳 What's new?

The fetched audio data can now be normalized according to 3 presets:

Preset	Definition
raw	$x$
dc_reject	$x-\overline{x}$
zscore	$\frac{x-\overline{x}}{\sigma (x)}$

The automatic dc rejection in the AudioData.get_value() method was removed, as it now is controlable through the normalization property.

🐳 How to use it?

The normalization property on AudioData, AudioDataset and Analysis can be set to either "raw", "dc_reject" or "zscore".
The fetched audio data will then be normalized accordingly when AudioData.get_value() is called.

🐬 Core API

Simply set the normalization property of AudioData or AudioDataset objects:

from osekit.core_api.audio_dataset import AudioDataset

ads = AudioDataset(
    ...,
    normalization="zscore"
)

ads.write(...) # The written audio files will be normalized z-scores.

🐬 Public API

Simply set the normalization property of the Analysis object:

from osekit.public_api.dataset import Dataset
from osekit.public_api.analysis import Analysis

dataset = Dataset(...)

analysis = Analysis(
    ...,
    normalization = "zscore",
)

dataset.run_analysis(analysis=analysis) # The audio data is turned to z-score during the analysis

[Gautzilla]

The PR is still in draft mode as I have to include normalization in the docs.

[mathieudpnt]

As we discussed, this might benefit from adding a "full-scale" normalization mode

[Gautzilla]

🐳 What's new?

The fetched audio data can now be normalized according to 4 presets given by the osekit.utils.audio_utils.Normalization flag:

Preset	Definition
Normalization.RAW	$x$
Normalization.DC_REJECT	$x-\overline{x}$
Normalization.PEAK	$\frac{x}{x_\text{max}}$
Normalization.ZSCORE	$\frac{x-\overline{x}}{\sigma (x)}$

The automatic dc rejection in the AudioData.get_value() method was removed, as it now is controlable through the normalization property.

🐳 How to use it?

The normalization property on AudioData, AudioDataset and Analysis can be set to any Normalization flag.
The fetched audio data will then be normalized accordingly when AudioData.get_value() is called.

⚠️ Normalization.DC_REJECT can be combined with any other (single) normalization, but any other combination will raise a ValueError:

from osekit.utils.audio_utils import Normalization

n = Normalization.DC_REJECT | Normalization.PEAK # OK
n = Normalization.DC_REJECT | Normalization.ZSCORE # OK
n = Normalization.ZSCORE| Normalization.PEAK # raises a ValueError
n =Normalization.DC_REJECT | Normalization.ZSCORE| Normalization.PEAK # raises a ValueError

🐬 Core API

Simply set the normalization property of AudioData or AudioDataset objects:

from osekit.core_api.audio_dataset import AudioDataset
from osekit.utils.audio_utils import Normalization

ads = AudioDataset(
    ...,
    normalization=Normalization.ZSCORE
)

ads.write(...) # The written audio files will be normalized z-scores.

🐬 Public API

Simply set the normalization property of the Analysis object:

from osekit.public_api.dataset import Dataset
from osekit.public_api.analysis import Analysis
from osekit.utils.audio_utils import Normalization

dataset = Dataset(...)

analysis = Analysis(
    ...,
    normalization=Normalization.ZSCORE,
)

dataset.run_analysis(analysis=analysis) # The audio data is turned to z-score during the analysis

[mathieudpnt]

[Gautzilla]

Resolving conflicts in notebooks looks buggy as f, so I had to make a few tweaks and now I need your doppelganger to approve the PR