antibody_utils.numbering¶

Numbering schemes, chains and numbered positions, and numbering with ANARCII.

class antibody_utils.numbering.Chain(*values)[source]¶

Bases: _CaseInsensitiveStrEnum

An antibody variable-domain chain type.

Members compare equal to their one-letter codes, and lookup is case-insensitive.

>>> Chain("h")
<Chain.HEAVY: 'H'>
>>> Chain.LIGHT == "L"
True

class antibody_utils.numbering.NumberedSequence(name, chain_type, scheme, positions, sequence, score, start, end)[source]¶

Bases: object

An antibody variable domain, numbered in one scheme.

name¶: The name of the input sequence.

chain_type¶: The chain type that ANARCII assigned: “H” (heavy), “K” (kappa) or “L” (lambda).

scheme¶: The numbering scheme.

positions¶: The position of each residue of the numbered domain, in sequence order. Positions with no residue are omitted.

sequence¶: The residues of the numbered domain.

score¶: ANARCII’s confidence score for the numbering.

start¶: The index of the domain’s first residue in the input sequence.

end¶: The index just past the domain’s last residue in the input sequence, so that input[start:end] is the numbered domain.

Raises:: ValueError – If positions and sequence differ in length.

annotate_regions(definition)[source]¶

Assign each residue to its region.

Parameters:: definition (Definition | str) – The region definition to apply.
Return type:: list[tuple[Position, str, Region | None]]
Returns:: A (position, residue, region) triple for each residue; see antibody_utils.regions.annotate_regions.

property chain: Chain¶

heavy, or light for kappa and lambda chains.

Type:: The chain

property numbering: list[tuple[Position, str]]¶: The (position, residue) pairs, in sequence order.

exception antibody_utils.numbering.NumberingError[source]¶

Bases: ValueError

A sequence could not be numbered as an antibody variable domain.

class antibody_utils.numbering.Position(number, insertion='')[source]¶

Bases: object

A numbered position: a residue number and an optional insertion code.

Positions order by number, then by insertion code, which is the order of residues in the Kabat, Chothia and Martin schemes. (IMGT orders the insertions at position 112 in reverse, so sort IMGT positions by sequence order rather than by Position.)

The insertion attribute is “” when there is no insertion code. Gemmi, Biopython, ANARCI and ANARCII write that as a single space instead, which Position accepts on input; use to_tuple to convert back.

Parameters:

number (int) – The residue number.
insertion (str) – The insertion code: an upper-case letter, or “” for none. Whitespace, such as the single space used by other tools, also means none.

Raises:

ValueError – If the insertion code is not a single letter.

>>> Position(100, "A")
Position(number=100, insertion='A')
>>> Position(35) < Position(35, "A") < Position(36)
True

classmethod from_tuple(position)[source]¶

Convert a (number, insertion) tuple, as used by ANARCI and Biopython.

Parameters:: position (tuple[int | str, str]) – The residue number (an integer, or a string of digits as ANARCII sometimes gives) and the insertion code, where “ “ means no insertion.
Return type:: Self
Returns:: The position.

>>> Position.from_tuple((52, " "))
Position(number=52, insertion='')
>>> Position.from_tuple(("111", "A"))
Position(number=111, insertion='A')

classmethod parse(text)[source]¶

Parse a position such as “100A”.

Parameters:: text (str) – The residue number, optionally followed by an insertion code.
Return type:: Self
Returns:: The position.
Raises:: ValueError – If the text is not a valid position.

>>> Position.parse("100a")
Position(number=100, insertion='A')
>>> Position.parse("35")
Position(number=35, insertion='')

to_tuple()[source]¶

Convert to a (number, insertion) tuple, with “ “ for no insertion.

This is the convention of Gemmi, Biopython, ANARCI and ANARCII.

Return type:: tuple[int, str]
Returns:: The residue number and insertion code.

>>> Position(52).to_tuple()
(52, ' ')
>>> Position(52, "A").to_tuple()
(52, 'A')

class antibody_utils.numbering.Scheme(*values)[source]¶

Bases: _CaseInsensitiveStrEnum

An antibody numbering scheme.

>>> Scheme("Chothia")
<Scheme.CHOTHIA: 'chothia'>

