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

NAME

Statistics::Zed - Basic deviation ratio: observed less expected (with optional continuity correction) divided by root variance

SYNOPSIS

use Statistics::Zed 0.07;

$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,
   variance => $variance, # or 'stdev'
);

$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.

+ Provides wraps to convert z-value to p-value, and convert p-value to z-value.

+ Organizes accumulated observed, expected and variance values over two or more runs ahead of making the calculation.

+ Purpose is to support tests in Statistics::Sequences.

METHODS

new

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

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

zscore

$zval = $zed->zscore(observed => 'number', expected => 'number', variance => 'number (non-zero)')
($zval, $pval, $obs_dev, $stdev) = $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.

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); # assumes 2-tailed
$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. If you send just one value (unkeyed), it is taken as the value.

p2z

$z_value = $zed->p2z($p) # the p-value is assumed to be 2-tailed
$z_value = $zed->p2z(value => $p) # the p-value is assumed to be 2-tailed
$z_value = $zed->p2z(value => $p, tails => 1) # specify 1-tailed probability

Returns the z-value associated with a p-value using Math::Cephes ndtri ("phi"). The p-value is assumed to be two-tailed, and so is firstly (before conversion) divided by 2, e.g., .05 becomes .025 so you get z = 1.96. As a one-tailed probability, it is then assumed to be a probability of being greater than a certain amount, i.e., of getting a z-value greater than that observed. So the phi function is actually given (1 - p-value) to work on - so you get back the z-value up to that point, before the p-value has to fit in. So .055 comes back as 1.598 (speaking of the top-end of the distribution), and .991 comes back as -2.349 (now going from right to left across the distribution). These assumptions are not the same as found in inversion methods in common spreadsheet packages but seem expected by human users like me of z-values and their p-values. (complain if useful)

dump

Prints to STDOUT a line giving the z_value and p_value.

Series testing

Aggregate results from multiple tests using a method to initialise the series, another to add data to the series, and a final one to sum the data, compute an aggregate Zscore from them, with all the values of interest ready to dump. Statistics::Descriptive objects are kept of each series' observed, expected and variance values, as sent to series_update, and a separate count of the number of series is kept - $zed->{'series'}->{'count'}.

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, matchcount_expected and variance values from the test.

series_test

Sums the observed, matchcount_expected and variance values from all the tests updated to the series since calling series_init, and produces a z-value from these sums. Returns the same values as zscore: wanting an array, then the z-value, its probability, the observed deviation and the standard deviation; otherwise, the z-value alone. Additionally, the $zed-{'series'}> object hash is lumped with the usual values, so you can access them like so:

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_str

Returns string: line giving the z_value and p_value for the series.

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, Stetigkeitskorrektur. 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

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.