emmax_time

emmax_time creates a time-based EMMAX (exponential moving maximum) for an update_by table operation. The formula for the time-based EMMAX of a column $X$ is:

$a_i = e^{\frac{-dt_i}{\tau}}$

$\max_0(X) = x_0$

$\max_i(X) = \max(a*\max_{i-1}(X), \; x_i)$

Where:

• $dt_i$ is the difference between time $t_i$ and $t_{i-1}$ in nanoseconds.
• $\tau$ is decay_time in nanoseconds, an input parameter to the method.
• $\max_i(X)$ is the exponential moving maximum of $X$ at time step $i$.
• $x_i$ is the current value.
• $i$ denotes the time step, ranging from $i=1$ to $i = n-1$, where $n$ is the number of elements in $X$.

Syntax

emmax_time(
    ts_col: str,
    decay_time: Union[int, str],
    cols: list[str],
    op_control: OperationControl = None,
) -> UpdateByOperation

Parameters

Parameter	Type	Description
ts_col	str	The name of the column in the source table containing timestamps.
decay_time	Union[int, str]	The decay rate. This can be expressed as an integer in nanoseconds or a string duration, e.g., "PT00:00:00.001" or "PTnHnMnS", where H is hour, M is minute, and S is second.
cols	Union[str, list[str]]	The string names of columns to be operated on. These can include expressions to rename the output, e.g., "new_col = col". When this parameter is left empty, update_by will perform the operation on all applicable columns.
op_control	OperationControl	An OperationControl to define how special cases should behave. When None, default OperationControl settings are used. See OperationControl for more information.

Returns

An UpdateByOperation to be used in an update_by table operation.

Examples

The following example performs an update_by on the source table using two emmax_time operations. Each uses a different decay_time value to demonstrate how it affects the output.

from deephaven.updateby import emmax_time
from deephaven.time import to_j_instant
from deephaven import empty_table

base_time = to_j_instant("2023-05-01T00:00:00 ET")

source = empty_table(20).update(
    ["Timestamp = '2023-05-01T00:00:00 ET' + i * SECOND", "X = randomInt(0,25)"]
)

result = source.update_by(
    ops=[emmax_time(ts_col="Timestamp", decay_time="PT00:03:00", cols="EmMaxX = X")]
)

result2 = source.update_by(
    ops=[emmax_time(ts_col="Timestamp", decay_time="PT00:01:00", cols="EmMaxX = X")]
)

result

result2

source

Related documentation

• How to use update_by
• How to create an empty table
• Time in Deephaven
• ternary conditional operator
• OperationControl
• update
• update_by
• Javadoc
• Pydoc