.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Statistics::OnLine 3pm" .TH Statistics::OnLine 3pm "2009-09-04" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Statistics::OnLine \- Pure Perl implementation of the on\-line algorithm to produce statistics .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Statistics::OnLine; \& my $s = Statistics::OnLine\->new; \& \& my @data = (1, 2, 3, 4, 5); \& $s\->add_data( @data ); \& $s\->add_data( 6, 7 ); \& $s\->add_data( 8 ); \& \& print "count = ",$s\->count,"\etmean = ",$s\->mean,"\etvariance = ",$s\->variance,"\etvariance_n = ", \& $s\->variance_n,"\etskewness = ",$s\->skewness,"\etkurtosis = ",$s\->kurtosis,"\en"; \& \& $s\->add_data( ); # does nothing! \& print "count = ",$s\->count,"\etmean = ",$s\->mean,"\etvariance = ",$s\->variance,"\etvariance_n = ", \& $s\->variance_n,"\etskewness = ",$s\->skewness,"\etkurtosis = ",$s\->kurtosis,"\en"; \& \& $s\->add_data( 9, 10 ); \& print "count = ",$s\->count,"\etmean = ",$s\->mean,"\etvariance = ",$s\->variance,"\etvariance_n = ", \& $s\->variance_n,"\etskewness = ",$s\->skewness,"\etkurtosis = ",$s\->kurtosis,"\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a tool to perform statistic operations on large datasets which, typically, could not fit the memory of the machine, e.g. a stream of data from the network. .PP Once instantiated, an object of the class provide an \f(CW\*(C`add_data\*(C'\fR method to add data to the dataset. When the computation of some statistics is required, at some point of the stream, the appropriate method can be called. After the execution of the statistics it is possible to continue to add new data. In turn, the object will continue to update the existing data to provide new statistics. .SH "METHODS" .IX Header "METHODS" .IP "\fInew()\fR" 4 .IX Item "new()" Creates a new \f(CW\*(C`Statistics::OnLine\*(C'\fR object and returns it. .IP "add_data(@)" 4 .IX Item "add_data(@)" Adds new data to the object and updates the internal state of the statistics. .Sp The method return the object itself in order to use it in chaining: .Sp .Vb 1 \& my $v = $s\->add_data( 1, 2, 3, 4 )\->variance; .Ve .IP "\fIclean()\fR" 4 .IX Item "clean()" Cleans the internal state of the object and resets all the internal statistics. .Sp Return the object itself in order to use it in chaining: .Sp .Vb 1 \& my $v = $s\->clean\->add_data( 1, 2, 3, 4 )\->variance; .Ve .IP "\fIcount()\fR" 4 .IX Item "count()" Returns the actual number or elements inserted and processed by the object. .IP "\fImean()\fR" 4 .IX Item "mean()" Returns the average of the elements inserted into the system: .Sp .Vb 1 \& \efract{ \esum_1^n{x_i} }{ n } .Ve .IP "\fIvariance()\fR" 4 .IX Item "variance()" Returns the variance of the element inserted into the system: .Sp .Vb 1 \& \efract{ \esum_1^n{avg \- x_i} }{ n \- 1 } .Ve .IP "\fIvariance_n()\fR" 4 .IX Item "variance_n()" Returns the variance of the element inserted into the system: .Sp .Vb 1 \& \efract{ \esum_1^n{avg \- x_i} }{ n } .Ve .IP "\fIskewness()\fR" 4 .IX Item "skewness()" Returns the skewness (third standardized moment) of the element inserted into the system .IP "\fIkurtosis()\fR" 4 .IX Item "kurtosis()" Returns the kurtosis (fourth standardized moment) of the element inserted into the system .SH "ERROR MESSAGES" .IX Header "ERROR MESSAGES" The conditions in which the system can return errors, using a \f(CW\*(C`die\*(C'\fR are: .IP "too few elements to compute \fIfunction\fR" 4 .IX Item "too few elements to compute function" Some functions need a minimum number of elements to be computed: \f(CW\*(C`mean\*(C'\fR, \f(CW\*(C`variance_n\*(C'\fR and \f(CW\*(C`skewness\*(C'\fR need at least one element, \f(CW\*(C`variance\*(C'\fR at least two and \f(CW\*(C`kurtosis\*(C'\fR needs at least four. .IP "variance is zero: cannot compute \fIkurtosis|skewness\fR" 4 .IX Item "variance is zero: cannot compute kurtosis|skewness" Both kurtosis and skewness need that variance to be greater than zero. .SH "THEORY" .IX Header "THEORY" On-line statistics are based on strong mathematical foundations which transform the standard computations into a sequence of operations that incrementally update with new values the actual ones. .PP There are some referencence in the web. This documentation suggest to start your investigation from . The linked page provides other useful references on the foundations of the method. .SH "CAVEAT" .IX Header "CAVEAT" The module is intended to be used in all the situations in which: (1) the number of data elements could be too large with respect the memory of the system, or (2) the elements arrive at different time stamps and intermediate results are needed. .PP If the length of the stream is fixed, all the data elements are present in a single place and there is not need for intermediate results, it could be better to use different modules, for instance Statistics::Lite, to make computations. .PP The reason for this choice is that the module uses a stable approximation, well suited for the use on steams (effectively an on-line algorithm). Using this system on fixed datasets could introduce some (little) approximation. .SH "HISTORY" .IX Header "HISTORY" .IP "0.02" 4 .IX Item "0.02" Corrected typos in documentation .IP "0.01" 4 .IX Item "0.01" Initial version of the module .SH "AUTHOR" .IX Header "AUTHOR" Francesco Nidito .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2009 Francesco Nidito. All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" Statistics::Lite,