Resources

Renesas IoT Sandbox Documentation

Analytics Library

This library includes functions that provide access to historical events of the current user. The current user is the API Basic User to which belongs the event that triggered the workflow.


Import


To use this library and its functions, you must use the import line at the beginning of your Base Python code.

import Analytics


Functions


Analytics.events

Usage: Analytics.events(stream_name, filters=None, date_range=None, limit=None, sort=None, user=None)

Returns the events in the specified stream, subject to filters, date_range, limit, and sort.

  • Credit cost: 1
  • Parameters:
    • stream_name: str name of stream from which to retrieve data
    • filters: Filter
    • date_range: DateRange
    • limit: int maximum number of values to return
    • sort: list|tuple pair of strings defining tag to sort by and sort order ('ASC' or 'DESC')
      • Example 1: ['observed_at', 'DESC']
      • Example 2: ('age', 'ASC')
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of dict of the form:
  • Example:

    • Sample Code:

      import Analytics
      
      events = Analytics.events('raw', filters=None, date_range=None, limit=1, sort=['observed_at', 'ASC'], user=None)
    • Return Value:
      
      [
      {
          "observed_at": "2015-04-11T21:36:53.832111+00:00",
          "stream_id": 4041905582898064089,
          "event_data": {
              "action": "Help Request",
              "sensor_id": "Kiosk_3",
              "type": "Kiosk"
          }
      },
      …
      ]

Note: here action, sensor_id and type are example event_data key names



Analytics.last_values

Usage: Analytics.last_values(tag_names = None, user=None)

Returns the last value and observed_at time for each of the tags specified in tag_names. If tag_names is not specified, then it will return for all tags for this user.

  • Credit cost: 1
  • Parameters:
    • tag_name: List, optional parameter containing the tags to get the last value of. Tags that do not exist will be ignored. If this is not specified, all tags are returned.
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of dictionaries with the observed_at time and the tag with its value.
  • Example:

    • Sample Code:

      import Analytics
      
      last_values = Analytics.last_values(tag_names = ['raw.test','raw.test2'], user=None)
    • Return Value:
      [{'observed_at': <time>, 'raw.test': <value>}, {'observed_at': <time>, 'raw.test2': <value>}]



Analytics.last_n_values

Usage: Analytics.last_n_values(tag_name, n, filters=None, date_range=None, user=None)

Returns up to the last limit values of tag tag_name in stream stream_name.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • n: int number of values to return
    • filters: Filter if provided, will apply to data before finding last n values
    • date_range: DateRange if provided, will only return the last n values between the dates
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of objects, sorted by observed_at field (most recent first) of the form:
  • Example:

    • Sample Code:

      import Analytics
      
      last_n_values = Analytics.last_n_values('raw.my_tag', 4, user='test_user')
    • Return Value:
      [
         {
              "raw.my_tag": 20
          }, 
          {
              "raw.my_tag": 40
          }, 
          {
              "raw.my_tag": 40
          }, 
          {
              "raw.my_tag": 60
          }
      ]

Note: In this case, raw.my_tag is the tag_name parameter

Bucketed functions

The bucketed functions (Analytics.bin_by...) produce statistics where date is grouped into "buckets". Buckets are automatically selected depending on the DateRange size:

* `DateRange` of less than a day: minute buckets
* `DateRange` of a day to 2 months: hour buckets
* `DateRange` of 2 months to 1 year: day buckets
* `DateRange` of 1 year to 10 year: week buckets
* Otherwise: month buckets



Analytics.bin_by_time

Usage: Analytics.bin_by_time(tag_name, date_range, filters=None)

