Analysis/Result.pm

filter: Statementstmt 71.8% 92 / 128 Branchbran 39.1% 18 / 46 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 72.7% 16 / 22 Podpod 66.6% 6 / 9 totaltotal 64.3% 132 / 205 CC 32 SCAR 21.3
CC
32
Cov
63%
record_grouping
30.0
_is_subset
12.0
__ANON__
11.1
CRAP 8.4
« Stemma.pm ↑ Summary HasStemma.pm »
1 package Text::Tradition::Analysis::Result;
2  
3 1 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use Digest::MD5 qw/ md5_hex /;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use Encode qw/ encode_utf8 /;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use JSON qw/ to_json /;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use Set::Scalar;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use Text::Tradition::Error;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 =head1 NAME
11  
12 =encoding utf8
13  
14 Text::Tradition::Analysis::Result - object to express an IDP calculation result
15 for a particular graph problem.
16
17 =head1 DESCRIPTION
18  
19 Given a graph (expressing a stemma hypothesis) and a set of witness groupings
20 (expressing variation in reading between witnesses related according to the
21 stemma hypothesis), it is possible to calculate certain properties of how the
22 readings might be related to each other. This calculation depends on a custom
23 program run under the IDP system [TODO URL]. As the problem is NP-hard, the
24 calculation can take a long time. The purpose of this object is to allow storage
25 of calculated results in a database.
26  
27 For each graph problem, the following features can be calculated:
28  
29 =over 4
30  
31 =item * Whether the reading groups form a genealogical pattern on the stemma.
32  
33 =item * The groupings, including lost/hypothetical witnesses if necessary, that minimize the amount of non-genealogical variation on the stemma.
34  
35 =item * The classes, which for each witness express whether (in a minimally non-genealogical case) the witness is a source of its reading, follows a parent witness, or reverts to an ancestral reading that is not the parent's.
36  
37 =back
38  
39 =head1 CONSTRUCTOR
40  
41 =head2 new
42  
43 Creates a new graph problem. Requires two properties:
44  
45 =over 4
46  
47 =item * setlist - An array of arrays expressing the witness sets. The inner
48 arrays will be converted to Set::Scalar objects, and must have distinct members.
49  
50 =item * graph - A dot description of a graph (e.g. the output of a call to
51 Text::Tradition::Stemma::editable) against which the sets will be analyzed.
52  
53 =back
54  
55 All other properties should be calculated by IDP rather than set manually.
56 These include:
57  
58 =over 4
59  
60 =item * is_genealogical - Boolean, indicating whether the witness sets form
61 genealogical groupings on the graph.
62  
63 =item * status - String to indicate whether a solution has been calculated
64 for this analysis problem. Recognized values are "OK" (calculated) and
65 "running" (being calculated now). All other values, or no value, imply that
66 the calculation has yet to take place.
67  
68 =item * groupings - These are extended (if necessary) versions of the witness
69 sets, which include the hypothetical witnesses necessary to minimize coincidence
70 of variation.
71  
72 =item * classes - These are key/value pairs, keyed by witness, indicating for
73 each witness whether it is the source of a reading variant, whether it represents
74 a reversion to an ancestor (but not parent) reading, or whether its reading
75 follows that of a parent on the graph.
76  
77 =back
78  
79 =begin testing
80  
81 use Set::Scalar;
82 use Test::More::UTF8;
83 use Text::Tradition;
84 use TryCatch;
85 use_ok( 'Text::Tradition::Analysis::Result' );
86  
87 # Make a problem with a graph and a set of groupings
88  
89 my $datafile = 't/data/florilegium_tei_ps.xml';
90 my $tradition = Text::Tradition->new( 'input' => 'TEI',
91 'name' => 'flortest',
92 'file' => $datafile );
93 my $s = $tradition->add_stemma( 'dotfile' => 't/data/florilegium.dot' );
94  
95 my $sets = [ [ qw/ D Q / ], [ qw/ F H / ], [ qw/ A B C P S T / ] ];
96 my $extant = {};
97 foreach my $set ( @$sets ) {
98 map { $extant->{$_} = 1 } @$set;
99 }
100 my $sitgraph = $s->editable( { extant => $extant } );
101 my $result = Text::Tradition::Analysis::Result->new(
102 graph => $sitgraph,
103 setlist => $sets );
104 is( ref( $result ), 'Text::Tradition::Analysis::Result', "Got a Result object" );
105 is( $result->graph, $sitgraph, "Got identical graph string back" );
106 is( $result->status, "new", "Calculation status of result set correctly" );
107 my @rsets = $result->sets;
108 is( $rsets[0], '(A B C P S T)', "First set is biggest set" );
109 is( $rsets[1], '(D Q)', "Second set is by alphabetical order" );
110 is( $rsets[2], '(F H)', "Second set is by alphabetical order" );
111  
112 # Add some calculation values
113 $result->is_genealogical( 1 );
114 $result->record_grouping( [ qw/ 4 5 D Q / ] );
115 try {
116 $result->record_grouping( [ qw/ 3 4 D H / ] );
117 ok( 0, "Recorded a grouping that does not match the input sets" );
118 } catch ( Text::Tradition::Error $e ) {
119 like( $e->message, qr/Failed to find witness set that is a subset of/,
120 "Correct error thrown on bad record_grouping attempt" );
121 }
122 # Test manually setting an out-of-range group
123 try {
124 $result->_set_grouping( 3, Set::Scalar->new( qw/ X Y / ) );
125 ok( 0, "Set a grouping at an invalid index" );
126 } catch ( Text::Tradition::Error $e ) {
127 is( $e->message, 'Set / group index 3 out of range for set_grouping',
128 "Caught attempt to set grouping at invalid index" );
129 }
130 $result->record_grouping( [ qw/ 3 F H / ] );
131 my $gp1 = $result->grouping(1);
132 is( $result->minimum_grouping_for( $rsets[1] ), $gp1,
133 "Found a minimum grouping for D Q" );
134 is( "$gp1", "(4 5 D Q)", "Retrieved minimum grouping is correct" );
135 is( $result->minimum_grouping_for( $rsets[0] ), $rsets[0],
136 "Default minimum grouping found for biggest group" );
137 $result->record_grouping( [ qw/ 1 α δ A B C P S T / ] );
138 my %classes = (
139 α => 'source',
140 3 => 'source',
141 4 => 'source' );
142 foreach my $gp ( $result->groupings ) {
143 map { my $c = $classes{$_} || 'copy'; $result->set_class( $_, $c ) } @$gp;
144 }
145 foreach my $gp ( $result->groupings ) {
146 foreach my $wit ( @$gp ) {
147 my $expected = $classes{$wit} || 'copy';
148 is( $result->class( $wit ), $expected, "Got expected witness class for $wit" );
149 }
150 }
151  
152 # Now write it out to JSON
153 my $struct = $result->TO_JSON;
154 my $newresult = Text::Tradition::Analysis::Result->new( $struct );
155 is( $result->object_key, $newresult->object_key,
156 "Object key stayed constant on export/import" );
157 my $problem = Text::Tradition::Analysis::Result->new( graph => $sitgraph, setlist => $sets );
158 is( $problem->object_key, $result->object_key,
159 "Object key stayed constant for newly created problem" );
160  
161  
162 =end testing
163  
164 =head1 METHODS
165  
166 =head2 $self->has_class( $witness )
167  
168 =head2 $self->class( $witness )
169  
170 If a class has been calculated for the given witness, has_class returns true
171 and class returns the calculated answer.
172  
173 =cut
174  
175 1 has 'setlist' => (
176 traits => ['Array'],
177 isa => 'ArrayRef[Set::Scalar]',
178 handles => {
179 sets => 'elements',
180 set_index => 'first_index',
181 },
182 required => 1
183 );
184  
185 1 has 'graph' => (
186 is => 'ro',
187 isa => 'Str',
188 required => 1
189 );
190  
191 1 has 'status' => (
192 is => 'rw',
193 isa => 'Str'
194 );
195  
196 1 has 'is_genealogical' => (
197 is => 'rw',
198 isa => 'Bool',
199 predicate => 'has_genealogical_result'
200 );
201  
202 has 'groupinglist' => (
203 traits => ['Array'],
204 isa => 'ArrayRef[Set::Scalar]',
205 handles => {
206 groupings => 'elements',
207 _set_grouping => 'set',
208 grouping => 'get',
209 },
210 248 ▶ default => sub { [] }
Subroutine __ANON__: called CC=1 SCAR=0.0
211 1 );
212  
213 1 has 'classlist' => (
214 traits => ['Hash'],
215 isa => 'HashRef[Str]',
216 handles => {
217 class => 'get',
218 has_class => 'exists',
219 set_class => 'set',
220 classes => 'elements',
221 assigned_wits => 'keys',
222 },
223 );
224  
225 248 ▶around BUILDARGS => sub {
Subroutine __ANON__: called CC=9 SCAR=24.1
226 248 my $orig = shift;
227 248 my $class = shift;
228 248 ▶ my $args = @_ == 1 ? $_[0] : { @_ };
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 ? : 0 248 248
229
230 # Convert the set list into a list of Set::Scalars, ordered first by size and
231 # then alphabetically by first-sorted.
232 throw( "Must specify a set list to Analysis::Result->new()" )
233 248 ▶ unless ref( $args->{'setlist'} ) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $args->{"setlist"} eq "ARRAY" 0 248 248
234 throw( "Empty set list specified to Analysis::Result->new()" )
235 248 ▶ unless @{$args->{'setlist'}};
Branch: 1 branch
BranchTrueFalseTotal
unless @{$args->{"setlist"};} 0 248 248
236 # Order the sets and make sure they are all distinct Set::Scalars.
237 297 $args->{'setlist'} = [ sort { by_size_and_alpha( $a, $b ) }
238 248 _check_set_args( $args->{'setlist'} ) ];
239 248 ▶ if( exists $args->{'groupinglist'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $args->{"groupinglist"}) 0 248 248
240 0 $args->{'groupinglist'} = [ _check_set_args( $args->{'groupinglist'} ) ];
241 }
242
243 # If we have been passed a Text::Tradition::Stemma or a Graph, save only
244 # its string.
245 248 ▶ if( ref( $args->{'graph'} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $args->{"graph"}) 248 0 248
246 248 my $st = delete $args->{'graph'};
247 248 my $type = ref( $st );
248 248 my $gopt = { linesep => ' ' };
249 248 ▶ if( $type eq 'Text::Tradition::Stemma' ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($type eq 'Text::Tradition::Stemma') { } 0 248 248
elsif ($type eq 'Graph') { } 248 0 248
250 0 $args->{'graph'} = $st->editable( $gopt );
251 } elsif( $type eq 'Graph' ) {
252 248 $args->{'graph'} = Text::Tradition::Stemma::editable_graph( $st, $gopt );
253 } else {
254 0 throw( "Passed argument to graph that is neither Stemma nor Graph" );
255 }
256 }
257
258 # If our only args are graph and setlist, then status should be 'new'
259 248 ▶ if( scalar keys %$args == 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar keys %$args == 2) 248 0 248
260 248 $args->{'status'} = 'new';
261 }
262
263 248 return $class->$orig( $args );
264 1 };
265  
266 248 ▶sub _check_set_args {
Subroutine _check_set_args: called CC=6 SCAR=19.9
267 248 my $setlist = shift;
268 248 my @sets;
269 248 foreach my $set ( @{$setlist} ) {
270 523 my $s = $set;
271 # Check uniqueness of the current set
272 523 ▶ if( ref( $set ) ne 'Set::Scalar' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $set ne "Set::Scalar") 0 523 523
273 0 $s = Set::Scalar->new( @$set );
274 0 ▶ throw( "Duplicate element(s) in set or group passed to Analysis::Result->new()" )
Branch: 1 branch
BranchTrueFalseTotal
unless @$set == $s->elements 0 0 0
275 unless @$set == $s->elements;
276 }
277 # Check distinctness of the set from all other sets given so far
278 523 foreach my $ps ( @sets ) {
279 311 ▶ throw( "Two sets $s / $ps are not disjoint" )
Branch: 1 branch
BranchTrueFalseTotal
unless $s->is_disjoint($ps) 0 311 311
280 unless $s->is_disjoint( $ps );
281 }
282 # Save the set.
283 523 push( @sets, $s );
284 }
285 248 return @sets;
286 }
287  
288 248 ▶sub BUILD {
Subroutine BUILD: called CC=3 SCAR=11.0
Pod undocumented
289 248 my $self = shift;
290
291 # Initialize the groupings array
292 248 my @sets = $self->sets;
293 248 foreach my $idx( 0 .. $#sets ) {
294 523 ▶ unless( $self->grouping( $idx ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->grouping($idx)) 523 0 523
295 523 my $g = $sets[$idx]->clone();
296 523 $self->_set_grouping( $idx, $g );
297 }
298 }
299 }
300  
301 523 ▶before '_set_grouping' => sub {
Subroutine __ANON__: called CC=2 SCAR=7.4
302 523 my $self = shift;
303 523 my $idx = $_[0];
304 523 my $max = scalar $self->sets;
305 523 ▶ if( $idx >= $max ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($idx >= $max) 0 523 523
306 0 throw( "Set / group index $idx out of range for set_grouping" );
307 }
308 1 };
309  
310 =head2 $self->object_key
311  
312 Returns a unique key that can be used to look up this graph/set combination in
313 a database. Currently an MD5 hash of the request_string.
314  
315 =cut
316  
317 496 ▶sub object_key {
Subroutine object_key: called CC=1 SCAR=0.0
Pod documented
318 496 my $self = shift;
319 496 return md5_hex( encode_utf8( $self->request_string ) );
320 }
321  
322 =head2 $self->request_string
323  
324 A request string is the graph followed by the groups, which should form a unique
325 key for the result.
326  
327 =cut
328  
329 496 ▶sub request_string {
Subroutine request_string: called CC=1 SCAR=0.0
Pod documented
330 496 my $self = shift;
331 496 return $self->graph . '//' . join( ',', $self->sets );
332 }
333  
334 =head2 by_size_and_alpha
335  
336 A useful utility function to sort Set::Scalar objects first in descending
337 order by size, then in ascending alphabetical order by first element (i.e.
338 by stringification.)
339  
340 =cut
341  
342 297 ▶sub by_size_and_alpha {
Subroutine by_size_and_alpha: called CC=2 SCAR=6.9
Pod documented
343 297 my( $a, $b ) = @_;
344 297 my $size = $b->members <=> $a->members;
345 297 ▶ return $size if $size;
Branch: 1 branch
BranchTrueFalseTotal
if $size 277 20 297
346 # Then sort by alphabetical order of set elements.
347 20 return "$a" cmp "$b";
348 }
349  
350 =head2 $self->sources
351  
352 Return all 'source' class witnesses in these sets for this graph.
353  
354 =cut
355  
356 0 ▶sub sources {
Subroutine sources: not called CC=1 SCAR=6.9
Pod documented
357 0 my $self = shift;
358 0 my @sources = grep { $self->class( $_ ) eq 'source' } $self->assigned_wits;
359 0 return @sources;
360 }
361  
362 =head2 $self->minimum_grouping_for( $set )
363  
364 Return the minimum grouping (including necessary hypothetical witnesses) for
365 the witness set specified. Will return undef if $set does not match one of
366 the defined witness sets in $self->sets.
367  
368 =cut
369  
370 # Look for a matching set in our setlist, and return its corresponding group
371 0 ▶sub minimum_grouping_for {
Subroutine minimum_grouping_for: not called CC=2 SCAR=17.9
Pod documented
372 0 my( $self, $set ) = @_;
373 0 ▶ my $midx = $self->set_index( sub { "$set" eq "$_" } );
Subroutine __ANON__: not called CC=1 SCAR=6.9
374 0 ▶ return undef unless defined $midx;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $midx 0 0 0
375 0 return $self->grouping( $midx );
376 }
377  
378 =head1 CALCULATION STORAGE METHODS
379  
380 =head2 $self->is_genealogical( $bool )
381  
382 Record that the sets are genealogical for this graph.
383  
384 =head2 $self->set_class( $witness, $class )
385  
386 Record that the witness in question is of the given class.
387  
388 =head2 $self->record_grouping( $group )
389  
390 Record that the group in question (either an arrayref or a Set::Scalar) forms
391 a minimum grouping on the graph. Will throw an error unless the group is a
392 (non-proper) superset of an existing witness set.
393  
394 =cut
395  
396 0 ▶sub record_grouping {
Subroutine record_grouping: not called CC=5 SCAR=34.0
Pod documented
397 0 my( $self, $group ) = @_;
398 0 ▶ unless( ref( $group ) eq 'Set::Scalar' ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $group eq "Set::Scalar") 0 0 0
399 0 my $s = Set::Scalar->new( @$group );
400 0 $group = $s;
401 }
402 # Find the set that is a subset of this group, and record it in the
403 # correct spot in our groupinglist.
404 0 my $idx = 0;
405 0 foreach my $set ( $self->sets ) {
406 0 ▶ if( _is_subset( $set, $group ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (_is_subset($set, $group)) 0 0 0
407 0 $self->_set_grouping( $idx, $group );
408 0 last;
409 }
410 0 $idx++;
411 }
412 0 ▶ if( $idx == scalar( $self->sets ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($idx == scalar $self->sets) 0 0 0
413 0 throw( "Failed to find witness set that is a subset of $group" );
414 }
415 }
416  
417 0 ▶sub _is_subset {
Subroutine _is_subset: not called CC=3 SCAR=24.8
418 # A replacement for the stupid Set::Scalar::is_subset
419 0 my( $set1, $set2 ) = @_;
420 0 my %all;
421 0 map { $all{$_} = 1 } $set2->members;
422 0 foreach my $m ( $set1->members ) {
423 0 ▶ return 0 unless $all{$m};
Branch: 1 branch
BranchTrueFalseTotal
unless $all{$m} 0 0 0
424 }
425 0 return 1;
426 }
427  
428 96 ▶sub TO_JSON {
Subroutine TO_JSON: called CC=8 SCAR=21.6
Pod undocumented
429 96 my $self = shift;
430 # Required values: graph and setlist
431 96 my $data = {
432 graph => $self->graph,
433 setlist => [],
434 };
435 96 foreach my $set ( $self->sets ) {
436 219 push( @{$data->{setlist}}, [ $set->members ] );
437 }
438 # Scalar values, if they are set
439 96 ▶ $data->{is_genealogical} = 1 if $self->is_genealogical;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_genealogical 0 96 96
440 96 ▶ $data->{status} = $self->status if $self->status;
Branch: 1 branch
BranchTrueFalseTotal
if $self->status 96 0 96
441
442 # Set values, if they exist
443 96 ▶ $data->{groupinglist} = [] if $self->groupings;
Branch: 1 branch
BranchTrueFalseTotal
if $self->groupings 96 0 96
444 96 foreach my $group ( $self->groupings ) {
445 219 push( @{$data->{groupinglist}}, [ $group->members ] );
446 }
447 96 ▶ $data->{classlist} = {} if $self->assigned_wits;
Branch: 1 branch
BranchTrueFalseTotal
if $self->assigned_wits 0 96 96
448 96 foreach my $wit ( $self->assigned_wits ) {
449 0 $data->{classlist}->{$wit} = $self->class( $wit );
450 }
451 96 return $data;
452 }
453  
454 0 ▶sub throw {
Subroutine throw: not called CC=1 SCAR=6.9
Pod undocumented
455 0 Text::Tradition::Error->throw(
456 'ident' => 'Analysis::Result error',
457 'message' => $_[0],
458 );
459 }
460  
461 1 ▶no Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
462 1 __PACKAGE__->meta->make_immutable;
463  
464 1 1;
« Stemma.pm ↑ Summary HasStemma.pm »