blib/lib/Math/StdDev.pm

filter: Statementstmt 92.8% 52 / 56 Branchbran 66.6% 12 / 18 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod 100% 5 / 5 totaltotal 88.3% 76 / 86 CC 12 SCAR 12.2
CC
12
Cov
86%
new
5.0
sampleVariance
3.8
mean
3.1
CRAP 3.4
↑ Summary
1 package Math::StdDev;
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 # perl -MPod::Markdown -e 'Pod::Markdown->new->filter(@ARGV)' lib/Math/StdDev.pm > README.md
7  
8 =head1 NAME
9  
10 Math::StdDev - Pure-perl mean and variance computation supporting running/online calculation (Welford's algorithm)
11  
12 =head1 SYNOPSIS
13  
14  
15 #!/usr/bin/perl -w
16
17 use Math::StdDev;
18  
19 my $d = new Math::StdDev();
20 $d->Update(2);
21 $d->Update(3);
22 print $d->mean() . "\t" . $d->sampleVariance(); # or $d->variance()
23  
24 or
25  
26 perl -MMath::StdDev -e '$d=new Math::StdDev; $d->Update(10**8+4, 10**8 + 7, 10**8 + 13, 10**8 + 16); print $d->mean() . "\n" . $d->sampleVariance() . "\n"'
27  
28  
29 =head1 DESCRIPTION
30  
31 This module impliments Welford's online algorithm (see https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance )
32 Maybe one day in future the two-pass algo could be included, along with Kahan compensated summation... so much math, so little time...
33  
34  
35 =head2 EXPORT
36  
37 None by default.
38  
39  
40 =head2 Notes
41  
42 =head2 new
43  
44 Usage is
45  
46 my $d = new Math::StdDev();
47 or
48 my $d = new Math::StdDev(1,2,3,4); # Add one or more samples, or a population, right from the start
49  
50  
51 =head2 Update
52  
53 Usage is
54  
55 my $d->Update(123);
56 or
57 my $d->Update(@list_of_scalars);
58  
59 =head2 mean()
60  
61 Usage is
62  
63 print $d->mean();
64  
65 =head2 variance
66  
67 Usage is
68  
69 print $d->variance();
70  
71 =head2 sampleVariance
72  
73 (same as variance, but uses n-1 divisor.) Usage is:
74  
75 print $d->sampleVariance();
76  
77 =cut
78  
79 1 require Exporter;
80  
81 1 our @ISA = qw(Exporter);
82 1 our($VERSION)='1.02';
83 1 our($UntarError) = '';
84  
85 1 our %EXPORT_TAGS = ( 'all' => [ qw( ) ] );
86  
87 1 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
88  
89 1 our @EXPORT = qw( );
90  
91  
92 2 ▶sub new {
Subroutine new: called CC=5 SCAR=16.1
Pod documented
93 2 my $class = shift;
94 2 my $this={};
95 2 $this->{count}=0;
96 2 $this->{mean}=0;
97 2 $this->{M2}=0;
98  
99 2 bless $this,$class;
100 2 ▶ if(defined $_[0]) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[0]) 2 0 2
101 2 $this->Update(@_); # Include anything passed into the new()
102 # Also compute the exact correct result using the 2-pass method, in case they're not going to provide more samples later
103 2 my $s=0;$s+=$_ foreach(@_);
104 2 my $m=$s/(1+$#_);
105 2 my $v=0;$v+=($_-$m)**2 foreach(@_);
106 2 $this->{exactMean}=$m;
107 2 $this->{exactVariance}=($v/(1+$#_))**.5;
108 2 ▶ $this->{exactSampleVariance}=($v/($#_))**.5 if($#_>0);
Branch: 1 branch
BranchTrueFalseTotal
if $#_ > 0 2 0 2
109 }
110  
111 2 return $this;
112 } # new
113  
114  
115 # # for a new value newValue, compute the new count, new mean, the new M2.
116 # # mean accumulates the mean of the entire dataset
117 # # M2 aggregates the squared distance from the mean
118 # # count aggregates the number of samples seen so far
119 # def update(existingAggregate, newValue):
120 # (count, mean, M2) = existingAggregate
121 # count += 1
122 # delta = newValue - mean
123 # mean += delta / count
124 # delta2 = newValue - mean
125 # M2 += delta * delta2
126 #
127 # return (count, mean, M2)
128 #
129 # # retrieve the mean, variance and sample variance from an aggregate
130 # def finalize(existingAggregate):
131 # (count, mean, M2) = existingAggregate
132 # (mean, variance, sampleVariance) = (mean, M2/count, M2/(count - 1))
133 # if count < 2:
134 # return float('nan')
135 # else:
136 # return (mean, variance, sampleVariance)
137  
138  
139  
140 3 ▶sub Update {
Subroutine Update: called CC=2 SCAR=6.9
Pod documented
141 3 my $this = shift;
142 3 ▶ while(defined($_[0])) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[0]) 16 3 19
143 16 my $newValue=shift;
144 16 $this->{count}++;
145 16 my $delta = $newValue - $this->{mean};
146 16 $this->{mean} += $delta / $this->{count};
147 16 my $delta2 = $newValue - $this->{mean};
148 16 $this->{M2} += $delta * $delta2;
149 }
150 3 undef($this->{exactMean}); # switch over to online method instead of two-pass method
151 } # Update
152  
153 3 ▶sub mean {
Subroutine mean: called CC=3 SCAR=11.3
Pod documented
154 3 my $this = shift;
155 0 ▶ if($this->{count}<1) { return undef; }
Branch: 1 branch
BranchTrueFalseTotal
if ($this->{"count"} < 1) 0 3 3
156 3 ▶ return $this->{exactMean} if(defined $this->{exactMean});
Branch: 1 branch
BranchTrueFalseTotal
if defined $this->{"exactMean"} 1 2 3
157 2 return $this->{mean};
158 }
159  
160 4 ▶sub variance {
Subroutine variance: called CC=3 SCAR=11.3
Pod documented
161 4 my $this = shift;
162 0 ▶ if($this->{count}<1) { return undef; }
Branch: 1 branch
BranchTrueFalseTotal
if ($this->{"count"} < 1) 0 4 4
163 4 ▶ return $this->{exactVariance} if(defined $this->{exactMean});
Branch: 1 branch
BranchTrueFalseTotal
if defined $this->{"exactMean"} 2 2 4
164 2 return ($this->{M2}/$this->{count})**0.5;
165 }
166  
167 2 ▶sub sampleVariance {
Subroutine sampleVariance: called CC=3 SCAR=13.3
Pod documented
168 2 my $this = shift;
169 0 ▶ if($this->{count}<2) { return undef; }
Branch: 1 branch
BranchTrueFalseTotal
if ($this->{"count"} < 2) 0 2 2
170 2 ▶ return $this->{exactSampleVariance} if(defined $this->{exactMean});
Branch: 1 branch
BranchTrueFalseTotal
if defined $this->{"exactMean"} 2 0 2
171 0 return ($this->{M2}/($this->{count}-1))**0.5;
172 }
173  
174  
175 1 1;
176  
177 __END__
↑ Summary