Time series in Functions

Functions supports operations on time series properties. In this page, we cover how to set up and use time series properties in functions.

Initial set up

To use time series in Functions, you will need to have already stored time series in the Ontology. You can follow the steps outlined here to get started.

Once your time series are stored in the ontology, we need to create a code repository for our time series Functions. In this repository, we start by importing Ontology types so we can reference the time series stored in these Ontology types.

Now you're ready to work with time series in Functions.

Working with time series in Functions

To access time series in Functions, start by creating an object-backed Function in your code repository. These functions can directly access the time series properties in your Ontology. Once you have written a Function, there are two ways to run your new function. You can either test your Function in live preview or publish your Function and start using it in other applications throughout the platform.

Here are some quick examples of common operations to get you started.

Getting the first or last point

When working with time series properties, it is useful to examine the first or last point. Since Functions do not have a built-in type for time series points, you can instead return the value or the timestamp. Take for example, the following function to read the latest temperature on a machine:

    @Function()
    public async getLatestTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const latest = await machine.temperatureId?.getLastPointV2();
        return latest?.value;
    }

You can similarly get the first temperature reading with the following function:

    @Function()
    public async getEarliestTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const earliest = await machine.temperatureId?.getFirstPointV2();
        return earliest?.value;
    }

Aggregating over a series

One useful aggregation is to compute the average over a range of points. Consider the following Function that gets the average temperature of an example machine.

    @Function()
    public async getAverageTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const aggregation = await machine.temperatureId?.aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return aggregation?.mean!;
    }

Taking the derivative

Building on the example above, you can also retrieve the average change in temperature on the same machine by using the following compute function:

    @Function()
    public async getAverageTemperature(machine: MachineRoot): Promise<Double | undefined> {
        const aggregation = await machine.temperatureId?.derivative()
            .aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return aggregation?.mean;
    }

Specifying a time range

You can apply other transforms in addition to derivatives to a time series. The following is an example of how you can apply timestamp parameters as a range on a time series.

    @Function()
    public async getAverageTemperatureOverRange(
        machine: MachineRoot,
        start: Timestamp,
        end: Timestamp): Promise<Double | undefined>
    {
        const latest = await machine.temperatureId?.timeRange({min: start, max: end})
            .aggregate()
            .overEntireRange()
            .mean()
            .compute();
        return latest?.mean;
    }