File Coverage

blib/lib/Text/NSP/Measures/3D/MI/tmi.pm

Criterion	Covered	Total	%
statement	28	29	96.5
branch	2	2	100.0
condition			n/a
subroutine	6	7	85.7
pod			n/a
total	36	38	94.7

=head1 NAME

Text::NSP::Measures::3D::MI::tmi - Perl implementation for True Mutual
                                   Information for trigrams.

=head1 SYNOPSIS

=head3 Basic Usage

  use Text::NSP::Measures::3D::MI::tmi;

  $tmi_value = calculateStatistic( n111=>10,
                                  n1pp=>40,
                                  np1p=>45,
                                  npp1=>42,
                                  n11p=>20,
                                  n1p1=>23,
                                  np11=>21,
                                  nppp=>100);

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

=head1 DESCRIPTION

True Mutual Information (tmi) is defined as the weighted average of the
pointwise mutual informations for all the observed and expected value pairs.

 tmi = [n111/nppp * log(n111/m111) + n112/nppp * log(n112/m112) +
        n121/nppp * log(n121/m121) + n122/nppp * log(n122/m122) +
        n211/nppp * log(n211/m211) + n212/nppp * log(n212/m212) +
        n221/nppp * log(n221/m221) + n222/nppp * log(n222/m222)]

 PMI =   log (n111/m111)

Here n111 represents the observed value for the cell (1,1,1) and m111
represents the expected value for that cell. The expected values for
the internal cells are calculated by taking the product of their
associated marginals and dividing by the sample size, for example:

            n1pp * np1p * npp1
   m111=   --------------------
                   nppp

=head2 Methods

=over

=cut


package Text::NSP::Measures::3D::MI::tmi;


use Text::NSP::Measures::3D::MI;
use strict;
use Carp;
use warnings;
no warnings 'redefine';
require Exporter;

our ($VERSION, @EXPORT, @ISA);

@ISA  = qw(Exporter);

@EXPORT = qw(initializeStatistic calculateStatistic
             getErrorCode getErrorMessage getStatisticName);

$VERSION = '0.97';


=item calculateStatistic($count_values) - This method calculates
the tmi value

INPUT PARAMS  : $count_values   .. Reference of an hash containing
                                   the count values computed by the
                                   count.pl program.

RETURN VALUES : $tmi            .. TMI value for this trigram.

=cut

sub calculateStatistic
{
  my %values = @_;

  # computes and returns the observed and expected 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::3D::MI::getValues(\%values)) ) {
    return(0);
  }

  #my $marginals = $self->computeMarginalTotals(@_);

  #  Now for the actual calculation of TMI!
  my $tmi = 0;

  # dont want ($nxy / $mxy) to be 0 or less! flag error if so!
  $tmi += $n111/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n111, $m111 )/ log 2;
  $tmi += $n112/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n112, $m112 )/ log 2;
  $tmi += $n121/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n121, $m121 )/ log 2;
  $tmi += $n122/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n122, $m122 )/ log 2;
  $tmi += $n211/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n211, $m211 )/ log 2;
  $tmi += $n212/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n212, $m212 )/ log 2;
  $tmi += $n221/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n221, $m221 )/ log 2;
  $tmi += $n222/$nppp * Text::NSP::Measures::3D::MI::computePMI( $n222, $m222 )/ log 2;

  return ($tmi);
}


=item getStatisticName() - Returns the name of this statistic

INPUT PARAMS  : none

RETURN VALUES : $name      .. Name of the measure.

=cut

sub getStatisticName
{
    return "True Mutual Information";
}



1;
__END__