Analysis Task Parameters

This page details all of the parameters that can be applied to an analysis task.

Parameters for all analysis tasks

The following parameters are supported for all analysis tasks:

Property Type Required Description
start unix timestamp No. Timestamp for start of the analysis period.
Specifying an analysis period...
end unix timestamp No. Timestamp for end of the analysis period.
Specifying an analysis period...
offset string No. Applies a time offset to the start and end parameters to adjust for your timezone.
Specifying an analysis period...
filter CSDL string No. Filter to select interactions for the analysis.
Specifying a query filter...
parameters.analysis_type string Yes.

Currently two types of analysis are supported, each with their own set of additional parameters:

Specifying an analysis period

Note that time ranges are treated as inclusive on the start and exclusive on the end.

Both start and end parameters are optional, however as best practice we recommend that you do provide these parameters for your analysis tasks so that you are sure which period you are analyzing.

If you omit either parameter the platform will use default a time period based upon the following rules:

  • If you specify a start and no end, the task's time period will be from the start point until now.
  • If you omit both the start and end parameters, the task's time period will resort to a default time period.
    • For frequency distribution analysis tasks the last 24 hours will be analyzed.
    • For time series analysis tasks the maximum period allowed by the selected interval will be analyzed. For example, if the interval is hours the analysis query defaults to 336 hours (2 weeks).

You can use the offset parameter to automatically adjust start and end parameters to your timezone.

The offset is expressed using a string including the number of hours to use for the offset, such as:

  • 8 Adjust for a timezone that is eight hours ahead of UTC.
  • +8 Adjust for a timezone that is eight hours ahead of UTC.
  • -8 Adjust for a timezone that is eight hours behind UTC.

For example, by setting the UTC offset to -8 and passing a time range which matches a 24-hour PST day, you can receive timeseries results at daily intervals and ensure that an author generating interactions which fall on two different UTC days, but the same PST day, are never double counted.

As an example, the following parameters analyze the top urls for the period from 1st January 2017 to 15th January 2017. The start and end parameters specify the time range using unix timestamps:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "Top urls for two week period",
  "type": "analysis",
  "parameters": {
    "start": 1483228800,
    "end": 1484438400,
    "parameters": {
      "analysis_type": "freqDist",
      "parameters": {
        "target": "li.all.articles.url",
        "threshold": 20
      }
    }
  }
}

Specifying a query filter

You can filter the interactions that will be included in your analysis using the filter parameter. The parameter expects a valid CSDL filter.

The filter parameter is optional. If you omit this parameter the task will process the entire content of the index, within the time period selected by the start and end parameters.

As an example, the following parameters analyze the top urls for LinkedIn members in the age group 25-34 years old. The filter parameter selects only members of the required age group for the analysis:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "25-34 year old members only",
  "type": "analysis",
  "parameters": {
    "filter": "li.user.member.age == \"25-34\"",
    "parameters": {
      "analysis_type": "freqDist",
      "parameters": {
        "target": "li.all.articles.url",
        "threshold": 20
      }
    }
  }
}

Specific parameters for analysis types

Depending on the type of analysis a different set of parameters is supported.

Time series analysis

For time series analysis the following parameters are supported:

Property Type Required Description
interval string Yes.

The resolution to break down the analysis by.

Valid values are month, week, day, hour, minute.

span integer No. How many interval units to span for each analysis 'bucket'.

The combination of these two parameters allow you to specify the size of the intervals for your time series analysis.

For example, if the interval is "week" and span is 2, the output is grouped into two-week buckets.

A span value greater than 1 can be applied to the intervals week, day, hour, minute but not to month.

As an example the following parameters perform a time series analysis breaking the analysis down into 2 hour buckets:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "Time series analysis",
  "type": "analysis",
  "parameters": {
    "parameters": {
      "analysis_type": "timeSeries",
      "parameters": {
        "interval": "hour",
        "span": 2
      }
    }
  }
}

Frequency distribution analysis

For frequency distribution analysis the following parameters are supported:

Property Type Required Description
target string Yes. The data target to be analyzed.
threshold integer No. Defaults to 200. The maximum number of results to return. The maximum value you can specify is 200.

These parameters allow you to specify the data target you want to analyze and the number of results to return.

As an example the following parameters analyze the top 10 domains for members aged between 25 and 34 years. The target parameter specifies that domains should be analyzed, and the threshold parameter specifies that the top 10 should be returned:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "25-34 year old members only",
  "type": "analysis",
  "parameters": {
    "filter": "li.user.member.age == \"25-34\"",
    "parameters": {
      "analysis_type": "freqDist",
      "parameters": {
        "target": "li.all.articles.url",
        "threshold": 10
      }
    }
  }
}

Nested frequency distribution analysis

You can perform nested frequency distribution analysis using the child parameter. Up to three levels of nesting are permitted (parent and child nested to two levels).

You specify a child parameter as an object containing an analysis_type, target, and optionally the threshold property.

The analysis_type value is always freqDist as this is currently the only supported child analysis type. The target and threshold parameters are the same as used for non-nested frequency distribution analysis.

Note that not all targets are valid for child analysis. The Target Explorer tool indicates which targets are valid.

As an example of two-level nesting, the following parameters analyze first the age groups of members, and then break down each age group by gender:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "Age-gender breakdown",
  "type": "analysis",
  "parameters": {
    "parameters": {
      "analysis_type": "freqDist",
      "parameters": {
        "target": "li.user.member.age",
        "threshold": 5
      },
      "child": {
        "analysis_type": "freqDist",
        "parameters": {
          "target": "li.user.member.gender",
          "threshold": 2
        }
      }
    }
  }
}

As an example of three-level nesting, the following parameters analyze members by first country, then age group, then gender:

{
  "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
  "name": "Country-age-gender breakdown",
  "type": "analysis",
  "parameters": {
    "parameters": {
      "analysis_type": "freqDist",
      "parameters": {
        "target": "li.user.member.country",
        "threshold": 10
      },
      "child": {
        "analysis_type": "freqDist",
        "parameters": {
          "target": "li.user.member.age",
          "threshold": 6
        },
        "child": {
          "analysis_type": "freqDist",
          "parameters": {
            "target": "li.user.member.gender",
            "threshold": 2
          }
        }
      }
    }
  }
}