NAME
Statistics::Zed  Datahandling and calculations for ratio of observed to standard deviation (zscore)
VERSION
Version 0.10
SYNOPSIS
use Statistics::Zed 0.10;
# new() with optional args:
$zed = Statistics::Zed>new(
ccorr => 1,
tails => 2,
precision_s => 3,
precision_p => 7,
);
# optionally preload one or more values with these names:
$zed>load(observed => [5, 6, 3], expected => [2.5, 3, 3], variance => [8, 8, 9]);
$zed>add(observed => [3, 6], expected => [2.7, 2.5], variance => [7, 8]); # update loaded arrays
$z_value = $zed>score(); # calc z_value from preloaded data
# alternatively, call zscore()  alias score()  with the required args (with arefs or single values):
$z_value = $zed>zscore(
observed => 5,
expected => 2.5,
variance => 8,
);
# as either of above, but call in array context for more results:
($z_value, $p_value, $observed_deviation, $standard_deviation) = $zed>zscore();
# as either of above but with optional args:
$z_value = $zed>zscore(ccorr => 1, precision_s => 3);
# get the normal distribution p_value only  alias z2p():
$p_value = $zed>p_value(); # using preloaded data
$p_value = $zed>p_value(observed => 5, expected => 2.5, variance => 8); # from given data
$p_value = $zed>p_value(tails => 2, ccorr => 1, precision_p => 5); # same as either with optional args
# "inverse phi" (wraps to Math::Cephes::ndtri):
$z_value = $zed>p2z(value => $p_value, tails => 12);
DESCRIPTION
Methods are provided to:
+ calculate a zscore: ratio of an observed deviation to a standard deviation, with optional continuity correction
+ convert zvalue to normal pvalue, and convert pvalue to normalequiv zvalue
+ load, add, save & retrieve observed, expected and variance values to compute z_score across samples
+ support ztesting in Statistics::Sequences and other modules.
Optionally, load/add observed, expected and variance values (named as such) and compute a zscore between/after updates. The module uses Statistics::Data to cache each observed, expected and variance values, and to provide for the load/add methods, as well as to save/retrieve these values between class calls (not documented here, see Statistics::Data). Alternatively, simply call zscore and pvalue, passing them the values by these labels in a hash (or hashref), with either single numerical values or referenced arrays of the same. Optionally, specify tails, where relevant, and precision the returned zvalues and pvalues as required.
SUBROUTINES/METHODS
new
$zed = Statistics::Zed>new();
$zed = Statistics::Zed>new(ccorr => NUM, tails => 12, precision_s => INT, precision_p => INT);
Returns a Statistics::Zed object. Accepts setting of any of the OPTIONS.
load
$zed>load(observed => [NUMs], expected => [NUMs], variance => [NUMs]); # labelled list of each required series
$zed>load({ observed => [NUMs], expected => [NUMs], variance => [NUMs] }); # same but as referenced hash
Optionally load data for each of observed, expected and variance series as arefs (reference to list of numbers), using load
in Statistics::Data. Returns 1 if successful but croaks if data cannot be loaded; see DIAGNOSTICS.
add
$zed>add(observed => [NUMs], expected => [NUMs], variance => [NUMs]); # labelled list of each required series
$zed>add({ observed => [NUMs], expected => [NUMs], variance => [NUMs] }); # same but as referenced hash
Update any existing, previously loaded data, via add
in Statistics::Data. Returns 1 if successful but croaks if data cannot be added; see DIAGNOSTICS.
zscore
$zval = $zed>zscore(); # assuming observed, expected and variance values already loaded/added, as above
$zval = $zed>zscore(observed => NUM, expected => NUM, variance => NUM);
$zval = $zed>zscore(observed => [NUMs], expected => [NUMs], variance => [NUMs]);
($zval, $pval, $obs_dev, $stdev) = $zed>zscore(); # same but array context call for more info
$zscore = $zed>zscore(observed => [12], expected => [5], variance => [16], ccorr => 1); # same but with continuity correction
Returns the zvalue for the values of observed, expected and variance sent to load and/or add, or as sent in a call to this method itself as a hash (or hashref). If called wanting an array, then the zvalue, its probability, the observed deviation and the standard deviation are returned.
Alias: score, z_value
As described in OPTIONS, optionally specify a numerical value for ccorr for performing the continuitycorrection to the observed deviation, and a value of either 1 or 2 to specify the tails for reading off the normal distribution.
The basic formula is the basic:
Z = ( × – X ) / SD
where X is the expected value (mean, etc.). If supplying an array of values for each of the required arguments, then the zscore is based on summing their values, i.e., (sum of observeds less sum of expecteds) divided by squareroot of the sum of the variances.
p_value
$p_value = $zed>p_value($z); # assumes 2tailed
$p_value = $zed>p_value(value => $z); # assumes 2tailed
$p_value = $zed>p_value(value => $z, tails => 1);
$p_value = $zed>p_value(); # assuming observed, expected and variance values already loaded/added, as above
$p_value = $zed>p_value(observed => NUM, expected => NUM, variance => NUM);
$p_value = $zed>p_value(observed => [NUMs], expected => [NUMs], variance => [NUMs]);
Alias: pvalue
, z2p
Send a zvalue, get its associated pvalue, 2tailed by default, or depending on the value of the optional argument tails. If you pass in just one value (unkeyed), it is taken as the zvalue. Alternatively, it can be passed the same arguments as for zscore so that it will calculate the zscore itself but return only the pvalue.
Uses Math::Cephes ndtr
normal probability function, which returns 0 if the zvalue is greater than or equal to 38.
The optional argument precision_p renders the returned pvalue to so many decimal places (simply by sprintf).
p2z
$z_value = $zed>p2z($p_value) # the pvalue is assumed to be 2tailed
$z_value = $zed>p2z(value => $p_value) # the pvalue is assumed to be 2tailed
$z_value = $zed>p2z(value => $p_value, tails => 1) # specify 1tailed probability
Returns the zvalue associated with a pvalue using the inverse phi function ndtri
in Math::Cephes. The pvalue is assumed to be twotailed, and so is firstly (before conversion) divided by 2, e.g., .05 becomes .025 so you get z = 1.96. As a onetailed probability, it is then assumed to be a probability of being greater than a certain amount, i.e., of getting a zvalue greater than or equal to that observed. So the inverse phi function is actually given (1  pvalue) to work on. So .055 comes back as 1.598 (speaking of the topend of the distribution), and .991 comes back as 2.349 (now going from right to left across the distribution). This is not the same as found in inversion methods in common spreadsheet packages but seems to be expected by humans.
obsdev
$obsdev = $zed>obsdev(); # assuming observed and expected values already loaded/added, as above
$obsdev = $zed>obsdev(observed => NUM, expected => NUM);
$obsdev = $zed>obsdev(observed => [NUMs], expected => [NUMs]);
Returns the observed deviation (only), as would be returned as the third value if calling zscore in array context. This is simply the (sum of) the observed value(s) less the (sum of) the expected value(s), with the (sum of) the latter given the continuity correction if this is (optionally) also given as an argument, named ccorr; see OPTIONS.
ccorr
$zed>ccorr(value => 1); # will be used in all methods, unless they are given a ccorr value to use
$val = $zed>ccorr(); # returns any value set in new() or previously here
Set the value of the optional ccorr argument to be used for all statistics methods, or, without a value, return the current value. This might be undef if it has not previously been explicitly set in new or via this method. To quash any set value, specify value => 0. When sending a value for ccorr to any other method, this value takes precedence over any previously set, but it does not "reset" the cached value that is set here or in new. See OPTIONS for how this value is used. It is assumed that the value sent is a valid numerical value.
tails
$zed>tails(value => 1); # will be used in all methods, unless they are given a tails value to use
$val = $zed>tails(); # returns any value set in new() or previously here
Set the value of the optional tails argument to be used for all statistics methods, or, without a value, return the current value. The default is 2; and this can be overriden by setting its value in new, by this method, or as an explicit argument in any method. When sending a value for tails to any other method, this value takes precedence over any previously set, but it does not "reset" the cached value that is set here or in new. See p_value, p2z and OPTIONS for how this value is used. The value set must be either 1 or 2; a croak is heard otherwise.
string
$str = $zed>string(); # assuming observed, expected and variance values already loaded/added, as above
$str = $zed>string(observed => NUM, expected => NUM, variance => NUM);
$str = $zed>string(observed => [NUMs], expected => [NUMs], variance => [NUMs]);
Returns a string giving the zscore and pvalue. Takes the same arguments as for zscore, which it calls itself, taking its returned values to make up a string in the form Z = 0.141, 1p = 0.44377. Accepts the optional arguments tails, ccorr, precsion_s and precision_p; see OPTIONS. In the example, precision_s has been specified as 3, precision_p has been set to 5, and tails has been set to 1.
dump
$zed>dump(); # assuming observed, expected and variance values already loaded/added, as above
$zed>dump(observed => NUM, expected => NUM, variance => NUM);
$zed>dump(observed => [NUMs], expected => [NUMs], variance => [NUMs]);
Prints to STDOUT a line giving the zscore and pvalue, being what would be returned by string but with a newline "\n" character appended.
OPTIONS
The following can be set in calls to the above methods, including new, where relevant.
ccorr
Apply the continuity correction. Default = 0. Otherwise, specify a correcting difference value (not necesarily 1), and the procedure is to calculate the observed difference as its absolute value less half of this correcting value, returning the observed difference with its original sign. To clarify for Germans, this is the Stetigkeitskorrektur.
tails
Tails from which to assess the association pvalue (1 or 2). Default = 2.
precision_s
Precision of the zvalue (the statistic). Default is undefined  you get all decimal values available.
precision_p
Precision of the associated pvalue. Default is undefined  you get all decimal values available.
Deprecated methods
Methods for "series testing" are deprecated. Use load and add instead to manage keeping a cache of the oberved, expected and variance values; the z and pmethods will look them up, if available. See dump_vals in Statistics::Data for dumping series data using the present class object, which uses Statistics::Data as a base.
DIAGNOSTICS
 Data for deviation ratio are incomplete

