Forecaster Hints

The Ad Forecaster is unable to predict sudden variations in traffic, such as the ones generated by the activation of new networks or the removal of a publisher. For those scenarios, Forecaster Hints should be used to provide the system with additional information about those new traffic sources.

Important: Use this feature with caution. When used incorrectly, it can lead to quality and performance problems. Please read the “Warnings and Troubleshooting” section carefully before using this feature.

Targeting

Each hint has a startDate, an endDate and a rule field. For more information about the targeting rule format, see our Rules documentation page.

Hint types

Multiplier

A “Multiplier Hint” multiplies the targeted value by a given constant factor.

For example, its possible to tell the system about a 10% drop in traffic from the USA during thanksgiving with the following hint:

{
  "id": "thanksgiving-2017",
  "type": "multiplier",
  "startDate": "2017-11-23 07:00:00",
  "endDate": "2017-11-23 23:00:00",
  "timeZone": "US/Central",
  "multiplier": 0.9,
  "rule": "geoCountry = \"US\""
}

Note that multiplier hints can also be used to upscale traffic, for example:

{
  "id": "blackfriday-2017",
  "type": "multiplier",
  "startDate": "2017-11-24 07:00:00",
  "endDate": "2017-11-24 23:00:00",
  "timeZone": "US/Central",
  "multiplier": 1.5,
  "rule": "geoCountry = \"US\""
}

Impression Count

An “Impression Count Hint” forces the number of targeted impressions to a constant value. This upscales/downscales the result as needed.

For example, to force the forecast to consider 100000 British impressions during Christmas, the following hint could be applied:

{
  "id": "christmas-2017",
  "type": "impressionCount",
  "startDate": "2017-12-24 07:00:00",
  "endDate": "2017-12-25 23:00:00",
  "impressionCount": 100000,
  "rule": "geoCountry = \"GB\""
}

If the Ad Forecaster cannot find any impressions targeted by rule, and the inventoryPoolRule is undefined, it will make a best effort to create artificial traffic. For this to happen, the rule field must contain all the fields described in the AVRO schema that are not nullable.

To avoid having to add such dummy fields to each rule, the Ad Forecaster system can be configured with default values to use when generating log rows.

If your experts know that there’s no traffic targeted by the rule field, it is usually recommended to use an inventory pool instead of allowing the forecast to generate artificial traffic based on real data.

Inventory Pools

Sometimes the human experts might not only want to tell the system how the traffic will change, but also that it will behave like a different kind of traffic.

By filling the inventoryPoolRule field, they can tell the Ad Forecaster system to:

  1. Ignore the original traffic targeted by rule;
  2. Use the traffic targeted by the inventoryPoolRule to generate new traffic targeted by rule;
  3. Apply the hint to the new traffic.

For example, if one of your publishers is a movie streaming service with a British website, that’s planning to launch a Spanish version, your experts can tell the forecaster that this new website will have Spanish traffic similar to the British traffic, but only with 70% of the users, with the following hint:

{
  "id": "notflix-es",
  "type": "multiplier",
  "startDate": "2018-01-01 07:00:00",
  "endDate": "2018-02-01 00:00:00",
  "multiplier": 0.7,
  "rule": "site = \"notflix.es\" and geoCountry = \"ES\"",
  "inventoryPoolRule": "site = \"notflix.co.uk\""
}

Note that the rule field now tells the Ad Forecaster which fields should be modified. In our example, we added geoCountry = "ES" to our rule so that the new traffic is all Spanish.

Warnings and Troubleshooting

Performance implications

In order to reliably simulate campaign delivery algorithms, the performance cost of applying a forecaster hint is similar to the cost of running a forecast in a system with that number of entries (i.e. applying a hint that doubles the traffic will be as slow as having the system deployed with twice as many impressions).

Warning messages

An incorrectly defined hint can lead to multiple performance and quality problems that can be hard to debug. To help debugging such problems, the Ad Forecaster sends Warnings in the forecast response.

While the existence of a warning does not mean that a forecast is incorrect, if a forecast is exhibiting slow performance or strange results, they can give some insights into the underlying problem.

A forecast response with a warning would include the following inside the warning attribute:

{
  "code": "OVRHNT",
  "message": "Hint overlap at: { country = \"FR\", !(country = \"EN\")}",
  "causes": ["hint2"]
}

MODHNT

This warning is thrown if any hint was applied during the forecast.

While this warning can usually be safely ignored, it helps to debug common problems (e.g. the targeting rule of a hint might be too broad).

CRTHNT

This warning is thrown if the Ad Forecaster had to create lower-quality artificial traffic to apply a hint.

This means that some impression count hint has a targeting rule without enough traffic. When this warning appears, it is usually recommended to add an inventory pool.

OVRHNT

This warning is thrown if the Ad Forecaster detected that two or more hints overlap each other.

This is a very dangerous situation that can lead to unexpected results.

For example, imagine that a human expert wants to define a small “ramp-up” in traffic, by multiplying the traffic of the first day by 1.5 and the traffic of the second day by 2.0. Assume that, due to an oversight, the rules were defined as following, with an overlap from “2018-02-02 00:00:00” to “2018-02-02 12:00:00”:

{
  "id": "hint-a",
  "type": "multiplier",
  "startDate": "2018-02-01 00:00:00",
  "endDate": "2018-02-02 12:00:00",
  "multiplier": 1.5,
  "rule": "geoCountry = \"GB\""
}
{
  "id": "hint-b",
  "type": "multiplier",
  "startDate": "2018-02-02 00:00:00",
  "endDate": "2018-02-03 00:00:00",
  "multiplier": 2,
  "rule": "geoCountry = \"GB\""
}

If this happens, the traffic from “2018-02-02 00:00:00” to “2018-02-02 12:00:00” will actually be multiplied by 3 (1.5 * 2), which is clearly not the behavior intended by the expert.

This can be particularly dangerous if a multiplier hint is inserted twice (effectively squaring the original multiplier) or if a multiplier hint overlaps with an impression count hint.

IPLHINT

This warning is thrown if the Ad Forecaster had to ignore some entries do to an inventory pool rule.

Recall from the “Inventory Pools” section that the Ad Forecaster ignores the traffic targeted by the rule field if the inventoryPoolRule is defined. This is by design, to allow human experts to be able to override low-quality forecasts for targets that have low traffic (e.g. publishers that have appeared recently).

This warning can usually be safely ignored, as it is just a reminder for the human experts to remove some hints once the Ad Forecaster has enough data for an high-quality forecast.