package Bio::Phylo::Matrices::Character;
use strict;
use warnings;
use base 'Bio::Phylo::Matrices::TypeSafeData';
use Bio::Phylo::Factory;
use Bio::Phylo::Util::CONSTANT qw'_CHARACTER_ _CHARACTERS_ _NS_BIOPHYLO_ /looks_like/';
use Bio::Phylo::Util::Exceptions 'throw';
my $fac = Bio::Phylo::Factory->new;
=head1 NAME
Bio::Phylo::Matrices::Character - A character (column) in a matrix
=head1 SYNOPSIS
# No direct usage
=head1 DESCRIPTION
Objects of this type represent a single character in a matrix. By default, a
matrix will adjust the number of such objects it requires automatically as its
contents grow or shrink. The main function, at present, for objects of this
type is to facilitate NeXML serialization of characters and their annotations.
=head1 METHODS
=head2 MUTATORS
=over
=item set_weight()
Type : Mutator
Title : set_weight
Usage : $character->set_weight(2);
Function: Sets character weight
Returns : $self
Args : A number
=cut
sub set_weight : Clonable {
my ( $self, $weight ) = @_;
if ( looks_like_number $weight ) {
if ( my ($meta) = @{ $self->get_meta('bp:charWeight') } ) {
$meta->set_triple( 'bp:charWeight' => $weight );
}
else {
$self->add_meta(
$fac->create_meta(
'-namespaces' => { 'bp' => _NS_BIOPHYLO_ },
'-triple' => { 'bp:charWeight' => $weight },
)
);
}
}
elsif ( defined $weight ) {
throw 'BadNumber' => "'$weight' is not a number";
}
return $self;
}
=item set_codonpos()
Type : Mutator
Title : set_codonpos
Usage : $character->set_codonpos(2);
Function: Sets codon position for the column
Returns : $self
Args : A number
=cut
sub set_codonpos : Clonable {
my ( $self, $codonpos ) = @_;
if ( $codonpos ) {
if ( $codonpos == 1 || $codonpos == 2 || $codonpos == 3 ) {
if ( my ($meta) = @{ $self->get_meta('bp:codonPos') } ) {
$meta->set_triple( 'bp:codonPos' => $codonpos );
}
else {
$self->add_meta(
$fac->create_meta(
'-namespaces' => { 'bp' => _NS_BIOPHYLO_ },
'-triple' => { 'bp:codonPos' => $codonpos },
)
);
}
}
elsif ( defined $codonpos ) {
throw 'BadNumber' => "'$codonpos' is not a valid 1-based codon position";
}
}
return $self;
}
=back
=head2 ACCESSORS
=over
=item get_weight()
Type : Accessor
Title : get_weight
Usage : my $weight = $character->get_weight();
Function: Gets character weight
Returns : A number (default is 1)
Args : NONE
=cut
sub get_weight {
shift->get_meta_object('bp:charWeight');
}
=item get_codonpos()
Type : Mutator
Title : get_codonpos
Usage : my $pos = $character->get_codonpos;
Function: Gets codon position for the column
Returns : 1, 2, 3 or undef
Args : None
=cut
sub get_codonpos {
shift->get_meta_object('bp:codonPos');
}
=back
=head2 SERIALIZERS
=over
=item to_xml()
Serializes characters to nexml format.
Type : Format convertor
Title : to_xml
Usage : my $xml = $characters->to_xml;
Function: Converts characters object into a nexml element structure.
Returns : Nexml block (SCALAR).
Args : NONE
=cut
sub to_xml {
my $self = shift;
if ( my $to = $self->get_type_object ) {
if ( $to->get_type !~ m/continuous/i ) {
$self->set_attributes( 'states' => $to->get_xml_id );
}
}
return $self->SUPER::to_xml;
}
sub _validate { 1 }
sub _container { _CHARACTERS_ }
sub _type { _CHARACTER_ }
sub _tag { 'char' }
=back
=cut
# podinherit_insert_token
=head1 SEE ALSO
There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo>
for any user or developer questions and discussions.
=over
=item L<Bio::Phylo::Matrices::TypeSafeData>
This object inherits from L<Bio::Phylo::Matrices::TypeSafeData>, so the
methods defined therein are also applicable to characters objects
objects.
=item L<Bio::Phylo::Manual>
Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com>.
=back
=head1 CITATION
If you use Bio::Phylo in published research, please cite it:
B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
I<BMC Bioinformatics> B<12>:63.
L<http://dx.doi.org/10.1186/1471-2105-12-63>
=cut
1;