Bio::T...hyloxml(3pm)

✨ NAME ✨

okay so bestie, this is Bio::TreeIO::phyloxml — the TreeIO implementation for parsing the PhyloXML format. 💖

(your terminal is out here calling it Bio::T...hyloxml(3pm) in the header because it ran out of room, it's literally the same page, don't stress 🫶)

---

🌸 SYNOPSIS 🌸

# do not use this module directly
use Bio::TreeIO;
my $treeio = Bio::TreeIO->new(-format => 'phyloxml',
                              -file => 'tree.dnd');
my $tree = $treeio->next_tree;

not me warning you twice: do not use this module directly. go through Bio::TreeIO, she's the one holding the keys. 🔑

---

🦋 DESCRIPTION 🦋

This module handles parsing and writing of phyloXML format. that's the whole job, and it does it. ✨

---

💌 FEEDBACK 💌

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. send your comments and suggestions, preferably to the Bioperl mailing list. your participation is much appreciated, fr fr. 🫶

bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. many experienced and responsive experts will be able look at the problem and quickly address it. please include a thorough description of the problem with code and data examples if at all possible. 👑

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

---

👑 AUTHOR - Mira Han 👑

Email mirhan@indiana.edu — she built this, show some respect. 💜

---

📖 APPENDIX 📖

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _. 💅

next_tree

• Title: next_tree
• Usage: my $tree = $treeio->next_tree
• Function: Gets the next tree in the stream
• Returns: Bio::Tree::TreeI
• Args: none

add_attribute

• Title: add_phyloXML_annotation
• Usage: my $node = $treeio->add_phyloXML_annotation(-obj=>$node, -attr=>"id_source = \"A\"")
• Function: add attributes to an object
• Returns: the node that we added annotations to
• Args:
  • -obj => object that will have the Annotation. (Bio::Tree::AnnotatableNode)
  • -attr => string in the form "A = B", where A is the attribute name and B is the attribute value

add_phyloXML_annotation

• Title: add_phyloXML_annotation
• Usage:

my $node = $treeio->add_phyloXML_annotation(-obj=>$node, -xml=>$xmlstring)
my $tree = $treeio->add_phyloXML_annotation('-obj'=>$tree, '-xml'=>'<sequence_relation id_ref_0="A" id_ref_1="B" type="orthology"/>')

• Function: add annotations to a node in the phyloXML format string
• Returns: the node that we added annotations to
• Args:
  • -obj => object that will have the Annotation. (Bio::Tree::AnnotatableNode)
  • -xml => string in phyloXML format that describes the annotation for the node

write_tree

• Title: write_tree
• Usage: $treeio->write_tree($tree);
• Function: Write a tree out to data stream in phyloxml format
• Returns: none
• Args: Bio::Tree::TreeI object

_write_tree_Helper_annotatableNode

• Title: _write_tree_Helper_annotatableNode
• Usage: internal method used by write_tree, not to be used directly
• Function: recursive helper function of write_tree for the annotatableNodes. translates annotations into xml elements.
• Returns: string describing the node
• Args: Bio::Node::AnnotatableNode object, string

_write_tree_Helper_generic

• Title: _write_tree_Helper_generic
• Usage: internal method used by write_tree, not to be used directly
• Function: recursive helper function of write_tree for generic NodesI. all tags are translated into property elements.
• Returns: string describing the node
• Args: Bio::Node::NodeI object, string

_relation_to_string

• Title: _relation_to_string
• Usage: internal method used by write_tree, not to be used directly
• Function: internal function used by write_tree to translate Annotation::Relation objects into xml elements.
• Returns: string describing the node
• Args: Bio::Node::AnnotatableNode (or Bio::SeqI) object that contains the Annotation::Relation, the Annotation::Relation object, the string

read_annotation

• Title: read_annotation
• Usage: $treeio->read_annotation(-obj=>$node, -path=>$path, -attr=>1);
• Function: read text value (or attribute value) of the annotations corresponding to the element path
• Returns: list of text values of the annotations matching the path
• Args:
  • -obj => object that contains the Annotation. (Bio::Tree::AnnotatableNode or Bio::SeqI)
  • -path => path of the nested elements
  • -attr => Boolean value to indicate whether to get the attribute of the element or the text value. (default is 0, meaning text value is returned)

---

🔍 Methods for parsing the XML document 🔍

processXMLNode

• Title: processXMLNode
• Usage: $treeio->processXMLNode
• Function: read the XML node and process according to the node type
• Returns: none
• Args: none

processAttribute

• Title: processAttribute
• Usage: $treeio->processAttribute(\%hash_for_attribute);
• Function: reads the attributes of the current element into a hash
• Returns: none
• Args: hash reference where the attributes will be stored.

