File Coverage

blib/lib/Text/NSP/Measures/3D/MI.pm
Criterion Covered Total %
statement 49 98 50.0
branch 38 56 67.8
condition n/a
subroutine 6 6 100.0
pod 2 2 100.0
total 95 162 58.6


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Text::NSP::Measures::3D::MI - Perl module that provides error checks and
4             framework to implement Loglikelihood,
5             Total Mutual Information, Pointwise Mutual
6             Information and Poisson Stirling Measure
7             for trigrams.
8              
9             =head1 SYNOPSIS
10              
11             =head3 Basic Usage
12              
13             use Text::NSP::Measures::3D::MI::ll;
14              
15             $ll_value = calculateStatistic( n111=>10,
16             n1pp=>40,
17             np1p=>45,
18             npp1=>42,
19             n11p=>20,
20             n1p1=>23,
21             np11=>21,
22             nppp=>100);
23              
24             if( ($errorCode = getErrorCode()))
25             {
26             print STDERR $erroCode." - ".getErrorMessage()."\n";
27             }
28             else
29             {
30             print getStatisticName."value for trigram is ".$ll_value."\n";
31             }
32              
33             =head1 DESCRIPTION
34              
35             This module is the base class for the Loglikelihood and the True Mutual
36             Information measures. All these measure are similar. This module provides
37             error checks specific for these measures, it also implements the
38             computations that are common to these measures.
39              
40             =over
41              
42             =item Log-Likelihood measure is computed as
43              
44             Log-Likelihood = 2 * [n111 * log(n111/m111) + n112 * log(n112/m112) +
45             n121 * log(n121/m121) + n122 * log(n122/m122) +
46             n211 * log(n211/m211) + n212 * log(n212/m212) +
47             n221 * log(n221/m221) + n222 * log(n222/m222)]
48              
49             =item Total Mutual Information
50              
51             tmi = [n111/nppp * log(n111/m111) + n112/nppp * log(n112/m112) +
52             n121/nppp * log(n121/m121) + n122/nppp * log(n122/m122) +
53             n211/nppp * log(n211/m211) + n212/nppp * log(n212/m212) +
54             n221/nppp * log(n221/m221) + n222/nppp * log(n222/m222)]
55              
56             =item Pointwise Mutual Information
57              
58             pmi = log (n111/m111)
59              
60             =item Poisson Stirling Measure
61              
62             ps = n111 * ( log(n111/m111) - 1)
63              
64             =back
65              
66             All these methods use the ratio of the observed values to expected values,
67             for computations, and thus have common error checks, so they have been grouped
68             together.
69              
70             =head2 Methods
71              
72             =over
73              
74             =cut
75              
76              
77             package Text::NSP::Measures::3D::MI;
78              
79              
80 6     6   4208 use Text::NSP::Measures::3D;
  6         15  
  6         1809  
81 6     6   30 use strict;
  6         12  
  6         113  
82 6     6   33 use Carp;
  6         11  
  6         356  
83 6     6   29 use warnings;
  6         11  
  6         3674  
