File Coverage

blib/lib/Lingua/Diversity/Result.pm
Criterion Covered Total %
statement 1 3 33.3
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 2 4 50.0


line stmt bran cond sub pod time code
1             package Lingua::Diversity::Result;
2              
3 1     1   16098 use Moose;
  0            
  0            
4              
5             our $VERSION = '0.04';
6              
7              
8              
9             #=============================================================================
10             # Attributes.
11             #=============================================================================
12              
13             has 'diversity' => (
14             is => 'ro',
15             isa => 'Num',
16             reader => 'get_diversity',
17             required => 1,
18             );
19              
20             has 'variance' => (
21             is => 'ro',
22             isa => 'Num',
23             reader => 'get_variance',
24             predicate => 'has_variance',
25             );
26              
27             has 'count' => (
28             is => 'ro',
29             isa => 'Num',
30             reader => 'get_count',
31             predicate => 'has_count',
32             );
33              
34              
35              
36              
37             #=============================================================================
38             # Standard Moose cleanup.
39             #=============================================================================
40              
41             no Moose;
42             __PACKAGE__->meta->make_immutable;
43              
44              
45             __END__
46              
47              
48             =head1 NAME
49              
50             Lingua::Diversity::Result - storing the result of a diversity measurement
51              
52             =head1 VERSION
53              
54             This documentation refers to Lingua::Diversity::Result version 0.04.
55              
56             =head1 SYNOPSIS
57              
58             use Lingua::Diversity::Result;
59              
60             # Given a Lingua::Diversity derived object and an array of data...
61            
62             # Measure diversity in the data and store the result in a Result object.
63             my $result = $diversity->measure( \@data );
64            
65             # A Result object always has a main 'diversity' field...
66             print "Diversity\t", $result->get_diversity(), "\n";
67              
68             # ... and may have a 'variance' and 'count' field...
69             if ( $result->has_variance() ) {
70             print "Variance\t", $result->get_variance(), "\n";
71             }
72             if ( $result->has_count() ) {
73             print "Count\t", $result->get_count(), "\n";
74             }
75              
76              
77             =head1 DESCRIPTION
78              
79             This class implements the result of a L<Lingua::Diversity> derived object's
80             diversity measurement. All diversity measures return a main value stored in
81             the Result's I<diversity> attribute. Those measures for which the main value
82             is an average may also return the corresponding variance and count (i.e.
83             number of observations), which are then stored in the Result's I<variance>
84             and I<count> attributes (this should be documented in the L<Lingua::Diversity>
85             derived class).
86              
87             =head1 CREATOR
88              
89             The creator (C<new()>) returns a new Lingua::Diversity::Result object.
90             In principle, the end user should never call it directly since it is invoked
91             by the C<measure()> and C<measure_per_category()> methods of a given
92             L<Lingua::Diversity> derived class.
93              
94             The constructor takes one required and two optional named parameters:
95              
96             =over 4
97              
98             =item diversity (required)
99              
100             A number characterizing the diversity measured in the data.
101              
102             =item variance
103              
104             If the value of the I<diversity> attribute is an average, this attribute
105             stores the corresponding variance.
106              
107             =item count
108              
109             If the value of the I<diversity> attribute is an average, this attribute
110             stores the corresponding number of observations. In the case of a
111             weighted average, the value of this attribute is the sum of weights, which
112             needs not be an integer.
113              
114             =back
115              
116             =head1 ACCESSORS AND PREDICATES
117              
118             =over 4
119              
120             =item get_diversity()
121              
122             Getter for the I<diversity> attribute.
123              
124             =item get_variance() and has_variance()
125              
126             Getter and predicate for the I<variance> attribute.
127              
128             =item get_count() and has_count()
129              
130             Getter and predicate for the I<count> attribute.
131              
132             =back
133              
134             =head1 DEPENDENCIES
135              
136             This module is part of the L<Lingua::Diversity> distribution, and extends
137             L<Lingua::Diversity>.
138              
139             =head1 BUGS AND LIMITATIONS
140              
141             There are no known bugs in this module.
142              
143             It has been designed under the assumption that a unified set of fields would
144             be convenient to characterize the output of various diversity measures. It
145             turns out that this assumption makes it necessary to leave a lot of useful
146             information out of the results, because the output of every diversity measure
147             has some specificity (besides commonalities with other measures). In a future
148             version, this could be solved by making the Lingua::Diversity::Class (at least
149             partly) abstract, and by designing a derived class for each diversity
150             measure.
151              
152             Please report problems to Aris Xanthos (aris.xanthos@unil.ch)
153              
154             Patches are welcome.
155              
156             =head1 AUTHOR
157              
158             Aris Xanthos (aris.xanthos@unil.ch)
159              
160             =head1 LICENSE AND COPYRIGHT
161              
162             Copyright (c) 2011 Aris Xanthos (aris.xanthos@unil.ch).
163              
164             This program is released under the GPL license (see
165             L<http://www.gnu.org/licenses/gpl.html>).
166              
167             This program is distributed in the hope that it will be useful, but WITHOUT
168             ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
169             FOR A PARTICULAR PURPOSE.
170              
171             =head1 SEE ALSO
172              
173             L<Lingua::Diversity>
174