blib/lib/Statistics/Regression.pm

filter: Statementstmt 8.4% 12 / 142 Branchbran 0.0% 0 / 66 Conditioncond 0.0% 0 / 7 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 16.6% 3 / 18 Podpod 80.0% 12 / 15 totaltotal 10.7% 27 / 252 CC 37 SCAR 42.0
CC
37
Cov
6%
include
182.0
theta
72.0
print1val
56.5
CRAP 66.6
« blib/lib/Chemistry/File/PDB.pm ↑ Summary blib/lib/Chemistry/Reaction.pm »
1 package Statistics::Regression;
2  
3 10 $VERSION = '0.15';
4  
5 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 ################################################################
8 10 ▶use constant TINY => 1e-8;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 ################################################################
10  
11 =head1 NAME
12  
13 Regression.pm - weighted linear regression package (line+plane fitting)
14  
15 =head1 SYNOPSIS
16  
17 use Statistics::Regression;
18  
19 # Create regression object
20 my $reg = Statistics::Regression->new(
21 3, "sample regression",
22 [ "const", "someX", "someY" ]
23 );
24  
25 # Add data points
26 $reg->include( 2.0, [ 1.0, 3.0, -1.0 ] );
27 $reg->include( 1.0, [ 1.0, 5.0, 2.0 ] );
28 $reg->include( 20.0, [ 1.0, 31.0, 0.0 ] );
29 $reg->include( 15.0, [ 1.0, 11.0, 2.0 ] );
30  
31 # Print the result
32 $reg->print();
33  
34 # Prints the following:
35 # ****************************************************************
36 # Regression 'sample regression'
37 # ****************************************************************
38 # Theta[0='const']= 0.2950
39 # Theta[1='someX']= 0.6723
40 # Theta[2='someY']= 1.0688
41 # R^2= 0.808, N= 4
42 # ****************************************************************
43  
44 # Or, to get the values of the coefficients and R^2
45 my @theta = $reg->theta;
46 my $rsq = $reg->rsq;
47  
48 =head1 DESCRIPTION
49  
50 Regression.pm is a multivariate linear regression package. That is, it
51 estimates the c coefficients for a line-fit of the type
52  
53 y= c(0)*x(0) + c(1)*x1 + c(2)*x2 + ... + c(k)*xk
54  
55 given a data set of N observations, each with k independent x variables and one
56 y variable. Naturally, N must be greater than k---and preferably considerably
57 greater. Any reasonable undergraduate statistics book will explain what a
58 regression is. Most of the time, the user will provide a constant ('1') as
59 x(0) for each observation in order to allow the regression package to fit an
60 intercept.
61  
62 =head1 ALGORITHM
63  
64 =head2 Original Algorithm (ALGOL-60):
65  
66 W. M. Gentleman, University of Waterloo, "Basic Description
67 For Large, Sparse Or Weighted Linear Least Squares Problems
68 (Algorithm AS 75)," Applied Statistics (1974) Vol 23; No. 3
69  
70 =head2 INTERNALS
71  
72 R=Rbar is an upperright triangular matrix, kept in normalized
73 form with implicit 1's on the diagonal. D is a diagonal scaling
74 matrix. These correspond to "standard Regression usage" as
75  
76 X' X = R' D R
77  
78 A backsubsitution routine (in thetacov) allows to invert the R
79 matrix (the inverse is upper-right triangular, too!). Call this
80 matrix H, that is H=R^(-1).
81  
82 (X' X)^(-1) = [(R' D^(1/2)') (D^(1/2) R)]^(-1)
83 = [ R^-1 D^(-1/2) ] [ R^-1 D^(-1/2) ]'
84  
85 =head2 Remarks
86  
87 This algorithm is the statistical "standard." Insertion of a new observation
88 can be done one obs at any time (WITH A WEIGHT!), and still only takes a low
89 quadratic time. The storage space requirement is of quadratic order (in the
90 indep variables). A practically infinite number of observations can easily be
91 processed!
92  
93  
94 =head1 METHODS
95  
96 =cut
97  
98 ################################################################
99  
100  
101 #### let's start with handling of missing data ("nan" or "NaN")
102  
103 10 my $nan= "NaN";
104 0 ▶sub isNaN {
Subroutine isNaN: not called CC=3 SCAR=24.8
Pod undocumented
105 0 ▶ if ($_[0] !~ /[0-9nan]/) { die "definitely not a number in NaN: '$_[0]'"; }
Branch: 1 branch
BranchTrueFalseTotal
unless ($_[0] =~ /[0-9nan]/) 0 0 0
106 0 ▶ return ($_[0]=~ /NaN/i) || ($_[0] != $_[0]);
Condition0%0/3
$_[0] =~ /NaN/i || $_[0] != $_[0]
l!l&&r!l&&!r
000
MC/DC0%0/2
$_[0] =~ /NaN/i || $_[0] != $_[0]
$_[0] =~ /NaN/i $_[0] != $_[0]
Truth table0%0/3
A || B
A= $_[0] =~ /NaN/iB= $_[0] != $_[0]
ABresult
1X1
011
000
107 }
108  
109  
110 ################################################################
111  
112 =head2 new
113  
114 my $reg = Statistics::Regression->new($n, $name, \@var_names)
115  
116 Receives the number of variables on each observations (i.e., an integer) and
117 returns the blessed data structure as a Statistics::Regression object. Also
118 takes an optional name for this regression to remember, as well as a reference
119 to a k*1 array of names for the X coefficients.
120  
121 =cut
122  
123 ################################################################
124 0 ▶sub new {
Subroutine new: not called CC=4 SCAR=30.0
Pod documented
125 0 my $classname= shift(@_);
126 0 my $K= shift(@_); # the number of variables
127 0 ▶ my $regname= shift(@_) || "with no name";
Condition0%0/2
shift @_ || 'with no name'
l!l
00
MC/DC0%0/1
shift @_ || 'with no name'
shift @_
Truth table0%0/2
A
A= shift @_
Aresult
11
00
128  
129 0 ▶ if (!defined($K)) { die "Regression->new needs at least one argument for the number of variables"; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $K) 0 0 0
130 0 ▶ if ($K<=1) { die "Cannot run a regression without at least two variables."; }
Branch: 1 branch
BranchTrueFalseTotal
if ($K <= 1) 0 0 0
131  
132 0 ▶ sub zerovec {
Subroutine zerovec: not called CC=2 SCAR=17.9
Pod undocumented
133 0 my @rv;
134 0 ▶ for (my $i=0; $i<=$_[0]; ++$i) { $rv[$i]=0; }
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= $_[0]) 0 0 0
135 0 return \@rv;
136 }
137  
138 0 bless {
139 k => $K,
140 regname => $regname,
141 xnames => shift(@_),
142  
143 # constantly updated
144 n => 0,
145 sse => 0,
146 syy => 0,
147 sy => 0,
148 wghtn => 0,
149 d => zerovec($K),
150 thetabar => zerovec($K),
151 rbarsize => ($K+1)*$K/2+1,
152 rbar => zerovec(($K+1)*$K/2+1),
153  
154 # other constants
155 neverabort => 0,
156  
157 # computed on demand
158 theta => undef,
159 sigmasq => undef,
160 rsq => undef,
161 adjrsq => undef
162 }, $classname;
163 }
164  
165 ################################################################
166  
167 =head2 dump
168  
169 $reg->dump
170  
171 Used for debugging.
172  
173 =cut
174  
175 ################################################################
176 0 ▶sub dump {
Subroutine dump: not called CC=2 SCAR=16.5
Pod documented
177 0 my $this= $_[0];
178 0 print "****************************************************************\n";
179 0 print "Regression '$this->{regname}'\n";
180 0 print "****************************************************************\n";
181 0 ▶ sub print1val {
Subroutine print1val: not called CC=8 SCAR=40.3
Pod undocumented
182 10 ▶ no strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
183 0 ▶ print "$_[1]($_[2])=\t". ((defined($_[0]->{ $_[2] }) ? $_[0]->{ $_[2] } : "intentionally undef"));
Branch: 1 branch
BranchTrueFalseTotal
defined $_[0]{$_[2]} ? : 0 0 0
184  
185 0 my $ref=$_[0]->{ $_[2] };
186  
187 0 ▶ if (ref($ref) eq 'ARRAY') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $ref eq 'ARRAY') { } 0 0 0
elsif (ref $ref eq 'HASH') { } 0 0 0
188 0 my $arrayref= $ref;
189 0 print " $#$arrayref+1 elements:\n";
190 0 ▶ if ($#$arrayref>30) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arrayref->$#* > 30) { } 0 0 0
191 0 print "\t";
192 0 ▶ for(my $i=0; $i<$#$arrayref+1; ++$i) { print "$i='$arrayref->[$i]';"; }
Branch: 1 branch
BranchTrueFalseTotal
if ($i < $arrayref->$#* + 1) 0 0 0
193 0 print "\n";
194 }
195 else {
196 0 ▶ for(my $i=0; $i<$#$arrayref+1; ++$i) { print "\t$i=\t'$arrayref->[$i]'\n"; }
Branch: 1 branch
BranchTrueFalseTotal
if ($i < $arrayref->$#* + 1) 0 0 0
197 }
198 }
199 elsif (ref($ref) eq 'HASH') {
200 0 my $hashref= $ref;
201 0 print " ".scalar(keys(%$hashref))." elements\n";
202 0 ▶ while (my ($key, $val) = each(%$hashref)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$hashref) 0 0 0
203 0 print "\t'$key'=>'$val';\n";
204 }
205 }
206 else {
207 0 print " [was scalar]\n"; }
208 }
209  
210 0 ▶ while (my ($key, $val) = each(%$this)) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$this) 0 0 0
211 0 $this->print1val($key, $key);
212 }
213 0 print "****************************************************************\n";
214 }
215  
216 ################################################################
217  
218 =head2 print
219  
220 $reg->print
221  
222 prints the estimated coefficients, and R^2 and N. For an example see the
223 SYNOPSIS.
224  
225 =cut
226  
227 ################################################################
228 0 ▶sub print {
Subroutine print: not called CC=3 SCAR=24.8
Pod documented
229 0 my $this= $_[0];
230 0 print "****************************************************************\n";
231 0 print "Regression '$this->{regname}'\n";
232 0 print "****************************************************************\n";
233  
234 0 my $theta= $this->theta();
235  
236 0 ▶ for (my $i=0; $i< $this->k(); ++$i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < $this->k) 0 0 0
237 0 ▶ print "Theta[$i".(defined($this->{xnames}->[$i]) ? "='$this->{xnames}->[$i]'":"")."]= ".sprintf("%12.4f", $theta->[$i])."\n";
Branch: 1 branch
BranchTrueFalseTotal
defined $this->{'xnames'}[$i] ? : 0 0 0
238 }
239 0 print "R^2= ".sprintf("%.3f", $this->rsq()).", N= ".$this->n()."\n";
240 0 print "****************************************************************\n";
241 }
242  
243  
244 ################################################################
245  
246 =head2 include
247  
248 $n = $reg->include( $y, [ $x1, $x2, $x3 ... $xk ], $weight );
249  
250 Add one new observation. The weight is optional. Note that inclusion with a
251 weight of -1 can be used to delete an observation.
252  
253 Returns the number of observations so far included.
254  
255 =cut
256  
257 ################################################################
258 0 ▶sub include {
Subroutine include: not called CC=13 SCAR=52.0
Pod documented
259 0 my $this = shift();
260 0 my $yelement= shift();
261 0 my $xrow= shift();
262 0 ▶ my $weight= shift() || 1.0;
Condition0%0/2
shift() || 1.0
l!l
00
MC/DC0%0/1
shift() || 1.0
shift()
Truth table0%0/2
A
A= shift()
Aresult
11
00
263  
264 # omit observations with missing observations;
265 0 ▶ if (!defined($yelement)) { die "Internal Error: yelement is undef"; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $yelement) 0 0 0
266 0 ▶ if (isNaN($yelement)) { return $this->{n}; }
Branch: 1 branch
BranchTrueFalseTotal
if (isNaN($yelement)) 0 0 0
267  
268 0 my @xcopy;
269 0 ▶ for (my $i=1; $i<=$this->{k}; ++$i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= $this->{"k"}) 0 0 0
270 0 ▶ if (!defined($xrow->[$i-1])) { die "Internal Error: xrow [ $i-1 ] is undef"; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $$xrow[$i - 1]) 0 0 0
271 0 ▶ if (isNaN($xrow->[$i-1])) { return $this->{n}; }
Branch: 1 branch
BranchTrueFalseTotal
if (isNaN($$xrow[$i - 1])) 0 0 0
272 0 $xcopy[$i]= $xrow->[$i-1];
273 }
274  
275 0 $this->{syy}+= ($weight*($yelement*$yelement));
276 0 $this->{sy}+= ($weight*($yelement));
277 0 ▶ if ($weight>=0.0) { ++$this->{n}; } else { --$this->{n}; }
Branch: 1 branch
BranchTrueFalseTotal
if ($weight >= 0.0) { } 0 0 0
278  
279 0 $this->{wghtn}+= $weight;
280  
281 0 ▶ for (my $i=1; $i<=$this->{k};++$i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= $this->{"k"}) 0 0 0
282 0 ▶ if ($weight==0.0) { return $this->{n}; }
Branch: 1 branch
BranchTrueFalseTotal
if ($weight == 0) 0 0 0
283 0 ▶ if (abs($xcopy[$i])>(TINY)) {
Branch: 1 branch
BranchTrueFalseTotal
if (abs $xcopy[$i] > "1e-08") 0 0 0
284 0 my $xi=$xcopy[$i];
285  
286 0 my $di=$this->{d}->[$i];
287 0 my $dprimei=$di+$weight*($xi*$xi);
288 0 my $cbar= $di/$dprimei;
289 0 my $sbar= $weight*$xi/$dprimei;
290 0 $weight*=($cbar);
291 0 $this->{d}->[$i]=$dprimei;
292 0 my $nextr=int( (($i-1)*( (2.0*$this->{k}-$i))/2.0+1) );
293 0 ▶ if (!($nextr<=$this->{rbarsize}) ) { die "Internal Error 2"; }
Branch: 1 branch
BranchTrueFalseTotal
unless ($nextr <= $this->{"rbarsize"}) 0 0 0
294 0 my $xk;
295 0 ▶ for (my $kc=$i+1;$kc<=$this->{k};++$kc) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kc <= $this->{"k"}) 0 0 0
296 0 $xk=$xcopy[$kc]; $xcopy[$kc]=$xk-$xi*$this->{rbar}->[$nextr];
297 0 $this->{rbar}->[$nextr]= $cbar * $this->{rbar}->[$nextr]+$sbar*$xk;
298 0 ++$nextr;
299 }
300 0 $xk=$yelement; $yelement-= $xi*$this->{thetabar}->[$i];
301 0 $this->{thetabar}->[$i]= $cbar*$this->{thetabar}->[$i]+$sbar*$xk;
302 }
303 }
304 0 $this->{sse}+=$weight*($yelement*$yelement);
305  
306 # indicate that Theta is garbage now
307 0 $this->{theta}= undef;
308 0 $this->{sigmasq}= undef; $this->{rsq}= undef; $this->{adjrsq}= undef;
309  
310 0 return $this->{n};
311 }
312  
313  
314  
315 ################################################################
316  
317  
318 =head2 theta
319  
320 $theta = $reg->theta
321 @theta = $reg->theta
322  
323 Estimates and returns the vector of coefficients. In scalar context returns an
324 array reference; in list context it returns the list of coefficients.
325  
326 =cut
327  
328 ################################################################
329  
330 0 ▶sub theta {
Subroutine theta: not called CC=8 SCAR=42.8
Pod documented
331 0 my $this= shift();
332  
333 0 ▶ if (defined($this->{theta})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $this->{"theta"}) 0 0 0
334 0 ▶ return wantarray ? @{$this->{theta}} : $this->{theta};
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
335 }
336  
337 0 ▶ if ($this->{n} < $this->{k}) { return; }
Branch: 1 branch
BranchTrueFalseTotal
if ($this->{"n"} < $this->{"k"}) 0 0 0
338 0 ▶ for (my $i=($this->{k}); $i>=1; --$i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i >= 1) 0 0 0
339 0 $this->{theta}->[$i]= $this->{thetabar}->[$i];
340 0 my $nextr= int (($i-1)*((2.0*$this->{k}-$i))/2.0+1);
341 0 ▶ if (!($nextr<=$this->{rbarsize})) { die "Internal Error 3"; }
Branch: 1 branch
BranchTrueFalseTotal
unless ($nextr <= $this->{"rbarsize"}) 0 0 0
342 0 ▶ for (my $kc=$i+1;$kc<=$this->{k};++$kc) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kc <= $this->{"k"}) 0 0 0
343 0 $this->{theta}->[$i]-=($this->{rbar}->[$nextr]*$this->{theta}->[$kc]);
344 0 ++$nextr;
345 }
346 }
347  
348 0 my $ref = $this->{theta}; shift(@$ref); # we are counting from 0
349  
350 # if in a scalar context, otherwise please return the array directly
351 0 ▶ wantarray ? @{$this->{theta}} : $this->{theta};
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
352 }
353  
354 ################################################################
355  
356 =head2 rsq, adjrsq, sigmasq, ybar, sst, k, n
357  
358 $rsq = $reg->rsq; # etc...
359  
360 These methods provide common auxiliary information. rsq, adjrsq,
361 sigmasq, sst, and ybar have not been checked but are likely correct.
362 The results are stored for later usage, although this is somewhat
363 unnecessary because the computation is so simple anyway.
364  
365 =cut
366  
367 ################################################################
368  
369 0 ▶sub rsq {
Subroutine rsq: not called CC=1 SCAR=6.9
Pod documented
370 0 my $this= shift();
371 0 return $this->{rsq}= 1.0- $this->{sse} / $this->sst();
372 }
373  
374 0 ▶sub adjrsq {
Subroutine adjrsq: not called CC=1 SCAR=6.9
Pod documented
375 0 my $this= shift();
376 0 return $this->{adjrsq}= 1.0- (1.0- $this->rsq())*($this->{n}-1)/($this->{n} - $this->{k});
377 }
378  
379 0 ▶sub sigmasq {
Subroutine sigmasq: not called CC=2 SCAR=17.9
Pod documented
380 0 my $this= shift();
381 0 ▶ return $this->{sigmasq}= ($this->{n}<=$this->{k}) ? "Inf" : ($this->{sse}/($this->{n} - $this->{k}));
Branch: 1 branch
BranchTrueFalseTotal
$this->{'n'} <= $this->{'k'} ? : 0 0 0
382 }
383  
384 0 ▶sub ybar {
Subroutine ybar: not called CC=1 SCAR=6.9
Pod documented
385 0 my $this= shift();
386 0 return $this->{ybar}= $this->{sy}/$this->{wghtn};
387 }
388  
389 0 ▶sub sst {
Subroutine sst: not called CC=1 SCAR=6.9
Pod documented
390 0 my $this= shift();
391 0 return $this->{sst}= ($this->{syy} - $this->{wghtn}*($this->ybar())**2);
392 }
393  
394 0 ▶sub k {
Subroutine k: not called CC=1 SCAR=6.9
Pod documented
395 0 my $this= shift();
396 0 return $this->{k};
397 }
398 0 ▶sub n {
Subroutine n: not called CC=1 SCAR=6.9
Pod documented
399 0 my $this= shift();
400 0 return $this->{n};
401 }
402  
403  
404 ################################################################
405  
406 =head1 BUGS/PROBLEMS
407  
408 =over 4
409  
410 =item Missing
411  
412 This package lacks routines to compute the standard errors of
413 the coefficients. This requires access to a matrix inversion
414 package, and I do not have one at my disposal. If you want to
415 add one, please let me know.
416  
417 =item Perl Problem
418  
419 perl is unaware of IEEE number representations. This makes it a
420 pain to test whether an observation contains any missing
421 variables (coded as 'NaN' in Regression.pm).
422  
423 =back
424  
425 =for comment
426 pod2html -noindex -title "perl weighted least squares regression package" Regression.pm > Regression.html
427  
428 =head1 VERSION
429  
430 0.15
431  
432 =head1 AUTHOR
433  
434 Naturally, Gentleman invented this algorithm. Adaptation by ivo welch. Alan
435 Miller (alan@dmsmelb.mel.dms.CSIRO.AU) pointed out nicer ways to compute the
436 R^2. Ivan Tubert-Brohman helped wrap the module as as standard CPAN
437 distribution.
438  
439 =head1 LICENSE
440  
441 This module is released for free public use under a GPL license.
442  
443 (C) Ivo Welch, 2001,2004.
444  
445 =cut
446  
447 10 1;
448  
449 # vim: sw=2 sts=2
« blib/lib/Chemistry/File/PDB.pm ↑ Summary blib/lib/Chemistry/Reaction.pm »