zooc.dsp.filters

Digital filters for single dimensional data processing in time domain.

class zooc.dsp.filters.Filter(*, data_values)

Bases: ABC

Mathematical filter to output a value based in single dimensional input data.

Parameters:

data_values (FloatArray) – Input data values.

abstractmethod describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

abstractmethod get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

abstractmethod is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

class zooc.dsp.filters.FilterExpDecay(*, data_values, data_t, max_linalg=20000000.0)

Bases: FilterMath

Exponentially decaying filter.

Parameters:

  • data_values (FloatArray) – Input data values.

  • data_t (FloatArray) – Time data.

  • max_linalg (Final[float]) – Maximum value for the linear algebra condition number of the covariance matrix. A typical valid value is in range of 1E5-20E6.

Raises:

ValueError – When data is not valid for exponential decay filter.

classmethod create(data)

Create a FilterExpDecay from dictionary data.

Parameters:

data (dict[float, float]) – <time>: <value> dictionary.

Returns:

FilterExpDecay.

Return type:

T

static model_func(t, a, k, c)

Mathematical function for exponential decay used by this filter.

Parameters:

  • t (FloatArray) – Time.

  • a (Float) – Amplitude constant.

  • k (Float) – Exponent constant.

  • c (Float) – Constant where the function decays to, i.e. the limit value.

Returns:

Value of the function at time t.

Return type:

FloatArray

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

find_worst_outlier()

Get the worst outlier from the data.

Returns:

Tuple of (time, value) of the worst outlier.

Return type:

tuple[float, float]

forecast(t_future)

Calculate the future value of the function starting from the last time point.

Parameters:

t_future (FloatAny) – Time after the latest data point [s].

Returns:

Value at t_future.

Return type:

FloatArray

get_amplitude()

Get the amplitude constant, i.e., the difference of the first sample and the final value.

Returns:

Amplitude.

Return type:

float

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_output()

Get the final limit value into which the function approaches.

Returns:

Final value, i.e., c.

Return type:

float

get_time_constant()

Get the time constant of the exponential decay function.

Returns:

Time constant [s].

Return type:

float

get_value_tc(value)

Get time as a multiple of the time constant for given value.

Example: A value at 63.5% of the final value would result 1.0 (1 time constant).

Parameters:

value (float) – Value to calculate the time constant for.

Returns:

Multiple of the time constant for given value.

Return type:

float

has_enough_data()

Was enough data points provided to solve the exponential decay function.

Returns:

True is enough data points.

Return type:

bool

is_pos_or_neg()

Check whether the function is rising or decreasing.

Returns:

True if rising.

Return type:

bool

is_valid(max_linalg=None)

Validate the data resembles exponentially decaying function.

  • At least 4 data points.

  • Numpy evaluates the data as valid.

Parameters:

max_linalg (float | None) – Maximum value for the linear algebra condition number of the covariance matrix.

Returns:

True: model is reliable.

Return type:

bool

solve(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatArray) – Time point [s].

Returns:

Value at t.

Return type:

FloatArray

solve_float(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatAny) – Time point [s].

Returns:

Value at t.

Return type:

float

solve_t0(t)

Calculate the value of the function starting from the first time point.

Parameters:

t (FloatAny) – Time after the first data point [s].

Returns:

Value at t_0 + t.

Return type:

FloatArray

a: float64

Amplitude constant.

property bounds: tuple[list[float], list[float]]

Get bounds for the model.

Returns:

Tuple of (lower_bounds, upper_bounds) for [a, k, c].

c: float64

Constant where the function decays to, i.e. the limit value.

k: float64

Exponent constant. Absolute value. Negative value is used in model_func()

parm_cov: FloatArray

Numpy covariance matrix of the parameters.

t_range: float64

Time range for normalized time.

t_zero: float64

Zero time point.

class zooc.dsp.filters.FilterExpDecayZ(*, data_values, data_t, max_linalg=20000000.0, tau_min_th, tau_max_th, noise_rel_range_th, noise_abs_range_th)

