mkt.databases.conservation.KLIFSResidueDotApp

class mkt.databases.conservation.KLIFSResidueDotApp(*, names: list[str] = <factory>, pockets: list[str] = <factory>, groups: list[str] = <factory>, position_labels: list[str] = <factory>, metric: str = 'blosum', blosum_name: str = 'BLOSUM62', linkage_method: str = 'average', conservation_threshold: float = 0.8, min_child_members: int = 2, weighting: str = 'none', exclude_pseudokinases: bool = False, gap_chars: str = '-X', distance_matrix: ~numpy.ndarray | None = None, linkage_matrix: ~numpy.ndarray | None = None, tree: ~scipy.cluster.hierarchy.ClusterNode | None = None, min_cluster_size: int = 12, default_aa: str = 'C')

Bases: KLIFSHierarchicalConservation

Interactive standalone-HTML per-amino-acid KLIFS dot-plot explorer.

A Select dropdown chooses one of the 20 amino acids (or the - gap); the plot then shows, for the 85 KLIFS pocket columns (x) against the human kinome in dendrogram leaf order (y), a dot wherever a kinase carries the selected residue at that column. Dots are colored by the dendrogram leaf coloring (Manning group / Lipid, with a black outline for pseudokinases). Dots of the same display-leaf clade that share the residue at a column (INT_RESIDUE_DOT_MIN_ENCLOSE or more) are enclosed, revealing columns “enriched” for that residue within a family (e.g. conserved cysteines). Hover reports the kinase, its display-leaf number, the UniProt residue (amino acid + canonical index, e.g. L858), the KLIFS label, and the KinHub / KLIFS family labels. All per-amino-acid data is precomputed and embedded, so the HTML needs no server.

Panel-only view built on KLIFSHierarchicalConservation; save_app writes a self-contained HTML file to the structured output tree.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Methods

_aggregate_singletons(splits, leaves)	Fold singleton leaves by tree adjacency so no leaf row holds one sequence.
_annotation_callouts(aa)	Find the shared-residue columns for the curated kinases of interest.
_annotation_lines(kinases, pos, label)	"{kinase} {residue}{uniprot_idx}" per kinase at KLIFS column pos.
_blosum_distance_matrix()	Substitution-score similarity distance (Metric A).
_column_stack(aa, pos, ordered_members, meta)	Kinases carrying aa at KLIFS column pos, in dendrogram leaf order.
_conserved_columns(conservation)	Filter per-column conservation to the conserved consensus residues.
_dot_style(i)	(fill, line) colors for leaf i's dot (black outline if pseudokinase).
_drop_pseudokinases()	Filter the panel to catalytically active kinases (in place).
_encode_pockets()	Integer-encode the pocket panel against the substitution-matrix alphabet.
_family_label(i)	Family used for the color: Lipid or Manning group (pseudo folds in).
_family_name(value)	Label for a family field, which may be a Family enum or a bare string.
_henikoff_weights(sequences)	Henikoff (1994) position-based sequence weights for a set of members.
_hover_families(i)	(kinhub_family, klifs_family) labels for leaf i's dot hover.
_identity_distance_matrix()	Percent-identity distance (Metric B): 1 - matches / non_gap_columns.
_is_kept(node_id)	True if both children of node_id are clades (>=2 members each).
_kinome_background()	Kinome amino-acid background (20-vector) over all KLIFS panel pockets.
_member_style(i)	(fill, edge, linewidth) for leaf i's name box / dot.
_nodelist()	Return the cached SciPy node list, indexed by node id.
_precompute_aa_data(ordered_members, ...)	Per-amino-acid stacked-dot and clade-enclosure payloads for the CustomJS switch.
_pseudocount_model([background])	Cached pseudocount model for the requested KL background.
_uniprot_index_at(i, pos)	1-based UniProt canonical index of leaf i at KLIFS column pos.
_walk_node(node, depth, records)	Recursively score a node and its children, appending one record per node.
analyze_nodes()	Walk the tree and compute per-node conservation, cached after first call.
build_display_tree([min_cluster_size, ...])	Build the renderer-neutral display tree from the linkage.
build_layout()	Assemble the Bokeh dot-plot layout with an amino-acid selector.
compute_distance_matrix()	Dispatch to the configured pairwise distance metric.
cophenetic_correlation()	Cophenetic correlation between the tree and the input distances.
critical_depth()	Most ancestral node at which each KLIFS column still survives-up.
from_conservation_data(data, **kwargs)	Build a renderer from a persisted KLIFSConservationData artifact.
gather_children(node_id)	Singleton-contracted multifurcating children of node_id.
group_concordance([n_clusters])	Adjusted Rand index between flat clusters and Manning groups.
members_consensus(member_idx)	Per-column >=threshold consensus residue for a member set (else None).
node_conservation(member_idx)	Per-column conservation for a set of member leaves.
node_information(member_idx[, background])	Per-column background-relative information content (bits) and effective count.
nodes_summary()	Tabular summary of per-node conservation counts (internal nodes only).
plot_critical_depth([figsize, cmap])	Plot per-KLIFS-column critical depth as an opaque track with a region bar.
residue_dot_layout([min_cluster_size])	Row/leaf assignment for the per-amino-acid dot plot.
save_app(output_path[, filename])	Build the dot-plot explorer and write a self-contained HTML file.
to_conservation_data([min_cluster_size, ...])	Package the clustering output as a serializable KLIFSConservationData.
tree_children(node_id)	The two linkage children of an internal node id.
tree_count(node_id)	Number of leaves under node_id (1 for a leaf).
tree_members(node_id)	Leaf indices under node_id (the node itself if it is a leaf).

