The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Statistics-Distributions-Ancova-0.32.2
River stage zero No dependents
++
/ Statistics::Distributions::Ancova

NAME

Statistics::Distributions::Ancova - Perl implementation of One-Way Analysis of Covariance for Independent Samples.

VERSION

This document describes Statistics::Distributions::Ancova version 0.32.2.

SYNOPSIS

    use Statistics::Distributions::Ancova;

    # Create an Ancova object and set significance value of p = 0.05 for statistical test. See METHODS for optional named arguments and default values.
    my $anc = Statistics::Distributions::Ancova->new ( { significance => 0.005, input_verbosity => 1, output_verbosity => 1 } );

    # Example using k=3 groups. Data includes our dependent variable of interest (Y) and covariant data (X) that is used to eliminate obscuring effects of covariance.
    my @Drug_A_Y =  ('29','27','31','33','32','24','16');
    my @Drug_A_X = ('53','64','55','67','55','45','35');
    my @Drug_B_Y = ('39','34','20','35','57','28','32','17');
    my @Drug_B_X = ('24','19','13','18','25','16','16','13');
    my @Drug_C_Y = ('12','21','26','17','25','9','12');
    my @Drug_C_X = ('5','12','12','9','12','3','3');

    # Data is sent to object as nested HASH reference. Individual group names are option, but to distinguish IV/DV, the names Y and X for the variables are compulsory.
    my $h_ref = { 'group_A' =>  {
                                    Y => \@Drug_A_Y,
                                    X => \@Drug_A_X,
                            }, 
                'group_B' =>  { 
                                    Y => \@Drug_B_Y,
                                    X => \@Drug_B_X,
                            }, 
                'group_C' =>  { 
                                    Y => \@Drug_C_Y,
                                    X => \@Drug_C_X,
                            }, 
                };

    # Feed the object the data pass data HASH reference with named argument 'data'.
    $anc->load_data ( { data => $h_ref } );

    # Perform analysis
    $anc->ancova_analysis;

    # 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.
    $anc->results();

DESCRIPTION

ANCOVA is a merger of ANOVA and regression for continuous variables. As with paired t-test and repeated-measures ANOVA this test removes the obscuring effects of pre-existing individual differences among subjects and thus may increase statistical power. In cases where a substantial portion of the variability that occurs within each of the set of a dependent variable Y is actually covariance with another concomitant variable X measures, this test removes the covariance with X from Y thus removing a portion of the irrelevant variability of individual differences. See http://en.wikipedia.org/wiki/Analysis_of_covariance for more info.

Methods

new

Creates new Statistics::Distributions::Ancova object. Without arguments defaults to a significance test value of p = 0.05.

    my $anc = Statistics::Distributions::Ancova->new ();

Use significance option to set the significance level for the test to values other than 0.05.

    my $anc = Statistics::Distributions::Ancova->new ( { significance => 0.005 } );

To print data-checking step messages (upon data loading with load_data) to STDOUT set input_verbosity to 1.

    my $anc = Statistics::Distributions::Ancova->new ( { input_verbosity => 1 } );

To print a detailed report when result method is called in VOID context to STDOUT set output_verbosity to 1.

    my $anc = Statistics::Distributions::Ancova->new ( { output_verbosity => 1 } );

set_significance

Convenience method to reset significance level. Without a value it defaults to p = 0.05 to change this use set_significance.

    $anc->set_significance();
    $anc->set_significance( 0.0005 );

set_input_verbosity

Convenience method to reset the input verbosity level. Pass it 1 for verbose and 0 or no argument to leave default silent state.

    $anc->set_input_verbosity (1); # Turns on verbosity
    $anc->set_input_verbosity (0);
    $anc->set_input_verbosity ();

set_output_verbosity

Convinience method to reset the output verbosity level. Pass it 1 for verbose and 0 or no argument to leave default silent state.

    $anc->set_output_verbosity (1); # Turns on verbosity
    $anc->set_output_verbosity (0);
    $anc->set_output_verbosity ();