antibody_utils.numbering.iter_number(sequences, scheme=Scheme.IMGT, *, cpu=False, batch_size=10000)[source]¶

Number antibody variable-domain sequences with ANARCII, lazily.

Sequences are read from sequences, and numbered batch_size at a time, only as the results are consumed. This suits inputs too large to hold in memory, such as a generator over a FASTA file.

Each sequence should contain one variable domain; any residues before or after it (such as a constant domain) are left unnumbered.

Parameters:

sequences (Mapping[str, str] | Iterable[str]) – Sequences of one-letter amino-acid codes, as a mapping from names to sequences, or as an iterable of sequences, which are named by their index (“0”, “1”, …).
scheme (Scheme | str) – The numbering scheme.
cpu (bool) – Run on the CPU even if a GPU is available.
batch_size (int) – How many sequences to pass to ANARCII at a time.

Yields:

A (name, numbered sequence) pair for each input sequence, in input order. A sequence that ANARCII could not number gives None, and a warning is logged.

Raises:

TypeError – If sequences is a single sequence string.
ValueError – If a sequence contains anything other than letters. (In particular, ANARCII would treat - and / as separators between paired chains.) The error is raised when that sequence’s batch is reached, after the results of earlier batches have been yielded.
ImportError – If ANARCII is not installed.

antibody_utils.numbering.number(sequences, scheme=Scheme.IMGT, *, cpu=False, batch_size=10000)[source]¶

Number a collection of antibody variable-domain sequences with ANARCII.

This returns every result at once, at about 1.2 KiB per sequence, so it takes only collections that are already in memory: a mapping or a sequence such as a list. To number a stream of sequences, such as a generator over a large FASTA file, use iter_number, which yields each result as it goes.

Parameters:

sequences (Mapping[str, str] | Sequence[str]) – Sequences of one-letter amino-acid codes, as a mapping from names to sequences, or as a sequence (such as a list) of them, which are named by their index (“0”, “1”, …).
scheme (Scheme | str) – The numbering scheme.
cpu (bool) – Run on the CPU even if a GPU is available.
batch_size (int) – How many sequences to pass to ANARCII at a time.

Return type:

dict[str, NumberedSequence | None]

Returns:

The numbered sequences, by name and in input order. A sequence that ANARCII could not number maps to None, and a warning is logged.

Raises:

TypeError – If sequences is not a mapping or a sequence, or is a single sequence string.
ValueError – If a sequence contains anything other than letters. (In particular, ANARCII would treat - and / as separators between paired chains.)
ImportError – If ANARCII is not installed.

antibody_utils.numbering.number_sequence(sequence, scheme=Scheme.IMGT, *, cpu=False)[source]¶

Number a single antibody variable-domain sequence with ANARCII.

Parameters:

sequence (str) – The sequence, as one-letter amino-acid codes.
scheme (Scheme | str) – The numbering scheme.
cpu (bool) – Run on the CPU even if a GPU is available.

Return type:

NumberedSequence

Returns:

The numbered sequence, named “sequence”.

Raises:

NumberingError – If ANARCII could not number the sequence.
ValueError – If the sequence contains anything other than letters.
ImportError – If ANARCII is not installed.

>>> numbered = number_sequence(
...     "EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSV"
...     "KGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSRWGGDGFYAMDYWGQGTLVTVSS",
...     cpu=True,
... )
>>> numbered.chain_type, len(numbered)
('H', 120)
>>> "".join(
...     residue
...     for _, residue, region in numbered.annotate_regions("imgt")
...     if region == "cdrh3"
... )
'SRWGGDGFYAMDY'

antibody_utils.numbering.parse_chain_position(text)[source]¶

Parse a chain-qualified position such as “H100A”.

Parameters:: text (str) – A chain letter (H or L) followed by a position.
Return type:: tuple[Chain, Position]
Returns:: The chain and the position.
Raises:: ValueError – If the text is not a valid chain-qualified position.

>>> parse_chain_position("H100A")
(<Chain.HEAVY: 'H'>, Position(number=100, insertion='A'))

Modules

`anarcii`	Number antibody sequences with ANARCII.
`positions`	Numbered positions in antibody variable domains.