cf.Data.convolution_filter

Data.convolution_filter(window=None, axis=None, mode=None, cval=None, origin=0, inplace=False)

Return the data convolved along the given axis with the specified filter.

The magnitude of the integral of the filter (i.e. the sum of the weights defined by the weights parameter) affects the convolved values. For example, filter weights of [0.2, 0.2 0.2, 0.2, 0.2] will produce a non-weighted 5-point running mean; and weights of [1, 1, 1, 1, 1] will produce a 5-point running sum. Note that the weights returned by functions of the scipy.signal.windows package do not necessarily sum to 1 (see the examples for details).

New in version 3.3.0.

Parameters

window: sequence of numbers

Specify the window of weights to use for the filter.

Parameter example:

An unweighted 5-point moving average can be computed with weights=[0.2, 0.2, 0.2, 0.2, 0.2]

Note that the scipy.signal.windows package has suite of window functions for creating weights for filtering (see the examples for details).

axis: int

Select the axis over which the filter is to be applied. removed. The axis parameter is an integer that selects the axis corresponding to the given position in the list of axes of the data.

Parameter example:

Convolve the second axis: axis=1.

Parameter example:

Convolve the last axis: axis=-1.

mode: str, optional

The mode parameter determines how the input array is extended when the filter overlaps an array border. The default value is 'constant' or, if the dimension being convolved is cyclic (as ascertained by the iscyclic method), 'wrap'. The valid values and their behaviours are as follows:

mode	Description	Behaviour
'reflect'	The input is extended by reflecting about the edge	(c b a | a b c | c b a)
'constant'	The input is extended by filling all values beyond the edge with the same constant value (k), defined by the cval parameter.	(k k k | a b c | k k k)
'nearest'	The input is extended by replicating the last point	(a a a | a b c | c c c )
'mirror'	The input is extended by reflecting about the centre of the last point.	(c b | a b c | b a)
'wrap'	The input is extended by wrapping around to the opposite edge.	(a b c | a b c | a b c)

The position of the window realtive to each value can be changed by using the origin parameter.

cval: scalar, optional

Value to fill past the edges of the array if mode is 'constant'. Defaults to None, in which case the edges of the array will be filled with missing data.

Parameter example:

To extend the input by filling all values beyond the edge with zero: cval=0

origin: int, optional

Controls the placement of the filter. Defaults to 0, which is the centre of the window. If the window has an even number of weights then then a value of 0 defines the index defined by width/2 -1.

Parameter example:

For a weighted moving average computed with a weights window of [0.1, 0.15, 0.5, 0.15, 0.1], if origin=0 then the average is centred on each point. If origin=-2 then the average is shifted to inclued the previous four points. If origin=1 then the average is shifted to include the previous point and the and the next three points.

inplace: bool, optional

If True then do the operation in-place and return None.

Returns

Data or None

The convolved data, or None if the operation was in-place.

Examples:

>>> d = cf.Data(numpy.arange(12).reshape(3, 4), 'metres')
>>> print(d.array)
[[ 0,  1,  2,  3],
 [ 4,  5,  6,  7],
 [ 8,  9, 10, 11]])
>>> d.cyclic()
set()
>>> e = d.convolution_filter([0.1, 0.5, 0.25], axis=1)
>>> print(e.array)
[[-- 0.7 1.55 --]
 [-- 4.1 4.95 --]
 [-- 7.5 8.35 --]]
>>> e = d.convolution_filter([0.1, 0.5, 0.25], axis=1, cval=0)
>>> print(e.array)
[[0.1  0.7  1.55 2.  ]
 [2.5  4.1  4.95 5.  ]
 [4.9  7.5  8.35 8.  ]]
>>> e = d.convolution_filter([0.1, 0.5, 0.25], axis=1, mode='wrap')
>>> print(e.array)
[[0.85 0.7  1.55 2.  ]
 [4.25 4.1  4.95 5.4 ]
 [7.65 7.5  8.35 8.8 ]]
>>> d.cyclic(1)
set()
>>> d.cyclic()
{1}
>>> e = d.convolution_filter([0.1, 0.5, 0.25], axis=1)
>>> print(e.array)
[[0.85 0.7  1.55 2.  ]
 [4.25 4.1  4.95 5.4 ]
 [7.65 7.5  8.35 8.8 ]]