Time series

In Cognite Data Fusion, a time series is the resource type for indexing a series of data points in time order. Examples of a time series are the temperature of a water pump asset, the monthly precipitation in a location and the daily average number of manufacturing defects.

Watch this video for a quick introduction to time series:

In this article:

About time series

An asset can have several time series connected to it. A water pump asset can for example have time series that measure the pump temperature, the pressure within the pump, rpm, flow volume, power consumption, and more.

Time series can be analyzed and visualized to draw inferences from the data, for example to identify trends, seasonal movements and random fluctuations. Other common uses of time series analysis include to forecast future values, for example to schedule maintenance, and to control the series by adjusting parameters, for example to optimize the performance of equipment.

A data point is a piece of information associated with a specific time, stored as a numerical or string value. Data points are identified by their timestamps, defined in milliseconds in Unix Epoch time. We do not support fractional milliseconds, and do not count leap seconds.

Use the isString flag on the time series object to decide whether to store data points in a time series as numerical values or as string values.

  • Numerical data points can be aggregated to reduce the amount of data transferred in query responses and improve performance. You can specify one or more aggregates (for example average, minimum and maximum) and also the time granularity for the aggregates (for example 1h for one hour). See Retrieve data points from a single time series by name for valid aggregate functions and granularities.

    Aggregates are aligned to the start time modulo of the granularity unit. For example, if you ask for daily average temperatures since Monday afternoon last week, the first aggregated data point will contain averages for Monday, the second for Tuesday, etc.

    Cognite Data Fusion determines aggregate alignment without considering data point timestamps. This allows Cognite Data Fusion to pre-calculate and quickly return aggregates, for example the daily average temperatures for a year. It also means that you can get different results if you aggregate over 60 minutes than if you aggregate over 1 hour because the two queries are aligned differently.

  • String data points can store arbitrary information like states (for example open or closed) or more complex information in JSON format. String data points can not be aggregated by Cognite Data Fusion.

Cognite Data Fusion stores discrete data points, but the underlying process measured by the data points can vary continuously. To interpolate between data points, use the isStep flag on the time series object to assume that each value stays the same until the next measurement (isStep), or that it linearly changes between the two measurements (not isStep).

TIP

See the time series API documentation for more information about how to work with time series.

Get the datapoints from a time series

You can get datapoints from a time series by using the name or the id of the time series.

  1. To get datapoints from a time series by using the name, in this case outside_temperature, enter:

    GET /api/0.5/projects/<project>/timeseries/data/outside-temperature
    Host: api.cognitedata.com
    api-key: <api-key>
    
    1
    2
    3

    The response will look similar to this:

    {
      "data": {
        "items": [
          {
            "name": "outside_temperature",
            "datapoints": [
              {
                "timestamp": 1533727936845,
                "value": 21.6
              },
              {
                "timestamp": 1533727950289,
                "value": 21.8
              },
              ...{
                "timestamp": 1533739764654,
                "value": 28.9
              },
              {
                "timestamp": 1533739777456,
                "value": 29.3
              }
            ]
          }
        ]
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27

Get aggregate values between two points in time

To visualize or analyse a longer time period, you can extract the aggregate values between two points in time. See Retrieve data points from a single time series by name for valid aggregate functions and granularities.

  1. For example, to return the hourly average aggregate with a granularity of 1 hour, for the last 5 hours, for the outside_temperature time series, enter:

    GET /api/0.5/projects/<project>/timeseries/data/outside_temperature?aggregates=avg&granularity=1h&start=5h-ago&end=now
    Host: api.cognitedata.com
    api-key: <api-key>
    
    1
    2
    3

    The response will look similar to this:

    {
      "data": {
        "items": [
          {
            "name": "outside_temperature",
            "datapoints": [
              {
                "timestamp": 1542452400000,
                "average": 15.133800861111105
              },
              {
                "timestamp": 1542456000000,
                "average": 14.286872172746543
              },
              ...{
                "timestamp": 1542466800000,
                "average": 11.290880027777767
              },
              {
                "timestamp": 1542470400000,
                "average": 11.047296781864254
              }
            ]
          }
        ]
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27

Get time series data in a dataframe

To analyze data, or to build a machine learning model, you can return the required data in a dataframe, where the time stamps are aligned for all time series.

  1. For example, to return the hourly average aggregate with a granularity of 1 hour, for the last 5 hours, for the outside_temperature and inside_temperature time series, enter:

     POST /api/0.5/projects/<project>/timeseries/dataframe
     Host: api.cognitedata.com
     api-key: <api-key>
    
    1
    2
    3

    To get the averages:

    {
      "start": "5h-ago",
      "end": "now",
      "aggregates": ["avg"],
      "granularity": "1h",
      "items": [
        {
          "name": "inside_temperature"
        },
        {
          "name": "outside_temperature"
        }
      ]
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

The CSV response looks similar to this:

timestamp inside_temperature outside_temperature
1542452400000 15.133800861111105 -0.4
1542456000000 14.286872172746543 -0.3
1542459600000 13.704991396697892 -0.3
1542463200000 12.409083402777783 -0.3
1542466800000 11.290880027777767 -0.25
1542470400000 11.004871248409353 -0.3

Cognite Data Fusion returns empty cells for any missing data for a period in a time series.

You can also ask for multiple aggregates, for example count, variance, min or max, to be included in the same data frame. See Retrieve data points from a single time series by name for valid aggregate functions and granularities.

Last Updated: 4/12/2019, 10:53:12 AM