Bases: FilterExpDecay

Exponentially decaying filter combined with min/max time constant and monotonic data validation.

Parameters:
Raises:

ValueError – When data is not valid for exponential decay filter.

classmethod create(data)

Create a FilterExpDecay from dictionary data.

Parameters:

data (dict[float, float]) – <time>: <value> dictionary.

Returns:

FilterExpDecay.

Return type:

T

static model_func(t, a, k, c)

Mathematical function for exponential decay used by this filter.

Parameters:

  • t (FloatArray) – Time.

  • a (Float) – Amplitude constant.

  • k (Float) – Exponent constant.

  • c (Float) – Constant where the function decays to, i.e. the limit value.

Returns:

Value of the function at time t.

Return type:

FloatArray

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

find_worst_outlier()

Get the worst outlier from the data.

Returns:

Tuple of (time, value) of the worst outlier.

Return type:

tuple[float, float]

forecast(t_future)

Calculate the future value of the function starting from the last time point.

Parameters:

t_future (FloatAny) – Time after the latest data point [s].

Returns:

Value at t_future.

Return type:

FloatArray

get_amplitude()

Get the amplitude constant, i.e., the difference of the first sample and the final value.

Returns:

Amplitude.

Return type:

float

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_output()

Get the final limit value into which the function approaches.

Returns:

Final value, i.e., c.

Return type:

float

get_time_constant()

Get the time constant of the exponential decay function.

Returns:

Time constant [s].

Return type:

float

get_value_tc(value)

Get time as a multiple of the time constant for given value.

Example: A value at 63.5% of the final value would result 1.0 (1 time constant).

Parameters:

value (float) – Value to calculate the time constant for.

Returns:

Multiple of the time constant for given value.

Return type:

float

has_enough_data()

Was enough data points provided to solve the exponential decay function.

Returns:

True is enough data points.

Return type:

bool

is_pos_or_neg()

Check whether the function is rising or decreasing.

Returns:

True if rising.

Return type:

bool

is_valid(max_linalg=None)

Validate the data resembles exponentially decaying function.

  • At least 4 data points.

  • Numpy evaluates the data as valid.

Parameters:

max_linalg (float | None) – Maximum value for the linear algebra condition number of the covariance matrix.

Returns:

True: model is reliable.

Return type:

bool

solve(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatArray) – Time point [s].

Returns:

Value at t.

Return type:

FloatArray

solve_float(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatAny) – Time point [s].

Returns:

Value at t.

Return type:

float

solve_t0(t)

Calculate the value of the function starting from the first time point.

Parameters:

t (FloatAny) – Time after the first data point [s].

Returns:

Value at t_0 + t.

Return type:

FloatArray

a: float64

Amplitude constant.

property bounds: tuple[list[float], list[float]]

Get bounds for the model.

Returns:

Tuple of (lower_bounds, upper_bounds) for [a, k, c].

c: float64

Constant where the function decays to, i.e. the limit value.

k: float64

Exponent constant. Absolute value. Negative value is used in model_func()

parm_cov: FloatArray

Numpy covariance matrix of the parameters.

t_range: float64

Time range for normalized time.

t_zero: float64

Zero time point.

class zooc.dsp.filters.FilterMath(*, data_values, data_t)

Bases: Filter

Abstract filter for forecasting future values.

Parameters:

  • data_t (FloatArray) – Time data.

  • data_values (FloatArray)

abstractmethod describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

forecast(t_future)

Calculate the future value of the function starting from the last time point.

Parameters:

t_future (FloatAny) – Time after the latest data point [s].

Returns:

Value at t_future.

Return type:

FloatArray

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

abstractmethod get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

abstractmethod is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

abstractmethod solve(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatArray) – Time point [s].

Returns:

Value at t.

Return type:

FloatArray

solve_float(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatAny) – Time point [s].

Returns:

Value at t.

Return type:

float

solve_t0(t)

Calculate the value of the function starting from the first time point.

Parameters:

