welford_variance

eve::welford_variance = functor<welford_variance_t>

inlineconstexpr

Header file

#include <eve/module/core.hpp>

Callable Signatures

namespace eve
{
   // Regular overloads
   constexpr auto welford_variance(auto x, auto ... xs)                  noexcept; /1
   constexpr auto welford_average(non_empty_product_type xs)             noexcept; /2
 
   //Semantic options
   constexpr auto welford_variance[widen](/*any previous overloads*/)    noexcept; /3
   constexpr auto welford_variance[unbiased](/*any previous overloads*/) noexcept; /4
}

Parameters

• xs:the parameters can be a mix of floating values or previous results of calls to welford_variance or a tuple of them

Return value

1. A struct containing The value of the arithmetic mean (average), the centered moment of order 2 (m2), the (sample) variance value normalized by the number of elements involved (variance) and the number of elements (count) involved is returned.
   This struct is convertble to the variance floating value. and possess four fields variance, average m2 and count.
2. The computation is made on the tuples elements
3. The computation and result use the upgraded data type if available
4. with this option the normalisation is done by by the number of elements involved, minus one. This provides the best unbiased estimator of the variance (population variance).

Note

The Welford algorithm does not provides as much option as the `variance` function, but is a quite stable algorithm that have the advantage to allow spliting the computation of the variance in multiple calls. For instance: the call with two tuples:
  wv = welford_corariance(kumi::cat(xs, ys))
is equivalent to the sequence:
  wxs = welford_variance(xs); wys = welford_variance(xs); wv = welford_variance(wxs, wys);
But the first two instructions can easily be executed in parallel.

External references

• Wikipedia Mean
• Wikipedia Variance
• E.Schubert and M. Gertz

Example

// revision 0
#include <eve/module/core.hpp>
#include <iostream>
#include <iomanip>
#include <tts/tts.hpp>
 
int main()
{
  eve::wide wf0{0.0, 1.0, 2.0, 3.0, -1.0, -2.0, -3.0, -4.0};
  eve::wide wf1{2.0, 3.0, -1.0, -2.0, -3.0, -4.0, 18.0, 32.0};
  using t_t = decltype(wf0);
 
  std::cout << "<- wf0                                    = " << wf0 << "\n";
  std::cout << "<- wf1                                    = " << wf1 << "\n";
 
  auto ma = eve::welford_variance(wf0, 2*wf0, 3*wf0);
  auto mb = eve::welford_variance(wf1, wf0);
  auto mab= eve::welford_variance(wf0, 2*wf0, 3*wf0, wf1, wf0);
  auto wmab = eve::welford_variance(ma, mb);
  std::cout << "ma = welford_variance(wf0, 2*wf0, 3*wf0)   = " << t_t(ma) << std::endl;
  std::cout << "mb = welford_variance(wf1, wf0)            = " << t_t(mb) << std::endl;
  std::cout << "eve::variance(wf0, 2*wf0, 3*wf0, wf1, wf0) = " << mab << std::endl;
  std::cout << "eve::welford_variance(ma, mb)              = " << t_t(wmab) << std::endl;
  auto vw = eve::welford_variance(4.0f, 3.0f, 2.0f, 1.0f);
  std::cout << "avg " << vw.average<< std::endl;
  std::cout << "var " << vw.variance << std::endl;
  std::cout << "s2  " << vw.m2   << std::endl;
  std::cout << eve::welford_variance[eve::unbiased](4.0f, 3.0f, 2.0f, 1.0f)<< std::endl;
  std::cout << eve::welford_variance(
    eve::welford_variance(1.0f, 2.0f),
    eve::welford_variance(3.0f, 4.0f))<< std::endl;
  std::cout << eve::welford_variance[eve::unbiased](
    eve::welford_variance(1.0f, 2.0f),
    eve::welford_variance(3.0f, 4.0f))<< std::endl;
}