/ 
Statistics-Zed-0.03
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.03;

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: z_2_p, 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.

p2z

$z = $zed->p2z($p)
$z = $zed->p2z($p, 2) # 2-tailed probability

Alias: p_2_z

Returns the z-value associated with a p-value, using Math::Cephes ndtri function ("phi"). If the class attribute tails has been set to 2, or if the second argument equals 2 (indicating a 2-tailed probability value), the p-value is firstly divided by 2. The absolute value of z is always returned. However, if p equals zero or is undefined, returns undef.

z2chi

$chi = $zed->z2chi($z)

Alias: z_2_chi

Send a z-value, get back a chi-value (the square of the thing ...).

chi2z

$z = $zed->chi2z($chi)
$z = $zed->chi2z($chi, $df)

Alias: chi_2_z

Send a chi-value, get back a z-value. If no degrees-of-freedom after the chi-value (as above), you get back the square-root of the thing. Otherwise:

   Z ~= ¬/(2CHI) – ¬/(2DF – 1)

Note that a negative Z-value returned by this method indicates that the chi-square is smaller than expected for so many dfs; the p-value for this Z-value indicates how much smaller.

vals2z

$z_aref = $zed->vals2z($chi)
$z_aref = $zed->vals2z($chi, $df)

Alias: vals_2_z

Given an array (reference) of numberical values, returns them as an array of standard scores (mean = 0, SD = 1).

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.