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	sub	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