element_phylogeny

• Title: element_phylogeny
• Usage: $treeio->element_phylogeny
• Function: initialize the parsing of a tree
• Returns: none
• Args: none

end_element_phylogeny

• Title: end_element_phylogeny
• Usage: $treeio->end_element_phylogeny
• Function: ends the parsing of a tree building a Tree::TreeI object.
• Returns: Tree::TreeI
• Args: none

element_clade

• Title: element_clade
• Usage: $treeio->element_clade
• Function: initialize the parsing of a node, creates a new AnnotatableNode with annotations
• Returns: none
• Args: none

end_element_clade

• Title: end_element_clade
• Usage: $treeio->end_element_clade
• Function: ends the parsing of a node
• Returns: none
• Args: none

element_relation

• Title: element_relation
• Usage: $treeio->element_relation
• Function: starts the parsing of clade relation & sequence relation
• Returns: none
• Args: none

end_element_relation

• Title: end_element_relation
• Usage: $treeio->end_element_relation
• Function: ends the parsing of clade relation & sequence relation
• Returns: none
• Args: none

element_default

• Title: element_default
• Usage: $treeio->element_default
• Function: starts the parsing of all other elements
• Returns: none
• Args: none

end_element_default

• Title: end_element_default
• Usage: $treeio->end_element_default
• Function: ends the parsing of all other elements
• Returns: none
• Args: none

annotateNode

• Title: annotateNode
• Usage: $treeio->annotateNode($element, $ac)
• Function: adds text value and attributes to the AnnotationCollection that has element name as key. If there are nested elements, optional AnnotationCollections are added recursively, with the nested element name as key. The structure of each AnnotationCollection is

'element' => AnnotationCollection {
    '_text' => SimpleValue (text value)
    '_attr' => AnnotationCollection {
        attribute1 => SimpleValue (attribute value 1)
        attribute2 => SimpleValue (attribute value 2)
        ...
    }
    ['nested element' => AnnotationCollection ]
}

• Returns: none
• Args: none

---

🧭 Methods for exploring the document 🧭

current_attr

• Title: current_attr
• Usage: $attr_hash = $treeio->current_attr;
• Function: returns the attribute hash for current item
• Returns: reference of the attribute hash
• Args: none

prev_attr

• Title: prev_attr
• Usage: $hash_ref = $treeio->prev_attr
• Function: returns the attribute hash for previous item
• Returns: reference of the attribute hash
• Args: none

current_element

• Title: current_element
• Usage: $element = $treeio->current_element
• Function: returns the name of the current element
• Returns: string (element name)
• Args: none

prev_element

• Title: prev_element
• Usage: $element = $treeio->current_element
• Function: returns the name of the previous element
• Returns: string (element name)
• Args: none

treetype

• Title: treetype
• Usage: $obj->treetype($newval)
• Function: returns the tree type (default is Bio::Tree::Tree)
• Returns: value of treetype
• Args: newvalue (optional)

nodetype

• Title: nodetype
• Usage: $obj->nodetype($newval)
• Function: returns the node type (default is Bio::Node::AnnotatableNode)
• Returns: value of nodetype
• Args: newvalue (optional)

---

🎀 Methods for implementing to_string callback for AnnotatableNode 🎀

node_to_string

• Title: node_to_string
• Usage: $annotatablenode->to_string_callback(\&node_to_string)
• Function: set as callback in AnnotatableNode, prints the node information in string
• Returns: string of node information
• Args: none

print_annotation

• Title: print_annotation
• Usage: $str = $annotatablenode->print_annotation($str, $annotationcollection)
• Function: prints the annotationCollection in a phyloXML format.
• Returns: string of annotation information
• Args: string to which the Annotation should be concatenated to, annotationCollection that holds the Annotations

print_attr

• Title: print_attr
• Usage: $str = $annotatablenode->print_attr($str, $annotationcollection)
• Function: prints the annotationCollection in a phyloXML format.
• Returns: string of attributes
• Args: string to which the Annotation should be concatenated to, AnnotationCollection that holds the attributes

print_sequence_annotation

• Title: print_sequence_annotation
• Usage: $str = $node->print_seq_annotation( $str, $seq );
• Function: prints the Bio::Seq object associated with the node in a phyloXML format.
• Returns: string that describes the sequence
• Args: string to which the Annotation should be concatenated to, Seq object to print in phyloXML

---

and that's the whole page bestie 💅 this one's running on perl v5.32.1, dated 2021-08-15, filed under Bio::T...hyloxml(3pm) — go parse a tree, you got this 🦋✨