Calculated Attributes

Overview

A Calculated Attribute (CA) is a read-only value about a single user, providing granular insight into user behavior. These attributes are defined in mParticle and are computed automatically over time by using the raw data stream of events and user information.

Calculated Attributes:

• Enable personalized campaigns and targeting with an always-on understanding of the customer behavior
• Help Marketers, Product Managers and Data Scientists better understand customer behavior and interactions with their brand
• Standardize the calculated values across the entire marketing and analytics stack, across platforms and tools

Structure

Calculated attributes can be defined to track almost anything on an individual user. A calculated attribute is composed of the following elements:

• Name: a descriptive label for the calculated attribute. Once activated, the name may not be changed.
• Description: an optional freeform field to describe the attribute.
• Calculation definition: This defines the logic for computing the attribute: the calculation type, criteria and the date range.
• Status: Calculated attributes are created in the draft status indicating that they are no being calculated. Once activated, calculated attributes are in the active status to indicate that they are being calculated and can be used across the mParticle platform and downstream.

Scope

Calculated attributes are defined and calculated in the scope of a single workspace, which means they use data available within that workspace only. You may create calculated attributes with the same name in multiple workspaces.

Initialization

Once a calculated attribute is activated, the initialization of existing data can take anywhere from 24 hours to several days, depending on the date range selected and the amount of data to be processed.

Calculation Speed

Calculations are either instant or delayed. Instant calculations are evaluated immediately and updated values are included in the same outgoing event batch with no delay.

Delayed calculations are evaluated with a small delay (usually a few minutes) and updated values are included in the next outgoing event batch and to outputs connected to a special feed input named “Calculated Attributes” (more about this feed).

Calculations

We currently support 13 calculations organized into four groups:

Count

Calculate the count of times an event has occurred. For example:

• Number of Logins in the last 30 days
• Number of Cart views in the last 7 days
• Total orders completed over lifetime.
• Count of videos watched over time

Aggregation

Calculate statistics about event attributes: sum, minimum, maximum, average, most frequent and unique values count.

For example:

• Sum of purchase revenue made over all time
• Maximum ride distance in last 60 days.
• Average booking price.
• Average order revenue in last 30 days.
• Sum of minutes watched for movie play events.
• Most frequent brand purchased
• Count of unique show genres watched

In the event of a tie, most frequent will pick the last value sorted alphabetically.

Occurrence

Calculate the timestamp or an event value of the first or last observation of a matching event: first value, first timestamp, last value and last timestamp.

For example:

• Last product category viewed
• First purchase date
• Last session start timestamp
• Last order amount
• Last product category purchased

List

Calculate the unique list of values for a specific event attribute:

For example:

• Unique game titles played
• Unique product categories viewed in the last 30 days

Calculation Details

The following table defines the details of all supported calculations. All timestamp values are in ISO 8601 format in the UTC timezone. Several calculations produce results with types that depend on the type of the event attribute selected, for example First Value will return a string if the event attribute selected is a string.

Group	Calculation Type	Format	Example	Speed
Count	Count	Numeric	123	Instant
Aggregation	Sum	Numeric	123.123	Instant
Aggregation	Minimum	Numeric	123.123	Instant
Aggregation	Maximum	Numeric	123.123	Instant
Aggregation	Average	Numeric	123.123	Delayed
Aggregation	Most frequent	Dynamic	romance	Delayed
Aggregation	Unique Values Count	Numeric	34	Delayed
Occurrence	First value	Dynamic	comedy	Delayed (until observed)
Occurrence	Last value	Dynamic	action	Instant
Occurrence	First timestamp	Timestamp	2020-01-01T22:14:47.1051728Z	Delayed (until observed)
Occurrence	Last timestamp	Timestamp	2020-01-10T22:14:47.1051728Z	Instant
List	Unique List	Comma separated list of dynamic values; maximum of 100.	"Item 1","Item 2","Item 3"	Instant

All calculation speeds here are after the values have been initialized. Setting the date range to ‘within the last’ will cause all calculations to update with delayed speed.

Date Range

Calculated attributes can be setup to calculate over defined date range. This allows you to limit calculations to a more relevant business window such as “unique list of product purchased in the last 30 days” or “total bookings made over the last year”.

The following date ranges are supported:

• Within the Last: limit calculations to the window of X days or weeks ago to now. For example, most frequent product categories viewed over the last 30 days.
• Since: limit calculations to the window of: a set start date to now. For example, number of orders made since Jan 1st of 2020.
• All Time: Do not limit calculations by date range; use all available data.

Type Conversions

Some calculated attributes, like sum, require numeric event attributes to function. If you select an attribute that is not detected as the correct type, the platform will warn you about using those fields in the calculated attribute definition. You can still use the calculated attribute despite the warning and it will attempt to convert the string values into numerics. For example, if you pass the attribute amount in as a numeric string like "34.32", a sum calculation will still work correctly: the string "34.32" will be converted to the decimal value 34.32.

