[scpubgit/stemmatology.git] / analysis / lib / Text / Tradition / HasStemma.pm

package Text::Tradition::HasStemma;

use strict;
use warnings;
use Moose::Role;
use Date::Parse;
use Text::Tradition::Stemma;

=head1 NAME

Text::Tradition::HasStemma - add-on to associate stemma hypotheses to
Text::Tradition objects

=head1 DESCRIPTION

It is often the case that, for a given text tradition, the order of copying
of the witnesses can or should be reconstructed (or at least the attempt
should be made.) This class is a role that can be applied to
Text::Tradition objects to record stemma hypotheses.  See the documentation
for L<Text::Tradition::Stemma> for more information.

=head1 METHODS

=head2 stemmata

Return a list of all stemmata associated with the tradition.

=head2 stemma_count

Return the number of stemma hypotheses defined for this tradition.

=head2 stemma( $idx )

Return the L<Text::Tradition::Stemma> object identified by the given index.

=head2 clear_stemmata

Delete all stemma hypotheses associated with this tradition.

=head2 has_stemweb_jobid

Returns true if there is currently a Stemweb job ID, indicating that a
stemma tree calculation from the Stemweb service is in process.

=head2 stemweb_jobid

Return the currently-running job ID (if any) for calculation of Stemweb 
trees.

=head2 set_stemweb_jobid( $jobid )

Record a job ID for a Stemweb calculation.

=cut

has 'stemmata' => (
	traits => ['Array'],
	isa => 'ArrayRef[Text::Tradition::Stemma]',
	handles => {
		stemmata => 'elements',
		_add_stemma => 'push',
		stemma => 'get',
		stemma_count => 'count',
		clear_stemmata => 'clear',
	},
	default => sub { [] },
	);
  
has 'stemweb_jobid' => (
	is => 'ro',
	isa => 'Str',
	writer => 'set_stemweb_jobid',
	predicate => 'has_stemweb_jobid',
	clearer => '_clear_stemweb_jobid',
	);
	
before 'set_stemweb_jobid' => sub {
	my( $self ) = shift;
	if( $self->has_stemweb_jobid ) {
		$self->throw( "Tradition already has a Stemweb jobid: "
			. $self->stemweb_jobid );
	}
};

=head2 add_stemma( $dotfile )

Initializes a Text::Tradition::Stemma object from the given dotfile,
and associates it with the tradition.

=begin testing

use Text::Tradition;

my $t = Text::Tradition->new( 
    'name'  => 'simple test', 
    'input' => 'Tabular',
    'file'  => 't/data/simple.txt',
    );
is( $t->stemma_count, 0, "No stemmas added yet" );
my $s;
ok( $s = $t->add_stemma( dotfile => 't/data/simple.dot' ), "Added a simple stemma" );
is( ref( $s ), 'Text::Tradition::Stemma', "Got a stemma object returned" );
is( $t->stemma_count, 1, "Tradition claims to have a stemma" );
is( $t->stemma(0), $s, "Tradition hands back the right stemma" );

=end testing

=cut

sub add_stemma {
	my $self = shift;
	my %opts = @_;
	my $stemma_fh;
	if( $opts{'dotfile'} ) {
		open $stemma_fh, '<', $opts{'dotfile'}
			or warn "Could not open file " . $opts{'dotfile'};
	} elsif( $opts{'dot'} ) {
		my $str = $opts{'dot'};
		open $stemma_fh, '<', \$str;
	}
	# Assume utf-8
	binmode $stemma_fh, ':utf8';
	my $stemma = Text::Tradition::Stemma->new( 
		'dot' => $stemma_fh );
	$self->_add_stemma( $stemma ) if $stemma;
	return $stemma;
}

=head2 record_stemweb_result( $format, $data )

Records the result returned by a Stemweb calculation, and clears any
existing job ID. Returns any new stemmata that were created.

=begin testing

use Text::Tradition;
use JSON qw/ from_json /;

