resolution

Filter structure files by resolution rank.

NoUniProtAccessionError

Bases: ValueError

Indicates that a structure has no UniProt accession.

OutsideTopError

Bases: ValueError

Indicates that a structure was ranked outside the top N.

ResolutionFilterStatistics dataclass

Statistics for filtering files based on ranked structure resolution.

This class is compatible with ClusterableStructure protocol.

Parameters:

Name	Type	Description	Default
input_file	Path	The path to the input file.	required
id	str	Identifier of the structure.	required
uniprot_accession	str | None	UniProt accession used for grouping.	required
resolution	float	Resolution from the structure file.	required
total_residue_count	int	Total residues across the whole structure.	required
is_alphafold	bool	Whether the structure was predicted by AlphaFold.	required
uniprot_start	int	Lowest UniProt residue position covered by the mapped chain.	required
uniprot_end	int	Highest UniProt residue position covered by the mapped chain.	required
sequence_identity	float	Sequence identity of the mapped chain to UniProt.	required
chain_length	int	Number of residues in the mapped chain.	required
passed	bool	Whether the file passed the ranking filter.	required
output_file	Path | None	The path to the output file, if passed.	required
discard_reason	Exception | None	If the file was discarded, the reason for discarding it.	None

SequenceIdentityBelowThresholdError

Bases: ValueError

Indicates that a structure has sequence identity below the specified threshold.

copy_resolution_statistics(stats, output_dir, copy_method='copy')

Copy files for passed statistics and set their output_file path.

Parameters:

Name	Type	Description	Default
stats	Iterable[ResolutionFilterStatistics]	Statistics with passed already set.	required
output_dir	Path	Directory where passed files will be written.	required
copy_method	CopyMethod	How to copy passed files to output directory.	'copy'

Yields:

Type	Description
Generator[ResolutionFilterStatistics]	Statistics with output_file set for passed entries.

filter_files_on_resolution(input_files, output_dir, top, *, coverage=False, group_by=True, min_sequence_identity=1.0, lax=False, copy_method='hardlink', scheduler_address=None)

Filter structure files by resolution rank.

Parameters:

Name	Type	Description	Default
input_files	list[Path]	Structure files to rank and filter.	required
output_dir	Path	Directory where passed files will be written.	required
top	int	Maximum number of files to keep.	required
coverage	bool	Whether to cluster by coverage. See cluster_structures.	False
group_by	bool	True applies top-N per accession. False applies top-N globally.	True
min_sequence_identity	float	Minimum sequence identity ratio to the Uniprot sequence for a structure to be passed. If not set then discards structures that are not fully identical to the Uniprot sequence. For example if set to 0.8 then structures that have sequence identity below 0.8 are discarded.	1.0
lax	bool	Whether to be lax in filtering. If True, files that fail to load or without resolution will be marked as passed instead of being discarded. When group_by is True, files without uniprot accessions will also be marked as passed instead of being discarded.	False
copy_method	CopyMethod	How to copy passed files to output directory.	'hardlink'
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

Yields:

Type	Description
Generator[ResolutionFilterStatistics]	Objects describing the filtering result for each input file.

filter_on_sequence_identity(min_sequence_identity, stats)

Discard statistics with sequence identity below the specified threshold.

Parameters:

Name	Type	Description	Default
min_sequence_identity	float	Minimum sequence identity ratio to the Uniprot sequence for a structure to be passed. If not set then discards structures that are not fully identical to the Uniprot sequence. For example if set to 0.8 then structures that have sequence identity below 0.8 are discarded.	required
stats	Iterable[ResolutionFilterStatistics]	Resolution statistics to filter.	required

Yields:

Type	Description
Generator[ResolutionFilterStatistics]	Statistics with passed set to False and discard_reason set for entries

load_resolution_statistics(input_files, scheduler_address=None)

Load resolution statistics for structure files, optionally in parallel.

Parameters:

Name	Type	Description	Default
input_files	list[Path]	Structure files to read metadata from.	required
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
list[ResolutionFilterStatistics]	Statistics objects with metadata filled in; passed is always
list[ResolutionFilterStatistics]	False and output_file is always None.

sort_resolution_statistics(stats, top, *, coverage=False, group_by=True)

Sort resolution statistics and mark the top N as passed based on the specified criteria.

Parameters:

Name	Type	Description	Default
stats	Iterable[ResolutionFilterStatistics]	Resolution statistics to sort. Each stat should have resolution and when group_by is True then should also have an uniprot_accession. Also the stat.discard_reason should be None.	required
top	int	Maximum number of entries to mark as passed.	required
coverage	bool	Whether to cluster by coverage. See cluster_structures.	False
group_by	bool	True applies top-N per accession. False applies top-N globally. Structures without uniprot accession are never passed.	True

Returns:

Type	Description
list[ResolutionFilterStatistics]	Resolution statistics with passed updated.

write_resolution_stats(stats, output)

Write resolution filter statistics to a CSV file.

Parameters:

Name	Type	Description	Default
stats	Iterable[ResolutionFilterStatistics]	Resolution filter statistics to write.	required
output	StdioPath	Output file path or "-" for stdout.	required