clustering_io

Helpers for writing clustering outputs for CLI commands.

AccessionClusters dataclass

Clusters for a single UniProt accession.

Attributes:

Name	Type	Description
uniprot_accession	str	UniProt accession for the clustered structures.
structures	list[ResolutionFilterStatistics]	Input structures that were clustered.
clusters	list[list[ResolutionFilterStatistics]]	Cluster assignments for the input structures.
condensed_distances	list[float]	Condensed pairwise distances between input structures used for clustering.
linkage_matrix	ndarray | None	Linkage matrix produced by hierarchical clustering, or None if not computed.

cluster_results_by_accession(stats)

Group and cluster structures by UniProt accession.

Parameters:

Name	Type	Description	Default
stats	Iterable[ResolutionFilterStatistics]	Structure statistics to group and cluster.	required

Returns:

Type	Description
list[AccessionClusters]	Cluster results grouped by accession, sorted by accession.

linkage_to_newick(linkage_matrix, structures)

Convert a scipy linkage matrix into Newick text.

Parameters:

Name	Type	Description	Default
linkage_matrix	ndarray	Linkage matrix produced by hierarchical clustering.	required
structures	list[T]	Structures corresponding to leaf rows in the linkage matrix.	required

Returns:

Type	Description
str	Newick-formatted tree string.

Raises:

Type	Description
ValueError	If the root node is missing either child.

write_clusters_csv(results, output)

Write structure-level cluster assignments.

Parameters:

Name	Type	Description	Default
results	list[AccessionClusters]	Cluster results to serialize.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.

write_condensed_distances_by_accession_csv(results, output)

Write condensed distances for all accessions into one CSV file.

Parameters:

Name	Type	Description	Default
results	list[AccessionClusters]	Cluster results grouped by accession.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.

write_condensed_distances_csv(condensed_distances, structures, output)

Write pairwise condensed distances in long CSV form.

Parameters:

Name	Type	Description	Default
condensed_distances	list[float]	Precomputed condensed distances matching structures order. See protein_quest.clustering.structure_distances how to compute these distances.	required
structures	list[T]	Structures corresponding to condensed_distances order.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.

write_dendrogram_nwk(linkage_matrix, structures, output)

Write a dendrogram in Newick format.

Parameters:

Name	Type	Description	Default
linkage_matrix	ndarray	Linkage matrix produced by hierarchical clustering.	required
structures	list[T]	Structures corresponding to leaf rows in the linkage matrix.	required
output	Path	Destination path for the Newick file.	required

Returns:

Type	Description
None	None.

Raises:

Type	Description
ValueError	If the linkage tree contains an internal node missing a child.

write_linkage_matrix_by_accession_csv(results, output)

Write linkage matrix rows for all accessions into one CSV file.

Parameters:

Name	Type	Description	Default
results	list[AccessionClusters]	Cluster results grouped by accession.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.

write_linkage_matrix_csv(linkage_matrix, structures, output)

Write a linkage matrix with human-readable node labels.

Parameters:

Name	Type	Description	Default
linkage_matrix	ndarray	Linkage matrix produced by hierarchical clustering.	required
structures	list[T]	Structures corresponding to leaf rows in the linkage matrix.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.

write_stats_csv(results, output)

Write accession-level clustering statistics.

Parameters:

Name	Type	Description	Default
results	list[AccessionClusters]	Cluster results to summarize.	required
output	Path	Destination path for the CSV file.	required

Returns:

Type	Description
None	None.