Statistics::Zed - Basic deviation ratio: observed less expected (with optional continuity correction) divided by root variance
use Statistics::Zed 0.072; $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);
+ 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.
$zed = Statistics::Zed->new();
Returns a Statistics::Zed object. Accepts setting of any of the OPTIONS.
$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 = ( × –
where X is the expected value (mean, etc.).
$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.
$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)
Prints to STDOUT a line giving the z_value and p_value.
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'}.
Clears any already accumulated data from previous tests.
$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.
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";
Returns string: line giving the z_value and p_value for the series.
Prints to STDOUT a line giving the z_value and p_value for the series.
The following can be set in the call to new
or test
or score
.
Apply the continuity correction, Stetigkeitskorrektur. Default = 0.
Tails from which to assess the association p-value (1 or 2). Default = 2.
Precision of the z-value (the statistic). Default = 2.
Precision of the associated p-value. Default = 0 - you get all decimal values available.
Statistics::Distributions : uprob
function, and precision_string
method is used here for reporting probability.
Statistics::Sequences : for application of this module.
Other distributions.
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).
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.