anomalyDetectorExtremeValues

This example uses a dataset that is far too large to display fully here. Instead, we've uploaded the data into THIS DOWNLOADABLE PROJECT. The project contains no script content, so you can copy-paste in the example ATL and try it yourself.

The full dataset contains sales data for 2020 and 2021. For reference, the first six rows are:

Suppose you want to look for periods (three months minimum) in which each monthly sales total is an extreme value. Also, suppose an extreme value is one 30% higher or lower than usual, allowing for normal variation as measured by standard deviation.

The ATL [[anomalyDetectorExtremeValues(Sales, Date, 'monthly', 30, 3)]] returns this result:

The results list contains two ATL objects, one for each anomalous subset. You can tell from the anomalyClass values that one anomaly is high and the other is low. The result is easier to understand by looking at this table of aggregated totals:

The high anomaly comprises a three-month period from Jun 2020 to Aug 2020. Each aggregated total in this subset is extremely high. Similarly, the low anomaly comprises a period from Feb 2021 to Apr 2021 and each total in that subset is extremely low.

Here's how you might extract values from the result to produce narrative text:

[[

results = anomalyDetectorExtremeValues(Sales, Date, 'monthly', 30, 3)

highOnly = filter(results, x -> x.anomalyClass == 'high')[0:1]

lowOnly = filter(results, x -> x.anomalyClass == 'low')[0:1]

highStartDate = map(highOnly, x -> "[[formatDateTime(x.startDate, 'MMM yyyy')]] ([[abbreviateNumber(currencyFormat(x.startValue))]])")

highEndDate = map(highOnly, x -> "[[formatDateTime(x.endDate, 'MMM yyyy')]] ([[abbreviateNumber(currencyFormat(x.endValue))]])")

lowStartDate = map(lowOnly, x -> "[[formatDateTime(x.startDate, 'MMM yyyy')]] ([[abbreviateNumber(currencyFormat(x.startValue))]])")

lowEndDate = map(lowOnly, x -> "[[formatDateTime(x.endDate, 'MMM yyyy')]] ([[abbreviateNumber(currencyFormat(x.endValue))]])")

normalAvg = unique(map(results, x -> x.normalMean))

"Monthly sales were extremely high from [[highStartDate]] to [[highEndDate]] and extremely low from [[lowStartDate]] to [[lowEndDate]]. Excluding the anomalous periods, average monthly sales were [[abbreviateNumber(currencyFormat(normalAvg))]]."

]]

The output text is:

NOTE ON QUARTERLY GRANULARITY

If you ran a similar analysis but with the TIME GRANULARITY parameter set to quarterly, the function would return an empty list. You can try this in the downloadable project using this ATL: [[anomalyDetectorExtremeValues(Sales,Date,'quarterly',30,3)]].

It's easier to understand the result (no anomalies) by looking at this table of aggregated totals:

Remember that the WINDOW SIZE parameter is set to 3. The total for Q3, 2020 (73,000) stands out as extremely high, but it's not detected as an anomaly because it's a single value. As per the ATL, function looks for sets of three or more extreme values.

Tip

To detect single values that are extremely high or extremely low, use anomalyDetectorContextual instead.

 

Assume a "Describe the Table" project with this data:

The table contains sales data for the first two weeks of Feb 2021. Typically, you would have sales data covering a longer period, but we've kept the dataset small to simplify the example. Use THIS DOWNLOADABLE PROJECT if you want to try the example yourself.

Suppose you want to look for periods (three days minimum) in which each daily sales total is an extreme value. Also, suppose an extreme value is one 30% higher or lower than usual, allowing for normal variation as measured by standard deviation.

The ATL [[anomalyDetectorExtremeValues(Sales, Date, 'daily', 30, 3)]] returns this result:

The results list contains a single ATL object. The anomalyClass value is mixed, which means the subset contains a mix of extremely high values and extremely low values. The result is easier to understand by looking at this table of aggregated totals:

The anomaly comprises a four-day period from Feb 6, 2021 to Feb 9, 2021. As you can see, there are two extremely high values and two extremely low values. Note that the highest and lowest values (22,000 and 1,000) are provided in the result object.

Here's how you might extract values from the result to produce narrative text:

[[

results = anomalyDetectorExtremeValues(Sales, Date, 'daily', 30, 3)

mixedOnly = filter(results, x -> x.anomalyClass == 'mixed')[0:1]

startDate = map(mixedOnly, x -> x.startDate)

endDate = map(mixedOnly, x -> x.endDate)

maxValDetails = map(mixedOnly, x -> "[[x.maxValueDate]] ([[abbreviateNumber(currencyFormat(x.maxValue))]])")

minValDetails = map(mixedOnly, x -> "[[x.minValueDate]] ([[abbreviateNumber(currencyFormat(x.minValue))]])")

normalAvg = abbreviateNumber(currencyFormat(map(mixedOnly, x -> x.normalMean)))

"Daily sales were either extremely high or extremely low from [[startDate]] to [[endDate]]. The highest sales total in this period was on [[maxValDetails]] and the lowest was on [[minValDetails]]. Excluding the anomalous period, average daily sales were [[normalAvg]]."

]]

The output text is: