Basic time series functions

Operators

indsl.ts_utils.operators.absolute(x)

Absolute value.

The absolute value of time series or numbers.

Parameters:

x – time series or numbers

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.add(a, b, align_timesteps: bool = False)

Add.

Add any two time series or numbers.

Parameters:

  • a – Time-series or number.

  • b – Time-series or number.

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.arithmetic_mean(a, b, align_timesteps: bool = False)

Arithmetic mean.

The mean of two time series or numbers.

Parameters:

  • a – Time series or number

  • b – Time series or number

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.arithmetic_mean_many(data: List[Series | float], align_timesteps: bool = False) → Series | float

Arithmetic mean many.

The mean of multiple time series.

Parameters:

  • data – List of time series

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.div(a, b, align_timesteps: bool = False)

Division.

Divide two time series or numbers. If the time series in the denominator contains zeros, all instances are dropped from the final result.

Parameters:

  • a – Numerator

  • b – Denominator

  • align_timesteps (bool) – Auto-align. Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.inv(x)

Inverse.

Element-wise inverse of time series or numbers.

Parameters:

x – time series or numbers

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.mod(a, b, align_timesteps: bool = False)

Modulo.

Modulo of time series or numbers.

Parameters:

  • a – dividend time series or number

  • b – divisor time series or number

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.mul(a, b, align_timesteps: bool = False)

Multiplication.

Multiply two time series or numbers.

Parameters:

  • a – Time-series or number.

  • b – Time-series or number.

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.neg(x)

Negation.

Negation of time series or numbers.

Parameters:

x – time series or numbers

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.power(a, b, align_timesteps: bool = False)

Power.

Power of time series or numbers.

Parameters:

  • a – base time series or number

  • b – exponent time series or number

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.sqrt(x)

Square root.

Square root of time series or numbers.

Parameters:

x – time series or numbers

Returns:

Time series.

Return type:

pandas.Series

indsl.ts_utils.operators.sub(a, b, align_timesteps: bool = False)

Subtraction.

The difference between two time series or numbers.

Parameters:

  • a – Time-series or number.

  • b – Time-series or number.

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

Time series.

Return type:

pandas.Series

Numerical calculus

indsl.ts_utils.numerical_calculus.differentiate(series: Series, time_unit: Timedelta = Timedelta('0 days 01:00:00')) → Series

Differentiation.

Differentiation (finite difference) using a second-order accurate numerical method (central difference). Boundary points are computed using a first-order accurate method.

Parameters:

  • series – Time series.

  • time_unit – Frequency. User defined granularity to potentially override unit of time. Defaults to 1 h. Accepts integer followed by time unit string (ms|s|m|h|d). For example: ‘1s’, ‘5m’, ‘3h’ or ‘1d’.

Returns:

First order derivative.

Return type:

pandas.Series

indsl.ts_utils.numerical_calculus.integrate_windows(values: ndarray, dt: ndarray, from_to_index: ndarray, number_of_windows: int) → ndarray

Integrate the windows.

Performs the integration, through the trapezoidal- or midpoint-method. Since all the from and to window indexes are available and all inputs are np.ndarrays, this is parallelized and sped up with numba.

Parameters:

  • values – Values to integrate corrected to the integrand rate.

  • dt – The time in milliseconds between datapoints.

  • from_to_index – index is the start of a window and value is the end index of the window.

  • number_of_windows – the number of windows to integrate

Returns:

The result of each integrated window.

Return type:

numpy.ndarray

indsl.ts_utils.numerical_calculus.sliding_window_integration(series: Series, window_length: Timedelta = Timedelta('0 days 00:05:00'), integrand_rate: Timedelta = Timedelta('0 days 01:00:00')) → Series

Sliding window integration.

Siding window integration using trapezoidal rule.

Parameters:

  • series – Time series.

  • window_length –

    window_length the length of time the window. Defaults to ‘5 minute’. Valid time units are:

    • ‘W’, ‘D’, ‘T’, ‘S’, ‘L’, ‘U’, or ‘N’

    • ‘days’ or ‘day’

    • ‘hours’, ‘hour’, ‘hr’, or ‘h’

    • ‘minutes’, ‘minute’, ‘min’, or ‘m’

    • ‘seconds’, ‘second’, or ‘sec’

    • ‘milliseconds’, ‘millisecond’, ‘millis’, or ‘milli’

    • ‘microseconds’, ‘microsecond’, ‘micros’, or ‘micro’

    • ‘nanoseconds’, ‘nanosecond’, ‘nanos’, ‘nano’, or ‘ns’.

  • integrand_rate –

    integrand_rate. if the integrands rate is per sec, per hour, per day. Defaults to ‘1 hour’. Valid time units are:

    • ‘W’, ‘D’, ‘T’, ‘S’, ‘L’, ‘U’, or ‘N’

    • ‘days’ or ‘day’

    • ‘hours’, ‘hour’, ‘hr’, or ‘h’

    • ‘minutes’, ‘minute’, ‘min’, or ‘m’

    • ‘seconds’, ‘second’, or ‘sec’

    • ‘milliseconds’, ‘millisecond’, ‘millis’, or ‘milli’

    • ‘microseconds’, ‘microsecond’, ‘micros’, or ‘micro’

    • ‘nanoseconds’, ‘nanosecond’, ‘nanos’, ‘nano’, or ‘ns’.

