Fixes #587: Enhanced FFT normalization handling across arithmetic ope…

…rations.

CONTRIBUTING.rst

@@ -244,7 +244,7 @@ A reminder for the maintainers on how to deploy.
 
 - Commit all changes to develop
 - Update HISTORY.rst in develop
-- Check if gallery needs to be updated
+- Check if examples/pyfar_demo.ipynb needs to be updated
 - Merge develop into main
 
 Switch to main and run::
@@ -255,6 +255,6 @@ $ git push --follow-tags
 The testing platform will then deploy to PyPI if tests pass.
 
 - merge main back into develop
-- check gallery in `binder`_
+- check `binder`_
 
-.. _binder: https://mybinder.org/v2/gh/pyfar/gallery/main?filepath=docs/gallery
+.. _binder: https://mybinder.org/v2/gh/pyfar/pyfar/main?filepath=examples%2Fpyfar_demo.ipynb

README.rst

@@ -10,7 +10,7 @@ pyfar
 .. image:: https://circleci.com/gh/pyfar/pyfar.svg?style=shield
     :target: https://circleci.com/gh/pyfar/pyfar
 .. image:: https://mybinder.org/badge_logo.svg
-    :target: https://mybinder.org/v2/gh/pyfar/gallery/main?filepath=docs/gallery
+    :target: https://mybinder.org/v2/gh/pyfar/pyfar/main?filepath=examples%2Fpyfar_demo.ipynb
 
 
 The python package for acoustics research (pyfar) offers classes to store
@@ -20,9 +20,9 @@ functions for digital audio signal processing.
 Getting Started
 ===============
 
-Check out `pyfar.org`_ for a tour through the pyfar
-universe, including complete documentation of this package and
-the other packages.
+Check out the `examples notebook`_ for a tour of the most important pyfar
+functionality and `read the docs`_ for the complete documentation. Packages
+related to pyfar are listed at `pyfar.org`_.
 
 Installation
 ============
@@ -44,6 +44,7 @@ Refer to the `contribution guidelines`_ for more information.
 
 
 .. _contribution guidelines: https://github.com/pyfar/pyfar/blob/develop/CONTRIBUTING.rst
+.. _examples notebook: https://mybinder.org/v2/gh/pyfar/pyfar/main?filepath=examples%2Fpyfar_demo.ipynb
 .. _pyfar.org: https://pyfar.org
 .. _read the docs: https://pyfar.readthedocs.io/en/latest
 .. _SoundFile: https://pysoundfile.readthedocs.io/en/latest/

examples/division_check.py

@@ -0,0 +1,4 @@
+import pyfar as pf
+signal = pf.signals.exponential_sweep_time(44100, (50, 2e4))
+signal.fft_norm = 'rms'
+1 / signal

examples/fft_norm_example.py

@@ -0,0 +1,50 @@
+import pyfar as pf
+import matplotlib.pyplot as plt
+import numpy as np
+from pyfar.classes.audio import _match_fft_norm
+
+# create an exponential sweep signal
+signal = pf.signals.exponential_sweep_time(44100, (50, 20e3))
+signal.fft_norm = 'rms'  # Initial FFT normalization of the sweep
+
+# performing the division
+divided_signal = 1 / signal
+divided_signal.fft_norm = 'amplitude'  # setting normalization post-division
+
+# generate white noise with the same length and sampling rate as the signal
+noise = pf.signals.noise(signal.n_samples, spectrum='white', seed=1, sampling_rate=signal.sampling_rate)
+noise.fft_norm = 'none' 
+
+# multiplying divided signal 
+result_signal = divided_signal * noise
+
+print("Before override:", divided_signal.fft_norm, noise.fft_norm)
+result_signal.fft_norm = _match_fft_norm(divided_signal.fft_norm, noise.fft_norm, 'multiply', norm_override='rms')
+print("After override:", result_signal.fft_norm)
+
+# match signal lengths with time vector
+t = np.linspace(0, signal.n_samples / signal.sampling_rate, num=signal.n_samples)
+
+
+plt.figure(figsize=(12, 9))
+plt.subplot(3, 1, 1)
+plt.plot(t, signal.time.ravel(), label='Original Signal')
+plt.title('Original Signal')
+plt.xlabel('Time (s)')
+plt.ylabel('Amplitude')
+
+plt.subplot(3, 1, 2)
+plt.plot(t, divided_signal.time.ravel(), label='Divided Signal')
+plt.title('Divided Signal (1 / Original)')
+plt.xlabel('Time (s)')
+plt.ylabel('Amplitude')
+
+plt.subplot(3, 1, 3)
+plt.plot(t, result_signal.time.ravel(), label='Resulting Signal (Divided * Noise)')
+plt.title('* Noise')
+plt.xlabel('Time (s)')
+plt.ylabel('Amplitude')
+
+plt.tight_layout()
+plt.show()
+