84             # use subs(calculateStatistic);
85             require Exporter;
86              
87             our ($VERSION, @EXPORT, @ISA);
88              
89             @ISA = qw(Exporter);
90              
91             @EXPORT = qw(initializeStatistic calculateStatistic
92             getErrorCode getErrorMessage getStatisticName
93             $n111 $n112 $n121 $n122 $n211 $n212 $n221 $n222
94             $m111 $m112 $m121 $m122 $m211 $m212 $m221 $m222
95             $nppp $n1pp $np1p $npp1 $n11p $n1p1 $np11 $n2pp
96             $np2p $npp2 $errorCodeNumber $errorMessage
97             getValues computePMI);
98              
99              
100             $VERSION = '1.03';
101              
102              
103             =item getValues($count_values) - This method calls
104             computeMarginalTotals the computeObservedValues() and
105             the computeExpectedValues() methods to compute the
106             observed and expected values. It checks these values
107             for any errors that might cause the Loglikelihood,
108             TMI and PMI measures to fail.
109              
110             INPUT PARAMS : $count_values .. Reference of an hash containing
111             the count values computed by the
112             count.pl program.
113              
114             RETURN VALUES : 1/undef ..returns '1' to indicate success
115             and an undefined(NULL) value to indicate
116             failure.
117              
118             =cut
119              
120             sub getValues
121             {
122 67     67 1 96 my ($values)=@_;
123              
124 67 100       174 if( !(Text::NSP::Measures::3D::computeMarginalTotals($values)) ) {
125 40         111 return;
126             }
127              
128 27 100       80 if( !(Text::NSP::Measures::3D::computeObservedValues($values)) ) {
129 20         56 return;
130             }
131              
132 7 50       25 if( !(Text::NSP::Measures::3D::computeExpectedValues($values)) ) {
133 0         0 return;
134             }
135              
136             # dont want ($nxy / $mxy) to be 0 or less! flag error if so and return;
137 7 50       20 if ( $n111 )
138             {
139 7 50       25 if ($m111 == 0)
140             {
141 0         0 $errorMessage = "Expected value in cell (1,1,1) must not be zero";
142 0         0 $errorCodeNumber = 211;
143 0         0 return;
144             }
145             }
146 7 100       20 if ( $n112 )
147             {
148 5 50       59 if ($m112 == 0)
149             {
150 0         0 $errorMessage = "Expected value in cell (1,1,2) must not be zero";
151 0         0 $errorCodeNumber = 211; return;
  0         0  
152             }
153             }
154 7 100       118 if ( $n121 )
155             {
156 5 50       22 if ($m121 == 0)
157             {
158 0         0 $errorMessage = "Expected value in cell (1,2,1) must not be zero";
159 0         0 $errorCodeNumber = 211; return;
  0         0  
160             }
161             }
162 7 100       80 if ( $n122 )
163             {
164 5 50       17 if ($m122 == 0)
165             {
166 0         0 $errorMessage = "Expected value in cell (1,2,2) must not be zero";
167 0         0 $errorCodeNumber = 211; return;
  0         0  
168             }
169             }
170 7 100       36 if ( $n211 )
171             {
172 6 50       18 if ($m211 == 0)
173             {
174 0         0 $errorMessage = "Expected value in cell (2,1,1) must not be zero";
175 0         0 $errorCodeNumber = 211;
176 0         0 return;
177             }
178             }
179 7 100       19 if ( $n212 )
180             {
181 5 50       15 if ($m212 == 0)
182             {
183 0         0 $errorMessage = "Expected value in cell (2,1,2) must not be zero";
184 0         0 $errorCodeNumber = 211; return;
  0         0  
185             }
186             }
187 7 100       24 if ( $n221 )
188             {
189 5 50       18 if ($m221 == 0)
190             {
191 0         0 $errorMessage = "Expected value in cell (2,2,1) must not be zero";
192 0         0 $errorCodeNumber = 211; return;
  0         0  
193             }
194             }
195 7 100       92 if ( $n222 )
196             {
197 5 50       18 if ($m222 == 0)
198             {
199 0         0 $errorMessage = "Expected value in cell (2,2,2) must not be zero";
200 0         0 $errorCodeNumber = 211;
201 0         0 return;
202             }
203             }
204              
205 7 50       22 if ($m111 < 0)
206             {
207 0         0 $errorMessage = "Expected Value for cell(1,1,1) should not be negative";
208 0         0 $errorCodeNumber = 212; return;
  0         0  
209             }
210 7 50       20 if ($m112 < 0)
211             {
212 0         0 $errorMessage = "Expected Value for cell (1,1,2) should not be negative";
213 0         0 $errorCodeNumber = 212; return;
  0         0  
214             }
215 7 50       28 if ($m121 < 0)
216             {
217 0         0 $errorMessage = "Expected Value for cell (1,2,1) should not be negative";
218 0         0 $errorCodeNumber = 212; return;
  0         0  
219             }
220 7 50       17 if ($m122 < 0)
221             {
222 0         0 $errorMessage = "Expected Value for cell (1,2,2) should not be negative";
223 0         0 $errorCodeNumber = 212; return;
  0         0  
224             }
225 7 50       20 if ($m211 < 0)
226             {
227 0         0 $errorMessage = "Expected Value for cell (2,1,1) should not be negative";
228 0         0 $errorCodeNumber = 212; return;
  0         0  
229             }
230 7 50       19 if ($m212 < 0)
231             {
232 0         0 $errorMessage = "Expected Value for cell (2,1,2) should not be negative";
233 0         0 $errorCodeNumber = 212; return;
  0         0  
234             }
235 7 50       32 if ($m221 < 0)
236             {
237 0         0 $errorMessage = "Expected Value for cell (2,2,1) should not be negative";
238 0         0 $errorCodeNumber = 212; return;
  0         0  
239             }
240 7 50       22 if ($m222 < 0)
241             {
242 0         0 $errorMessage = "Expected Value for cell (2,2,2) should not be negative";
243 0         0 $errorCodeNumber = 212; return;
  0         0  
244             }
245              
246             # Everything looks good so we can return 1
247 7         28 return 1;
248             }
249              
250              
251              
252             =item computePMI($n, $m) - Computes the pmi of a given
253             observed and expected value pair.
254              
255             INPUT PARAMS : $n ..Observed value
256             $m ..Expected value
257              
258             RETURN VALUES : lognm .. the log of the ratio of
259             observed value to expected
260             value.
261              
262             =cut
263              
264             sub computePMI
265             {
266 42     42 1 50 my $n = shift;
267 42         56 my $m = shift;
268 42 100       65 if($n)
269             {
270 29         37 my $val = $n/$m;
271 29         155 return log($val);
272             }
273             else
274             {
275 13         27 return 0;
276             }
277             }
278              
279              
280              
281             1;
282             __END__