GlobalAnalytics Library

These functions provide access to historical events across basic users.

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

  •  Less than a day: minute buckets
  • 1 day to 2 months: hour buckets
  • 2 months to 1 year: day buckets
  • 1 year to 10 years: week buckets
  • 10+ years: month buckets

 

Import

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

import GlobalAnalytics

 

Functions

Get events from stream 

GlobalAnalytics.events_by_stream(stream_namefilters=None, date_range=None, limit=1000, sort=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 to limit events by tag (Filter Library)
  • date_rangeDateRangeto query events between specific dates (DateRange Library)
  • limitint maximum number of values to return
  • sortlist|tuple pair of strings defining tag to sort by and sort order 
    • Example 1: ['observed_at', 'DESC']
    • Example 2: ('age', 'ASC')

Return Value 

list dictionaries containing each event's user, observed_at time, stream_idevent_data, and event_id.

Example

  • Sample Code:

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

Exceptions

  • InsightsException
    • Any insights error such as non-existent tag or stream, or issues communicating with insights

Bin by time

GlobalAnalytics.bin_by_time(tag_namedate_rangepopulation=None)

Returns statistics for the population defined by population, for tag_name data. 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 to limit statistics by date (DateRange Library)
  • populationPopulationFilter to limit statistics by population (PopulationFilter Library)

Return Value 

list list of dicts containing the observed_at timestamp for the bucket as well as the average, min, max, and count for that bucket.

Example

  • Sample Code:

    import GlobalAnalytics
    import DateRange
    
    week = DateRange.this_week()
    bin_by_time = GlobalAnalytics.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
        },
        …
    ]

Exceptions

  • InsightsException
    • Any insights error such as non-existent tag or stream, or issues communicating with insights


Bin by value

GlobalAnalytics.bin_by_value(tag_namepopulation=None)

Returns the distribution of all distinct values of a particular tag for all events for all users in the defined population.

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")
  • populationPopulationFilter to limit statistics by population (PopulationFilter Library)

Return Value 

list list of dicts, one for each distinct value, containing the number of occurrences, its percentage of the whole, and its rank

Example

  • Sample Code:

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

Exceptions

  • InsightsException
    • Any insights error such as non-existent tag or stream, or issues communicating with insights


List users

GlobalAnalytics.list_users(population=None)

Returns a list of users in the population defined by a population filter.

Credit cost: 1

Parameters

Return Value 

list list of dicts including each user's login_id and user ID

Example

  • Sample Code:

    import GlobalAnalytics
    
    all_users = GlobalAnalytics.bin_by_value()
  • Return Value:
    [{u'login_id': u'user1', u'user': 352769716122759168L}, {u'login_id': u'user2', u'user': 352771148062351360L}]

Exceptions

  • InsightsException
    • Issues communicating with insights

Check if basic user exists

GlobalAnalytics.check_user_exists(login_id)

Returns True if the API Basic User already exists, False otherwise.

Credit cost: 1

Parameters

  • login_idstr username of the user that is being checked

Return Value 

bool

Example

  • Sample Code:

    import GlobalAnalytics
    
    exists = GlobalAnalytics.check_user_exists('user1')
  • Return Value:
    True

Exceptions

  • InsightsException
    • Issues communicating with insights