mkt.databases.conservation.KLIFSTreeConservationApp

class mkt.databases.conservation.KLIFSTreeConservationApp(*, 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, logo_cutoff: float = 0.1, name_trunc: int = 14)

Bases: KLIFSHierarchicalConservation

Interactive standalone-HTML Bokeh explorer for the KLIFS conservation tree.

Renders the agglomerative similarity dendrogram with singleton-peel chains contracted into multifurcating nodes (so a kinase that peels off attaches directly to its clade), above a per-node conservation logo that updates on tap. In the logo, letter height is the consensus frequency and color encodes novelty relative to the parent clade (region color = newly conserved/changed, black = inherited, grey = below threshold). Tree branches are colored by family while a clade is monophyletic (lipid > pseudokinase > Manning group) and grey once mixed; split nodes are filled by whether they carry a fixed-difference breakpoint. All per-node data is precomputed and embedded, so the HTML needs no server.

Panel-only view built on KLIFSHierarchicalConservation (no cohort data); 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).
_conserved_columns(conservation)	Filter per-column conservation to the conserved consensus residues.
_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.
_family_types()	Per-leaf family label and per-node subtree purity, with a color map.
_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.
_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 layout (logo, legend, dendrogram) with tap interactivity.
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 explorer and write a self-contained HTML file to output_path.
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	Subtrees with fewer members collapse to a single tappable bar.
logo_cutoff	Minimum consensus frequency for a residue to appear in the per-node logo.
name_trunc	Max items shown in a tooltip field before truncation.
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.

_family_types() → tuple[list[str], dict[int, str | None], dict[str, str]]

Per-leaf family label and per-node subtree purity, with a color map.

Returns:

tuple[list[str], dict[int, str | None], dict[str, str]]

(leaf_types, node_type, type_colors) where leaf_types[i] is the leaf’s family (lipid > pseudokinase > Manning group), node_type[nid] is the subtree’s pure family or None if mixed, and type_colors maps a family to its color.

blosum_name: str

Substitution matrix name used by the "blosum" metric.

build_layout()

Assemble the Bokeh layout (logo, legend, dendrogram) with tap interactivity.

Returns:

bokeh.models.LayoutDOM

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

conservation_threshold: float

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

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

logo_cutoff: float

Minimum consensus frequency for a residue to appear in the per-node logo.

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

Subtrees with fewer members collapse to a single tappable bar.

name_trunc: int

Max items shown in a tooltip field before truncation.

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 explorer and write a self-contained HTML file to output_path.

Parameters:

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

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

tree: ClusterNode | None

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

weighting: str

"none" (default) or "henikoff".

Type:

Per-node consensus weighting