# differentiate

 function of dascore.transform.differentiate source

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 calcualte
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 derivate, for an evenly spaced coordiante, is defined as:

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

Where $$\hat{f}(x)$$ is the estiamted derivative of $$f$$ at $$x$$, $$dx$$ 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)