my $t = Text::Tradition->new( 
    'name'  => 'Stemweb test', 
    'input' => 'Self',
    'file'  => 't/data/besoin.xml',
    'stemweb_jobid' => '4',
    );

is( $t->stemma_count, 0, "No stemmas added yet" );

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"}' );
my $newst = $t->record_stemweb_result( $answer );
is( scalar @$newst, 1, "New stemma was returned from record_stemweb_result" );
is( $newst->[0], $t->stemma(0), "Answer has the right object" );
ok( !$t->has_stemweb_jobid, "Job ID was removed from tradition" );
is( $t->stemma_count, 1, "Tradition has new stemma" );
ok( $t->stemma(0)->is_undirected, "New stemma is undirected as it should be" );
is( $t->stemma(0)->identifier, "RHM 1382777054_0", "Stemma has correct identifier" );
is( $t->stemma(0)->from_jobid, 4, "New stemma has correct associated job ID" );


=end testing

=cut

sub record_stemweb_result {
	my( $self, $answer ) = @_;
	my $jobid = $self->stemweb_jobid;
	my $stemmata = [];
	if( $answer->{format} eq 'dot' ) {
		$self->add_stemma( dot => $answer->{result} );
	} elsif( $answer->{format} eq 'newick' ) {
		$stemmata = Text::Tradition::Stemma->new_from_newick( $answer->{result} );
		my $title = sprintf( "%s %d", $answer->{algorithm}, 
			str2time( $answer->{start_time} ) );
		my $i = 0;
		foreach my $stemma ( @$stemmata ) {
			my $ititle = $title . "_$i"; $i++;
			$stemma->set_identifier( $ititle );
			$stemma->_set_from_jobid( $jobid );
			$self->_add_stemma( $stemma );
		}
	} else {
		$self->throw( "Cannot parse tree results with format " . $answer->{format} );
	}
	$self->_clear_stemweb_jobid();
	return $stemmata;
}

1;

=head1 LICENSE

This package is free software and is provided "as is" without express
or implied warranty.  You can redistribute it and/or modify it under
the same terms as Perl itself.

=head1 AUTHOR

Tara L Andrews E<lt>aurum@cpan.orgE<gt>
Commit	Line	Data
951ddfe8	1	package Text::Tradition::HasStemma;
	2
	3	use strict;
	4	use warnings;
	5	use Moose::Role;
a47b32d9	6	use Date::Parse;
951ddfe8	7	use Text::Tradition::Stemma;
	8
	9	=head1 NAME
	10
a445ce40	11	Text::Tradition::HasStemma - add-on to associate stemma hypotheses to
a445ce40	12	Text::Tradition objects
951ddfe8	13
	14	=head1 DESCRIPTION
	15
a445ce40	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.
951ddfe8	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
98f22390	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
951ddfe8	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
98f22390	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	};
951ddfe8	84
	85	=head2 add_stemma( $dotfile )
	86
	87	Initializes a Text::Tradition::Stemma object from the given dotfile,
	88	and associates it with the tradition.
	89
	90	=begin testing
	91
	92	use Text::Tradition;
	93
	94	my $t = Text::Tradition->new(
	95	'name' => 'simple test',
	96	'input' => 'Tabular',
	97	'file' => 't/data/simple.txt',
	98	);
