NAME
Statistics::Zed - Basic ztest/zscore, with optional continuity correction
SYNOPSIS
use Statistics::Zed 0.04;
$zed = Statistics::Zed->new(
ccorr => 1,
tails => 2,
precision_s => 5,
precision_p => 5,
);
($z_value, $p_value, $observed_deviation, $standard_deviation) =
$zed->score( # or zscore
observed => $obs,
expected => $exp, # or key stdev or variance
error => $variance,
);
$deviate = $zed->test( # or ztest
observed => $obs,
expected => $exp,
error => $variance, # or key stdev or variance
samplings => $samplings,
);
$p_value = $zed->z2p(value => $z_value, tails => 1|2);
$z_value = $zed->p2z(value => $p_value, tails => 1|2);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(value => $z); # assumes 2-tailed
$p = $zed->z2p(value => $z, tails => 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.
p2z
$z_value = $zed->p2z(value => $p) # the p-value is assumed to be 2-tailed
$z_value = $zed->p2z(value => $p, tails => 1) # 1-tailed probabilityReturns the z-value associated with a p-value, using Math::Cephes ndtri function ("phi"). If the tails attribute equals 2 (indicating a 2-tailed probability value), the p-value is firstly divided by 2. A check is firstly made to ensure that what is sent as a probability actually looks like a probability.
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 hashCalled 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
Statistics::Distributions : uprob function, and precision_string method is used here for reporting probability.
Statistics::Sequences : for application of this module.
TO DO/BUGS
Other distributions.
AUTHOR/LICENSE
- Copyright (c) 2006-2010 R Garton
-
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.