Skip to main content
`Ctrl`+`K`
scipy.signal.

# upfirdn

scipy.signal.upfirdn(h, x, up=1, down=1, axis=-1, mode='constant', cval=0)

  Upsample, FIR filter, and downsample.

  Parameters:
    h array_like

      1-D FIR (finite-impulse response) filter coefficients.

    x array_like

      Input signal array.

    up int, optional

      Upsampling rate. Default is 1.

    down int, optional

      Downsampling rate. Default is 1.

    axis int, optional

      The axis of the input data array along which to apply the linear filter. The filter is applied to each subarray along this axis. Default is -1.

    mode str, optional

      The signal extension mode to use. The set `{"constant", "symmetric", "reflect", "edge", "wrap"}` correspond to modes provided by `numpy.pad`. `"smooth"` implements a smooth extension by extending based on the slope of the last 2 points at each end of the array. `"antireflect"` and `"antisymmetric"` are anti-symmetric versions of `"reflect"` and `"symmetric"`. The mode “line” extends the signal based on a linear trend defined by the first and last points along the `axis`.

      Added in version 1.4.0.

    cval float, optional

      The constant value to use when `mode == "constant"`.

      Added in version 1.4.0.

  Returns:
    y ndarray

      The output signal array. Dimensions will be the same as x except for along axis, which will change size according to the h, up, and down parameters.

  Notes

  The algorithm is an implementation of the block diagram shown on page 129 of the Vaidyanathan text [1] (Figure 4.3-8d).

  The direct approach of upsampling by factor of P with zero insertion, FIR filtering of length `N`, and downsampling by factor of Q is O(N*Q) per output sample. The polyphase implementation used here is O(N/P).

  Added in version 0.18.

  Array API Standard Support

  `upfirdn` has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable `SCIPY_ARRAY_API=1` and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

  Library | CPU | GPU
  --- | --- | ---
  NumPy | ✅ | n/a
  CuPy | n/a | ✅
  PyTorch | ✅ | ⛔
  JAX | ⚠️ no JIT | ⛔
  Dask | ⚠️ computes graph | n/a

  CuPy only supports `mode="constant"` and `cval=0.0`.

  > See Support for the array API standard for more information.

  References

  [1]

  P. P. Vaidyanathan, Multirate Systems and Filter Banks, Prentice Hall, 1993.

  Examples

  Simple operations:

      >>> import numpy as np
      >>> from scipy.signal import upfirdn
      >>> upfirdn([1, 1, 1], [1, 1, 1])   # FIR filter
      array([ 1.,  2.,  3.,  2.,  1.])
      >>> upfirdn([1], [1, 2, 3], 3)  # upsampling with zeros insertion
      array([ 1.,  0.,  0.,  2.,  0.,  0.,  3.])
      >>> upfirdn([1, 1, 1], [1, 2, 3], 3)  # upsampling with sample-and-hold
      array([ 1.,  1.,  1.,  2.,  2.,  2.,  3.,  3.,  3.])
      >>> upfirdn([.5, 1, .5], [1, 1, 1], 2)  # linear interpolation
      array([ 0.5,  1. ,  1. ,  1. ,  1. ,  1. ,  0.5])
      >>> upfirdn([1], np.arange(10), 1, 3)  # decimation by 3
      array([ 0.,  3.,  6.,  9.])
      >>> upfirdn([.5, 1, .5], np.arange(10), 2, 3)  # linear interp, rate 2/3
      array([ 0. ,  1. ,  2.5,  4. ,  5.5,  7. ,  8.5])

  Apply a single filter to multiple signals:

      >>> x = np.reshape(np.arange(8), (4, 2))
      >>> x
      array([[0, 1],
             [2, 3],
             [4, 5],
             [6, 7]])

  Apply along the last dimension of `x`:

      >>> h = [1, 1]
      >>> upfirdn(h, x, 2)
      array([[ 0.,  0.,  1.,  1.],
             [ 2.,  2.,  3.,  3.],
             [ 4.,  4.,  5.,  5.],
             [ 6.,  6.,  7.,  7.]])

  Apply along the 0th dimension of `x`:

      >>> upfirdn(h, x, 2, axis=0)
      array([[ 0.,  1.],
             [ 0.,  1.],
             [ 2.,  3.],
             [ 2.,  3.],
             [ 4.,  5.],
             [ 4.,  5.],
             [ 6.,  7.],
             [ 6.,  7.]])