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

NAME

Statistics::Zed - Basic ztest/zscore, with optional continuity correction, Fisher's r-to-z, z-to-r, et al.

SYNOPSIS

use Statistics::Zed 0.01;

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(
       observed => $obs,
       expected => $exp,
       error => $variance,
);

my $deviate = $zed->test(
       observed => $obs,
       expected => $exp,
       variance => $variance,
       samplings => $samplings,
);

my $p_value = $zed->p_value($deviate);

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, but with some standalone utilities. Obsolescence is desirable.

METHODS

Interface

new

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

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

Stats-'n'-stuff

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 std_dev 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 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 std_dev 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 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.).

z_2_p

$p = $zed->z_2_p($z)

Alias: z2p, p_value

Send a z-value, get its associated p-value, 2-tailed by default. Uses Math::Cephes ndtr.

p_2_z

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

Alias: p2z

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.

z_2_r

$r = $zed->z_2_r($z)

Alias: z2r

Send a z-value - get back a correlation coefficient.

r_2_z

$z = $zed->r_2_z($r)

Alias: r2z

Performs the Fisher r-to-z transformation. Send a correlation coefficient - get back a z-value.

z_2_chi

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

Alias: z2chi

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

chi_2_z

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

Alias: chi2z

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

Series testing

A means to aggregate results from multiple tests is exploratively supported, but only when accessing the tests through the main Sequences package. 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";

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.