antibody_utils.structure¶

Antibody structure tools.

Read a structure with read_structure, which identifies and numbers its antibody chains, then pair a heavy and a light chain into an Fv, and copy regions of them with select.

class antibody_utils.structure.AntibodyChain(chain, numbered, indices)[source]¶

Bases: object

A chain of a structure with a numbered antibody variable domain.

Only the residues of the variable domain are numbered. Any others on the chain (such as a constant domain, a tag, ligands or water) are left out here, but remain in the structure.

property chain: Chain¶: Whether this is a heavy or a light chain.

property gemmi_chain: Chain¶: The whole chain in the structure, including unnumbered residues.

property name: str¶: The chain’s name in the structure.

property numbered: NumberedSequence¶: The numbered variable domain.

region_residues(definition)[source]¶

Group the residues of the domain by region.

Regions are assigned with antibody_utils.regions.annotate_regions, as for antibody_utils.sequence.region_sequences.

Parameters:: definition (Definition | str) – The region definition to apply.
Return type:: dict[Region, list[Residue]]
Returns:: The residues of each region present, in sequence order.

property residues: list[Residue]¶: The residues of the numbered domain, in sequence order.

property scheme: Scheme¶: The numbering scheme.

class antibody_utils.structure.AntibodyStructure(structure, chains, scheme, model)[source]¶

Bases: object

A structure with its antibody chains identified and numbered.

Create one with antibody_utils.structure.read_structure or antibody_utils.structure.from_gemmi.

chains¶: The antibody chains, in the order they appear in the structure.

property heavy_chains: tuple[AntibodyChain, ...]¶: The heavy chains.

property light_chains: tuple[AntibodyChain, ...]¶: The light chains.

property model: Model¶: The model that the antibody chains belong to.

property other_chains: list[Chain]¶: The chains of the model that are not antibody chains.

scheme¶: The numbering scheme.

structure¶: The underlying GEMMI structure, with its original numbering.

class antibody_utils.structure.Fv(heavy, light)[source]¶

Bases: object

A variable fragment: a heavy and a light chain that pair.

Chains are not paired automatically: choose the pair yourself, for example from the structure’s metadata: Fv(structure[“H”], structure[“L”]).

property heavy: AntibodyChain¶: The heavy chain.

property light: AntibodyChain¶: The light chain.

property name: str¶: The heavy and light chain names, joined, such as “HL”.

property numbered: tuple[NumberedSequence, NumberedSequence]¶

The numbered heavy and light domains.

These can be passed straight to antibody_utils.sequence.identity and antibody_utils.sequence.similarity.

region_residues(definition)[source]¶

Group the residues of both domains by region.

Parameters:: definition (Definition | str) – The region definition to apply.
Returns:: the heavy chain’s, then the light chain’s.
Return type:: dict[Region, list[Residue]]

property scheme: Scheme¶: The numbering scheme.

antibody_utils.structure.from_gemmi(structure, scheme=Scheme.IMGT, *, chains=None, model=0, cpu=False)[source]¶

Number the antibody chains of a structure that is already loaded.

The structure is copied, so later changes to structure do not affect the result. The arguments are as for read_structure.

Parameters:

structure (Structure) – The structure.
scheme (Scheme | str) – The numbering scheme.
chains (Mapping[str, Chain | str] | None) – The antibody chains whose numbering to use as it is.
model (int) – The index of the model to use.
cpu (bool) – When numbering with ANARCII, run on the CPU.

Return type:

AntibodyStructure

Returns:

The structure, with its antibody chains.

antibody_utils.structure.read_structure(path, scheme=Scheme.IMGT, *, chains=None, model=0, cpu=False)[source]¶

Read a structure file and number its antibody chains.

Parameters:

path (str | PathLike[str]) – A PDB, mmCIF or other file that GEMMI can read, optionally gzipped.
scheme (Scheme | str) – The numbering scheme. With chains, this is the scheme that the file is already numbered in.
chains (Mapping[str, Chain | str] | None) – The antibody chains, as a mapping from chain names to their types (“H” or “L”), whose numbering in the file is used as it is. By default, every chain is numbered with ANARCII instead.
model (int) – The index of the model to use.
cpu (bool) – When numbering with ANARCII, run on the CPU even if a GPU is available.

Return type:

AntibodyStructure

Returns:

The structure, with its antibody chains.

Raises:

KeyError – If a chain named in chains is not in the structure.
ValueError – If a chain named in chains has no residues numbered in the variable domain, or its numbering is out of order.
ImportError – If chains is not given and ANARCII is not installed.

antibody_utils.structure.select(source, regions=('fv',), *, definition, exclude=(), atoms=None)[source]¶

Copy regions of antibody chains into a new structure.

The copy holds one model, with a chain for each antibody chain selected. Its residues are numbered in the chains’ numbering scheme, so that, for example, select(fv, definition=”imgt”).write_pdb(“fv.pdb”) writes an IMGT-numbered Fv. The original structure is left unchanged.

Regions are assigned as by AntibodyChain.region_residues.

Parameters:

source (AntibodyChain | Fv | Iterable[AntibodyChain]) – An antibody chain, an Fv, or several antibody chains from one structure.
regions (Iterable[Region | str]) – The regions, or region groups such as “cdrs”, to copy. By default, the whole variable domain (“fv”).
definition (Definition | str) – The region definition to apply.
exclude (Iterable[Region | str]) – Regions, or region groups, to leave out, such as [“cdrh3”].
atoms (Iterable[str] | None) – The names of the atoms to copy, such as BACKBONE_ATOMS. By default, every atom.

Return type:

Structure

Returns:

The new structure, with the original’s name, unit cell and space group.

Raises:

ValueError – If a region or group name is not recognised, or the chains come from different structures.

Modules

`models`	Antibody chains in a structure, and the Fvs that pair them.
`parser`	Read structures and identify their numbered antibody chains.
`selection`	Copy selected regions and atoms of antibody chains into a new structure.