Skip to content

quality

FilterQualityResult dataclass

Result of filtering a structure file based on PDBe quality scores.

Attributes:

Name Type Description
pdb_id str | None

The PDB ID of the structure if available.
input_file Path | None

The path to the input structure file if available.
geometry_quality float | None

The geometry quality score if available.
passed bool

A boolean indicating whether the structure passed the filter.
reason str | None

The reason for discarding or passing the structure. None if passed without any special reason.

QualityClusteringPartitions dataclass

Partitioned structures for clustered PDBe quality filtering.

Attributes:

Name Type Description
clusterable_structures list[QualityStructure]

List of QualityStructure objects with UniProt metadata and non-None geometry_quality
unclustered_structures list[UnclusteredStructure]

List of UnclusteredStructure objects without UniProt accession but with non-None geometry_quality for filtering
no_quality_results list[FilterQualityResult]

List of FilterQualityResult objects with None geometry_quality
resolution_passed_results list[FilterQualityResult]

List of FilterQualityResult objects that passed due to valid resolution when pass_given_resolution is True or when the structure is an AlphaFold model.

extend(others)

Extend the current partitions with other QualityClusteringPartitions.

Parameters:

Name Type Description Default
others Iterable[QualityClusteringPartitions]

An iterable of QualityClusteringPartitions to extend the current partitions with.

 required

Returns:

Type Description
QualityClusteringPartitions

The current QualityClusteringPartitions instance with extended lists.

QualityStructure dataclass

Adapter that combines StructureMetadata with geometry_quality for ClusterableStructure.

Implements the ClusterableStructure protocol so that structures filtered by PDBe quality can participate in residue-range clustering.

resolution_value property

Return ignored resolution so cluster member sorting is done on geometry quality

See structure_sort_key for sorting logic.

UnclusteredStructure dataclass

Structure without UniProt accession that cannot be clustered.

Contains the minimum information needed to apply quality filtering to structures that lack UniProt metadata.

Note: geometry_quality is guaranteed to be non-None as structures with None quality are filtered out earlier in the pipeline.

id property

Return the PDB ID as the structure identifier.

resolution_value property

Return ignored resolution so cluster member sorting is done on geometry quality

See structure_sort_key for sorting logic.

cluster_and_select_quality_structures(clusterable_structures, top_per_cluster, minimal_geometry_quality)

Cluster structures by UniProt coverage and select passing results.

This function performs pure computation without any I/O operations. It groups structures by UniProt accession, clusters them by residue-range overlap, and marks structures as passed only when they are in the top N of their cluster and meet the geometry quality threshold. Args: clusterable_structures: Iterable of QualityStructure objects to cluster. top_per_cluster: Maximum number of top structures to keep per UniProt cluster. (Selection still requires geometry_quality >= minimal_geometry_quality.) minimal_geometry_quality: Minimum geometry quality threshold for selection.

Returns:

Type Description
list[FilterQualityResult]

A list of FilterQualityResult objects indicating the selection status of each structure.

filter_by_pdbe_quality(scores, input_files, /, *, minimal_geometry_quality=0.0, top=None, pass_given_resolution=False, cluster_by_uniprot_accession_and_coverage=1, scheduler_address=None)

Filter structure files by PDBe quality with optional UniProt-based clustering.

Structures are grouped by UniProt accession, then clustered by residue-range overlap using hierarchical clustering. The top N structures per cluster are selected using the geometry-quality-aware sort key.

This is opt-in via the cluster_by_uniprot_accession_and_coverage parameter. When set to 0, UniProt-accessioned structures are not clustered by coverage overlap; instead, they are treated like unclustered structures and ranked globally by geometry quality. Args: scores: A mapping from PDB IDs to their corresponding Scores objects. input_files: Collection of structure file paths (e.g. from glob_structure_files). minimal_geometry_quality: Minimum geometry quality score to pass the filter. top: Maximum number of unclustered structures (those without a UniProt accession) that can pass the filter. Structures are ranked by geometry quality descending and only the top N are allowed to pass. If None, all qualifying structures pass. pass_given_resolution: If set, structures with a valid resolution will pass regardless of other criteria. cluster_by_uniprot_accession_and_coverage: Number of top structures to keep per UniProt cluster. If 0, clustering is disabled. scheduler_address: Address of the Dask scheduler to connect to. If not provided, will create a local cluster. If set to sequential will run tasks sequentially.