Returns:

Time series

Return type:

pandas.Series

indsl.ts_utils.numerical_calculus.trapezoidal_integration(series: Series, time_unit: Timedelta = Timedelta('0 days 01:00:00')) → Series

Integration.

Cumulative integration using trapezoidal rule with an optional user-defined time unit.

Parameters:

  • series – Time series.

  • time_unit – Frequency. User defined granularity to potentially override unit of time. Defaults to 1 h. Accepted formats can be found here: https://pandas.pydata.org/docs/reference/api/pandas.Timedelta.html. Some examples are: ‘1s’, ‘5m’, ‘3h’ or ‘1d’, but combinations also work: “1d 6h 43s”

Returns:

Cumulative integral.

Return type:

pandas.Series

indsl.ts_utils.numerical_calculus.window_index(np_datetime_ns: ndarray[Any, dtype[float64]], windowlength_in_ns: int) → ndarray

Sliding window indexing.

Returns a np.ndarray where the index corresponds to the starting point of a window, the value at the index corresponds to numerical indexes for the end of the window. This gives the window span each window is supposed to integrate to.

Parameters:

  • np_datetime_ns – Datetime in integer ns.

  • windowlength_in_ns – The length of the window in ns.

Retruns:

np.ndarray: indexing of timewindows

Logarithmic functions

indsl.ts_utils.logarithmic_functions.exp(x)

Exp.

Calculates the exponential of a time series.

Parameters:

x – time-series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.logarithmic_functions.log(x)

Ln.

Calculates the natural logarithm of a time series.

Parameters:

x – time-series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.logarithmic_functions.log10(x)

Log base 10.

Calculates the logarithm with base 10 of a time series.

Parameters:

x – time-series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.logarithmic_functions.log2(x)

Log base 2.

Calculates the logarithm with base 2 of a time series.

Parameters:

x – time-series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.logarithmic_functions.logn(x, base, align_timesteps: bool = False)

Log, any base.

Calculates the logarithm with base “n” of a time series.

Parameters:

  • x – Input time-series or number

  • base – Base time-series or number

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

time series

Return type:

pandas.Series

Trigonometric functions

indsl.ts_utils.trigonometric_functions.arccos(x)

Arccos.

Calculates the trigonometric arccosine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arccosh(x)

Arccosh.

Calculates the hyperbolic arccosine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arcsin(x)

Arcsin.

Calculates the trigonometric arcsine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arcsinh(x)

Arcsinh.

Calculates the hyperbolic arcsine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arctan(x)

Arctan.

Calculate inverse hyperbolic tangent of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arctan2(x1, x2, align_timesteps: bool = False)

Arctan(x1, x2).

Element-wise arc tangent of x1/x2 choosing the quadrant correctly.

Parameters:

  • x1 – First time series or number

  • x2 – Second time series or number

  • align_timesteps (bool) – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.arctanh(x)

Arctanh.

Calculates the hyperbolic arctangent of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.cos(x)

Cos.

Calculates the trigonometric cosine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.cosh(x)

Cosh.

Calculates the hyperbolic cosine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.deg2rad(x)

Degrees to radians.

Converts angles from degrees to radians.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.rad2deg(x)

Radians to degrees.

Converts angles from radiants to degrees.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.sin(x)

Sin.

Calculates the trigonometric sine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.sinh(x)

Sinh.

Calculates the hyperbolic sine of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.tan(x)

Tan.

Calculates the trigonometric tangent of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

indsl.ts_utils.trigonometric_functions.tanh(x)

Tanh.

Calculates the hyperbolic tangent of time series.

Parameters:

x – time series

Returns:

time series

Return type:

pandas.Series

Utility functions

indsl.ts_utils.utility_functions.bin_map(x1, x2, align_timesteps: bool = False)

Element-wise greater-than.

Maps to a binary array by checking if one time series is greater than another.

Parameters:

  • x1 – First time series or number

  • x2 – Second time series or number

  • align_timesteps – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

