clustering

Generic clustering of UniProt-mapped structures by residue-range overlap.

Any object satisfying the ClusterableStructure protocol can be clustered.

`CLUSTER_DISTANCE_THRESHOLD = 1 / MIN_OVERLAP_RESIDUES` `module-attribute`

Maximum pairwise distance considered connected in distance-based clustering.

`MIN_OVERLAP_RESIDUES = 1` `module-attribute`

Minimum required overlap size for assigning entries to the same cluster.

`NO_OVERLAP_DISTANCE = CLUSTER_DISTANCE_THRESHOLD + 1e-06` `module-attribute`

Finite fallback distance used when two ranges do not overlap.

`ClusterCoverageError`

Bases: ValueError

Raised when not all clusters are represented in the top results.

`ClusterableStructure`

Bases: SortableStructure, Protocol

Protocol describing the minimum interface required for clustering.

Extends SortableStructure with residue-range information needed for overlap-based clustering.

Attributes:

Name	Type	Description
`uniprot_start`	`int`	Lowest UniProt residue position covered by the structure.
`uniprot_end`	`int`	Highest UniProt residue position covered by the structure.

`SortableStructure`

Bases: Hashable, Protocol

Protocol describing the minimum interface required for sorting.

Attributes:

Name	Type	Description
`id`	`str`	Identifier of the structure, used as a deterministic tie-breaker.
`resolution_value`	`float`	Resolution in Angstrom. `0.0` means missing/undesirable so entries with a real resolution rank first.
`sequence_identity`	`float`	Sequence identity of the structure to the UniProt sequence in range `[0, 1]`. For example gaps or mutations in structure versus UniProt sequence will lower this value.
`chain_length`	`int`	Number of residues in the chain mapped to the UniProt sequence.
`geometry_quality`	`float \| None`	Geometry quality score (`0.0` - `100.0`) or `None` if unavailable. Higher is better.

`cluster_structures(structures)`

Cluster structures by overlapping UniProt residue coverage.

Parameters:

Name	Type	Description	Default
`structures`	`list[T]`	Structures to cluster. All structures must have valid residue ranges; callers responsible for filtering out structures with missing range information beforehand. Each structure must satisfy ClusterableStructure protocol.	required

Returns:

Type	Description
`list[list[T]]`	Sorted list of clusters with members also sorted.

`cluster_structures_with_intermediates(structures)`

Cluster structures and return reusable intermediate artifacts.

Parameters:

Name	Type	Description	Default
`structures`	`list[T]`	Structures to cluster. All structures must have valid residue ranges; callers responsible for filtering out structures with missing range information beforehand. Each structure must satisfy ClusterableStructure protocol.	required

Returns:

Type	Description
`list[list[T]]`	Tuple of:
`list[float]`	Sorted clusters with sorted members.
`ndarray \| None`	Condensed pairwise distances used for hierarchical clustering.
`tuple[list[list[T]], list[float], ndarray \| None]`	Linkage matrix or `None` when fewer than two structures are provided.

`filter_structures_on_clustered_resolution(structures, top, selection_strategy='per_cluster_top')`

Filter structures by resolution within residue-range clusters.

Looks at how structures uniprot ranges overlap and clusters them by similarity of covered residue ranges. Then returns up to top structures by interleaving cluster members round-robin,

Parameters:

Name	Type	Description	Default
`structures`	`list[T]`	Structures to filter. Must all have valid residue ranges. Each structure must satisfy ClusterableStructure protocol.	required
`top`	`int`	Number of top results to retain.	required
`selection_strategy`	`TopClusterSelectionStrategy`	Strategy for selecting top results. - `across_clusters_top`: Take the top N structures across all clusters. - `per_cluster_top`: Take the top N structures from each cluster.	`'per_cluster_top'`

Returns:

Type	Description
`list[T]`	Filtered list of up to `top` structures.

Raises:

Type	Description
`ClusterCoverageError`	If not all clusters are represented in the top results.
`ValueError`	If an unknown selection strategy is provided.

`flatten_hierarchical_clusters(linkage_matrix, structures)`

Form flat clusters from a hierarchical clustering linkage matrix.

Wrapper around scipy.cluster.hierarchy.fcluster with distance criterion and CLUSTER_DISTANCE_THRESHOLD. followed by mapping back to the original structures and sorting of clusters and their members.

Clusters themselves are ordered by chain length descending, then by start and end residue, then identifier.

Parameters:

Name	Type	Description	Default
`linkage_matrix`	`ndarray`	Linkage matrix as returned by scipy's linkage function.	required
`structures`	`list[T]`	Original list of structures corresponding to the distance matrix used to compute the linkage matrix.	required

Returns:

Type	Description
`list[list[T]]`	Sorted list of clusters with members also sorted.

`hierarchical_clustering(condensed_distances)`

Wrapper around scipy.cluster.hierarchy.linkage with complete method.

Parameters:

Name	Type	Description	Default
`condensed_distances`	`list[float]`	Condensed distance matrix as a flat list	required

Returns:

Type	Description
`ndarray`	Linkage matrix as returned by scipy's linkage function.

`interleave_longest(*iterables)`

Yield values round-robin from each iterable until all are exhausted.

Examples:

Scalar example.

>>> list(interleave_longest([1, 2, 3], [4, 5], [6, 7, 8]))
[1, 4, 6, 2, 5, 7, 3, 8]

Parameters:

Name	Type	Description	Default
`iterables`	`Iterable[T]`	Iterables to round-robin.	`()`

Yields:

