added a frequency2scale function as the dual to scale2frequency (#635)

* added a frequency2scale function as the dual to scale2frequency

Update test_functions.py

documentation for frequency2scale function

* add a bit more detail on frequency normalization to the docstring

This info is present in doc/source/ref/cwt.rst, but it seems helpful to
include it here as well.

Co-authored-by: Gregory Lee <grlee77@gmail.com>

doc/source/ref/cwt.rst

@@ -147,4 +147,26 @@ scales. The right column are the corresponding Fourier power spectra of each
 filter.. For scales 1 and 2 it can be seen that aliasing due to violation of
 the Nyquist limit occurs.
 
+Converting frequency to scale for ``cwt``
+-------------------------------
+
+To convert frequency to scale for use in the wavelet transform the function
+:func:`pywt.frequency2scale` can be used. This is the complement of the
+:func:`pywt.scale2frequency` function as seen in the previous section. Note that
+the input frequency in this function is normalized by 1/dt, or the sampling
+frequency fs. This function is useful for specifying the transform as a function
+of frequency directly.
+
+.. sourcecode:: python
+
+    >>> import numpy as np
+    >>> import pywt
+    >>> dt = 0.01  # 100 Hz sampling
+    >>> fs = 1 / dt
+    >>> frequencies = np.array([100, 50, 33.33333333, 25]) / fs # normalize
+    >>> scale = tfrequency2scale('cmor1.5-1.0', frequencies)
+    >>> scale
+    array([1., 2., 3., 4.])
+
+
 .. plot:: pyplots/cwt_scaling_demo.py

pywt/_functions.py

@@ -17,7 +17,8 @@
 from ._extensions._pywt import DiscreteContinuousWavelet, Wavelet, ContinuousWavelet
 
 
-__all__ = ["integrate_wavelet", "central_frequency", "scale2frequency", "qmf",
+__all__ = ["integrate_wavelet", "central_frequency", 
+           "scale2frequency", "frequency2scale", "qmf",
            "orthogonal_filter_bank",
            "intwave", "centrfrq", "scal2frq", "orthfilt"]
 
@@ -161,24 +162,48 @@ def central_frequency(wavelet, precision=8):
 
 
 def scale2frequency(wavelet, scale, precision=8):
-    """
+    """Convert from CWT "scale" to normalized frequency.
 
     Parameters
     ----------
     wavelet : Wavelet instance or str
         Wavelet to integrate.  If a string, should be the name of a wavelet.
     scale : scalar
+        The scale of the CWT.
     precision : int, optional
         Precision that will be used for wavelet function approximation computed
         with ``wavelet.wavefun(level=precision)``.  Default is 8.
 
     Returns
     -------
     freq : scalar
+        Frequency normalized to the sampling frequency. In other words, for a
+        sampling interval of `dt` seconds, the normalized frequency of 1.0
+        corresponds to (`1/dt` Hz).
 
     """
     return central_frequency(wavelet, precision=precision) / scale
 
+def frequency2scale(wavelet, freq, precision=8):
+    """Convert from to normalized frequency to CWT "scale".
+
+    Parameters
+    ----------
+    wavelet : Wavelet instance or str
+        Wavelet to integrate.  If a string, should be the name of a wavelet.
+    freq : scalar
+        Frequency, normalized so that the sampling frequency corresponds to a
+        value of 1.0.
+    precision : int, optional
+        Precision that will be used for wavelet function approximation computed
+        with ``wavelet.wavefun(level=precision)``.  Default is 8.
+
+    Returns
+    -------
+    scale : scalar
+
+    """
+    return central_frequency(wavelet, precision=precision) / freq
 
 def qmf(filt):
     """

pywt/tests/test_functions.py

@@ -26,6 +26,13 @@ def test_scal2frq_scale():
     result = pywt.scale2frequency(w, scale, precision=12)
     assert_almost_equal(result, expected, decimal=3)
 
+def test_frq2scal_freq():
+    freq = 2
+    w = pywt.Wavelet('db1')
+    expected = 1. / freq
+    result = pywt.frequency2scale(w, freq, precision=12)
+    assert_almost_equal(result, expected, decimal=3)
+
 
 def test_intwave_orthogonal():
     w = pywt.Wavelet('db1')