t (FloatAny) – Time after the first data point [s].

Returns:

Value at t_0 + t.

Return type:

FloatArray

class zooc.dsp.filters.FilterMedian(*, data_values, MIN_SAMPLES_STDDEV=2, max_abs_input_range)

Bases: Filter

Median output filter for 1D data with min/max input noise tolerance.

Parameters:

  • data_values (FloatArray) – Input data values.

  • max_abs_input_range (float) – Allowed absolute input range.

  • MIN_SAMPLES_STDDEV (Final[int])

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

property filtered_series: FloatArray

Get the median filtered output.

Returns:

Filtered output.

property stddev: float

Get the linear regression standard deviation of the data.

Returns:

Standard deviation.

class zooc.dsp.filters.FilterMedianLinear(*, data_values, MIN_SAMPLES_STDDEV=2, max_abs_input_range, data_t)

Bases: FilterMath, FilterMedian

Median output filter for data with time dimension and linear regression.

Parameters:

  • data_values (FloatArray) – Input data values.

  • data_t (FloatArray) – Time data.

  • max_abs_input_range (float) – Allowed absolute noise threshold over the input range.

  • MIN_SAMPLES_STDDEV (Final[int])

static create(data, max_abs_input_range)

Create a FilterLinear from dictionary data.

Parameters:

  • data (dict[float, float]) – <time>: <value> dictionary.

  • max_abs_input_range (float) – See FilterMedian.

Returns:

FilterMedianLinear.

Return type:

FilterMedianLinear

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

forecast(t_future)

Calculate the future value of the function starting from the last time point.

Parameters:

t_future (FloatAny) – Time after the latest data point [s].

Returns:

Value at t_future.

Return type:

FloatArray

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

solve(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatArray) – Time point [s].

Returns:

Value at t.

Return type:

FloatArray

solve_float(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatAny) – Time point [s].

Returns:

Value at t.

Return type:

float

solve_t0(t)

Calculate the value of the function starting from the first time point.

Parameters:

t (FloatAny) – Time after the first data point [s].

Returns:

Value at t_0 + t.

Return type:

FloatArray

property correlation: float

Get the linear regression correlation of the data.

Note, correlation of constant (flat) data is 0.

Returns:

Correlation as r-value.

property filtered_series: FloatArray

Get the median filtered output.

Returns:

Filtered output.

property intercept: float

Get the linear regression. y-intercept of the data.

Returns:

y-intercept at t=0.

property slope: float

Get the linear regression slope of the data.

Returns:

Slope [x/y].

property stddev: float

Get the linear regression standard deviation of the data.

Returns:

Standard deviation.

property stderr_relative: float

Get the linear regression slope’s relative standard error.

Note, not reliable for (nearly) constant (flat) dataset.

Returns:

Relative standard error of the slope [n].

class zooc.dsp.filters.FilterMonotonic(*, data_values, noise_rel_range_th, noise_abs_range_th)

Bases: Filter, ABC

Abstract filter for monotonically increasing or decreasing data with noise tolerance.

Parameters:

  • data_values (FloatArray) – Input data values.

  • noise_rel_range_th (float64 | float) – Allowed relative noise threshold over the value range when verifying data, e.g. 0.1 -> 10%.

  • noise_abs_range_th (float64 | float) – Allowed absolute noise threshold over the value range when verifying data.

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_noise_th()

Get allowed noise threshold, larger of relative and absolute noise thresholds.

Returns:

Noise threshold as absolute value.

Return type:

float

abstractmethod get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

is_monotonic()

Is input data monotonic within the noise tolerance.

Returns:

True if monotonic.

Return type:

bool

is_monotonic_dec(noise)

Check whether the input data is decreasing monotonically within noise tolerance.

Parameters:

noise (float) – Absolute noise tolerance.

Returns:

True if monotonically decreasing.

Return type:

bool

is_monotonic_inc(noise)

Check whether the input data is increasing monotonically within the noise tolerance.

Parameters:

noise (float) – Absolute noise tolerance.