Type	Description
`T`	Elements interleaved from the provided iterables.

`sort_structures(structures)`

Sort structures by quality criteria.

See structure_sort_key for sort criteria.

Parameters:

Name	Type	Description	Default
`structures`	`Iterable[T]`	Structures to sort. Each structure must satisfy ClusterableStructure protocol.	required

Returns:

Type	Description
`list[T]`	List of structures sorted by the criteria above.

`structure_distance(a, b)`

Jaccard-like distance between two structures' UniProt residue ranges.

Non-overlapping ranges return NO_OVERLAP_DISTANCE.

Both arguments must satisfy ClusterableStructure protocol.

Parameters:

Name	Type	Description	Default
`a`	`ClusterableStructure`	First structure.	required
`b`	`ClusterableStructure`	Second structure.	required

Returns:

Type	Description
`float`	Distance between the two structures in range `[0, NO_OVERLAP_DISTANCE]`

`structure_distances(structures)`

Condensed (upper-triangle) pairwise distance matrix for a list of structures.

Parameters:

Name	Type	Description	Default
`structures`	`list[T]`	Structures to compute distances for. Each structure must satisfy ClusterableStructure protocol.	required

Returns:

Type	Description
`list[float]`	Condensed distance matrix as a flat list, suitable for input to scipy.cluster.hierarchy.linkage.

`structure_overlap(a, b)`

Number of overlapping UniProt residues between two structures.

Both arguments must satisfy ClusterableStructure protocol.

Parameters:

Name	Type	Description	Default
`a`	`ClusterableStructure`	First structure.	required
`b`	`ClusterableStructure`	Second structure.	required

Returns:

Type	Description
`int`	Number of overlapping residues.

`structure_sort_key(member)`

Deterministic quality sort key for a cluster member.

Sequence identity descending (highest first)
Resolution ascending (lowest first)
Geometry quality descending (highest first; None sorts after valid values)
Chain length descending (longest first)
Identifier ascending (deterministic tie-break)

A failing chain_length access (for example for PDB results with unparsable chain metadata) is treated as 0 so such entries can still be sorted alongside valid ones.

Structures with lower resolution are preferred. If resolution is missing aka 0.0, those structures are undesirable.

`structure_union(a, b)`

Number of unique UniProt residues in the union of two structures.

Both arguments must satisfy ClusterableStructure protocol.

Parameters:

Name	Type	Description	Default
`a`	`ClusterableStructure`	First structure.	required
`b`	`ClusterableStructure`	Second structure.	required

Returns:

Type	Description
`int`	Number of unique residues in the union of the two structures.

`top_members_across_clusters(clusters, top)`

Return up to top members across clusters by interleaving cluster members round-robin.

Parameters:

Name	Type	Description	Default
`clusters`	`list[list[T]]`	Ordered clusters whose members are also sorted. First cluster and its first member is considered best.	required
`top`	`int`	Maximum number of members to return.	required

Returns:

Type	Description
`list[T]`	Interleaved members truncated to `top`.

Raises:

Type	Description
`ClusterCoverageError`	If not all clusters are represented in the top results.

`top_members_per_cluster(clusters, top)`

Return up to top members from each cluster, interleaved round-robin.

Parameters:

Name	Type	Description	Default
`clusters`	`list[list[T]]`	Ordered clusters whose members are also sorted. First cluster and its first member is considered best.	required
`top`	`int`	Maximum number of members to keep from each cluster.	required

Returns:

Type	Description
`list[T]`	Interleaved members after truncating each cluster to `top` members.

clustering

CLUSTER_DISTANCE_THRESHOLD = 1 / MIN_OVERLAP_RESIDUES module-attribute

MIN_OVERLAP_RESIDUES = 1 module-attribute

NO_OVERLAP_DISTANCE = CLUSTER_DISTANCE_THRESHOLD + 1e-06 module-attribute

ClusterCoverageError

ClusterableStructure

SortableStructure

cluster_structures(structures)

cluster_structures_with_intermediates(structures)

filter_structures_on_clustered_resolution(structures, top, selection_strategy='per_cluster_top')

flatten_hierarchical_clusters(linkage_matrix, structures)

hierarchical_clustering(condensed_distances)

interleave_longest(*iterables)

sort_structures(structures)

structure_distance(a, b)

structure_distances(structures)

structure_overlap(a, b)

structure_sort_key(member)

structure_union(a, b)

top_members_across_clusters(clusters, top)

top_members_per_cluster(clusters, top)

`CLUSTER_DISTANCE_THRESHOLD = 1 / MIN_OVERLAP_RESIDUES` `module-attribute`

`MIN_OVERLAP_RESIDUES = 1` `module-attribute`

`NO_OVERLAP_DISTANCE = CLUSTER_DISTANCE_THRESHOLD + 1e-06` `module-attribute`

`ClusterCoverageError`

`ClusterableStructure`

`SortableStructure`

`cluster_structures(structures)`

`cluster_structures_with_intermediates(structures)`

`filter_structures_on_clustered_resolution(structures, top, selection_strategy='per_cluster_top')`

`flatten_hierarchical_clusters(linkage_matrix, structures)`

`hierarchical_clustering(condensed_distances)`

`interleave_longest(*iterables)`

`sort_structures(structures)`

`structure_distance(a, b)`

`structure_distances(structures)`

`structure_overlap(a, b)`

`structure_sort_key(member)`

`structure_union(a, b)`

`top_members_across_clusters(clusters, top)`

`top_members_per_cluster(clusters, top)`