:py:mod:`biotaphy.common.data_readers`
======================================

.. py:module:: biotaphy.common.data_readers

.. autoapi-nested-parse::

   Module containing tools for reading alignment files in various formats.

   .. todo:: * FASTA reader?



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   biotaphy.common.data_readers.create_sequence_list_from_dict
   biotaphy.common.data_readers.get_character_matrix_from_sequences_list
   biotaphy.common.data_readers.load_alignment_from_filename
   biotaphy.common.data_readers.read_csv_alignment_flo
   biotaphy.common.data_readers.read_json_alignment_flo
   biotaphy.common.data_readers.read_phylip_alignment_flo
   biotaphy.common.data_readers.read_table_alignment_flo



.. py:exception:: AlignmentIOError

   Bases: :py:obj:`Exception`

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: create_sequence_list_from_dict(values_dict)

   Creates a list of sequences from a dictionary.

   :param values_dict: A dictionary of taxon name keys and a list of
                       values for each value.
   :type values_dict: dict

   .. note::

      * The dictionary should have structure::
      
          {
              "{taxon_name}" : [{values}]
          }

   :returns: A list of Sequence objects and None for headers.
   :rtype: list

   :raises AlignmentIOError: If a dictionary value is not a list.


.. py:function:: get_character_matrix_from_sequences_list(sequences, var_headers=None)

   Converts a list of sequences into a character matrix.

   :param sequences: A list of Sequence objects
                     to be converted.
   :type sequences: :obj:`list` of :obj:`Sequence`
   :param var_headers: If provided, uses these
                       as variable headers for the columns in the matrix.
   :type var_headers: :obj:`list` of headers, optional

   :returns: A matrix of sequence data.
   :rtype: Matrix


.. py:function:: load_alignment_from_filename(filename)

   Attempts to load an alignment from a file path by guessing schema.

   :param filename: The file location containing the alignment
   :type filename: str

   :raises RuntimeError: Raised with the method needed to load the alignment
       cannot be determined.

   :returns: Containing a list of sequences and headers
   :rtype: tuple


.. py:function:: read_csv_alignment_flo(csv_flo)

   Reads a CSV file-like object and return a list of sequences and headers.

   :param csv_flo: A file-like object with CSV alignment data.
   :type csv_flo: file-like

   :returns: A list of Sequence objects and headers.

   :raises AlignmentIOError: If the number of columns is inconsistent across the
       sequences.


.. py:function:: read_json_alignment_flo(json_flo)

   Read a JSON file-like object and return a list of sequences and headers.

   :param json_flo: A file-like object with JSON alignment data.
   :type json_flo: file-like

   .. note::

      * File should have structure::
      
          {
              "headers" : [{header_names}],
              "values" : [
                  {
                      "name" : "{taxon_name}",
                      "values" : [{values}]
                  }
              ]
          }

   :returns: A list of Sequence objects and headers.

   :raises AlignmentIOError: If headers are provided but they are not a list.


.. py:function:: read_phylip_alignment_flo(phylip_flo)

   Reads a phylip alignment file-like object and return the sequences.

   :param phylip_flo: The phylip file-like object.
   :type phylip_flo: file-like

   .. note::

      * We assume that the phylip files are extended and not strict (in terms
          of how many characters for taxon names).
      * The phylip file is in the format::
          numoftaxa numofsites
          seqlabel sequence
          seqlabel sequence

   :returns: A list of Sequence objects.

   :raises AlignmentIOError: If there is a problem creating sequences.


.. py:function:: read_table_alignment_flo(table_flo)

   Reads a table from a file-like object.

   :param table_flo: A file-like object containing table data.
   :type table_flo: file-like

   :returns: A list of Sequence objects.

   :raises AlignmentIOError: If there is a problem creating sequences.