time series

Return type:

np.ndarray

indsl.ts_utils.utility_functions.ceil(x)

Round up.

Rounds up a time series to the nearest integer greater than or equal to the current value.

Parameters:

x – time series

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.clip(x, low: float = -inf, high: float = inf)

Clip (low, high).

Given an interval, values of the time series outside the interval are clipped to the interval edges.

Parameters:

  • x (pd.Series) – time series

  • low – Lower limit Lower clipping limit. Default: -infinity

  • high – Upper limit Upper clipping limit. Default: +infinity

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.create_series_from_timesteps(timesteps: List[timedelta]) → Series

Time series from timestamps.

Create a time series which starts on the 2021-1-1 and contains data points with the provided timesteps in seconds. All values of the output series are zero.

Parameters:

timesteps – Time steps between points.

Returns:

Time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.floor(x)

Round down.

Rounds a time series down to the nearest integer smaller than or equal to the current value.

Parameters:

x – time series

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.generate_step_series(flag: Series) → Series

Step-wise time series.

Construct a step-wise time series (with 0-1 values) from a flag time series. Consecutive 1 values are merged in one step.

Parameters:

flag – Binary time series. The length of the flag time series has to be the same as the original data points.

Returns:

Time series

Return type:

pd.Series

Example

Given 4 datapoints and a flag with values [0, 0, 1, 0]

data points: x——-x——-x——-x flag: 0 0 1 0

The resulting step series is represented as:

x——-x

step series: x—————x

0 01 1

indsl.ts_utils.utility_functions.get_timestamps(series: Series, unit: Literal['ns', 'us', 'ms', 's', 'm', 'h', 'D', 'W'] = 'ms') → Series

Get index of time series.

Get timestamps of the time series as values. The timestamps follow the Unix convention (Number of seconds starting from January 1st, 1970). Precision loss in the order of nanoseconds may happen if unit is not nanoseconds.

Parameters:

  • series – Time-series

  • unit – Timestamp unit Valid values “ns|us|ms|s|m|h|D|W”. Default “ms”

Returns:

time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.iqr_test(x: ndarray, limit: Literal['upper', 'lower'] = 'upper', direction: Literal['greater', 'less'] = 'greater') → ndarray

Z-scores test.

This functions performs a iqr test and returns a binary time series.

Parameters:

  • x – Data values.

  • limit – Cut-off limit.

  • direction – Direction of the test. Options: - “greater”: the function will check if the values are greater than the cut-off limit. - “less”: the function will check if the values are less than the cut-off limit.

Returns:

Binary np.array with the results of the test.

1 values indicate that the test has passed.

Return type:

np.ndarray

indsl.ts_utils.utility_functions.maximum(x1, x2, align_timesteps: bool = False)

Element-wise maximum.

Computes the maximum value of two time series or numbers.

Parameters:

  • x1 – First time series or number

  • x2 – Second time series or number

  • align_timesteps – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.minimum(x1, x2, align_timesteps: bool = False)

Element-wise minimum.

Computes the minimum value of two time series.

Parameters:

  • x1 – First time series or number

  • x2 – Second time series or number

  • align_timesteps – Auto-align Automatically align time stamp of input time series. Default is False.

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.modified_z_scores_test(x: ndarray, cutoff: float = 3.0, direction: Literal['greater', 'less'] = 'greater') → ndarray

Z-scores test.

This functions performs a modified z-scores test given a cut-off value and returns a binary time series.

Parameters:

  • x – Data values.

  • cutoff – Cut-off value.

  • direction – Direction of the test. Options: - “greater”: the function will check if the modified z-scores are greater than the cut-off - “less”: the function will check if the modified z-scores are less than the cut-off

Returns:

Binary np.array with the results of the test.

1 values indicate that the test has passed.

Return type:

np.ndarray

indsl.ts_utils.utility_functions.normality_assumption_test(series: Series | ndarray, max_data_points: int = 5000, min_p_value: float = 0.05, min_W: float = 0.5) → Tuple[float, float] | None

Test for normality assumption.

This function performs a Shapiro-Wilk test to check if the data is normally distributed.

Parameters:

  • series – Time series

  • max_data_points – Maximum number of data points. The test is only performed if the time series contains less data points than this value. Default to 5000.

  • min_p_value – Minimum p value. Probability of the time series not being normally distributed. Default to 0.05.

  • min_W – Minimum W value. W is between 0 and 1, small values lead to a rejection of the normality assumption. Ref: https://www.nrc.gov/docs/ML1714/ML17143A100.pdf Default to 0.5.

Raises:

  • UserValueError – time series has more than the maximum number of datapoints allowed for this test.

  • UserValueError – time series is uniform and not normally distributed

  • UserValueError – time series is not normally distributed.

