Issue 558: Adding a windowed simple moving average forecaster.

anomdetect/src/main/java/com/expedia/adaptivealerting/anomdetect/forecast/point/algo/sma/SmaPointForecaster.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2018-2019 Expedia Group, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.expedia.adaptivealerting.anomdetect.forecast.point.algo.sma;
+
+import com.expedia.adaptivealerting.anomdetect.forecast.point.PointForecast;
+import com.expedia.adaptivealerting.anomdetect.forecast.point.PointForecaster;
+import com.expedia.metrics.MetricData;
+import com.google.common.collect.EvictingQueue;
+
+import lombok.Generated;
+import lombok.Getter;
+
+import static com.expedia.adaptivealerting.anomdetect.util.AssertUtil.notNull;
+
+/**
+ * Point forecaster based on the Simple Moving Average (SMA) method
+ */
+public class SmaPointForecaster implements PointForecaster {
+
+    @Getter
+    @Generated // https://reflectoring.io/100-percent-test-coverage/
+    private SmaPointForecasterParams params;
+
+    @Getter
+    @Generated // https://reflectoring.io/100-percent-test-coverage/
+    private double mean;
+
+    @Getter
+    @Generated // https://reflectoring.io/100-percent-test-coverage/
+    private EvictingQueue<Double> periodOfValues;
+
+    public SmaPointForecaster() {
+        this(new SmaPointForecasterParams());
+    }
+
+    public SmaPointForecaster(SmaPointForecasterParams params) {
+        notNull(params, "params can't be null");
+        params.validate();
+        this.params = params;
+        this.periodOfValues = EvictingQueue.create(params.getLookBackPeriod());
+
+        if (params.getInitialPeriodOfValues() != null) {
+            params.getInitialPeriodOfValues().forEach(this::updateMeanEstimate);
+        }
+    }
+
+    @Override
+    public PointForecast forecast(MetricData metricData) {
+        notNull(metricData, "metricData can't be null");
+        updateMeanEstimate(metricData.getValue());
+
+        return new PointForecast(mean, false);
+    }
+
+    private void updateMeanEstimate(double observed) {
+        double meanSum = mean * periodOfValues.size();
+
+        // remove the head's contribution to the mean's sum only if present and we have a full period of data
+        Double head = periodOfValues.peek();
+        if (head != null && periodOfValues.size() == params.getLookBackPeriod()) {
+            meanSum -= head;
+        }
+
+        periodOfValues.add(observed);
+
+        // add in the observed value's contribution to the mean's sum & recalculate the mean
+        meanSum += observed;
+        mean = meanSum / periodOfValues.size();
+    }
+
+}

anomdetect/src/main/java/com/expedia/adaptivealerting/anomdetect/forecast/point/algo/sma/SmaPointForecasterParams.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2018-2019 Expedia Group, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.expedia.adaptivealerting.anomdetect.forecast.point.algo.sma;
+
+import java.util.List;
+
+import com.expedia.adaptivealerting.anomdetect.util.AlgoParams;
+
+import lombok.Data;
+import lombok.experimental.Accessors;
+
+import static com.expedia.adaptivealerting.anomdetect.util.AssertUtil.isStrictlyPositive;
+import static com.expedia.adaptivealerting.anomdetect.util.AssertUtil.isTrue;
+
+@Data
+@Accessors(chain = true)
+public final class SmaPointForecasterParams implements AlgoParams {
+
+    /**
+     * How many previous observations to include in the average.
+     */
+    private int lookBackPeriod = Integer.MAX_VALUE;
+
+    /**
+     * An optional period's worth of values to seed the forecaster with.
+     * If specified, length of list must equal lookBackPeriod.
+     */
+    private List<Double> initialPeriodOfValues;
+
+    @Override
+    public void validate() {
+        isStrictlyPositive(lookBackPeriod, "Required: lookBackPeriod > 0");
+        isTrue(initialPeriodOfValuesValid(), "When specified, initialPeriodOfValues.size must equal lookBackPeriod");
+    }
+
+    private boolean initialPeriodOfValuesValid() {
+        return initialPeriodOfValues == null ||
+            initialPeriodOfValues.size() == lookBackPeriod;
+    }
+}

anomdetect/src/test/java/com/expedia/adaptivealerting/anomdetect/forecast/point/algo/sma/SmaPointForcasterTest.java