Returns:

Type Description
list[FilterQualityResult]

A list of FilterQualityResult objects.

filter_unclustered_structures(unclustered_structures, /, *, minimal_geometry_quality, top, cluster=False)

Filter unclustered structures by geometry quality and top N limit.

Parameters:

Name Type Description Default
unclustered_structures Iterable[UnclusteredStructure]

Iterable of UnclusteredStructure objects to filter.

 required
minimal_geometry_quality float

Minimum geometry quality threshold for selection.

 required
top int | None

Maximum number of unclustered structures that can pass the filter. Structures are ranked by geometry quality descending and only the top N are allowed to pass. If None, all structures that meet the quality threshold are allowed to pass.

 required
cluster bool

If set, indicates that the filtering is part of a clustering process.

 False

Returns:

Type Description
list[FilterQualityResult]

A list of FilterQualityResult objects indicating the selection status of each unclustered structure.

partition_structures_for_quality_clustering(input_files, scores, /, *, pass_given_resolution=False, cluster=True, scheduler_address=None)

Partition structures for clustered PDBe quality filtering.

This function handles all I/O operations by reading structure files to extract UniProt metadata. It returns both clustered structures (with UniProt accession) and unclustered structures (without UniProt accession) with quality data. Structures with None geometry_quality are separated out.

Each input file's PDB ID is obtained from the structure's name field (the id field in the CIF file). Files whose structure name is not found in scores are treated as having missing geometry quality.

Parameters:

Name Type Description Default
input_files Collection[Path]

Iterable of structure file paths.

 required
scores Mapping[str, Scores]

A mapping from PDB IDs to their corresponding Scores objects.

 required
pass_given_resolution bool

If set, structures with a valid resolution will pass regardless of other criteria.

 False
cluster bool

If set, structures with UniProt accession will be clustered by residue-range overlap. If not set, all structures with UniProt accession will be treated as unclustered.

 True
scheduler_address SchedulerAddress

Address of the Dask scheduler to connect to. If not provided, will create a local cluster. If set to sequential will run tasks sequentially.

 None

Returns:

Type Description
QualityClusteringPartitions

A QualityClusteringPartitions object containing:
QualityClusteringPartitions
  • clusterable_structures: List of QualityStructure objects with UniProt metadata and non-None geometry_quality
QualityClusteringPartitions
  • unclustered_structures: List of UnclusteredStructure objects without UniProt accession but with non-None geometry_quality for filtering
QualityClusteringPartitions
  • no_quality_results: List of FilterQualityResult objects with None geometry_quality or failed to read structure or extract metadata
QualityClusteringPartitions
  • resolution_passed_results: List of FilterQualityResult objects that passed due to valid resolution when pass_given_resolution is True

read_quality_json(f)

Read a JSON file containing PDBe quality scores.

Parameters:

Name Type Description Default
f Path

Path to the JSON file containing PDBe quality scores.

 required

Returns:

Type Description
dict[str, Scores]

A dictionary mapping PDB IDs (lowercase) to their corresponding Scores objects.

write_quality_stats_csv(results, write_stats, output_dir)

Writes a CSV file containing quality statistics for PDB IDs.

Parameters:

Name Type Description Default
results Iterable[FilterQualityResult]

An iterable of FilterQualityResult objects containing the quality results for each PDB ID.

 required
write_stats StdioPath

Path to the output CSV file to write statistics.

 required
output_dir Path

The directory where the output files are located.

 required
The CSV file will contain the following columns
  • pdb_id: The PDB ID of the structure.
  • input_file: The path to the input structure file.
  • geometry_quality: The geometry quality score from the Scores object.
  • passed: A boolean indicating whether the structure passed the filter.
  • output_file: The path to the output structure file if it passed the filter.
  • reason: The reason for discarding or passing the structure.