analysis/lib/Text/Tradition/HasStemma.pm

   1 package Text::Tradition::HasStemma;
   2
   3 use strict;
   4 use warnings;
   5 use Moose::Role;
   6 use Date::Parse;
   7 use Text::Tradition::Stemma;
   8
   9 =head1 NAME
  10
  11 Text::Tradition::HasStemma - add-on to associate stemma hypotheses to
  12 Text::Tradition objects
  13
  14 =head1 DESCRIPTION
  15
  16 It is often the case that, for a given text tradition, the order of copying
  17 of the witnesses can or should be reconstructed (or at least the attempt
  18 should be made.) This class is a role that can be applied to
  19 Text::Tradition objects to record stemma hypotheses.  See the documentation
  20 for L<Text::Tradition::Stemma> for more information.
  21
  22 =head1 METHODS
  23
  24 =head2 stemmata
  25
  26 Return a list of all stemmata associated with the tradition.
  27
  28 =head2 stemma_count
  29
  30 Return the number of stemma hypotheses defined for this tradition.
  31
  32 =head2 stemma( $idx )
  33
  34 Return the L<Text::Tradition::Stemma> object identified by the given index.
  35
  36 =head2 clear_stemmata
  37
  38 Delete all stemma hypotheses associated with this tradition.
  39
  40 =head2 has_stemweb_jobid
  41
  42 Returns true if there is currently a Stemweb job ID, indicating that a
  43 stemma tree calculation from the Stemweb service is in process.
  44
  45 =head2 stemweb_jobid
  46
  47 Return the currently-running job ID (if any) for calculation of Stemweb
  48 trees.
  49
  50 =head2 set_stemweb_jobid( $jobid )
  51
  52 Record a job ID for a Stemweb calculation.
  53
  54 =cut
  55
  56 has 'stemmata' => (
  57         traits => ['Array'],
  58         isa => 'ArrayRef[Text::Tradition::Stemma]',
  59         handles => {
  60                 stemmata => 'elements',
  61                 _add_stemma => 'push',
  62                 stemma => 'get',
  63                 stemma_count => 'count',
  64                 clear_stemmata => 'clear',
  65         },
  66         default => sub { [] },
  67         );
  68
  69 has 'stemweb_jobid' => (
  70         is => 'ro',
  71         isa => 'Str',
  72         writer => 'set_stemweb_jobid',
  73         predicate => 'has_stemweb_jobid',
  74         clearer => '_clear_stemweb_jobid',
  75         );
  76
  77 before 'set_stemweb_jobid' => sub {
  78         my( $self ) = shift;
  79         if( $self->has_stemweb_jobid ) {
  80                 $self->throw( "Tradition already has a Stemweb jobid: "
  81                         . $self->stemweb_jobid );
  82         }
  83 };
  84
  85 =head2 add_stemma( dotfile => $dotfile )
  86 =head2 add_stemma( dot => $dotstring )
  87 =head2 add_stemma( $stemma_obj )
  88
  89 Initializes a Text::Tradition::Stemma object from the given dotfile,
  90 and associates it with the tradition.
  91
  92 =begin testing
  93
  94 use Text::Tradition;
  95
  96 my $t = Text::Tradition->new(
  97     'name'  => 'simple test',
  98     'input' => 'Tabular',
  99     'file'  => 't/data/simple.txt',
 100     );
 101 is( $t->stemma_count, 0, "No stemmas added yet" );
 102 my $s;
 103 ok( $s = $t->add_stemma( dotfile => 't/data/simple.dot' ), "Added a simple stemma" );
 104 is( ref( $s ), 'Text::Tradition::Stemma', "Got a stemma object returned" );
 105 is( $t->stemma_count, 1, "Tradition claims to have a stemma" );
 106 is( $t->stemma(0), $s, "Tradition hands back the right stemma" );
 107
 108 =end testing
 109
 110 =cut
 111
 112 sub add_stemma {
 113         my $self = shift;
 114         my $stemma;
 115         if( ref( @_ ) eq 'Text::Tradition::Stemma' ) {
 116                 $stemma = shift;
 117         } else {
 118                 $stemma = Text::Tradition::Stemma->new( @_ );
 119         }
 120         $self->_add_stemma( $stemma ) if $stemma;
 121         return $stemma;
 122 }
 123
 124 =head2 record_stemweb_result( $format, $data )
 125
 126 Records the result returned by a Stemweb calculation, and clears any
 127 existing job ID. Returns any new stemmata that were created.
 128
 129 =begin testing
 130
 131 use Text::Tradition;
 132 use JSON qw/ from_json /;
 133
 134 my $t = Text::Tradition->new(
 135     'name'  => 'Stemweb test',
 136     'input' => 'Self',
 137     'file'  => 't/data/besoin.xml',
 138     'stemweb_jobid' => '4',
 139     );
 140
 141 is( $t->stemma_count, 0, "No stemmas added yet" );
 142
 143 my $answer = from_json( '{"status": 0, "job_id": "4", "algorithm": "RHM", "format": "newick", "start_time": "2013-10-26 10:44:14.050263", "result": "((((((((((((F,U),V),S),T1),T2),A),J),B),L),D),M),C);\n", "end_time": "2013-10-26 10:45:55.398944"}' );
 144 my $newst = $t->record_stemweb_result( $answer );
 145 is( scalar @$newst, 1, "New stemma was returned from record_stemweb_result" );
 146 is( $newst->[0], $t->stemma(0), "Answer has the right object" );
 147 ok( !$t->has_stemweb_jobid, "Job ID was removed from tradition" );
 148 is( $t->stemma_count, 1, "Tradition has new stemma" );
 149 ok( $t->stemma(0)->is_undirected, "New stemma is undirected as it should be" );
 150 is( $t->stemma(0)->identifier, "RHM 1382784254_0", "Stemma has correct identifier" );
 151 is( $t->stemma(0)->from_jobid, 4, "New stemma has correct associated job ID" );
 152
 153
 154 =end testing
 155
 156 =cut
 157
 158 sub record_stemweb_result {
 159         my( $self, $answer ) = @_;
 160         my $jobid = $self->stemweb_jobid;
 161         my $stemmata = [];
 162         if( $answer->{format} eq 'dot' ) {
 163                 $self->add_stemma( dot => $answer->{result} );
 164         } elsif( $answer->{format} eq 'newick' ) {
 165                 $stemmata = Text::Tradition::Stemma->new_from_newick( $answer->{result} );
 166                 my $title = sprintf( "%s %d", $answer->{algorithm},
 167                         str2time( $answer->{start_time}, 'UTC' ) );
 168                 my $i = 0;
 169                 foreach my $stemma ( @$stemmata ) {
 170                         my $ititle = $title . "_$i"; $i++;
 171                         $stemma->set_identifier( $ititle );
 172                         $stemma->_set_from_jobid( $jobid );
 173                         $self->_add_stemma( $stemma );
 174                 }
 175         } else {
 176                 $self->throw( "Cannot parse tree results with format " . $answer->{format} );
 177         }
 178         $self->_clear_stemweb_jobid();
 179         return $stemmata;
 180 }
 181
 182 1;
 183
 184 =head1 LICENSE
 185
 186 This package is free software and is provided "as is" without express
 187 or implied warranty.  You can redistribute it and/or modify it under
 188 the same terms as Perl itself.
 189
 190 =head1 AUTHOR
 191
 192 Tara L Andrews E<lt>aurum@cpan.orgE<gt>