 NAME
 SYNOPSIS
 DESCRIPTION
 METHODS
 EXAMPLE
 REFERENCES
 SEE ALSO
 BUGS/LIMITATIONS
 REVISION HISTORY
 AUTHOR/LICENSE
 END
NAME
Statistics::Sequences::Pot  Helmut Schmidt's test of forcelike runs of a discrete state within a numerical or categorical sequence
SYNOPSIS
use strict;
use Statistics::Sequences::Pot 0.12; # methods/args here are not compatible with earlier versions
my $pot = Statistics::Sequences::Pot>new();
$pot>load([qw/2 0 8 5 3 5 2 3 1 1 9 4 4 1 5 5 6 5 8 7 5 3 8 5 6/]); # strings/numbers; or send as "data => $aref" with each stat call
my $val = $pot>observed(state => 5); # other methods include: expected(), variance(), obsdev() and stdev()
$val = $pot>zscore(state => 5, tails => 2, ccorr => 1); # # or want an array & get back both z and pvalue
$val = $pot>p_value(state => 5, tails => 1); # assuming data are loaded; alias: test()
my $href = $pot>stats_hash(values => {observed => 1, p_value => 1}, state => 5); # include any other statmethod as needed
$pot>dump(values => {observed => 1, expected => 1, p_value => 1}, state => 5, flag => 1, precision_s => 3, precision_p => 7);
# prints: observed = 4.310, expected = 4.529, p_value = 0.8090600
DESCRIPTION
The Pot statistic measures the bunching relative to the spacing of a single state within a series of other states, conceived by Helmut Schmidt as a targeted "potential" energy (or Pot) that dissipates exponentially between states. It's not limited to considering only clusters of consecutive states (or bunches), as is the case with the more familiar Runs test of sequences.
Say you're interested in the occurrence of the state 3 within an array of digits: note how, in the following arrays, there are increasing breaks between the 3s (separated by 0, 1 and then 2 other states):
4, 7, 3, 3
3, 4, 3, 7
3, 8, 1, 3
The occurrence of 3 is, with the Pottest, of exponentially declining interest across these sequences, given the increasing breaks by other states between the occurrences of 3. The statistic does not ignore these ever remoter occurrences of the state of interest; it accounts for increased spacing between them as if there were an exponentially declining force, a potential towards 3, within the datastream (up to a theoretical or empirical asymptote that may be specified).
Running the Pottest involves testing its significance as a standard "z" score; Schmidt (2000) provided data demonstrating Pot's conformance with the normal distribution. This will naturally be improved by repeated sampling, and by using block averages.
METHODS
Methods are essentially as described in Statistics::Sequences
new
$pot = Statistics::Sequences::Pot>new();
Returns a new Pot object. Expects/accepts no arguments but the classname.
load
$pot>load(@data); # anonymously
$pot>load(\@data);
$pot>load('sample1' => \@data); # labelled whatever
Loads data anonymously or by name  see load in the Statistics::Data manpage for details on the various ways data can be loaded and then retrieved (more than shown here).
Data can be categorical or numerical, and multivalued  i.e, unlike in tests of runs and joins, they do not have to be dichotomous.
add, read, unload
See Statistics::Data for these additional operations on data that have been loaded.
observed, pot_observed, pvo
$v = $pot>observed(state => 'x'); # use the first data loaded anonymously; specify a 'state' within it to test its pot
$v = $pot>observed(index => 1, state => 'x'); # ... or give the required "index" for the loaded data
$v = $pot>observed(label => 'mysequence', state => 'x'); # ... or its "label" value
$v = $pot>observed(data => [qw/x z x x p c/], state => 'x'); # ... or just give the data now
Returns observed value of pot, a measure of the number and size of bunchings of the state that occurred within the array. The data to calculate this on can already have been loaded, or you send it here as a flat referenced array keyed as data. The observed value of pot is based on Schmidt (2000), Equations 67, and his Appended program, viz.:
I,J=1..N
Σ r^{n(I)  n(J)}
I<J
where
r = e^{–N/MS}
is the number of observations, and S (for scale) is a constant determining the range r of the potential energy between pairs of I and J states. These values are set as name => value
pairs, as follows.
state => string
The state within the data whose bunching is to be tested. This is the only required argument; croak
if no state is specified. Returns 0 if this state does not exist in the data.
scale => numeric >= 1
Optionally, the scale of the range parameter, which should be greater than or equal to 1. Default = 1; values less than 1 are effected as 1.
In most situations, should all states be equiprobable, or their probability be proportionate to their number, r would reflect the average distance, or delay, between successive states, equal to the number of all observations divided by the number of states. For example, if there were 10 possible states, and 100 observations have been made, then the probability of reoccurrence of any one of the 10 states within any slot will be equal to 100/10, with S = 1, i.e., expecting that any one of the states would mostly occur by a spacing of 10, and then by an exponentially declining tendency toward consecutive occurrence. In this way, with S = 1, Pot is a measure of "shortrange bunching," as Schmidt called it. Bunching over a larger range than this minimally expected range can be measured with S > 1. This is specified, optionally, as the argument named scale to test. Hypothesistesting might be made with respect to various values of the scale parameter.
expected, pot_expected, pve
$v = $pot>expected(state => 'x'); # or specify loaded data by "index" or "label", or give it as "data"  see observed()
$v = $pot>expected(data => [qw/x z x x p c/], state => 'x'); # use these data
Returns the theoretically expected value of Pot, given N states among M observations, and r range of clustering within these observations. It is calculated as follows from Schmidt (2000) Eq. 8, given the above definitions.
Pot = ((N(N – 1))/(M(M – 1))) . (r/1 – r) . (M – (1/(1 – r)))
variance, pot_variance, pvv
$v = $pot>variance(state => 'x'); # or specify loaded data by "index" or "label", or give it as "data"  see observed()
$v = $pot>variance(data => [qw/x z x x p c/], state => 'x'); # use these data
Returns the variance in the theoretically expected value of pot, given by Schmidt (2000) Equation 9a:
Variance = (r²/ (1 – r²) . (N / M) . (1 – (N / M))² . N
obsdev, observed_deviation
$v = $pot>obsdev(state => 'x'); # use data already loaded  anonymously; or specify its "label" or "index"  see observed()
$v = $pot>obsdev(data => [qw/x z x x p c/], state => 'x'); # use these data
Returns the deviation of (difference between) observed and expected pot for the loaded/given sequence (O  E).
stdev, standard_deviation
$v = $pot>stdev(state => 'x'); # use data already loaded  anonymously; or specify its "label" or "index"  see observed()
$v = $pot>stdev(data => [qw/x z x x p c/], state => 'x');
Returns squareroot of the variance.
z_value, zscore, pot_zscore, pzs
$v = $pot>z_value(ccorr => 1, state => 'x'); # use data already loaded  anonymously; or specify its "label" or "index"  see observed()
$v = $pot>z_value(data => $aref, ccorr => 1, state => 'x');
($zvalue, $pvalue) = $pot>z_value(data => $aref, ccorr => 1, tails => 2, state => 'x'); # same but wanting an array, get the pvalue too
Returns the zscore from a test of pot deviation, taking the pot expected away from that observed and dividing by the root expected pot variance, by default with a continuity correction to expectation. Called wanting an array, returns the zvalue with its pvalue for the tails (1 or 2) given.
The data to test can already have been loaded, or sent directly as an aref keyed as data.
Other options are precision_s (for the z_value) and precision_p (for the p_value).
p_value, test, pot_test, ptt
$p = $pot>p_value(state => 'x'); # using loaded data and default args
$p = $pot>p_value(ccorr => 01, tails => 12, state => 'x'); # normalapproximation based on loaded data
$p = $pot>p_value(data => $aref, ccorr => 1, tails => 2, state => 'x'); # using given data (bypassing load and read)
Test the currently loaded data for significance of the vale of pot. Returns the zscore from test of pot deviation, or, called wanting an array, the zvalue with its pvalue for the tails (1 or 2) given.
stats_hash
$href = $pot>stats_hash(values => {observed => 1, expected => 1, variance => 1, z_value => 1, p_value => 1}, prob => .5, ccorr => 1);
Returns a hashref for the counts and stats as specified by hashref in its "values" argument, and with any options for calculating them. See "stats_hash" in Statistics::Sequences for details.
dump
$pot>dump(values => { observed => 1, variance => 1, p_value => 1}, exact => 1, flag => 1, precision_s => 3); # among other options
Print Pottest results to STDOUT. See dump in the Statistics::Sequences manpage for details.
EXAMPLE
Using Pot as a test of bunching of a particular state within a collection of quasirandom events.
use strict;
use Statistics::Sequences::Pot;
my ($i, @data) = ();
# Init random integers ranging from 0 to 15:
for ($i = 0; $i < 960; $i++) { $data[$i] = int(rand(16)); }
# Assess degree of bunching within these data with respect to a randomly selected target state:
my $state = int(rand(16));
my $pot = Statistics::Sequences::Pot>new();
$pot>load(\@data);
my %args = (state => $state, values => {p_value => 1, observed => 1, expected => 1, stdev => 1});
my $statsref = $pot>stats_hash(\%args);
# Access the results of this analysis:
print "The probability of obtaining as much bunching of $state as observed is $statsref>{'p_value'}.\n";
print "The observed value of Pot was $statsref>{'observed'}, with expected value $statsref>{'expected'} ($statsref>{'stdev'}).\n";
# or print the lot, and more, in English:
$pot>dump(%args, precision_s => 3, precision_p => 7,);
REFERENCES
Schmidt, H. (2000). A proposed measure for psiinduced bunching of randomly spaced events. Journal of Parapsychology, 64, 301316.
SEE ALSO
http://www.fourmilab.ch/rpkp/ for Schmidt's many papers on the physical conceptualisation and properties of psi.
Statistics::Descriptive : The present module adds data to "Full" objects of this package in order to access descriptives re bunches and spaces.
Statistics::Frequency : the proportional_frequency()
method in this module could be informative when working with data of the kind used here.
BUGS/LIMITATIONS
No computational bugs as yet identfied. Hopefully this will change, given time.
Limitations of the code, perhaps, concern the nonunique storage of data arrays (compared to, say, Statistics::DependantTTest
, but see Statistics::TTest
). This would require a unique name for each array of data, and explicit reference to one or another array with each test (when, perhaps, you'd have only one dataset, after all). In any case, the data are accepted as array references.
REVISION HISTORY
See CHANGES in installation dist for revisions.
AUTHOR/LICENSE
 Copyright (c) 20062013 Roderick Garton

rgarton AT cpan DOT org
This program is free software. It may be used, redistributed and/or modified under the same terms as Perl5.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.
END
This ends documentation of a Perl implementation of Helmut Schmidt's test of pot (potential energy) of occurrence of a state among others in a categorical sequence.