differentiate

function of dascore.transform.differentiate

differentiate(
    patch: Patch ,
    dim: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] ,
    order: int = 2,
    step: int = 1,
)-> ‘PatchType’

Calculate first derivative along dimension(s) using centeral diferences.

The shape of the output patch is the same as the input patch. Derivative along edges are calculated with the same order (accuarcy) as centeral points using non-centered stencils.

Parameters

Parameter	Description
patch	The patch to differentiate.
dim	The dimension(s) along which to differentiate. If None differentiates over all dimensions.
order	The order of the differentiation operator. Must be a possitive, even integar.
step	The number of columns/rows to skip for differention. eg: an array of [a b c d e] uses b and d to calculate diff of c when step = 1 and order = 2. When step = 2, a and e are used to calculate diff at c.

Note

For order=2 (the default) numpy’s gradient function is used. When order != 2, the optional package findiff must be installed in which case order is interpreted as accuracy (“order” means order of differention in that package).

The second order first derivative, for an evenly spaced coordinate, is defined as:

$\hat{f} (x) = \frac{f (x + d x) - f (x - d x)}{2 d x} + O ({d x}^{2})$

Where $\hat{f} (x)$ is the estiamted derivative of $f$ at $x$ , $d x$ is the sample spacing, and $O$ is the error term.

Examples

import dascore as dc
patch = dc.get_example_patch()

# Example 1
# 2nd order stencil for 1st derivative along time dimension
patch_diff_1 = patch.differentiate(dim='time', order=2)

# Example 2
# 1st derivative along all dimensions
patch_diff_2 = patch.differentiate(dim=None)

# Example 3
# 1st derivative using a step size of 3. This spaces out the columns
# or rows used for estimating the derivative.
patch_diff_3 = patch.differentiate(dim="distance", step=3, order=2)