mkt.databases.pssm.SubstitutionPseudocounts

class mkt.databases.pssm.SubstitutionPseudocounts(matrix: str = 'BLOSUM62', beta: float = 10.0, background: ndarray | None = None)

Bases: object

Substitution-aware pseudocount / information-content scorer for MSA columns.

Parameters:

• matrix (str) – Biopython substitution matrix name (default "BLOSUM62"); its implied background and conditional target probabilities P(a | b) are recovered from the matrix itself (no hardcoded frequency tables).

• beta (float) – Henikoff/PSI-BLAST pseudocount strength; the total pseudocount mass is beta * (distinct residue types observed) per column (default 10).

• background (np.ndarray | None) – KL background q_a (length-20, STR_AA20 order) for column_information(); defaults to ARR_SWISSPROT_BG. Supply a dataset-specific composition for “surprising relative to this dataset”.

__init__(matrix: str = 'BLOSUM62', beta: float = 10.0, background: ndarray | None = None) → None

Methods

__eq__(other)	Return self==value.
__init__([matrix, beta, background])
__post_init__()
_build_target_probs()	Conditional target probabilities P(a | b) recovered from the matrix.
column_information(counts)	Background-relative information content of a column, in bits.
pseudocounts(counts)	Substitution-aware pseudocount vector B * g_a for a column.
smoothed_freqs(counts)	Posterior-mean residue frequencies p_a = (n_a + B g_a) / (N + B).

Attributes

__dataclass_fields__
__dataclass_params__
__match_args__
background
beta
matrix
target_probs	20 x 20 conditional target probabilities P[a, b] = P(a | b) (columns sum to 1).

__init__(matrix: str = 'BLOSUM62', beta: float = 10.0, background: ndarray | None = None) → None

_build_target_probs() → ndarray

Conditional target probabilities P(a | b) recovered from the matrix.

From the log-odds scores S_ab (half-bits) form the odds Q_ab = 2^(S_ab/2). The implied background f is the distribution whose joint f_a f_b Q_ab has marginal f – i.e. Q f = 1 – and P(a | b) = f_a Q_ab, column-normalized to absorb the log-odds rounding.

background: ndarray | None = None

beta: float = 10.0

column_information(counts: ndarray) → float | None

Background-relative information content of a column, in bits.

IC = sum_a p_a log2(p_a / q_a) (KL of the smoothed column against background); >= 0, higher = more conserved-and-surprising. An empty column returns None rather than scoring the bare pseudocount against the background.

Parameters:

counts (np.ndarray) – Length-20 (weighted) residue counts n_a.

Returns:

Information content in bits, or None for an empty column.

Return type:

float | None

matrix: str = 'BLOSUM62'

pseudocounts(counts: ndarray) → ndarray

Substitution-aware pseudocount vector B * g_a for a column.

g_a = sum_b (n_b / N) P(a | b) spreads each observed residue’s mass onto its substitution neighbors; B = beta * (# distinct residue types observed).

Parameters:

counts (np.ndarray) – Length-20 (weighted) residue counts n_a in STR_AA20 order.

Returns:

Length-20 pseudocount vector B * g_a (zeros for an empty column).

Return type:

np.ndarray

smoothed_freqs(counts: ndarray) → ndarray | None

Posterior-mean residue frequencies p_a = (n_a + B g_a) / (N + B).

Returns:

Length-20 smoothed distribution, or None for an empty column (N = 0).

Return type:

np.ndarray | None

property target_probs: ndarray

20 x 20 conditional target probabilities P[a, b] = P(a | b) (columns sum to 1).