antibody_utils.numbering.anarcii¶

Number antibody sequences with ANARCII.

This module needs the numbering extra: pip install “antibody-utils[numbering]”. ANARCII (and with it PyTorch) is imported only when sequences are first numbered, so importing antibody_utils stays quick without it.

For large inputs, use iter_number, which numbers sequences in batches and yields the results as it goes, so that memory use depends on the batch size rather than on the number of sequences.

Functions

`iter_number`(sequences[, scheme, cpu, batch_size])	Number antibody variable-domain sequences with ANARCII, lazily.
`number`(sequences[, scheme, cpu, batch_size])	Number a collection of antibody variable-domain sequences with ANARCII.
`number_sequence`(sequence[, scheme, cpu])	Number a single antibody variable-domain sequence with ANARCII.

Classes

NumberedSequence(name, chain_type, scheme, ...)

An antibody variable domain, numbered in one scheme.

Exceptions

NumberingError

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

class antibody_utils.numbering.anarcii.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.anarcii.NumberingError[source]¶

Bases: ValueError

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

antibody_utils.numbering.anarcii.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.anarcii.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.anarcii.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'