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:
- Ignore the original traffic targeted by
rule
; - Use the traffic targeted by the
inventoryPoolRule
to generate new traffic targeted byrule
; - 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.