view release on metacpan or  search on metacpan

lib/App/Chart/Math/Moving/EMA.pm  view on Meta::CPAN

# Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2011 Kevin Ryde

# This file is part of Chart.
#
# Chart is free software; you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation; either version 3, or (at your option) any later version.
#
# Chart is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
# details.
#
# You should have received a copy of the GNU General Public License along
# with Chart.  If not, see <http://www.gnu.org/licenses/>.

package App::Chart::Math::Moving::EMA;
require 5;
use strict;
use warnings;
use Carp;
use POSIX ();

use vars '@ISA';
@ISA = ('App::Chart::Math::Moving');

use constant type => 'average';
use constant parameter_info_array =>
  [ { name      => 'N',
      share_key => 'ema_N',
      type      => 'float',
      minimum   => 1,
      default   => 20,
      decimals  => 0,
      step      => 1,
    },
  ];

sub warmup_omitted_fraction {
  my ($self) = @_;
  return $self->{'warmup_omitted_fraction'} || 0.001;
}

sub new {
  my $class = shift;
  my $self = SUPER::new (@_);
  $self->{'f'}      = $self->N_to_f ($self->{'N'});
  $self->{'alpha'}  = $self->N_to_alpha ($self->{'N'});
  $self->{'sum'}    = 0;
  $self->{'weight'} = 0;
  return $self;
}

sub next {
  my ($self, $value) = @_;

  # $sum is v0 + v1*f + v2*f^2 + v3*f^3 + ... + vk*f^k, for as many $value's
  # as so far entered
  #
  # $weight is the corresponding 1 + f + f^2 + ... + f^k.  This approaches
  # 1/(1-f), but on the first few outputs it's much smaller, so must
  # calculate it explicitly.

  return ($self->{'sum'}
          = $self->{'sum'} * $self->{'f'} + $value * $self->{'alpha'})
    / ($self->{'weight'}
       = $self->{'weight'} * $self->{'f'} + $self->{'alpha'});
}

sub warmup_count {
  my ($self) = @_;
  if ($self->{'N'} <= 1) {
    return 0;
  } else {
    return _ema_omitted_search ($self->{'f'},
                               $self->warmup_omitted_fraction) - 1 ;
  }
}

# _ema_omitted_search() returns the number of terms t needed in an EMA to
# have an omitted part <= TARGET, where target is a proportion between 0 and
# 1.  This means
#
#     Omitted(t-1) <= target
#     f^t <= target
#     t >= log(target) / log(f)
#
# Can have f==0 when count==1 (a degenerate EMA, which just follows the
# given points exactly).  log(0) isn't supported on guile 1.6, hence the
# special case.
#
# Actually log(f) approaches -2/N as N increases, but it's easy enough to
# do the calculation exactly.
#
sub _ema_omitted_search {
  my ($f, $target) = @_;
  if ($f == 0) {
    return 0;
  } else {
    return POSIX::ceil (log($target) / log($f));
  }
}

# ema_omitted() returns the fraction (between 0 and 1) of weight omitted by
# stopping an EMA at the f^k term, which means the first k+1 terms.
#