diff --git a/docs/reference/aggregations/reducer/movavg-aggregation.asciidoc b/docs/reference/aggregations/reducer/movavg-aggregation.asciidoc index 18cf98d263d..ef5f97e12ee 100644 --- a/docs/reference/aggregations/reducer/movavg-aggregation.asciidoc +++ b/docs/reference/aggregations/reducer/movavg-aggregation.asciidoc @@ -21,9 +21,9 @@ A `moving_avg` aggregation looks like this in isolation: [source,js] -------------------------------------------------- { - "movavg": { + "moving_avg": { "buckets_path": "the_sum", - "model": "double_exp", + "model": "holt", "window": 5, "gap_policy": "insert_zero", "settings": { @@ -153,9 +153,9 @@ although typically less than the `simple` model: .Linear moving average with window of size 100 image::images/reducers_movavg/linear_100window.png[] -==== Single Exponential +==== EWMA (Exponentially Weighted) -The `single_exp` model is similar to the `linear` model, except older data-points become exponentially less important, +The `ewma` model (aka "single-exponential") is similar to the `linear` model, except older data-points become exponentially less important, rather than linearly less important. The speed at which the importance decays can be controlled with an `alpha` setting. Small values make the weight decay slowly, which provides greater smoothing and takes into account a larger portion of the window. Larger valuers make the weight decay quickly, which reduces the impact of older values on the @@ -169,7 +169,7 @@ The default value of `alpha` is `0.5`, and the setting accepts any float from 0- "the_movavg":{ "moving_avg":{ "buckets_path": "the_sum", - "model" : "single_exp", + "model" : "ewma", "settings" : { "alpha" : 0.5 } @@ -187,13 +187,13 @@ image::images/reducers_movavg/single_0.2alpha.png[] .Single Exponential moving average with window of size 10, alpha = 0.7 image::images/reducers_movavg/single_0.7alpha.png[] -==== Double Exponential +==== Holt-Linear -The `double_exp` model, sometimes called "Holt's Linear Trend" model, incorporates a second exponential term which +The `holt` model (aka "double exponential") incorporates a second exponential term which tracks the data's trend. Single exponential does not perform well when the data has an underlying linear trend. The double exponential model calculates two values internally: a "level" and a "trend". -The level calculation is similar to `single_exp`, and is an exponentially weighted view of the data. The difference is +The level calculation is similar to `ewma`, and is an exponentially weighted view of the data. The difference is that the previously smoothed value is used instead of the raw value, which allows it to stay close to the original series. The trend calculation looks at the difference between the current and last value (e.g. the slope, or trend, of the smoothed data). The trend value is also exponentially weighted. @@ -208,7 +208,7 @@ The default value of `alpha` and `beta` is `0.5`, and the settings accept any fl "the_movavg":{ "moving_avg":{ "buckets_path": "the_sum", - "model" : "double_exp", + "model" : "holt", "settings" : { "alpha" : 0.5, "beta" : 0.5 @@ -217,7 +217,7 @@ The default value of `alpha` and `beta` is `0.5`, and the settings accept any fl } -------------------------------------------------- -In practice, the `alpha` value behaves very similarly in `double_exp` as `single_exp`: small values produce more smoothing +In practice, the `alpha` value behaves very similarly in `holt` as `ewma`: small values produce more smoothing and more lag, while larger values produce closer tracking and less lag. The value of `beta` is often difficult to see. Small values emphasize long-term trends (such as a constant linear trend in the whole series), while larger values emphasize short-term trends. This will become more apparently when you are predicting values. @@ -251,14 +251,14 @@ as your buckets: } -------------------------------------------------- -The `simple`, `linear` and `single_exp` models all produce "flat" predictions: they essentially converge on the mean +The `simple`, `linear` and `ewma` models all produce "flat" predictions: they essentially converge on the mean of the last value in the series, producing a flat: [[simple_prediction]] .Simple moving average with window of size 10, predict = 50 image::images/reducers_movavg/simple_prediction.png[] -In contrast, the `double_exp` model can extrapolate based on local or global constant trends. If we set a high `beta` +In contrast, the `holt` model can extrapolate based on local or global constant trends. If we set a high `beta` value, we can extrapolate based on local constant trends (in this case the predictions head down, because the data at the end of the series was heading in a downward direction): diff --git a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/SingleExpModel.java b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/EwmaModel.java similarity index 92% rename from src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/SingleExpModel.java rename to src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/EwmaModel.java index f17ba68f498..8d563062813 100644 --- a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/SingleExpModel.java +++ b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/EwmaModel.java @@ -33,9 +33,9 @@ import java.util.Map; /** * Calculate a exponentially weighted moving average */ -public class SingleExpModel extends MovAvgModel { +public class EwmaModel extends MovAvgModel { - protected static final ParseField NAME_FIELD = new ParseField("single_exp"); + protected static final ParseField NAME_FIELD = new ParseField("ewma"); /** * Controls smoothing of data. Alpha = 1 retains no memory of past values @@ -44,7 +44,7 @@ public class SingleExpModel extends MovAvgModel { */ private double alpha; - public SingleExpModel(double alpha) { + public EwmaModel(double alpha) { this.alpha = alpha; } @@ -68,7 +68,7 @@ public class SingleExpModel extends MovAvgModel { public static final MovAvgModelStreams.Stream STREAM = new MovAvgModelStreams.Stream() { @Override public MovAvgModel readResult(StreamInput in) throws IOException { - return new SingleExpModel(in.readDouble()); + return new EwmaModel(in.readDouble()); } @Override @@ -98,11 +98,11 @@ public class SingleExpModel extends MovAvgModel { alpha = 0.5; } - return new SingleExpModel(alpha); + return new EwmaModel(alpha); } } - public static class SingleExpModelBuilder implements MovAvgModelBuilder { + public static class EWMAModelBuilder implements MovAvgModelBuilder { private double alpha = 0.5; @@ -115,7 +115,7 @@ public class SingleExpModel extends MovAvgModel { * * @return The builder to continue chaining */ - public SingleExpModelBuilder alpha(double alpha) { + public EWMAModelBuilder alpha(double alpha) { this.alpha = alpha; return this; } diff --git a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/DoubleExpModel.java b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/HoltLinearModel.java similarity index 90% rename from src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/DoubleExpModel.java rename to src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/HoltLinearModel.java index 7d32989cda1..e386de73052 100644 --- a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/DoubleExpModel.java +++ b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/HoltLinearModel.java @@ -32,9 +32,9 @@ import java.util.*; /** * Calculate a doubly exponential weighted moving average */ -public class DoubleExpModel extends MovAvgModel { +public class HoltLinearModel extends MovAvgModel { - protected static final ParseField NAME_FIELD = new ParseField("double_exp"); + protected static final ParseField NAME_FIELD = new ParseField("holt"); /** * Controls smoothing of data. Alpha = 1 retains no memory of past values @@ -48,15 +48,15 @@ public class DoubleExpModel extends MovAvgModel { */ private double beta; - public DoubleExpModel(double alpha, double beta) { + public HoltLinearModel(double alpha, double beta) { this.alpha = alpha; this.beta = beta; } /** * Predicts the next `n` values in the series, using the smoothing model to generate new values. - * Unlike the other moving averages, double-exp has forecasting/prediction built into the algorithm. - * Prediction is more than simply adding the next prediction to the window and repeating. Double-exp + * Unlike the other moving averages, Holt-Linear has forecasting/prediction built into the algorithm. + * Prediction is more than simply adding the next prediction to the window and repeating. Holt-Linear * will extrapolate into the future by applying the trend information to the smoothed data. * * @param values Collection of numerics to movingAvg, usually windowed @@ -75,7 +75,7 @@ public class DoubleExpModel extends MovAvgModel { } /** - * Calculate a doubly exponential weighted moving average + * Calculate a Holt-Linear (doubly exponential weighted) moving average * * @param values Collection of values to calculate avg for * @param numForecasts number of forecasts into the future to return @@ -99,8 +99,6 @@ public class DoubleExpModel extends MovAvgModel { int counter = 0; - //TODO bail if too few values - T last; for (T v : values) { last = v; @@ -128,7 +126,7 @@ public class DoubleExpModel extends MovAvgModel { public static final MovAvgModelStreams.Stream STREAM = new MovAvgModelStreams.Stream() { @Override public MovAvgModel readResult(StreamInput in) throws IOException { - return new DoubleExpModel(in.readDouble(), in.readDouble()); + return new HoltLinearModel(in.readDouble(), in.readDouble()); } @Override @@ -165,11 +163,11 @@ public class DoubleExpModel extends MovAvgModel { beta = 0.5; } - return new DoubleExpModel(alpha, beta); + return new HoltLinearModel(alpha, beta); } } - public static class DoubleExpModelBuilder implements MovAvgModelBuilder { + public static class HoltLinearModelBuilder implements MovAvgModelBuilder { private double alpha = 0.5; private double beta = 0.5; @@ -183,7 +181,7 @@ public class DoubleExpModel extends MovAvgModel { * * @return The builder to continue chaining */ - public DoubleExpModelBuilder alpha(double alpha) { + public HoltLinearModelBuilder alpha(double alpha) { this.alpha = alpha; return this; } @@ -195,7 +193,7 @@ public class DoubleExpModel extends MovAvgModel { * * @return The builder to continue chaining */ - public DoubleExpModelBuilder beta(double beta) { + public HoltLinearModelBuilder beta(double beta) { this.beta = beta; return this; } diff --git a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/MovAvgModelModule.java b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/MovAvgModelModule.java index 71ccbcb31b0..a144459ab5d 100644 --- a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/MovAvgModelModule.java +++ b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/MovAvgModelModule.java @@ -36,8 +36,8 @@ public class MovAvgModelModule extends AbstractModule { public MovAvgModelModule() { registerParser(SimpleModel.SimpleModelParser.class); registerParser(LinearModel.LinearModelParser.class); - registerParser(SingleExpModel.SingleExpModelParser.class); - registerParser(DoubleExpModel.DoubleExpModelParser.class); + registerParser(EwmaModel.SingleExpModelParser.class); + registerParser(HoltLinearModel.DoubleExpModelParser.class); } public void registerParser(Class parser) { diff --git a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/TransportMovAvgModelModule.java b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/TransportMovAvgModelModule.java index bc085f6241a..a09c8265654 100644 --- a/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/TransportMovAvgModelModule.java +++ b/src/main/java/org/elasticsearch/search/aggregations/reducers/movavg/models/TransportMovAvgModelModule.java @@ -34,8 +34,8 @@ public class TransportMovAvgModelModule extends AbstractModule { public TransportMovAvgModelModule() { registerStream(SimpleModel.STREAM); registerStream(LinearModel.STREAM); - registerStream(SingleExpModel.STREAM); - registerStream(DoubleExpModel.STREAM); + registerStream(EwmaModel.STREAM); + registerStream(HoltLinearModel.STREAM); } public void registerStream(MovAvgModelStreams.Stream stream) { diff --git a/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgTests.java b/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgTests.java index f6f92ab278d..a2996612e11 100644 --- a/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgTests.java +++ b/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgTests.java @@ -34,11 +34,11 @@ import org.elasticsearch.search.aggregations.metrics.ValuesSourceMetricsAggregat import org.elasticsearch.search.aggregations.reducers.BucketHelpers; import org.elasticsearch.search.aggregations.reducers.ReducerHelperTests; import org.elasticsearch.search.aggregations.reducers.SimpleValue; -import org.elasticsearch.search.aggregations.reducers.movavg.models.DoubleExpModel; +import org.elasticsearch.search.aggregations.reducers.movavg.models.HoltLinearModel; import org.elasticsearch.search.aggregations.reducers.movavg.models.LinearModel; import org.elasticsearch.search.aggregations.reducers.movavg.models.MovAvgModelBuilder; import org.elasticsearch.search.aggregations.reducers.movavg.models.SimpleModel; -import org.elasticsearch.search.aggregations.reducers.movavg.models.SingleExpModel; +import org.elasticsearch.search.aggregations.reducers.movavg.models.EwmaModel; import org.elasticsearch.test.ElasticsearchIntegrationTest; import org.hamcrest.Matchers; import org.junit.Test; @@ -83,7 +83,7 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { enum MovAvgType { - SIMPLE ("simple"), LINEAR("linear"), SINGLE("single"), DOUBLE("double"); + SIMPLE ("simple"), LINEAR("linear"), EWMA("ewma"), HOLT("holt"); private final String name; @@ -198,11 +198,11 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { case LINEAR: values.add(linear(window)); break; - case SINGLE: - values.add(singleExp(window)); + case EWMA: + values.add(ewma(window)); break; - case DOUBLE: - values.add(doubleExp(window)); + case HOLT: + values.add(holt(window)); break; } @@ -245,12 +245,12 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { } /** - * Single exponential moving avg + * Exponentionally weighted (EWMA, Single exponential) moving avg * * @param window Window of values to compute movavg for * @return */ - private double singleExp(Collection window) { + private double ewma(Collection window) { double avg = 0; boolean first = true; @@ -266,11 +266,11 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { } /** - * Double exponential moving avg + * Holt-Linear (Double exponential) moving avg * @param window Window of values to compute movavg for * @return */ - private double doubleExp(Collection window) { + private double holt(Collection window) { double s = 0; double last_s = 0; @@ -410,7 +410,7 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { } @Test - public void singleSingleValuedField() { + public void ewmaSingleValuedField() { SearchResponse response = client() .prepareSearch("idx").setTypes("type") @@ -420,12 +420,12 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { .subAggregation(metric) .subAggregation(movingAvg("movavg_counts") .window(windowSize) - .modelBuilder(new SingleExpModel.SingleExpModelBuilder().alpha(alpha)) + .modelBuilder(new EwmaModel.EWMAModelBuilder().alpha(alpha)) .gapPolicy(gapPolicy) .setBucketsPaths("_count")) .subAggregation(movingAvg("movavg_values") .window(windowSize) - .modelBuilder(new SingleExpModel.SingleExpModelBuilder().alpha(alpha)) + .modelBuilder(new EwmaModel.EWMAModelBuilder().alpha(alpha)) .gapPolicy(gapPolicy) .setBucketsPaths("the_metric")) ).execute().actionGet(); @@ -438,8 +438,8 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { List buckets = histo.getBuckets(); assertThat("Size of buckets array is not correct.", buckets.size(), equalTo(mockHisto.size())); - List expectedCounts = testValues.get(MovAvgType.SINGLE.toString() + "_" + MetricTarget.COUNT.toString()); - List expectedValues = testValues.get(MovAvgType.SINGLE.toString() + "_" + MetricTarget.VALUE.toString()); + List expectedCounts = testValues.get(MovAvgType.EWMA.toString() + "_" + MetricTarget.COUNT.toString()); + List expectedValues = testValues.get(MovAvgType.EWMA.toString() + "_" + MetricTarget.VALUE.toString()); Iterator actualIter = buckets.iterator(); Iterator expectedBucketIter = mockHisto.iterator(); @@ -462,7 +462,7 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { } @Test - public void doubleSingleValuedField() { + public void holtSingleValuedField() { SearchResponse response = client() .prepareSearch("idx").setTypes("type") @@ -472,12 +472,12 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { .subAggregation(metric) .subAggregation(movingAvg("movavg_counts") .window(windowSize) - .modelBuilder(new DoubleExpModel.DoubleExpModelBuilder().alpha(alpha).beta(beta)) + .modelBuilder(new HoltLinearModel.HoltLinearModelBuilder().alpha(alpha).beta(beta)) .gapPolicy(gapPolicy) .setBucketsPaths("_count")) .subAggregation(movingAvg("movavg_values") .window(windowSize) - .modelBuilder(new DoubleExpModel.DoubleExpModelBuilder().alpha(alpha).beta(beta)) + .modelBuilder(new HoltLinearModel.HoltLinearModelBuilder().alpha(alpha).beta(beta)) .gapPolicy(gapPolicy) .setBucketsPaths("the_metric")) ).execute().actionGet(); @@ -490,8 +490,8 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { List buckets = histo.getBuckets(); assertThat("Size of buckets array is not correct.", buckets.size(), equalTo(mockHisto.size())); - List expectedCounts = testValues.get(MovAvgType.DOUBLE.toString() + "_" + MetricTarget.COUNT.toString()); - List expectedValues = testValues.get(MovAvgType.DOUBLE.toString() + "_" + MetricTarget.VALUE.toString()); + List expectedCounts = testValues.get(MovAvgType.HOLT.toString() + "_" + MetricTarget.COUNT.toString()); + List expectedValues = testValues.get(MovAvgType.HOLT.toString() + "_" + MetricTarget.VALUE.toString()); Iterator actualIter = buckets.iterator(); Iterator expectedBucketIter = mockHisto.iterator(); @@ -730,7 +730,7 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { currentValue = current.value(); if (gapPolicy.equals(BucketHelpers.GapPolicy.SKIP)) { - // if we are ignoring, movavg could go up (double_exp) or stay the same (simple, linear, single_exp) + // if we are ignoring, movavg could go up (holt) or stay the same (simple, linear, ewma) assertThat(Double.compare(lastValue, currentValue), lessThanOrEqualTo(0)); } else if (gapPolicy.equals(BucketHelpers.GapPolicy.INSERT_ZEROS)) { // If we insert zeros, this should always increase the moving avg since the last bucket has a real value @@ -789,7 +789,7 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { currentValue = current.value(); if (gapPolicy.equals(BucketHelpers.GapPolicy.SKIP)) { - // if we are ignoring, movavg could go up (double_exp) or stay the same (simple, linear, single_exp) + // if we are ignoring, movavg could go up (holt) or stay the same (simple, linear, ewma) assertThat(Double.compare(lastValue, currentValue), lessThanOrEqualTo(0)); } else if (gapPolicy.equals(BucketHelpers.GapPolicy.INSERT_ZEROS)) { // If we insert zeros, this should always increase the moving avg since the last bucket has a real value @@ -1055,9 +1055,9 @@ public class MovAvgTests extends ElasticsearchIntegrationTest { case 1: return new LinearModel.LinearModelBuilder(); case 2: - return new SingleExpModel.SingleExpModelBuilder().alpha(alpha); + return new EwmaModel.EWMAModelBuilder().alpha(alpha); case 3: - return new DoubleExpModel.DoubleExpModelBuilder().alpha(alpha).beta(beta); + return new HoltLinearModel.HoltLinearModelBuilder().alpha(alpha).beta(beta); default: return new SimpleModel.SimpleModelBuilder(); } diff --git a/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgUnitTests.java b/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgUnitTests.java index 156f4f873a7..2a3f862c321 100644 --- a/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgUnitTests.java +++ b/src/test/java/org/elasticsearch/search/aggregations/reducers/moving/avg/MovAvgUnitTests.java @@ -140,9 +140,9 @@ public class MovAvgUnitTests extends ElasticsearchTestCase { } @Test - public void testSingleExpMovAvgModel() { + public void testEWMAMovAvgModel() { double alpha = randomDouble(); - MovAvgModel model = new SingleExpModel(alpha); + MovAvgModel model = new EwmaModel(alpha); int numValues = randomIntBetween(1, 100); int windowSize = randomIntBetween(1, 50); @@ -170,9 +170,9 @@ public class MovAvgUnitTests extends ElasticsearchTestCase { } @Test - public void testSinglePredictionModel() { + public void testEWMAPredictionModel() { double alpha = randomDouble(); - MovAvgModel model = new SingleExpModel(alpha); + MovAvgModel model = new EwmaModel(alpha); int windowSize = randomIntBetween(1, 50); int numPredictions = randomIntBetween(1,50); @@ -206,10 +206,10 @@ public class MovAvgUnitTests extends ElasticsearchTestCase { } @Test - public void testDoubleExpMovAvgModel() { + public void testHoltLinearMovAvgModel() { double alpha = randomDouble(); double beta = randomDouble(); - MovAvgModel model = new DoubleExpModel(alpha, beta); + MovAvgModel model = new HoltLinearModel(alpha, beta); int numValues = randomIntBetween(1, 100); int windowSize = randomIntBetween(1, 50); @@ -250,10 +250,10 @@ public class MovAvgUnitTests extends ElasticsearchTestCase { } @Test - public void testDoublePredictionModel() { + public void testHoltLinearPredictionModel() { double alpha = randomDouble(); double beta = randomDouble(); - MovAvgModel model = new DoubleExpModel(alpha, beta); + MovAvgModel model = new HoltLinearModel(alpha, beta); int windowSize = randomIntBetween(1, 50); int numPredictions = randomIntBetween(1,50);