load_data

To load or re-load data. Pass the data as named arguement 'data' within an anonymous HASH pointing to nested HASH reference containing the data. Within this HASH reference each subsequent nested HASH corresponds to a separate individual/group. The names of these groups are arbitrary. Within each nested group HASH there must be exactly to keys. One called 'Y' (corresponding to the Dependent Variable that we wish to adjust using covariance) that points to an array ref or directly as an anonymous array of the corresponding data. The other key must be termed 'X' and corresponds to the concomitant variable whose covariation will be used to adjust Y. X is also passed as an array ref/anonymous array.

  $anc->load_data ( { data => { 'GroupA' => {   Y => [qw/ 29 27 31 33 32 24 16 /],      X => [qw/ 53 64 55 67 55 45 35 /], },
                                'GroupB' => {   Y => [qw/ 39 34 20 35 57 28 32 17 /],   X => [qw/ 24 19 13 18 25 16 16 13 /], }, 
                                'GroupC' => {   Y => [qw/ 12 21 26 17 25 9 12 /],       X => [qw/ 5 12 12 9 12 3 3 /], }, }, 
                  } );

unload

To clear the object use unload.

    $anc->unload;

ancova_analysis

To perform the analysis.

    $anc->ancova_analysis;

results

Used to access the results of the ANCOVA analysis. This method is context-dependent and will return a variety of different values depending on its calling context. In VOID context prints a report to STDOUT (use set_output_verbosity to print more detailed report).

    # To print a short report to STDOUT
    $anc->results();
    # To print a detailed report set output_verbosity to 1 on object creation or using the set_output_verbosity> method.
    $anc->set_output_verbosity(1);
    $anc->results();

In LIST context it either returns the full list of all relevant values of F, p, df, MS... or returns an ordered subset of the values depending on whether you call it without or with numbered arguments respectively (see below).

    # Calling results in LIST without arguments returns the full list of relevant values of F, p, df, MS...
    my %hash;
    @hash{qw($F_score, $p_value, $MS_bg, $SS_bg_Adj, $df_bg_Y, $MS_wg, $SS_wg_Adj, $df_wg_Y_Adj, $SS_total_Adj)} = $anc->results();
    for (keys %hash) { print qq{\n$_ = $hash{$_} } };

However, calling results in LIST context with numbered arguments corresponding to those below returns those arguments in the order passed to the method.

    #      0         1        2        3          4         5        6            7              8      
    # ($F_score, $p_value, $MS_bg, $SS_bg_Adj, $df_bg_Y, $MS_wg, $SS_wg_Adj, $df_wg_Y_Adj, $SS_total_Adj) = $anc->results(2,3,5)   
    print qq{\n\nCalling in LIST context. The F value, p_value, MS_bg and MS_wg are: @{$anc->results(0,1,2,,5)}};

In BOOLEAN context it returns true or false depending on whether the obtained F score was significant at the p_value chosen upon object creation or set using the set_significance method (defaults to p = 0.05).

    if ($anc->results) { print qq{\nThis result is significant.} } else { print qq{\nThis result is not significant.} }

In STRING context it returns a string message about whether the obtained F score was significant at the chosen p_value.

    print qq{\n\nCall result in string returns a message : }, ''.$anc->results;  # Prints 'This value of F is significant at your chosen .05 level'...

DEPENDENCIES

'version' => 0, 'Statistics::Distributions' => '1.02', 'Math::Cephes' => '0.47', 'Carp' => '1.08', 'Perl6::Form' => '0.04', 'Contextual::Return' => '0.2.1', 'List::Util' => '1.19',

AUTHOR

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

LICENCE AND COPYRIGHT

Copyright (c) 2009, Daniel S. T. Hughes <dsth@cpan.org>. 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.

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.