/ 
Statistics-Zed-0.032
River stage two • 9 direct dependents • 10 total dependents
/ Statistics::Zed

NAME

Statistics::Zed - Basic ztest/zscore, with optional continuity correction

SYNOPSIS

use Statistics::Zed 0.032;

my $zed = Statistics::Zed->new(
   ccorr    => 1,
   tails    => 2,
   precision_s => 5,
   precision_p => 5,
);

my ($z_value, $p_value, $observed_deviation, $standard_deviation) = 
   $zed->score( # or score
       observed => $obs,
       expected => $exp, # or key stdev or variance
       error => $variance,
);

my $deviate = $zed->test( # or ztest
       observed => $obs,
       expected => $exp,
       error => $variance, # or key stdev or variance
       samplings => $samplings,
);

my $p_value = $zed->p_value($deviate); # or z2p

DESCRIPTION

Calculates a standard, run-of-the-mill z-score: the ratio of an observed deviation to a standard deviation; and performs a z-test or returns the z-score. Purpose is simply to support Statistics::Sequences.

METHODS

Interface

new

$zed = Statistics::Zed->new();

Returns a Statistics::Zed object. Accepts setting of any of the OPTIONS.

Stats

ztest

$zed->ztest(observed => 'number', expected => 'number', variance => 'number (non-zero)', samplings => 'positive integer')

Alias: test

You supply the observed and c<expected> values of your statistic, and the variance or stdev or just error of any kind; ... and the number of samplings ("sample-size", N, "trials", etc.).

Optionally specify a logical value for ccorr for performing the continuity-correction to the observed deviation, and a value of either 1 or 2 to specify the tails for reading off the probability associated with the z-value. When passed to this function, values of ccorr and tails become the values used in this and subsequent tests.

When called in array context, returns an array consisting of the z-statistic ("standard normal deviate"), its probability, the observed deviation (the difference between the observed and expected values of your statistic), and the standard deviation (the square-root of the variance supplied).

If you only want the z-value, then expect a string:

$z_value = $zed->test(...)

The basic formula is the basic:

   Z× = ( × – µ ) / SD / ¬/n

zscore

$zed->zscore(observed => 'number', expected => 'number', variance => 'number (non-zero)')

Alias: score

You supply the observed and expected values of your statistic, and the variance or stdev or just error of any kind.

Optionally specify a logical value for ccorr for performing the continuity-correction to the observed deviation, and a value of either 1 or 2 to specify the tails for reading off the probability associated with the z-value. When passed to this function, values of ccorr and tails become the values used in this and subsequent tests.

When called in array context, returns an array consisting of the z-statistic ("standard score"), its probability, the observed deviation (the difference between the observed and expected values of your statistic), and the standard deviation (the square-root of the variance supplied).

If you only want the z-value, then expect a string:

$z_value = $zed->score(...)

The basic formula is the basic:

   Z = ( × – X ) / SD

where X is the expected value (mean, etc.).

z2p

$p = $zed->z2p($z)
$p = $zed->z2p($z, 1)

Alias: p_value

Send a z-value, get its associated p-value, 2-tailed by default, or depending on what the value of $zed->{'tails'} is, or what is sent as the second argument, if anything. Uses Math::Cephes ndtr.

dump

Prints to STDOUT a line giving the z_value and p_value.

Series testing

A means to aggregate results from multiple tests is supported. Three methods are presently used to effect this.

series_init

Clears any already accumulated data from previous tests.

series_update

$zed->series_update() # use any cached values of "observed", "expected" and "variance"
$zed->series_update(variance => 'number', expected => 'number', observed => 'number') # supply own in a hash

Called once you have performed a test on a sample. It caches the observed, expectation and variance values from the test.

series_test

Sums the observed, expectation and variance values from all the tests updated to the series since calling series_init, and produces a z-value from these sums. It returns nothing in particular, but the following statement shows how the series values can be accessed.

print "Series summed runs: 
   expected = ", $zed->{'series'}->{'expected'}, " 
   observed = ", $zed->{'series'}->{'observed'}," 
   z = $zed->{'series'}->{'z_value'}, $zed->{'tails'}p = $zed->{'series'}->{'p_value'}\n";

series_dump

Prints to STDOUT a line giving the z_value and p_value for the series.

OPTIONS

The following can be set in the call to new or test or score.

ccorr

Apply the continuity correction. Default = 0.

tails

Tails from which to assess the association p-value (1 or 2). Default = 2.

precision_s

Precision of the z-value (the statistic). Default = 2.

precision_p

Precision of the associated p-value. Default = 0 - you get all decimal values available.

SEE ALSO

Math::Cephes : the ndtr and ndtri functions are used here for determining probability or z-values, respectively. (This is only in preference to using Statistics::Distributions so that whether we want a p- or zvalue, the same class of methods is used.)

Statistics::Distributions : the precision_string method is used here for reporting probability.

Statistics::Sequences : for application of this module.

TO DO/BUGS

Other distributions.

AUTHOR/LICENSE

rgarton AT cpan DOT org

This program is free software. It may be used, redistributed and/or modified under the same terms as Perl-5.6.1 (or later) (see http://www.perl.com/perl/misc/Artistic.html).

Disclaimer

To the maximum extent permitted by applicable law, the author of this module disclaims all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to the software and the accompanying documentation.