951ddfe8	99	is( $t->stemma_count, 0, "No stemmas added yet" );
	100	my $s;
	101	ok( $s = $t->add_stemma( dotfile => 't/data/simple.dot' ), "Added a simple stemma" );
	102	is( ref( $s ), 'Text::Tradition::Stemma', "Got a stemma object returned" );
	103	is( $t->stemma_count, 1, "Tradition claims to have a stemma" );
	104	is( $t->stemma(0), $s, "Tradition hands back the right stemma" );
	105
	106	=end testing
	107
	108	=cut
	109
	110	sub add_stemma {
	111	my $self = shift;
	112	my %opts = @_;
	113	my $stemma_fh;
	114	if( $opts{'dotfile'} ) {
	115	open $stemma_fh, '<', $opts{'dotfile'}
	116	or warn "Could not open file " . $opts{'dotfile'};
	117	} elsif( $opts{'dot'} ) {
	118	my $str = $opts{'dot'};
	119	open $stemma_fh, '<', \$str;
	120	}
	121	# Assume utf-8
	122	binmode $stemma_fh, ':utf8';
	123	my $stemma = Text::Tradition::Stemma->new(
	124	'dot' => $stemma_fh );
	125	$self->_add_stemma( $stemma ) if $stemma;
	126	return $stemma;
	127	}
	128
98f22390	129	=head2 record_stemweb_result( $format, $data )
	130
	131	Records the result returned by a Stemweb calculation, and clears any
738620c7	132	existing job ID. Returns any new stemmata that were created.
98f22390	133
a47b32d9	134	=begin testing
	135
	136	use Text::Tradition;
	137	use JSON qw/ from_json /;
	138
	139	my $t = Text::Tradition->new(
	140	'name' => 'Stemweb test',
	141	'input' => 'Self',
	142	'file' => 't/data/besoin.xml',
	143	'stemweb_jobid' => '4',
	144	);
	145
	146	is( $t->stemma_count, 0, "No stemmas added yet" );
	147
	148	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"}' );
738620c7	149	my $newst = $t->record_stemweb_result( $answer );
	150	is( scalar @$newst, 1, "New stemma was returned from record_stemweb_result" );
	151	is( $newst->[0], $t->stemma(0), "Answer has the right object" );
a47b32d9	152	ok( !$t->has_stemweb_jobid, "Job ID was removed from tradition" );
	153	is( $t->stemma_count, 1, "Tradition has new stemma" );
	154	ok( $t->stemma(0)->is_undirected, "New stemma is undirected as it should be" );
	155	is( $t->stemma(0)->identifier, "RHM 1382777054_0", "Stemma has correct identifier" );
738620c7	156	is( $t->stemma(0)->from_jobid, 4, "New stemma has correct associated job ID" );
a47b32d9	157
	158
	159	=end testing
98f22390	160
	161	=cut
	162
	163	sub record_stemweb_result {
a47b32d9	164	my( $self, $answer ) = @_;
738620c7	165	my $jobid = $self->stemweb_jobid;
738620c7	166	my $stemmata = [];
a47b32d9	167	if( $answer->{format} eq 'dot' ) {
	168	$self->add_stemma( dot => $answer->{result} );
	169	} elsif( $answer->{format} eq 'newick' ) {
5873cf38	170	$stemmata = Text::Tradition::Stemma->new_from_newick( $answer->{result} );
a47b32d9	171	my $title = sprintf( "%s %d", $answer->{algorithm},
	172	str2time( $answer->{start_time} ) );
	173	my $i = 0;
98f22390	174	foreach my $stemma ( @$stemmata ) {
a47b32d9	175	my $ititle = $title . "_$i"; $i++;
a47b32d9	176	$stemma->set_identifier( $ititle );
738620c7	177	$stemma->_set_from_jobid( $jobid );
98f22390	178	$self->_add_stemma( $stemma );
98f22390	179	}
98f22390	180	} else {
a47b32d9	181	$self->throw( "Cannot parse tree results with format " . $answer->{format} );
98f22390	182	}
a47b32d9	183	$self->_clear_stemweb_jobid();
738620c7	184	return $stemmata;
98f22390	185	}
98f22390	186
951ddfe8	187	1;
	188
	189	=head1 LICENSE
	190
	191	This package is free software and is provided "as is" without express
	192	or implied warranty. You can redistribute it and/or modify it under
	193	the same terms as Perl itself.
	194
	195	=head1 AUTHOR
	196
	197	Tara L Andrews E<lt>aurum@cpan.orgE<gt>