Attributes

min_cluster_size	Display-tree collapse threshold (sets the display-leaf clades that are enclosed).
default_aa	cysteine).
names	List of HGNC kinase names (one per pocket).
pockets	List of 85-character KLIFS pocket strings, column-aligned by construction.
groups	Manning group per kinase, used for the external concordance check.
position_labels	KLIFS region labels (e.g. "g.l:4") for the 85 pocket columns.
metric	"blosum" (default) or "identity".
blosum_name	Substitution matrix name used by the "blosum" metric.
linkage_method	"average" (UPGMA, default) or "complete".
conservation_threshold	Minimum consensus-residue frequency for a column to count as conserved.
min_child_members	Minimum child-clade size considered in survives-up pruning; children smaller than this (e.g. singleton outliers peeled off at the root) are ignored.
weighting	"none" (default) or "henikoff".
exclude_pseudokinases	If True, drop predicted pseudokinases (KinaseInfo.is_pseudokinase()) from the panel before clustering, so the tree and conservation reflect catalytically active kinases only (default: False).
gap_chars	Characters treated as gap/unknown and excluded from scoring and conservation.
distance_matrix	Square N x N pairwise distance matrix; computed post-init unless supplied (e.g. injected by from_conservation_data() from a persisted artifact).
linkage_matrix	SciPy linkage matrix; computed post-init unless supplied.
tree	Root ClusterNode of the hierarchical tree, computed post-init.
_node_records	Cached per-node conservation records (see analyze_nodes()).
_nodelist_cache	Cached SciPy to_tree(rd=True) node list, indexed by node id.
_kinome_bg_cache	Cached kinome amino-acid background (from the KLIFS panel) for the IC measure.
_pssm_cache	Cached substitution-aware pseudocount models, keyed by background choice.

_column_stack(aa: str, pos: int, ordered_members: list[int], meta: dict) → list[dict]

Kinases carrying aa at KLIFS column pos, in dendrogram leaf order.

Each entry is the precomputed per-kinase meta dict; the list order is the bottom-to-top stacking order for the frequency dot plot (so same-clade dots are contiguous and can be enclosed).

_dot_style(i: int) → tuple[str, str]

(fill, line) colors for leaf i’s dot (black outline if pseudokinase).

_precompute_aa_data(ordered_members: list[int], leaf_of_member: dict[int, int]) → tuple[dict, dict, dict]

Per-amino-acid stacked-dot and clade-enclosure payloads for the CustomJS switch.

For each amino acid this builds a frequency dot plot: within each KLIFS column the kinases carrying the residue are stacked (y = 0, 1, 2, …) in dendrogram leaf order, so a column’s dot count is its frequency and empty columns simply have no dots. Runs of >= INT_RESIDUE_DOT_MIN_ENCLOSE consecutive same-clade dots within a column are enclosed.

Returns:

(aa_data, enc_data, max_count) keyed by amino-acid symbol; the first two are dicts of parallel arrays ready to become a ColumnDataSource, and max_count is the tallest column stack (for the y-range).

Return type:

tuple[dict, dict, dict]

blosum_name: str

Substitution matrix name used by the "blosum" metric.

build_layout()

Assemble the Bokeh dot-plot layout with an amino-acid selector.

Returns:

The column layout ready for bokeh.embed.file_html().

Return type:

bokeh.models.LayoutDOM

conservation_threshold: float

Minimum consensus-residue frequency for a column to count as conserved.

default_aa: str

cysteine).

Type:

Amino acid shown on first load (default

distance_matrix: np.ndarray | None

Square N x N pairwise distance matrix; computed post-init unless supplied (e.g. injected by from_conservation_data() from a persisted artifact).

exclude_pseudokinases: bool

If True, drop predicted pseudokinases (KinaseInfo.is_pseudokinase()) from the panel before clustering, so the tree and conservation reflect catalytically active kinases only (default: False).

gap_chars: str

Characters treated as gap/unknown and excluded from scoring and conservation.

groups: list[str]

Manning group per kinase, used for the external concordance check.

linkage_matrix: np.ndarray | None

SciPy linkage matrix; computed post-init unless supplied.

linkage_method: str

"average" (UPGMA, default) or "complete".

Type:

SciPy linkage method

metric: str

"blosum" (default) or "identity".

Type:

Pairwise distance metric

min_child_members: int

Minimum child-clade size considered in survives-up pruning; children smaller than this (e.g. singleton outliers peeled off at the root) are ignored. Set to 1 to require every immediate child to agree (the strict, topology-sensitive definition).

min_cluster_size: int

Display-tree collapse threshold (sets the display-leaf clades that are enclosed).

names: list[str]

List of HGNC kinase names (one per pocket).

pockets: list[str]

List of 85-character KLIFS pocket strings, column-aligned by construction.

position_labels: list[str]

KLIFS region labels (e.g. "g.l:4") for the 85 pocket columns.

save_app(output_path: str, filename: str | None = None) → None

Build the dot-plot explorer and write a self-contained HTML file.

Parameters:

• output_path (str) – Directory to write the HTML file into.

• filename (str | None, optional) – Output filename; defaults to STR_FILE_RESIDUE_DOT_APP.

tree: ClusterNode | None

Root ClusterNode of the hierarchical tree, computed post-init.

weighting: str

"none" (default) or "henikoff".

Type:

Per-node consensus weighting