[Cascavel-pm] Módulo de desvio padrão

[Alex E. J. Falcão]

Senhores,

    como estou arrumando a casa, resolvi escrever uns modulos mais
"bonitinhos" para acertar os meus scripts. Um deles mandei outro dia, o
Statistcs::Forecast e agora fiz um para desvio padrão.

    Ai vai o Statistics::StdDev. Aceito criticas e sugestões.

    Abraço a todos
    Alex Falcão

################################

package Statistics::StdDev;

$VERSION = '0.1';

use strict;

=head1 NAME

Statistics::StdDev

=head1 DESCRIPTION

This is a Oriented Object module that calculates a standard deviation based
on a sample values. The new value is calculated by using linear regression.

=head1 SYNOPSIS

   use Statistics::StdDev;

Create forecast object

   my $STDDEV = new Statistics::StdDev("My Standard Deviation Name");

Add data

   $STDDEV->{Data} = \@Array;

Calculate the result

   $STDDEV->calc;

Get the result

   my $Result_StdDev = $STDDEV->{StdDev);
   my $Result_Avg = $STDDEV->{Avg);

=head1 INTERNALS

The equation for Standard Deviation is:

        sqrt( (sum(X-X)**2)/(N-1) )

=head1 METHODS

=over

=item F<new>

Receives a Standard Deviation name, only to remember
and returns the blessed data structure as
a Statistics::StdDev object.

 my $STDDEV = new Statistics::StdDev("My Standard Deviation");

=cut

################################################################

sub new {
        my $classname= shift(@_);
        my $StdDevName = shift(@_) || "with no name";
        my $Data = shift(@_) || undef;
        my $self = {
                StdDevName => $StdDevName,
                Data => $Data,

                # Initialializing Acumulative variables
                Sum => 0,
                SumQ => 0
        };

        bless $self;
        return $self;

}

=item F<calc>

Calculate and return the forecast value.

 $STDDEV->calc;

=cut

################################################################

sub calc {
        my $self = shift;

        # Verify if the inputed values are correct.
        if (!$self->{Data}) { die "Cannot run without values" };
        if (join("", @{$self->{Data}}) =~ /[^0-9\-]/) { die "You tried to
input an illegal value." };

        # Calculate the Sum of inputed values.
        for (my $X=0; $X <= $#{$self->{Data}}; $X++) {
           $self->{Sum} += $self->{Data}[$X];
           $self->{SumQ} += $self->{Data}[$X]**2;
        }

        $self->{N} = $#{$self->{Data}}+1;               # Number of Elements
        $self->{Avg} = $self->{Sum} / $self->{N};       # Average

        $self->{StdDev} = sqrt( abs(($self->{N}*$self->{SumQ} -
$self->{Sum}**2) / ($self->{N} * ($self->{N} -1))) );


}

################################################################

=item F<dump>

Prints data for debuging propose.

 $STDDEV->{dump};

=item F<Sum>

Returns the sum of inputed values.

 my $Sum = $STDDEV->{Sum};

=item F<SumQ>

Returns the quad sum of inputed values minus average.

 my $SumQ = $STDDEV->{SumQ};

=item F<Avg>

Returns the average of inputed values.

 my $Avg = $STDDEV->{Avg};

=item F<N>

Return the number of inputed values.

 my $N = $STDDEV->{N};

=back

=cut

################################################################

sub dump {

        my $self = shift;
        print "\n\n";
        print "###########################################\n";
        print "      This is a Standard Deviation dump    \n";
        print "###########################################\n";
        print "\n";
        if ($self->{N}) {
           print ".  StdDev Name   : ", $self->{StdDevName}, "\n";
           print ".  Number of elements: ", $self->{N}, "\n";
           print ".  --------------------------------------- \n";
           print ".  Inputed Values\n\t", join(";  ", @{$self->{Data}}),
"\n";
           print ".  Sum of inputed values   : ", $self->{Sum}, "\n";
           print ".  --------------------------------------- \n";
           print ".  Sum of (X-AvgX)**2 values : ", $self->{SumQ}, "\n";
           print ".  Average of values   : ", $self->{Avg}, "\n";
           print ".  --------------------------------------- \n";
           print ".  Std Dev value    : +/- ", $self->{StdDev}, "\n";
           print ".  --------------------------------------- \n";
           print ".  Thanks for using Statistics::StdDev\n\n";
        } else {
           print "Error: You have to use method <calc> \n";
           print "       before dump the values.\n";
           print "\n";
        }
}

=head1 EXAMPLE

   use Statistics::StdDev;

   my @X = (1,3,7,12);

   my $STDDEV = new Statistics::StdDev("My Std Dev");

   $STDDEV->{Data} = \@X;
   $STDDEV->calc;

   print "The Std Dev ", $STDDEV->{StdDevName}, "\n";
   print "The Average value is ", $STDDEV->{Avg};
   print " and has the Standard Deviation value: ", $STDDEV->{StdDev}, "\n";

=head1 BUG

There is no bug found yet.

=head1 AUTHOR

This module was developed by Alex Falcao (alfspsp em hotmail.com).

=head1 STATUS OF THE MODULE

This is the first version and calculates Standard Deviation value.

=head1 VERSION

0.1

=head1 COPYRIGHT

This module is released for free public use under a GPL license.

=cut

1;