Returns:

True if monotonically rising.

Return type:

bool

is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

class zooc.dsp.filters.FilterMonotonicImpl(*, data_values, noise_rel_range_th, noise_abs_range_th)

Bases: FilterMonotonic

Dummy implementation of FilterMonotonic.

Parameters:

  • data_values (FloatArray)

  • noise_rel_range_th (float64 | float)

  • noise_abs_range_th (float64 | float)

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_noise_th()

Get allowed noise threshold, larger of relative and absolute noise thresholds.

Returns:

Noise threshold as absolute value.

Return type:

float

get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

is_monotonic()

Is input data monotonic within the noise tolerance.

Returns:

True if monotonic.

Return type:

bool

is_monotonic_dec(noise)

Check whether the input data is decreasing monotonically within noise tolerance.

Parameters:

noise (float) – Absolute noise tolerance.

Returns:

True if monotonically decreasing.

Return type:

bool

is_monotonic_inc(noise)

Check whether the input data is increasing monotonically within the noise tolerance.

Parameters:

noise (float) – Absolute noise tolerance.

Returns:

True if monotonically rising.

Return type:

bool

is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

class zooc.dsp.filters.FilterStable(*, data_values, MIN_SAMPLES_STDDEV=2, max_abs_input_range, data_t, max_slope, max_rse, max_stddev)

Bases: FilterMedianLinear

Stable filter for 2D data.

Data is determined as stable (valid) when the slope is small and correlation high.

Parameters:

  • data_values (FloatArray) – Input data values.

  • max_abs_input_range (float) – Allowed absolute noise threshold over the input range.

  • data_t (FloatArray) – Time data.

  • max_slope (float) – Maximum allowed slope in given unit / time [x/y].

  • max_rse (float) – Maximum relative standard error of the slope when slope is high [n].

  • max_stddev (float) – Maximum standard deviation when slope is low [y].

  • MIN_SAMPLES_STDDEV (Final[int])

static create(data, max_abs_input_range)

Create a FilterLinear from dictionary data.

Parameters:

  • data (dict[float, float]) – <time>: <value> dictionary.

  • max_abs_input_range (float) – See FilterMedian.

Returns:

FilterMedianLinear.

Return type:

FilterMedianLinear

describe()

Describe the filter output.

Returns:

Dictionary of properties and their values.

Return type:

dict[str, object]

forecast(t_future)

Calculate the future value of the function starting from the last time point.

Parameters:

t_future (FloatAny) – Time after the latest data point [s].

Returns:

Value at t_future.

Return type:

FloatArray

get_full_range()

Get the full range of the input data.

Returns:

Input range.

Return type:

float

get_output()

Get the output value of the filter.

Returns:

Filtered output value.

Return type:

float

is_valid()

Check whether the data is valid for the filter.

Returns:

True if valid.

Return type:

bool

solve(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatArray) – Time point [s].

Returns:

Value at t.

Return type:

FloatArray

solve_float(t)

Calculate the value of the function at the given time point.

Parameters:

t (FloatAny) – Time point [s].

Returns:

Value at t.

Return type:

float

solve_t0(t)

Calculate the value of the function starting from the first time point.

Parameters:

t (FloatAny) – Time after the first data point [s].

Returns:

Value at t_0 + t.

Return type:

FloatArray

property correlation: float

Get the linear regression correlation of the data.

Note, correlation of constant (flat) data is 0.

Returns:

Correlation as r-value.

property filtered_series: FloatArray

Get the median filtered output.

Returns:

Filtered output.

property intercept: float

Get the linear regression. y-intercept of the data.

Returns:

y-intercept at t=0.

property slope: float

Get the linear regression slope of the data.

Returns:

Slope [x/y].

property stddev: float

Get the linear regression standard deviation of the data.

Returns:

Standard deviation.

property stderr_relative: float

Get the linear regression slope’s relative standard error.

Note, not reliable for (nearly) constant (flat) dataset.

Returns:

Relative standard error of the slope [n].