align_sequences
Read-only
Multiple-sequence alignment over several sequences, under either of TWO engines that answer different questions and neither of which is a fallback for the other. poa (partial-order, poapy) aligns into a graph, keeps every path a read took and produces its own consensus row — what a pile of reads over one locus wants. progressive (biotite) computes Feng-Doolittle distances, clusters them into a guide tree and merges along it under "once a gap, always a gap" — the classic MSA algorithm, what a FAMILY of homologous genes wants, and what a reader coming from Clustal or MUSCLE expects. Wire many upstream record/sequence outputs into sequences, or name library documents.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gap | No | `poa` only: score for a gap column. Negative. Only applies when engine is poa. Advanced. | |
| match | No | `poa` only: score for a pair of identical symbols. Only applies when engine is poa. Advanced. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| engine | No | which aligner builds the alignment. They answer DIFFERENT questions: `poa` keeps every path through a pile of reads and emits its own consensus row, `progressive` merges a family along a guide tree the way Clustal and MUSCLE do. Each engine reads only its own parameters below. Values: poa (Partial-order (poapy) - reads over one locus), progressive (Progressive (biotite) - a family, guide-tree merged). | poa |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| gap_open | No | `progressive`, affine only: the penalty for STARTING a gap. Negative. Only applies when affine_gap is true. | |
| mismatch | No | `poa` only: score for a mismatching pair. Negative. Only applies when engine is poa. Advanced. | |
| sequences | No | the sequences to align — wire several upstream outputs here, or list library document names/ids. | |
| affine_gap | No | `progressive` only: `false` charges one flat penalty per gap column; `true` charges separate opening and extension penalties, which is what keeps a real indel as ONE gap instead of many. Only applies when engine is progressive. | |
| gap_extend | No | `progressive`, affine only: the penalty for each column a gap is extended by. Negative, and gentler than `gap_open` - an extension harsher than the opening makes the aligner prefer many short gaps to one long indel. Only applies when affine_gap is true. | |
| guide_tree | No | `progressive` only: which tree the merge follows. The Feng-Doolittle distances are the aligner's either way; this chooses only how they are clustered into an order. UPGMA is biotite's own and the one the port reproduces byte-for-byte; neighbour-joining and BIONJ do not assume a molecular clock, so on sequences evolving at different rates they group by relatedness where UPGMA groups by raw similarity - which is exactly the case where the guide tree changes the alignment. Values: upgma (UPGMA (biotite's own)), nj (Neighbour-joining), bionj (BIONJ), wpgma (WPGMA). Only applies when engine is progressive. | upgma |
| gap_penalty | No | `progressive` only: the flat penalty per gap column. Negative. Only applies when affine_gap is false. | |
| align_matrix | No | `progressive` only: the substitution matrix the ALIGNMENT itself is scored with - distinct from `score_matrix`, which only scores the quality report afterwards. `auto` reads the alphabet: EDNAFULL for nucleotides, BLOSUM62 for protein. Naming the wrong one is not an error the engine can raise - BLOSUM62 reads A, C, G and T as alanine, cysteine, glycine and threonine and returns a number. Values: auto (Auto - from the alignment's alphabet), EDNAFULL (EDNAFULL - nucleotides (EMBOSS NUC.4.4)), BLOSUM62 (BLOSUM62 - amino acids). Only applies when engine is progressive. | auto |
| global_align | No | global alignment rather than local. Poapy's own default is LOCAL; both this tool and the MSA inspector open on global, which is the choice a full-length comparison wants - switch it off for reads over part of a locus. Only applies when engine is poa. Advanced. | |
| score_matrix | No | substitution matrix for the pyMSA sum-of-pairs and star scores in the quality report. Both engines. Left unset only the matrix-free scores are computed (entropy, % non-gaps, % totally conserved columns) - an honest absence rather than a score under a matrix that does not match the alphabet. Values: PAM250 (PAM250 - amino acids, greater evolutionary distance), BLOSUM62 (BLOSUM62 - amino acids), EDNAFULL (EDNAFULL - nucleotides). Advanced. | |
| include_subject | No | also align the node's subject (the open or wired record). | |
| terminal_penalty | No | `progressive` only: `true` charges overhanging ends like an internal gap - right for full-length homologues. `false` makes them free, which is right when a sequence covers only part of the region, e.g. a read against a gene. Only applies when engine is progressive. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fit | Yes | per row: its closest row in this alignment, their identity here, and the same pair's identity aligned on its own with free end gaps (biotite align_optimal) — the loss shows where the alignment holds a row out of register; `outliers` names the rows flagged. `{ ok: false, reason }` when the check could not run | |
| rows | Yes | aligned rows (name + gapped sequence) | |
| count | Yes | number of aligned sequences (excluding the consensus row) | |
| engine | Yes | which aligner produced this alignment — `poa` or `progressive` | |
| figure | Yes | the alignment's first 80 columns drawn as the MSA canvas opens on them: rows named, residues shaded by column identity, the conservation line under the block. draw_alignment draws any other window | |
| length | Yes | alignment width in columns | |
| scores | Yes | the pyMSA quality scores: summed entropy (nats, pyMSA's sign — negative), % non-gaps, % totally conserved columns, and the sum-of-pairs/star pair when a `score_matrix` was named | |
| consensus | Yes | the per-column majority consensus (POA returns its own graph consensus row; the progressive engine has no graph, so the majority is the consensus for both) | |
| conservation | Yes | the Clustal-style conservation line, one character per column — `*` where every row carries the same residue and the column is ungapped | |
| guideTreeNewick | Yes | `progressive` only: the guide tree the merge followed, in Newick, labelled with the row names. Branch lengths are deliberately omitted — a guide tree's heights are a clustering artifact, not divergence estimates | |
| alignedSequences | Yes | the aligned input rows only, excluding the generated consensus — wire this into build_tree |