mkt.databases.pssm.column_conservation

mkt.databases.pssm.column_conservation(sequences: list[str], gap_chars: str = '-X', weights: list[float] | None = None) → list[tuple[str | None, float]]

Per-column consensus residue and its frequency for a set of aligned sequences.

The column-level conservation primitive: any subset of aligned sequences (e.g. a whole MSA, or the members of a clade in a hierarchical tree) can be scored without instantiating a stateful analyzer. Gap/unknown characters in gap_chars are excluded; a column that is all gaps yields (None, 0.0).

Optional per-sequence weights generalize the unweighted residue counts to a weighted consensus (e.g. Henikoff sequence weights to down-weight redundant subfamilies); None reproduces the unweighted counts exactly. Because the reported fraction is a ratio of summed weights it is invariant to the overall weight scale.

Parameters:

• sequences (list[str]) – Aligned sequence strings of equal length.

• gap_chars (str) – Characters treated as gap/unknown and excluded from the consensus (default: STR_GAP_CHARS).

• weights (list[float] | None) – Optional per-sequence weights (same length as sequences). None weights every sequence equally (default: None).

Returns:

One (consensus_aa, fraction) tuple per column, where fraction is the consensus residue’s (weighted) frequency among the observed (non-gap) residues.

Return type:

list[tuple[str | None, float]]