DOC: fix conflicting ewma documentation

[Komnomnomnom]

The information in the docs, in the parameter description and in the body of the docstring is conflicting. This should hopefully make them consistent amongst themselves (and with the code).

[cpcloud]

should these stray \alphas really be :math:\alpha``?

[Komnomnomnom]

Good point! I've updated it so they're all mathified :-)

[cpcloud]

excellent!

[Komnomnomnom]

Just noticed #4321 which should be covered by these fixes too (it only updates the docs).

[jreback]

are the docs existing docs just inconsistent with the code (before this change / #4321?)

[Komnomnomnom]

Yep the docs are inconsistent right now but how they are fixed depends on whether you define alpha = 1 / (1 + c) or alpha = 1 - (1 / (1+c)) = c / (1 + c), unfortunately the current docstring and docs have a mix of both of these.

I've made these changes with alpha = 1 / (1 + c) in mind as that's what I'm familiar with. Here's the relevant bits from the code (algos.pyx)

neww = 1. / (1. + com)
oldw = 1. - neww   
...
output[i] = oldw * prev + neww * cur

Given the definition for alpha = 1 / (1 + com) implies neww = alpha and oldw = 1 - alpha. Assuming prev = output[i-1] = y_t-1 and cur = x_t means the docs should read

y_t = (1 - \alpha) y_{t-1} + \alpha x_t

as they do with this fix, and the fix in #4321.

As I said you can do it all the other way around by defining alpha = 1 - 1 / (1 + c) but you'd still need to update the docs and docstring to make it all consistent (the docs right now define alpha = 1 / (1 + c) but matching the given formula to the code implies alpha = 1 - (1 / (1 +c))). The docstring is similarly conflicted.

[jreback]

@Komnomnomnom ok...but your changes make this consistent (with the def of alpha that you are showing)...so that is fine (you might want to mention that it can be done the other way too...., but not go into detail)

[Komnomnomnom]

Ok I added a very short note to the docs.

[jreback]

@Komnomnomnom merge?
@cpcloud ok?

[Komnomnomnom]

Yep, go for it. If someone wants to change the wording or anything feel free.