Repository: pyfar/pyfar (python)

Issue:
Inconsistency for fractional filter returns 
[fractional_octave_bands](https://pyfar.readthedocs.io/en/stable/modules/pyfar.dsp.filter.html#pyfar.dsp.filter.fractional_octave_bands) and [reconstructing_fractional_octave_bands](https://pyfar.readthedocs.io/en/stable/modules/pyfar.dsp.filter.html#pyfar.dsp.filter.reconstructing_fractional_octave_bands) have different output parameter

seems like ``reconstructing_fractional_octave_bands``returns signal, frequencies or filter, frequencies
and ``fractional_octave_bands`` returns signal or filter


also the inputs are not perfect. the ``sampling_rate`` is not at the same position and ``num_fractions`` has sometimes defaults and another time not.
```
pyfar.dsp.filter.reconstructing_fractional_octave_bands(signal, num_fractions=1, frequency_range=(63, 16000), overlap=1, slope=0, n_samples=4096, sampling_rate=None)

pyfar.dsp.filter.fractional_octave_bands(signal, num_fractions, sampling_rate=None, frequency_range=(20.0, 20000.0), order=14)
```

Pull request:
deprecate 'frequencies' reconstructing_fractional_octave_bands()
deprecate `frequencies` return in `reconstructing_fractional_octave_bands()`

Closes #657 


Patch:
diff --git a/pyfar/dsp/filter/fractional_octaves.py b/pyfar/dsp/filter/fractional_octaves.py
index 955fbfae..283b2d03 100644
--- a/pyfar/dsp/filter/fractional_octaves.py
+++ b/pyfar/dsp/filter/fractional_octaves.py
@@ -4,6 +4,7 @@ import numpy as np
 import scipy.signal as spsignal
 import pyfar as pf
 from pyfar._utils import rename_arg
+from pyfar.classes.warnings import PyfarDeprecationWarning
 
 
 def fractional_octave_frequencies(
@@ -396,7 +397,9 @@ def reconstructing_fractional_octave_bands(
     filter : FilterFIR
         FIR Filter object. Only returned if ``signal = None``.
     frequencies : np.ndarray
-        Center frequencies of the filters.
+        Center frequencies of the filters. Return variable will be removed
+        in pyfar 0.9.0. To get the fractional octave center frequencies, use
+        :py:func:`~pyfar.dsp.filter.fractional_octave_frequencies` instead.
 
     References
     ----------
@@ -414,7 +417,10 @@ def reconstructing_fractional_octave_bands(
         >>> import matplotlib.pyplot as plt
         >>> # generate data
         >>> x = pf.signals.impulse(2**12)
-        >>> y, f = pf.dsp.filter.reconstructing_fractional_octave_bands(x)
+        >>> y = pf.dsp.filter.reconstructing_fractional_octave_bands(x)[0]
+        >>> # get center frequencies
+        >>> f = pf.dsp.filter.fractional_octave_frequencies(
+        ...    frequency_range=(60, 16000))[1]
         >>> y_sum = pf.Signal(np.sum(y.time, 0), y.sampling_rate)
         >>> # time domain plot
         >>> ax = pf.plot.time_freq(y_sum, color='k', unit='ms')
@@ -518,6 +524,11 @@ def reconstructing_fractional_octave_bands(
         f"(num_fractions={num_fractions}, frequency_range={frequency_range}, "
         f"overlap={overlap}, slope={slope})")
 
+    warnings.warn(("Return parameter 'frequencies' will be removed in pyfar"
+                   " 0.9.0. To get the fractional octave center frequencies,"
+                   " use `pyfar.dsp.filter.fractional_octave_frequencies` "
+                   "instead."), PyfarDeprecationWarning, stacklevel=2)
+
     if signal is None:
         # return the filter object
         return filt, f_m[f_id]


Test patch:
diff --git a/tests/test_deprecations.py b/tests/test_deprecations.py
index 8331fc9f..190eec60 100644
--- a/tests/test_deprecations.py
+++ b/tests/test_deprecations.py
@@ -394,3 +394,13 @@ def test_deprecations_audio_io():
     if version.parse(pf.__version__) >= version.parse('0.9.0'):
         with pytest.raises(TypeError):
             pf.io.audio_subtypes(format='wav')
+
+
+def test_deprecations_reconstructing_fractional_octave_bands_frequencies():
+    with pytest.warns(
+        PyfarDeprecationWarning, match="Return parameter 'frequencies' will be"
+        " removed in pyfar 0.9.0. To get the fractional octave center "
+        "frequencies, use `pyfar.dsp.filter.fractional_octave_frequencies` "
+        "instead."):
+        pfilt.reconstructing_fractional_octave_bands(None,
+                                                     sampling_rate=44.1e3)