indsl.ts_utils.utility_functions.remove(series: Series, to_remove: List[float] | None = None, range_from: float | None = None, range_to: float | None = None)

Remove.

Remove specific values or a range of values from a time series.

Parameters:

  • series – Time series

  • to_remove – Values List of values to remove. The values must be seperated by semicolons. Infinity and undefined values can be replaced by using the keywords inf, -inf and nan. If empty, which is the default, all values are kept.

  • range_from – Range start Only values above this parameter will be kept. If empty, which is the default, this range filter is deactivated.

  • range_to – Range end Only values below this parameter will be kept. If empty, which is the default, the range filter is deactivated.

Returns:

time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.replace(series: Series, to_replace: List[float] | None = None, value: float | None = 0.0)

Replace.

Replace values in a time series. The values to replace should be a semicolon-separated list. Undefined and infinity values can be replaced by using nan, inf and -inf (e.g. 1.0, 5, inf, -inf, 20, nan).

Parameters:

  • series – Time series

  • to_replace – Replace List of values to replace. The values must be seperated by semicolons. Infinity and undefined values can be replaced by using the keywords inf, -inf and nan. The default is to replace no values.

  • value – Value used as replacement. Default is 0.0

Returns:

time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.round(x, decimals: int)

Round.

Rounds a time series to a given number of decimals.

Parameters:

  • x – time series

  • decimals – number of decimals

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.set_timestamps(timestamp_series: Series, value_series: Series, unit: Literal['ns', 'us', 'ms', 's', 'm', 'h', 'D', 'W'] = 'ms') → Series

Set index of time series.

Sets the time series values to the Unix timestamps. The timestamps follow the Unix convention (Number of seconds starting from January 1st, 1970). Both input time series must have the same length.

Parameters:

  • timestamp_series – Timestamp time series

  • value_series – Value time series

  • unit – Timestamp unit Valid values “ns|us|ms|s|m|h|D|W”. Default “ms”

Returns:

time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.sign(x)

Sign.

Element-wise indication of the sign of a time series.

Parameters:

x – time series

Returns:

time series

Return type:

pd.Series

indsl.ts_utils.utility_functions.threshold(series: Series, low: float = -inf, high: float = inf)

Threshold.

Indicates if the input series exceeds the lower and higher limits. The output series is 1.0 if the input is between the (inclusive) limits, and 0.0 otherwise.

Parameters:

  • series – Time series

  • low – Lower limit threshold. Default: -infinity

  • high – Upper limit threshold. Default: +infinity

Returns:

Time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.threshold_test(x: ndarray, cutoff: float, direction: Literal['greater', 'less']) → ndarray

Threshold test.

This functions performs a threshold test based on a direction (greater than or less than).

Parameters:

  • x – Data values.

  • cutoff – Cut-off value.

  • direction – Direction of the test. Options: - “greater”: the function will check if the values are greater than the cut-off limit. - “less”: the function will check if the values are less than the cut-off limit.

Returns:

Binary np.array with the results of the test.

1 values indicate that the test has passed.

Return type:

np.ndarray

indsl.ts_utils.utility_functions.time_shift(series: Series, n_units: float = 0, unit: Literal['ns', 'us', 'ms', 's', 'm', 'h', 'D', 'W'] = 'ms') → Series

Shift time series.

Shift time series by a time period

Parameters:

  • series – Time-series

  • n_units – Time periods to shift Number of time periods to shift

  • unit – Time period unit Valid values “ns|us|ms|s|m|h|D|W”. Default “ms”

Returns:

time series

Return type:

pd.Series

Raises:
indsl.ts_utils.utility_functions.union(series1: Series, series2: Series) → Series

Union.

Takes the union of two time series. If a time stamp occurs in both series, the value of the first time series is used.

Parameters:

  • series1 – time series

  • series2 – time series

Returns:

time series

Return type:

pd.Series

Raises:

UserTypeError – series1 or series2 is not a time series

indsl.ts_utils.utility_functions.z_scores_test(x: ndarray, cutoff: float = 3.0, direction: Literal['greater', 'less'] = 'greater') → ndarray

Z-scores test.

This functions performs a z-scores test given a cut-off value and returns a binary time series.

Parameters:

  • x – Data values.

  • cutoff – Cut-off Number of standard deviations from the mean.

  • direction – Direction of the test. Options: - “greater”: the function will check if the z-scores are greater than the cut-off - “less”: the function will check if the z-scores are less than the cut-off

Returns:

Binary np.array with the results of the test.

1 values indicate that the test has passed.

Return type:

np.ndarray