Seeding

Seeding allows you to pass in historic values for calculated attributes that mParticle will build upon as new data arrives, without passing in all the raw events. This allows you to seamlessly transition from your own calculations to mParticle’s. You can seed calculated attributes in both draft (recommended) and active states; the calculated attribute must exist before seeding it.

Seeding requires two pieces of information:

• the seed values: values required to calculate the attribute
• the seed cut-off date: any data prior to this date is processed by your team into seed values, and mParticle only uses data on or after this date in CA calculation and combines the result with the seed values. This ensure accurate transition into mParticle platform and avoid duplications of data in calculating a CA.

Workflow

1. CA must be created in mParticle platform prior to sending any seed. The CA can be in either draft or active state. It’s recommended that CA be activated after seeds for all users have been sent to mParticle. The reason is that once a CA is activated, mParticle will start calculating it, not knowing if there is a seed or not, and thus some users may show inaccurate CA values until seeds have been received.
2. Send seeds via the Calculated Attributes Seeding API. Note that CA creation or update takes up to 5 min to be included in our cache, and thus if you send seeds immediately after CA creation or update, you may get NOT FOUND error.
3. Once mParticle has received seeds, we will combine them with CA calculation results based on live data received after the cutoff date.

Seeding Usage Notes

1. After seeds have been sent to mParticle, any of the following changes will make the previously received seeds invalid and subsequently deleted from mParticle.

   • CA name
   • CA calculation type, e.g., from sum to count.
   • Seeding cutoff date
   • Deleting the CA
2. If you need to update the seeds after already sending them to mParticle, simply send the updated seeds to mParticle again. We will overwrite previously received seeds.

Using Calculated Attributes

Forwarding via Event Batches

mParticle will enrich incoming batches with active calculated attributes for that user. Just like regular user attributes, you can restrict which outputs receive them, using data filters.

Forwarding via Feed

There is a special feed named ‘Calculated Attributes’ that allows you to send calculated attributes downstream whenever they change, without an event from the user; this feed is especially useful for keeping calculated attributes with delayed calculations synchronized throughout your stack and for sending calculated attributes downstream alongside kit integrations. This input will appear once you have activated a calculated attribute. When a new connection is made to this input, CA values for users who have not been seen since their delayed CAs were calculated will be sent. This feed sends an update when calculated attributes change (both instant & delayed), it does not send user attributes.

Control which downstream system receives these updates by intentionally connecting specific platforms to receive the calculated attribute updates. You can also filter out calculated attributes you do not wish to forward using the platform filters page.

Live Stream, User Activity View & Profile API

Calculated attributes can be viewed alongside other user attributes in the Live Stream, User Activity view and are accessible via the Profile API.

Audiences

Calculated attributes can be used in the Audience builder by selecting User > Calculated Attributes. They will show up as ‘string’ types at first and will automatically switch to the correct type as they are computed across many users. You can build audience criteria with a calculated attribute that is calculating and when the attribute values are completed for each user, their audience membership will be updated.

How to: Create a Calculated Attribute

To create a Calculated Attribute:

1. Within the Activity section of your dashboard’s side navigation panel, select Calculated Attributes, and then select + Calculated Attribute.
2. Enter the Calculated Attribute Name and an optional Description.
3. Select the Calculation Type for your calculations. Please see the Calculation Types section for more details
4. When applicable, select the operation.

5. Click on the data criteria section to define the data used to run the calculation.

   1. From the dropdown, select the event to calculate on.
   2. Certain calculations are based on an event attribute for the selected event. When applicable, select the attribute.
   3. Some operations requires a specific data type to run calculation. When selected attribute is not compatible with the operation a warning message will be displayed. If you want to force a specific event attribute to be used you can continue past the warning and activate the calculated attribute. For example, if you pass in purchase amount as a string you can force it to be a number for use in a sum calculation.
   4. Save your changes.

6. To adjust date range for your calculation, click on Date Range criteria.

   1. Select Since from dropdown for calculations that require to be run from a specific start date
   2. Select Within the last from dropdown for calculations that require to be run over a specific rolling time period. Enter a number and specify a time unit of Days or Weeks.
   3. Save your changes.

How to: Activate a Calculated Attribute

A calculated attribute must first be activated in order for mParticle to start calculating its values across your users.

To activate a Calculated Attribute:

1. Select Activate after defining the Calculated Attribute.
2. Once activated, Calculated Attribute is immediately available across the mParticle platform. This allows you to create audiences, setup connections, and data filters as an example.

When activated, mParticle will start to compute and initialize the initial value for the calculated attribute. This uses both the historical data in mParticle and real-time incoming data.

Depending on the date range, volume of data in your workspace, and complexity of definition, calculations will have varying SLAs before it first becomes available across your customer profiles. Whilst calculating, the UI will display its calculation progress.