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_namefilters=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_namestr name of stream from which to retrieve data
    • filtersFilter
    • date_rangeDateRange
    • limitint maximum number of values to return
    • sortlist|tuple pair of strings defining one tag to sort by and sort order ('ASC' or 'DESC')
      • Example 1: ['observed_at', 'DESC']
      • Example 2: ('age', 'ASC')
    • userstr 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 actionsensor_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_nameList, 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.
    • userstr 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_namenfilters=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_namestr tag name, including stream name (eg. "raw.score")
    • nint number of values to return
    • filtersFilter if provided, will apply to data before finding last n values
    • date_rangeDateRange if provided, will only return the last n values between the dates
    • userstr 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_namedate_rangefilters=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_namestr tag name, including stream name (eg. "raw.score")
    • date_rangeDateRange
    • filtersFilter
  • 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_namedate_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_namestr tag name, including stream name (eg. "raw.score")
    • date_rangeDateRange
  • 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_namedate_rangegroup_tag_nameperiodfilters=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_namestr; tag name, including stream name (eg. "raw.score")
    • date_rangeDateRange
    • group_tag_namestr; tag name of tag to group by
    • periodPeriod; bucketing window (i.e. "millisecond", "second", "minute", "hour", "day",...)
    • filtersFilter;
  • 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'])
Have more questions? Submit a request

0 Comments

Article is closed for comments.