@@ -0,0 +1,117 @@
+package com.expedia.adaptivealerting.anomdetect.forecast.point.algo.sma;
+
+import java.io.InputStreamReader;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Function;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import com.expedia.metrics.MetricData;
+import com.expedia.metrics.MetricDefinition;
+import com.opencsv.bean.CsvToBeanBuilder;
+
+import lombok.val;
+
+import static org.junit.Assert.assertEquals;
+
+public class SmaPointForcasterTest {
+    private static final double TOLERANCE = 0.001;
+
+    private static List<SmaPointForecasterTestRow> testRows;
+
+    @BeforeClass
+    public static void setUpClass() {
+        loadSampleData();
+    }
+
+    @Test
+    public void testWithInitialValues() {
+        SmaPointForecasterParams params = new SmaPointForecasterParams()
+            .setLookBackPeriod(3)
+            .setInitialPeriodOfValues(Arrays.asList(1.0, 2.0, 3.0));
+        SmaPointForecaster sma3 = new SmaPointForecaster(params);
+
+        // [1.0, 2.0, 3.0]; mean=2.0
+        assertEquals(2.0, sma3.getMean(), TOLERANCE);
+        // [2.0, 3.0, 4.0]; mean=3.0
+        assertEquals(3.0, sma3.forecast(createMetricData(4.0)).getValue(), TOLERANCE);
+        // [3.0, 4.0, 5.0]; mean=4.0
+        assertEquals(4.0, sma3.forecast(createMetricData(5.0)).getValue(), TOLERANCE);
+    }
+
+    @Test
+    public void testNoInitialValues() {
+        SmaPointForecasterParams params = new SmaPointForecasterParams().setLookBackPeriod(3);
+        SmaPointForecaster sma3 = new SmaPointForecaster(params);
+
+        // [2.0]; mean=2.0
+        assertEquals(2.0, sma3.forecast(createMetricData(2.0)).getValue(), TOLERANCE);
+        // [2.0, 4.0]; mean=3.0
+        assertEquals(3.0, sma3.forecast(createMetricData(4.0)).getValue(), TOLERANCE);
+        // [2.0, 4.0, 6.0]; mean=4.0
+        assertEquals(4.0, sma3.forecast(createMetricData(6.0)).getValue(), TOLERANCE);
+        // [4.0, 6.0, 8.0]; mean=6.0
+        assertEquals(6.0, sma3.forecast(createMetricData(8.0)).getValue(), TOLERANCE);
+    }
+
+    @Test
+    public void testAgainstSampleData() {
+        List<SmaPointForecaster> forecasters = Arrays.asList(
+            createSmaForecaster(1),
+            createSmaForecaster(3),
+            createSmaForecaster(9),
+            createSmaForecaster(21)
+        );
+
+        List<Function<SmaPointForecasterTestRow, Double>> expectedValueExtractors = Arrays.asList(
+            SmaPointForecasterTestRow::getSma1,
+            SmaPointForecasterTestRow::getSma3,
+            SmaPointForecasterTestRow::getSma9,
+            SmaPointForecasterTestRow::getSma21
+        );
+
+        testRows.forEach(testRow -> {
+            for (int i = 0; i < forecasters.size(); i++) {
+                validateForecaster(testRow, forecasters.get(i), expectedValueExtractors.get(i));
+            }
+        });
+    }
+
+    private SmaPointForecaster createSmaForecaster(int period) {
+        return new SmaPointForecaster(new SmaPointForecasterParams().setLookBackPeriod(period));
+    }
+
+    private void validateForecaster(SmaPointForecasterTestRow testRow, SmaPointForecaster forecaster,
+        Function<SmaPointForecasterTestRow, Double> expectedValueExtractor) {
+
+        Double expectedSmaValue = expectedValueExtractor.apply(testRow);
+
+        MetricData metricData = createMetricData(testRow.getObserved());
+        double actualSmaValue = forecaster.forecast(metricData).getValue();
+
+        assertEquals(failureMessage(forecaster, testRow), expectedSmaValue, actualSmaValue, TOLERANCE);
+    }
+
+    private MetricData createMetricData(double observed) {
+        return new MetricData(
+            new MetricDefinition("some-key"),
+            observed,
+            System.currentTimeMillis()
+        );
+    }
+
+    private String failureMessage(SmaPointForecaster forecaster, SmaPointForecasterTestRow testRow) {
+        int lookbackPeriod = forecaster.getParams().getLookBackPeriod();
+        return "forecaster SMA" + lookbackPeriod + " failed. testRow=" + testRow;
+    }
+
+    private static void loadSampleData() {
+        val is = ClassLoader.getSystemResourceAsStream("tests/sma-sample-input.csv");
+        testRows = new CsvToBeanBuilder<SmaPointForecasterTestRow>(new InputStreamReader(is))
+            .withType(SmaPointForecasterTestRow.class)
+            .build()
+            .parse();
+    }
+}

