chains
Chain-level structure helpers and transformations.
CHAIN_PROVENANCE_SOFTWARE_NAME = 'protein-quest.structure.chains.write_single_chain_structure_file'
module-attribute
Name stored in structure metadata to record chain extraction provenance.
ChainIdSystem = Literal['auth', 'label']
module-attribute
Which chain identifier system is used.
label: PDB-assigned chain id (label_asym_idin mmcif).auth: author-reported chain id (auth_asym_idin mmcif).
If they differ, chain ids are shown as
label_asym_id [auth auth_asym_id] on https://www.rcsb.org/.
For more information see rcsb help and gemmi documentation
ChainExtractionProvenance
dataclass
Provenance information for chain extraction.
Attributes:
| Name | Type | Description |
|---|---|---|
chain2keep |
str
|
The chain identifier that was kept from the input structure. Stored in 'auth' chain id system. |
out_chain |
str
|
The chain identifier that is used in this output structure. Stored in 'auth' chain id system. |
chains_in_structure(structure)
Get a list of chains in a structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
Structure
|
The gemmi structure to get chains from. |
required |
Returns:
| Type | Description |
|---|---|
set[Chain]
|
A set of chains in the structure. Returned chain objects are in 'auth' chain id system. |
find_chain_in_model(model, wanted_chain)
Find a chain in a model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
Model
|
The gemmi model to search in. |
required |
wanted_chain
|
str
|
The chain identifier to search for. Interpreted in 'auth' chain id system. |
required |
Returns:
| Type | Description |
|---|---|
Chain | None
|
The found chain or None if not found. Returned chain object is in 'auth' chain id system. |
find_chain_in_structure(structure, wanted_chain, chain_system='auth')
Find a chain in a structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
Structure
|
The gemmi structure to search in. |
required |
wanted_chain
|
str
|
The chain identifier to search for. |
required |
chain_system
|
ChainIdSystem
|
System of |
'auth'
|
Returns:
| Type | Description |
|---|---|
Chain | None
|
The found chain or None if not found. Returned chain object is in 'auth' chain id system. |
get_label2auth_chains(structure)
Build a label-to-author chain mapping from a structure.
This function primarily reads mmCIF _atom_site.label_asym_id and
_atom_site.auth_asym_id columns from group_PDB == 'ATOM' rows to derive
label_asym_id -> auth_asym_id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
Structure
|
The structure to inspect. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
A dictionary mapping label chain ids to author chain ids. Keys are in 'label' chain id system. Values are in 'auth' chain id system. If the same label appears multiple times, the first observed mapping is kept to ensure deterministic output. |
make_single_chain_structure(input_structure, chain2keep, out_chain='A', input_file=None, force=False)
Make a single chain structure.
By keeping given chain and renaming it to out_chain.
Also
- removes ligands and waters
- renumbers atoms ids
- removes chem_comp section from cif files
- stores chain2keep and out_chain as JSON-ified
ChainExtractionProvenance
object in the
contact_authorfield of a new software item. The software item also contains this function name, version and current date.
This function is equivalent to the following gemmi commands:
gemmi convert --remove-lig-wat --select=B --to=cif chain-in/3JRS.cif - | gemmi convert --from=cif --rename-chain=B:A - chain-out/3JRS_B2A.gemmi.cif
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_structure
|
Structure
|
The input structure. |
required |
chain2keep
|
str
|
The chain to keep. Interpreted in 'auth' chain id system. |
required |
out_chain
|
str
|
The chain identifier for the output file. Written in 'auth' chain id system. |
'A'
|
input_file
|
Path | None
|
The input file path, used for logging and error messages. |
None
|
force
|
bool
|
Rewrite the structure even when it is already a single matching chain. |
False
|
Returns:
| Type | Description |
|---|---|
Structure | None
|
The new structure with only the specified chain, or None if no changes were needed. |
Raises:
| Type | Description |
|---|---|
ChainNotFoundError
|
If the specified chain is not found in the input file. |
nr_of_residues_in_total(structure)
Count the total number of residues in the structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
Structure
|
The gemmi Structure object to analyze. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The total number of residues in the structure. |
nr_residues_in_chain(file, chain='A')
Returns the number of residues in a specific chain from a structure file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
Path
|
Path to the input structure file. |
required |
chain
|
str
|
Chain to count residues of. Interpreted in 'auth' chain id system. |
'A'
|
Returns:
| Type | Description |
|---|---|
int
|
The number of residues in the specified chain. |
retrieve_chain_extraction_provenance(structure)
Extract the provenance information from a structure.
Gives back what chain renamed as a result of call to protein-quest filter chain command or
write_single_chain_structure_file
function.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
Structure
|
The gemmi structure to extract provenance from. |
required |
Returns:
| Type | Description |
|---|---|
tuple[SoftwareItem, ChainExtractionProvenance] | None
|
A tuple of the software item and the provenance information, or None if not found. |
Raises:
| Type | Description |
|---|---|
JSONDecodeError
|
If the contact_author field is not valid JSON. |
ClassValidationError
|
If the contact_author field is valid JSON is incorrect shape. |
write_single_chain_structure_file(input_file, chain2keep, output_dir, out_chain='A', copy_method='copy', force=False)
Write a single chain from a structure file to a new structure file.
Does additional processing see make_single_chain_structure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_file
|
Path
|
Path to the input structure file. |
required |
chain2keep
|
str
|
The chain to keep. Interpreted in 'auth' chain id system. |
required |
output_dir
|
Path
|
Directory to save the output file. |
required |
out_chain
|
str
|
The chain identifier for the output file. Written in 'auth' chain id system. |
'A'
|
copy_method
|
CopyMethod
|
How to copy when no changes are needed to output file. |
'copy'
|
force
|
bool
|
Rewrite the structure even when it is already a single matching chain, and overwrite an existing output file. |
False
|
Returns:
| Type | Description |
|---|---|
Path
|
Path to the output structure file |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the input file does not exist. |
ChainNotFoundError
|
If the specified chain is not found in the input file. |