Basic Usage

  use Text::NSP::Measures::2D::MI::ll;

  my $npp = 60; my $n1p = 20; my $np1 = 20;  my $n11 = 10;

  $ll_value = calculateStatistic( n11=>$n11,
                                      n1p=>$n1p,
                                      np1=>$np1,
                                      npp=>$npp);

  if( ($errorCode = getErrorCode()))
  {
    print STDERR $errorCode." - ".getErrorMessage()."\n"";
  }
  else
  {
    print getStatisticName."value for bigram is ".$ll_value."\n"";
  }

Introduction

The measures that have been implemented in this distribution are:

1) MI (Mutual Information based Measures)

2) CHI (Measures belonging to the CHI family)

3) Dice (Measures belonging to the Dice family)

4) Fishers Exact Tests

5) Odds Ratio

Further discussion about these measures is in their respective documentations.

Writing your own association measures

You can either write your new measure as a new module, or you can simply write a perl program. Here we will describe how to write a new measure as a perl module Perl.

1.

To create a new Perl module for the measure issue the following command (replace 'NewMeasure' with the name of your measure):

                      or

            or

                        or

2.

Let us say you have named your module NewMeasure. The first line of the file should declare that it is a package. Thus the first line of the file NewMeasure.pm should be...

                  or

3.

3 You need to implement at least one method in your package

            |word2  | not-word2|
            --------------------
    word1   | n11   |   n12    |  n1p
  not-word1 | n21   |   n22    |  n2p
            --------------------
              np1       np2       npp

  if( !(Text::NSP::Measures::2D::computeObservedValues(\%values)) ) {
      return;
  }

4.

The last lines of a module should always return true, to achieve this make sure that the last two lines of the are:

  1;
  __END__
    

Please see, that you can put in documentation after these lines.

5.

There are four other methods that are not mandatory, but may be implemented. These are:

     i) initializeStatistic()
    ii) getErrorCode
   iii) getErrorMessage
   iv) getStatisticName()
    

statistical.pl calls initializeStatistic before calling any other method, if there is no need for any specific initialization in the measure you need not define this method, and the initialization will be handled by the Text::NSP::Measures modules initializeStatistic() method.

The getErrorCode method is called immediately after every call to method calculateStatistic(). This method is used to return the errorCode, if any, in the previous operations. To view all the possible error codes and the corresponding error message please refer to the Text::NSP documentation (perldoc Text::NSP).You can create new error codes in your measure, if the existing error codes are not sufficient.

The Text::NSP::Measures module implements both getErrorCode() and getErrorMessage() methods and these implementations of the method will be invoked if the user does not define these methods. But if you want to add some other actions that need to be performed in case of an error you must override these methods by implementing them in your module. You can invoke the Text::NSP::Measures getErrorCode() methods from your measures getErrorCode() method.

An example of this is below:

  sub getErrorCode
  {
    my $code = Text::NSP::Measures::getErrorCode();

    #your code here

    return $code; #(or any other value)
  }

  sub getErrorMessage
  {
    my $message = Text::NSP::MeasuresgetErrorMessage();

    #your code here

    return $message; #(or any other value)
  }
    

The fourth method that may be implemented is getStatisticName(). If this method is implemented, it is expected to return a string containing the name of the statistic being implemented. This string is used in the formatted output of statistic.pl. If this method is not implemented, then the statistic name entered on the commandline is used in the formatted output.

Note that all the methods described in this section are optional. So, if the user elects to not implement these methods, no harm will be done.

The user may implement other methods too, but since statistic.pl is not expecting anything besides the five methods above, doing so would have no effect on statistic.pl.

6.

You will need to install your module before you can use it. You can do this by

  Change to the base directory for the module, i.e.
  NewMeasure

  Then issue the following commands:

    perl Makefile.PL
    make
    make test
    make install

        or

    perl Makefile.PL PREFIX=<destination directory>
    make
    make test
    make install
    

If you get any errors in the installation process, please make sure that you have not made any syntactical error in your code and also make sure that you have already installed the Text-NSP package.

An Example

  # computes and returns the marginal totals from the frequency
  # combination values. returns undef if there is an error in
  # the computation or the values are inconsistent.
  if(!(Text::NSP::Measures::2D::computeMarginalTotals($values)) ){
    return;
  }

  # computes and returns the observed and marginal values from
  # the frequency combination values. returns 0 if there is an
  # error in the computation or the values are inconsistent.
  if( !(Text::NSP::Measures::2D::computeObservedValues($values)) ) {
      return;
  }


  #  Now for the actual calculation of the association measure
  my $NewMeasure = 0;

  $NewMeasure += $n11;
  $NewMeasure += $n12;
  $NewMeasure += $n21;
  $NewMeasure += $n22;

  return ( $NewMeasure );
}

Errors to look out for:

1.

The Text-NSP package is not installed - Make sure that Text-NSP package is installed and you have inherited the correct module (Text::NSP::Measures::2D or Text::NSP::Measures::3D).

2.

The five methods (1 mandatory, 4 non-mandatory) must have their names match EXACTLY with those shown above. Again, names are all case sensitive.

3.

This statement is present at the end of the module: 1;

Methods

initializeStatistic() - Provides an empty method which is called in case the measures do not override this method. If you need some measure specific initialization, override this method in the implementation of your measure.

INPUT PARAMS : none

RETURN VALUES : none

calculateStatistic() - Provides an empty framework. Your Measure should override this method. INPUT PARAMS : none

RETURN VALUES : none

getErrorCode() - Returns the error code in the last operation if any and resets the errorCode to 0.

# INPUT PARAMS : none

# RETURN VALUES : errorCode .. The current error code.

getErrorMessage() - Returns the error message in the last operation if any and resets the string to ''.

# INPUT PARAMS : none

# RETURN VALUES : errorMessage .. The current error message.

getStatisticName() - Provides an empty method which is called in case the measures do not override this method.

INPUT PARAMS : none

RETURN VALUES : none