Tree I/O Reference
==================

Import path
-----------

.. code-block:: python

   from phylognn.io import TreeReadConfig, read_tree_as_ete3

Optional dependency boundary
----------------------------

Core workflows use `ete3.Tree` directly. `phylognn.io` is the explicit
optional boundary for `DendroPy`-backed file reading and conversion. Install the
`beast` or `all` extra before using DendroPy readers.

Reader configuration
--------------------

.. py:class:: TreeReadConfig(schema="nexus", tree_index=0, preserve_underscores=True, extract_comment_metadata=True, rooting=None, keep_annotations=True, annotation_prefix="meta_")

   Frozen configuration for DendroPy-backed tree reading.

Reader functions
----------------

.. py:function:: read_tree_as_ete3(file_path, schema="nexus", tree_index=0, preserve_underscores=True, extract_comment_metadata=True, rooting=None, keep_annotations=True, annotation_prefix="meta_")

   Read one tree from a file and return an `ete3.Tree`.

.. py:function:: read_tree_with_dendropy(file_path, config)

   Read one `DendroPy` tree from a file using `TreeReadConfig`.

.. py:function:: dendropy_tree_to_ete3(dtree, config=None)

   Convert a `DendroPy` tree to an `ete3.Tree`.

Common failures
---------------

Missing `DendroPy` raises `ModuleNotFoundError` with install guidance. Invalid
paths raise `FileNotFoundError`. Invalid tree indexes and empty files raise
`ValueError`. Parser failures are wrapped in `RuntimeError`.

Related guide
-------------

See :doc:`../user_guide/tree_input` and :doc:`../troubleshooting`.