uniprot_chains

Helpers for parsing and formatting UniProt chain strings.

For example the Uniprot Sparql endpoint returns a string like A=1-100 to show in which chain of a PDB entry the Uniprot accession is located.

Pdb2UniprotChainsMapping = dict[str, set[UniprotChainMapping]]

Dictionary mapping PDB ID to UniProt chain mappings used for injection.

UniprotChains = tuple[UniprotChainRange, ...]

Parsed UniProt chain-group/range assignments in source order.

UniprotChainMapping dataclass

UniProt accession plus parsed chain/range assignments for injection.

Attributes:

Name	Type	Description
uniprot_accession	str	UniProt accession to inject.
chain_ranges	UniprotChains	Parsed chain/range assignments in either auth or label system, depending on the caller context.

UniprotChainRange dataclass

One chain-group to UniProt residue-range assignment.

Attributes:

Name	Type	Description
chain_ids	tuple[str, ...]	Chain ids in the group, in the order they appeared in the source string.
start	int	Inclusive UniProt residue start.
end	int	Inclusive UniProt residue end.

preferred_chain_id property

Preferred chain id for legacy single-chain consumers.

Numeric leading chain ids are skipped when an alternative chain id exists.

__len__()

Inclusive length of this UniProt residue range.

all_chain_ids(chain_ranges)

Return all unique chain ids in first-seen order.

Parameters:

Name	Type	Description	Default
chain_ranges	UniprotChains	Parsed UniProt chain assignments.	required

Returns:

Type	Description
tuple[str, ...]	Unique chain ids in the order they first appear.

chain_length(chain_ranges)

Return the total aligned UniProt residue count across all ranges.

Parameters:

Name	Type	Description	Default
chain_ranges	UniprotChains	Parsed UniProt chain assignments.	required

Returns:

Type	Description
int	Sum of inclusive lengths across all ranges.

covered_uniprot_range(chain_ranges)

Return the minimum start and maximum end residue positions.

Parameters:

Name	Type	Description	Default
chain_ranges	UniprotChains	Parsed UniProt chain assignments.	required

Returns:

Type	Description
tuple[int, int]	Tuple of (minimum_start, maximum_end).

Raises:

Type	Description
ValueError	If chain_ranges is empty.

first_chain_id(chain_ranges)

Return the preferred chain id from parsed UniProt chains.

Parameters:

Name	Type	Description	Default
chain_ranges	UniprotChains	Parsed UniProt chain assignments.	required

Returns:

Type	Description
str	Preferred chain id from the first chain group.

Raises:

Type	Description
ValueError	If chain_ranges is empty.

format_uniprot_chains(chain_ranges)

Format parsed UniProt chain assignments back into a string.

Parameters:

Name	Type	Description	Default
chain_ranges	UniprotChains	Parsed UniProt chain assignments.	required

Returns:

Type	Description
str	String representation such as A/B=2-459,C=520-610.

parse_chain_ids(uniprot_chains)

Parse all unique chain ids from a UniProt chains string.

Unlike parse_uniprot_chains(), this helper only requires valid chain groups and tolerates invalid or missing ranges such as A=-.

Parameters:

Name	Type	Description	Default
uniprot_chains	str	UniProt chains string such as A/B=1-100.	required

Returns:

Type	Description
tuple[str, ...]	Chain ids in first-seen order with duplicates removed.

Raises:

Type	Description
ValueError	If the string does not contain at least one valid chain group or contains an empty chain id.

parse_uniprot_chains(uniprot_chains)

Parse a UniProt chains string into chain-group/range assignments.

The UniProt chains string is formatted (with EBNF notation) as follows:

chain_group=range(,chain_group=range)*

where:

chain_group := chain_id(/chain_id)*
chain_id    := [A-Za-z0-9]+
range       := start-end
start, end  := integer

Parameters:

Name	Type	Description	Default
uniprot_chains	str	UniProt chains string such as A/B=2-459,A/B=520-610.	required

Returns:

Type	Description
UniprotChains	Parsed chain-group/range assignments in source order.

Raises:

Type	Description
ValueError	If the input contains an invalid or incomplete range, or if a parsed range is otherwise invalid.

preferred_chain_id(chain_ids)

Return the preferred chain id for legacy single-chain consumers.

Numeric leading chain ids are skipped when a non-numeric alternative is available.

Parameters:

Name	Type	Description	Default
chain_ids	tuple[str, ...]	Chain ids in source order.	required

Returns:

Type	Description
str	Preferred chain id for consumers that only support a single chain.

Raises:

Type	Description
ValueError	If chain_ids is empty.