Analysis Workflows And Calculated Metrics

Get all functions

Returns a full list of calculated metric functions that the user can access. See the functions documentation for more information on available functions.

all_functions <- get_cm_functions(company_id = company_id)

knitr::kable(head(all_functions[1:6]))

Create a calculated metric

The process of creating a calculated metric has been designed in a modular way to enable the systematic approach to building and maintaining complex calculated metrics in the most efficient way. The goal is to enhance analysis and data science workflows. The essential elements of a calculated metric are: function, formula, build. The following code chunks will illustrate the basics of interacting with each element.

?cm_function

cm_func <- cm_function(
  func = "col-sum",
  metric = "visits",
  seg_filter = NULL,
  rsid = rsid,
  company_id = company_id
)

jsonlite::toJSON(cm_func, pretty = T, auto_unbox = T)

?cm_formula

cm_form <- cm_formula(
  operator = 'divide',
  metrics = list(cm_func, "singlepagevisits"),
  seg_filters = NA, #add segment filters for each metric if needed
  rsid = rsid,
  company_id = company_id
)

jsonlite::toJSON(cm_form, pretty = T, auto_unbox = T)

?cm_build

cm_obj <- cm_build(
  name = 'Test Calculated Metric',
  description = 'Test cm description',
  formula = cm_form,
  seg_filter = NULL,
  polarity = "positive",
  precision = 0,
  type = "decimal",
  create_cm = FALSE, #should this be created in the UI
  debug = FALSE,
  rsid = rsid,
  company_id = company_id
)

cm_obj

Validate a calculated metric object

Because report suites can have different configurations, dimensions, or metrics, a calculated metric that is valid in one report suite may not be valid in another. To determine which calculated metric to use in different report suites, and why it may or may not be available, you can use the cm_validate. This endpoint allows you to POST a definition along with a target report suite id. The validate endpoint responds with compatibility information on the calculated metric.

?cm_val

cm <- cm_val(cm_obj)

cm

[1] “The calculated metric definition IS VALID”

Once yo determine make we can create the new calculated metric in the UI by setting the argument create_cm = TRUE.

#create the calculated metric in the UI
cm_obj <- cm_build(
  name = 'Test Calculated Metric',
  description = 'Test cm description',
  formula = cm_form,
  seg_filter = NULL, #include an overall segment filter
  polarity = "positive",
  precision = 0,
  type = "decimal",
  create_cm = TRUE, #should this be created in the UI
  debug = FALSE,
  rsid = rsid,
  company_id = company_id
)

knitr::kable(cm_obj)

{“rsid”:“igeo1xxpnwcidadobepm”,“id”:“cm300010142_6537f60dde0e706af6156fb1”,“name”:“Test Calculated Metric”,“description”:“Test cm description”,“isDeleted”:false,“migratedIds”:[],“internal”:false,“owner”:{“id”:200654087},“hidden”:false,“componentType”:“calculatedMetric”,“polarity”:“positive”,“precision”:0,“type”:“decimal”,“definition”:{“formula”:{“func”:“divide”,“col1”:{“func”:“col-sum”,“description”:“Column Sum”,“col”:{“func”:“metric”,“name”:“metrics/visits”,“description”:“Visits”}},“col2”:{“func”:“metric”,“name”:“metrics/singlepagevisits”,“description”:“Single Page Visits”}},“func”:“calc-metric”,“version”:[1,0,0]},“compatibility”:{“identityMetrics”:[{“identity”:“metrics/visits”},{“identity”:“metrics/singlepagevisits”}],“functions”:[“col-sum”,“divide”],“validator_version”:“1.0.0”,“supported_products”:[“oberon”],“supported_schema”:[“schema_oberon”,“schema_frag”]},“legacyId”:““,”categories”:[“Calculated Metrics”],“modified”:“2023-10-24T16:51:25Z”}

Adding a segment filter

On every level of a calculated metric, function, formula, and object, you can add an additional level of control by inserting a segment filter.

# use the new segment id to create a segment
cm_obj_seg_filter <- cm_build(
  name = 'Test Segment Filtered Calculated Metric',
  description = 'Test cm description that includes a segment id',
  formula = cm_form,
  seg_filter = segid, #adding the segment here
  create_cm = FALSE,
  rsid = rsid,
  company_id = company_id
)

cm_val(cm_obj_seg_filter)

[1] “The calculated metric definition IS VALID”

