Skip to content

Alignment

FASTA/PHYLIP alignment loading with site-pattern compression.

Alignment dataclass

Compressed alignment with site-pattern multiplicities.

Attributes:

Name Type Description
seq_type 'DNA' or 'AA'
index AlignmentIndex tying local taxa to the global TaxonTable
patterns uint8 array of shape (n_local, n_patterns) - encoded states
weights int32 array of shape (n_patterns,) - column multiplicities
n_sites total alignment length (= weights.sum())
Source code in src/hifuku/alignment.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@dataclass(frozen=True)
class Alignment:
    """
    Compressed alignment with site-pattern multiplicities.

    Attributes
    ----------
    seq_type : 'DNA' or 'AA'
    index    : AlignmentIndex tying local taxa to the global TaxonTable
    patterns : uint8 array of shape (n_local, n_patterns) - encoded states
    weights  : int32 array of shape (n_patterns,) - column multiplicities
    n_sites  : total alignment length (= weights.sum())
    """
    seq_type: str
    index: AlignmentIndex
    patterns: np.ndarray
    weights: np.ndarray
    n_sites: int

    def __repr__(self) -> str:
        return (
            f"Alignment(seq_type={self.seq_type!r}, "
            f"n_taxa={self.index.n_local}, "
            f"n_patterns={self.patterns.shape[1]}, "
            f"n_sites={self.n_sites})"
        )

load_alignment 

load_alignment(path: Union[str, Path], taxon_table: TaxonTable, *, schema: str = 'fasta') -> Alignment

Read an alignment file and return a compressed :class:Alignment.

Parameters:

Name Type Description Default
path Union[str, Path]
required
taxon_table Shared global TaxonTable; taxa are registered here.
required
schema str
'fasta'
Notes

Sequence type (DNA vs protein) is inferred from the DendroPy matrix class that successfully parses the file.

Source code in src/hifuku/alignment.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def load_alignment(
    path: Union[str, Path],
    taxon_table: TaxonTable,
    *,
    schema: str = "fasta",
) -> Alignment:
    """
    Read an alignment file and return a compressed :class:`Alignment`.

    Parameters
    ----------
    path        : FASTA or PHYLIP file path.
    taxon_table : Shared global TaxonTable; taxa are registered here.
    schema      : ``'fasta'`` (default) or ``'phylip'``.

    Notes
    -----
    Sequence type (DNA vs protein) is inferred from the DendroPy matrix
    class that successfully parses the file.

    - Sukumaran & Holder (2010) : CharacterMatrix API; taxon registration.
    """
    path = Path(path)
    schema = schema.lower()

    # Try DNA first, fall back to protein
    # Sukumaran & Holder (2010) : CharacterMatrix API
    cm, seq_type = _read_character_matrix(path, schema)

    labels = [t.label.strip() for t in cm.taxon_namespace]
    index = AlignmentIndex(taxon_table, labels)

    # Encode each sequence to a list of integer codes
    encoder = _dna_encoder if seq_type == "DNA" else _aa_encoder
    encoded_cols = _encode_matrix(cm, labels, encoder)  # list[tuple[int,...]]

    patterns, weights = _compress_patterns(encoded_cols, len(labels))

    return Alignment(
        seq_type=seq_type,
        index=index,
        patterns=patterns,
        weights=weights,
        n_sites=int(weights.sum()),
    )