Returns statistics for the current user for tag_name data filtered by filters. Tag name data is from the period specified by date_range and is bucketed based on the date_range window.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
    • filters: Filter
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_time = Analytics.bin_by_time('raw.test', week)
    • Return Value:
      [
          {
              "observed_at": "2015-04-11T21:36:53.832111+00:00",
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          …
      ]



Analytics.bin_by_value

Usage: Analytics.bin_by_value(tag_name, date_range)

Returns the distribution of all distinct values of a particular tag for all events for the current user, that were observed in the specified time period.

For each distinct value, the number of occurrences, its percentage of the whole, and its rank are returned. Note that ranks can occur multiple times in the case of ties.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_value = Analytics.bin_by_value('raw.test', week)
    • Example:
      [
          {
              "count": 30,
              "percent": 90.9090909090909,
              "rank": 1,
              "value": 5
          },
          ...
      ]



Analytics.bin_by_time_and_value

Usage: Analytics.bin_by_time_and_value(tag_name, date_range, group_tag_name, period, filters=None)

Returns statistics for the current user for tag_name data filtered by filters, over the period specified by date_range, bucketed into a number of buckets based on the date_range window size. Each bucket has statistics for data in that bucket grouped by group_tag_name.

  • Credit cost: 1
  • Parameters:
    • tag_name: str; tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
    • group_tag_name: str; tag name of tag to group by
    • period: Period; bucketing window (i.e. "millisecond", "second", "minute", "hour", "day",...)
    • filters: Filter;
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_time_and_value = Analytics.bin_by_time_and_value('raw.email', week, 'raw.test', 'hour', filters=None)
    • Return Value:
      [
          {
              "observed_at": "2015-04-11T21:35:53.832111+00:00",
              "group": 0,
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          {
              "observed_at": "2015-04-11T21:36:53.832111+00:00",
              "group": 1,
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          …
      ]



Sample Code

import Analytics
import Filter
import DateRange

#x returns a list of the last 10 events under the 'raw' stream
x = Analytics.events(stream_name='raw', limit=10)

#y returns a list of the last 10 events of this hour, from the 'raw.myoutkey' tag, with a value equal to the string 'hello world', in ascending order.
y = Analytics.events('raw', Filter.string_tag('raw.myoutkey').equal_to('hello world'), DateRange.this_hour(), 10, ['observed_at', 'ASC'])

Getting Started
User Roles & Permissions
Streams, Tags, & Data Types
Dashboard Widgets
API
Workflow Studio
Workflow Libraries
Metering
Special Characters
Third Party Integration
Mobile
API Explorer

Analytics Library

This library includes functions that provide access to historical events of the current user. The current user is the API Basic User to which belongs the event that triggered the workflow.


Import


To use this library and its functions, you must use the import line at the beginning of your Base Python code.

import Analytics


Functions


Analytics.events

Usage: Analytics.events(stream_name, filters=None, date_range=None, limit=None, sort=None, user=None)

Returns the events in the specified stream, subject to filters, date_range, limit, and sort.

  • Credit cost: 1
  • Parameters:
    • stream_name: str name of stream from which to retrieve data
    • filters: Filter
    • date_range: DateRange
    • limit: int maximum number of values to return
    • sort: list|tuple pair of strings defining tag to sort by and sort order ('ASC' or 'DESC')
      • Example 1: ['observed_at', 'DESC']
      • Example 2: ('age', 'ASC')
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of dict of the form:
  • Example:

    • Sample Code:

      import Analytics
      
      events = Analytics.events('raw', filters=None, date_range=None, limit=1, sort=['observed_at', 'ASC'], user=None)
    • Return Value:
      
      [
      {
          "observed_at": "2015-04-11T21:36:53.832111+00:00",
          "stream_id": 4041905582898064089,
          "event_data": {
              "action": "Help Request",
              "sensor_id": "Kiosk_3",
              "type": "Kiosk"
          }
      },
      …
      ]

Note: here action, sensor_id and type are example event_data key names



Analytics.last_values

Usage: Analytics.last_values(tag_names = None, user=None)

Returns the last value and observed_at time for each of the tags specified in tag_names. If tag_names is not specified, then it will return for all tags for this user.

  • Credit cost: 1
  • Parameters:
    • tag_name: List, optional parameter containing the tags to get the last value of. Tags that do not exist will be ignored. If this is not specified, all tags are returned.
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of dictionaries with the observed_at time and the tag with its value.
  • Example:

    • Sample Code:

      import Analytics
      
      last_values = Analytics.last_values(tag_names = ['raw.test','raw.test2'], user=None)
    • Return Value:
      [{'observed_at': <time>, 'raw.test': <value>}, {'observed_at': <time>, 'raw.test2': <value>}]



Analytics.last_n_values

Usage: Analytics.last_n_values(tag_name, n, filters=None, date_range=None, user=None)

Returns up to the last limit values of tag tag_name in stream stream_name.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • n: int number of values to return
    • filters: Filter if provided, will apply to data before finding last n values
    • date_range: DateRange if provided, will only return the last n values between the dates
    • user: str name of user from which to retrieve data. If not specified, default is the user that triggered the function.
  • Returns: list List of objects, sorted by observed_at field (most recent first) of the form:
  • Example:

    • Sample Code:

      import Analytics
      
      last_n_values = Analytics.last_n_values('raw.my_tag', 4, user='test_user')
    • Return Value:
      [
         {
              "raw.my_tag": 20
          }, 
          {
              "raw.my_tag": 40
          }, 
          {
              "raw.my_tag": 40
          }, 
          {
              "raw.my_tag": 60
          }
      ]

Note: In this case, raw.my_tag is the tag_name parameter

Bucketed functions

The bucketed functions (Analytics.bin_by...) produce statistics where date is grouped into "buckets". Buckets are automatically selected depending on the DateRange size:

* `DateRange` of less than a day: minute buckets
* `DateRange` of a day to 2 months: hour buckets
* `DateRange` of 2 months to 1 year: day buckets
* `DateRange` of 1 year to 10 year: week buckets
* Otherwise: month buckets



Analytics.bin_by_time

Usage: Analytics.bin_by_time(tag_name, date_range, filters=None)

Returns statistics for the current user for tag_name data filtered by filters. Tag name data is from the period specified by date_range and is bucketed based on the date_range window.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
    • filters: Filter
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_time = Analytics.bin_by_time('raw.test', week)
    • Return Value:
      [
          {
              "observed_at": "2015-04-11T21:36:53.832111+00:00",
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          …
      ]



Analytics.bin_by_value

Usage: Analytics.bin_by_value(tag_name, date_range)

Returns the distribution of all distinct values of a particular tag for all events for the current user, that were observed in the specified time period.

For each distinct value, the number of occurrences, its percentage of the whole, and its rank are returned. Note that ranks can occur multiple times in the case of ties.

  • Credit cost: 1
  • Parameters:
    • tag_name: str tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_value = Analytics.bin_by_value('raw.test', week)
    • Example:
      [
          {
              "count": 30,
              "percent": 90.9090909090909,
              "rank": 1,
              "value": 5
          },
          ...
      ]



Analytics.bin_by_time_and_value

Usage: Analytics.bin_by_time_and_value(tag_name, date_range, group_tag_name, period, filters=None)

Returns statistics for the current user for tag_name data filtered by filters, over the period specified by date_range, bucketed into a number of buckets based on the date_range window size. Each bucket has statistics for data in that bucket grouped by group_tag_name.

  • Credit cost: 1
  • Parameters:
    • tag_name: str; tag name, including stream name (eg. "raw.score")
    • date_range: DateRange
    • group_tag_name: str; tag name of tag to group by
    • period: Period; bucketing window (i.e. "millisecond", "second", "minute", "hour", "day",...)
    • filters: Filter;
  • Returns: list List of dicts of the form:
  • Example:

    • Sample Code:

      import Analytics
      import DateRange
      
      week = DateRange.this_week()
      bin_by_time_and_value = Analytics.bin_by_time_and_value('raw.email', week, 'raw.test', 'hour', filters=None)
    • Return Value:
      [
          {
              "observed_at": "2015-04-11T21:35:53.832111+00:00",
              "group": 0,
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          {
              "observed_at": "2015-04-11T21:36:53.832111+00:00",
              "group": 1,
              "avg": 123,
              "min": 123,
              "max": 123,
              "count": 123
          },
          …
      ]



Sample Code

import Analytics
import Filter
import DateRange

#x returns a list of the last 10 events under the 'raw' stream
x = Analytics.events(stream_name='raw', limit=10)

#y returns a list of the last 10 events of this hour, from the 'raw.myoutkey' tag, with a value equal to the string 'hello world', in ascending order.
y = Analytics.events('raw', Filter.string_tag('raw.myoutkey').equal_to('hello world'), DateRange.this_hour(), 10, ['observed_at', 'ASC'])