Now that we know it is a valid segment, let’s create it and pull the data along with the previous segment to see the difference in the data.

# use the new segment id to create a segment
cm_obj_seg_filter <- cm_build(
  name = 'Test Segment Filtered Calculated Metric',
  description = 'Test cm description that includes a segment id',
  formula = cm_form,
  seg_filter = segid, #adding the segment here
  create_cm = TRUE,
  rsid = rsid,
  company_id = company_id
)

cm_seg_filter <- jsonlite::fromJSON(cm_obj_seg_filter)$id

cm_no_seg_filter <- jsonlite::fromJSON(cm_obj)$id

df_cm <- aw_freeform_table(company_id = company_id, 
                           rsid = rsid, 
                           metrics = c(cm_no_seg_filter, cm_seg_filter),
                           dimensions = 'daterangeday', 
                           prettynames = T)
knitr::kable(df_cm)

Update a calculated metric

To update the name or description it is as simple as adding them within a list function of the updates argument.

?cm_update

cm_updated <- cm_update(
  id = cm_no_seg_filter,
  updates = list(name = "new name",
                 description = "this is a new description"),
  locale = "en_US",
  debug = FALSE,
  company_id = company_id
)
# Name Change
c(`old name` =  jsonlite::fromJSON(cm_obj)$name,`new name` = cm_updated$name)

# Description Change
c(`old description` =  jsonlite::fromJSON(cm_obj)$description,`new description` = cm_updated$description)

    old name                           new name 

“Test Calculated Metric” “new name”

  old description                       new description 

“Test cm description” “this is a new description”

For updating an existing calculated metrics within the definition there is a more complex solution that needs to be done.

cm_updated <- aw_get_calculatedmetrics(filterByIds = cm_updated$id, 
                                       expansion = 'definition')

#change the col1 values to reflect a new function `mean`
cm_updated$definition$formula$col1$func <- 'mean'
cm_updated$definition$formula$col1$description <- 'Mean'
cm_updated$definition$formula$col1$`include-zeros` <- FALSE

cm_update_complete <- cm_update(
  id = cm_updated$id,
  updates = jsonlite::unbox(cm_updated),
  locale = "en_US",
  debug = FALSE,
  company_id = company_id
)

cm_update_complete$definition$formula$col1$func [1] “mean”

cm_update_complete$definition$formula$col1$description [1] “Mean”

Copy a Calculated Metric

cm_var <- aw_get_calculatedmetrics(filterByIds = jsonlite::fromJSON(cm_obj)$id, 
                                   expansion = 'definition')

jsonlite::toJSON(cm_var)

copy_res <- cm_copy(cm_id = cm_var$id, 
                    name = 'Here I copy the cm', 
                    description = 'I want to add a new description', 
                    polarity = 'negative', 
                    precision = 2, 
                    type = 'percent',
                    create_cm = T)

copy_res “{”rsid”:“igeo1xxpnwcidadobepm”,“id”:“cm300010142_6537f722de0e706af6156fb3”,“name”:“Here I copy the cm”,“description”:“I want to add a new description”,“isDeleted”:false,“migratedIds”:[],“internal”:false,“owner”:{“id”:200654087},“hidden”:false,“componentType”:“calculatedMetric”,“polarity”:“negative”,“precision”:2,“type”:“percent”,“definition”:{“formula”:{“func”:“divide”,“col1”:{“func”:“mean”,“description”:“Mean”,“col”:{“func”:“metric”,“name”:“metrics/visits”,“description”:“Visits”},“include-zeros”:false},“col2”:{“func”:“metric”,“name”:“metrics/singlepagevisits”,“description”:“Single Page Visits”}},“func”:“calc-metric”,“version”:[1,0,0]},“compatibility”:{“identityMetrics”:[{“identity”:“metrics/visits”},{“identity”:“metrics/singlepagevisits”}],“functions”:[“mean”,“divide”],“validator_version”:“1.0.0”,“supported_products”:[“oberon”],“supported_schema”:[“schema_oberon”,“schema_frag”]},“legacyId”:““,”categories”:[“Calculated Metrics”],“modified”:“2023-10-24T16:56:02Z”}”

cm_val(copy_res) [1] “The calculated metric definition IS VALID”

Delete calculated metrics

?cm_delete

deleted <- cm_delete(
  cm_id = cm_no_seg_filter,
  warn = FALSE,
  locale = "en_US",
  debug = FALSE,
  rsid = rsid,
  company_id = company_id
)