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)differentiate
differentiate(
self ,
dim: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] ,
order: int = 2,
step: int = 1,
)-> ‘Self’
Calculate first derivative along dimension(s) using central differences.
The shape of the output patch is the same as the input patch. Derivative along edges are calculated with the same order (accuracy) as central 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 positive, even integer. |
| step |
The number of columns/rows to skip for differentiation. 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 differentiation in that package).
Strided output uses the derivative backend’s result dtype, including floating-point results for integer input and complex-valued derivatives.
The second order first derivative, for an evenly spaced coordinate, is defined as:
\[ \hat{f}(x) = \frac{f(x + dx) - f(x - dx)}{2dx} + O({dx}^2) \]
Where \(\hat{f}(x)\) is the estimated derivative of \(f\) at \(x\), \(dx\) is the sample spacing, and \(O\) is the error term.
The output data_type is mapped through the pairs a derivative is known to relate: along time displacement, velocity and acceleration follow one another and strain becomes strain_rate (phase becomes phase_rate); along distance motion becomes strain, which is what velocity_to_strain_rate does. A derivative the pairs cannot name all the way through – of an unknown data_type, or over both dimensions at once – is a quantity with no label here, and clears data_type rather than leaving a stale one on it.
A dimension with missing samples (holes in its step) raises; use split_gaps or fill_gaps first.