anomdetect/src/test/java/com/expedia/adaptivealerting/anomdetect/forecast/point/algo/sma/SmaPointForecasterParamsTest.java

@@ -0,0 +1,45 @@
+package com.expedia.adaptivealerting.anomdetect.forecast.point.algo.sma;
+
+import java.util.Arrays;
+
+import org.junit.Test;
+
+public class SmaPointForecasterParamsTest {
+
+    @Test
+    public void validParamsTotallyEmpty() {
+        new SmaPointForecasterParams()
+            .validate();
+    }
+
+    @Test
+    public void validParamsLookbackOnly() {
+        new SmaPointForecasterParams()
+            .setLookBackPeriod(3)
+            .validate();
+    }
+
+    @Test
+    public void validParamsFullyPopulated() {
+        new SmaPointForecasterParams()
+            .setLookBackPeriod(3)
+            .setInitialPeriodOfValues(Arrays.asList(1.0, 2.0, 3.0))
+            .validate();
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void invalidLookbackPeriod() {
+        new SmaPointForecasterParams()
+            .setLookBackPeriod(-1)
+            .validate();
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void invalidInitialPeriodOfValues() {
+        new SmaPointForecasterParams()
+            .setLookBackPeriod(2)
+            .setInitialPeriodOfValues(Arrays.asList(1.0, 2.0, 3.0))
+            .validate();
+    }
+
+}

anomdetect/src/test/java/com/expedia/adaptivealerting/anomdetect/forecast/point/algo/sma/SmaPointForecasterTestRow.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2018-2019 Expedia Group, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.expedia.adaptivealerting.anomdetect.forecast.point.algo.sma;
+
+import com.opencsv.bean.CsvBindByName;
+
+import lombok.Data;
+import lombok.ToString;
+
+@Data
+@ToString
+public class SmaPointForecasterTestRow {
+
+    @CsvBindByName
+    private int rownum;
+
+    @CsvBindByName
+    private double observed;
+
+    @CsvBindByName
+    private double sma1;
+
+    @CsvBindByName
+    private double sma3;
+
+    @CsvBindByName
+    private double sma9;
+
+    @CsvBindByName
+    private double sma21;
+}

anomdetect/src/test/resources/tests/sma-sample-input.csv

@@ -0,0 +1,27 @@
+"rownum","observed","sma1","sma3","sma9","sma21"
+1,0,0,0,0,0
+2,0,0,0,0,0
+3,0,0,0,0,0
+4,1,1,0.3333333333,0.25,0.25
+5,2,2,1,0.6,0.6
+6,3,3,2,1,1
+7,4,4,3,1.428571429,1.428571429
+8,3,3,3.333333333,1.625,1.625
+9,2,2,3,1.666666667,1.666666667
+10,1,1,2,1.777777778,1.6
+11,0,0,1,1.777777778,1.454545455
+12,5,5,2,2.333333333,1.75
+13,10,10,5,3.333333333,2.384615385
+14,15,15,10,4.777777778,3.285714286
+15,20,20,15,6.666666667,4.4
+16,15,15,16.66666667,7.888888889,5.0625
+17,10,10,15,8.666666667,5.352941176
+18,5,5,10,9,5.333333333
+19,100,100,38.33333333,20,10.31578947
+20,200,200,101.6666667,42.22222222,19.8
+21,300,300,200,75,33.14285714
+22,400,400,300,118.3333333,52.19047619
+23,500,500,400,172.2222222,76
+24,600,600,500,236.6666667,104.5714286
+25,700,700,600,312.7777778,137.8571429
+26,800,800,700,400.5555556,175.8571429