Croaked when loading or adding data. As the croak goes on to say, loading and adding (updating) needs arefs of data labelled observed, expected and variance. Also, if any one of them are loaded/updated at one time, it's expected that all three are loaded/updated. For more info about loading data, see Statistics::Data.
 Cannot compute zvalue: No defined or numerical '$_' value(s)

Croaked via zscore if the three required observed, expected and variance values were not defined in the present call (each to a reference to an array of values, or with a single numerical value), or could not be accessed from a previous load/add. See access in Statistics::Data for any error that might have resulted from a bad load/add. See
looks_like_number
in Scalar::Util for any error that might have resulted from supplying a single value for observed, expected or variance.  Cannot compute pvalue: Argument 'tails' should have value of either 1 or 2, not '$tails'

Croaked when calling p_value directly or via zscore, or when calling p2z, and any given value for tails is not appropriate.
 Cannot compute zvalue from pvalue

Croaked by p2z if its value attribute is not defined, is empty string, is not numeric, or, if numeric, is greater than 1 or less than zero, as per all_proportions in Statistics::Data.
 Cannot set tails() option: value must be numeric and equal either 1 or 2, not '$_'

Croaked from tails method; selfexplanatory.
 Could not print statistical values

Croaked by the internal dump method if, for some reason, printing to STDOUT is not available.
DEPENDENCIES
Math::Cephes  ndtr
and ndtri
normal distribution functions
Statistics::Lite  sum
method
String::Util  hascontent
and nocontent
methods
Scalar::Util  looks_like_number
method
Statistics::Data  this module uses the latter as a base, for its loading/adding data methods (if required), and a p2z validity check.
SEE ALSO
Statistics::Sequences : for application of this module.
AUTHOR
Roderick Garton, <rgarton at cpan.org>
LICENSE AND COPYRIGHT
Copyright 20062014 Roderick Garton.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See perl.org for more information.