NAME

Statistics::Distributions::GTest - Perl implementation of the Log-Likelihood Ratio Test (G-test) of Independence.

VERSION

This document describes Statistics::Distributions::GTest version 0.1.5.

SYNOPSIS

    use Statistics::Distributions::GTest;

    # Create an GTest object.
    my $gtest = Statistics::Distributions::GTest->new();

    # A 3x3 example. Data is sent to object a reference to a LoL.
    my $a_ref = [
                    [ 458, 537 ,345],
                    [ 385, 457 ,456],
                    [ 332, 376 ,364 ],
                ];

    # Feed the object the data by passing reference with named argument 'table'.
    $gtest->read_data ( { table => $a_ref } );

    # Perform the analysis using one of the two methods - see DESCRIPTION.
    $gtest->G();
    #$gtest->G_alt();

    # Print a table of the calculated expected values.
    $gtest->print_expected();

    # To access results use results method. The return of this method is context dependent (see METHODS). 
    # To print a report to STDOUT call results in VOID context - may also call in BOOLEAN, NUMERIC and LIST (see METHODS).
    $gtest->results();

DESCRIPTION

The G-test of independence is an alternative to the chi-square test of independence for testing for independence in contingency tables. G-tests are coming into increasing use and as with the chi-square test for independence the G-test for independence is used when you have two nominal variables each with two or more possible values. The null hypothesis is that the relative proportions of one variable are independent of the second variable. This module implements two two equivalent, but marginally different approaches to calculate G scores (that described in http://en.wikipedia.org/wiki/G-test and that used by http://udel.edu/~mcdonald/statgtestind.html). Benchmarking indicates that first approach works about a third faster than the alternative. However, this difference diminishes as the categories increase. See http://en.wikipedia.org/wiki/G-test and http://udel.edu/~mcdonald/statgtestind.html.

METHODS

new

Create a new Statistics::Distributions::GTest object.

    my $gtest = Statistics::Distributions::GTest->new();

read_data

Used for loading data into object. Data is fed as a reference to a list of lists within an anonymous hash using the named argument 'table'.

    $gtest->read_data ( { table => $LoL_ref } );

G

To calculate G value. This method implements the calculation described in http://en.wikipedia.org/wiki/G-test.

   $gtest->G();

G_alt

To calculate G you may also use this method. This method implements procedure described in http://udel.edu/~mcdonald/statgtestind.html. This approach does not directly generate a table of expected values.

    $gtest->G_alt();

print_expected

Prints a table of the calculated expected values to STDOUT. If you used G_alt to calculate G it will first generated the table of excpeted values.

   $gtest->print_expected();

print_observed

Prints a table of the observation values to STDOUT.

   $gtest->print_observed();

results

Used to access the results of the G-test calculation. This method is context-dependent and will return a variety of different values depending on its calling context. In VOID context it simply prints the calculated value of G, df and the p_value in a table to STDOUT.

    $gtest->results();

In BOOLEAN context it requires you to pass it a value for the significance level of the test you wish to apply e.g. 0.05. It returns True or False depending on whether the null hypothesis is rejected at that significance level.

    # test if the result is significant at the p = 0.05 level.
    if ($gtest->results( 0.05 )) { print qq{\nthis is significant } } else { print qq{\nthis is not significant} }

In LIST context it simply returns a LIST of the calculated values of G, df and p for the observation data.

    my ($G, $df, $p) = $gtest->results();

In NUMERIC context it returns the calculated value of G.

    print qq{\n\nG in numeric is: }, 0+$gtest->results();

DEPENDENCIES

'version' => 0, 'Statistics::Distributions' => '1.02', 'Math::Cephes' => '0.47', 'Carp' => '1.08', 'Contextual::Return' => '0.2.1', 'List::Util' => '1.19', 'Text::SimpleTable' => '2.0',

AUTHOR

Daniel S. T. Hughes <dsth@cpan.net>

LICENCE AND COPYRIGHT

Copyright (c) 2009, Daniel S. T. Hughes <dsth@cantab.net>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

SEE ALSO

Statistics::Descriptive, Statistics::Distributions, Statistics::Distributions::Analyze, Statistics::ANOVA, Statistics::Distributions::Ancova, Statistics::ChiSquare.

DISCLAIMER OF WARRANTY

Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the software "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.

cpanm Statistics::Distributions::GTest

perl -MCPAN -e shell
install Statistics::Distributions::GTest