Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    Tools · Computational Biology

    Antibody Numbering & Humanization

    Number antibody, nanobody and TCR variable domains in IMGT, Kabat and Chothia, mark the CDRs, find the nearest human germline, flag sequence liabilities, and list advisory humanization candidates.

    Updated October 20, 2026

    On this page

    Prices, workflows, and method papersOpen in the app

    Design tools produce antibody sequences and structures; this tool reads them as antibodies. Give it sequences or PDB / mmCIF structures and it numbers each variable domain, marks the CDRs, names the closest human germline, flags liabilities that depend on where a residue sits, and, if you ask, lists framework substitutions toward that germline.

    How it works

    ANARCI aligns each chain to HMMs built from IMGT germlines with HMMER, decides whether it is heavy, kappa, lambda, or a TCR alpha or beta chain, and assigns positions in IMGT, Kabat and Chothia. Kabat and Chothia cover immunoglobulins only, so TCR chains are numbered in IMGT. CDR boundaries come from a fixed table per scheme applied to the numbered positions, so insertion codes such as Kabat 52A stay with their loop.

    Germline. Each chain gets its closest germline V and J gene and a germline_identity value: the V-gene identity to the nearest human germline, from 0 to 1. It is a descriptive germline-content measure, not a T20 or OASis humanness score, and it does not predict immunogenicity.

    Liability flags are the ones that need numbering to mean anything: N-glycosylation sequons and deamidation or isomerization motifs inside a CDR, and cysteines other than the canonical pair. Review them; they are not verdicts.

    Humanization is opt-in and advisory. A framework position that differs from the nearest human germline is a candidate substitution, and a position that is a CDR under any of the three schemes is never touched. Candidates are ranked by distance to the nearest CDR edge; each chain also gets one sequence with all of them applied.

    Inputs and outputs

    Provide sequences (FASTA or raw), structure files, or both. You get per-chain annotations, per-residue numbering, a FASTA of the numbered chains, a map from structure residues to scheme positions, and humanization candidates when requested. A sequence that cannot be numbered becomes a failed row; the job still finishes.

    In a workflow, designs from RFAntibody, BoltzGen or FreeBindCraft bind to the structure input. The numbered sequences carry germline_identity, so a filter step can keep the most germline-like designs before Binding ΔΔG or ESMFold2. To test a subset of candidates, apply it with Sequence Mutator.

    Honest limits

    • Numbering uses human and mouse HMMs; other species number, but their germline calls are weak.
    • The germline reference is a dated IMGT snapshot, stamped into every output. Newer alleles are not called.
    • Heavy-light pairing is not scored.
    • This is not a validated humanization or immunogenicity predictor. Treat candidates as hypotheses to test.

    Numbering is ANARCI (Dunbar and Deane, 2016); germline data are from IMGT®, the international ImMunoGeneTics information system.

    Run it from the API

    Submit with Submit a job and the job_type below. Price it first with Estimate job reservation cost: submitting reserves that amount from your wallet, and the charge settles at the actual runtime.

    Antibody Numbering & Humanization antibody-annotate

    Job type
    antibody-annotate
    Hardware
    cpu (default)
    Typical runtime
    3 min on CPU

    Payload

    Provide at least one of: sequences, structures.

    Payload fields
    FieldTypeDescription
    sequencesstring | object[] | artifact_ref
    structuresfile_object | file_object[]
    chains[]string[]

    Limits: min items 1, max items 50

    schemes[]any[]

    Default: ["imgt","kabat","chothia"]One of: "imgt", "kabat", "chothia"Limits: min items 1

    humanizeboolean

    Default: false

    File fields take {"name": "x.pdb", "content_b64": "…"} or a stored artifact, {"$artifact": {"id": "art-…", "port": "…"}}. Files are up to 25 MiB each.

    Example

    from cognichem_client import CogniChem
    
    client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
    payload = {
        "sequences": ">trastuzumab_VH\nEVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKG… (345 characters)",
        "schemes": ["imgt", "kabat", "chothia"],
        "humanize": True,
    }
    
    estimate = client.jobs.estimate(job_type="antibody-annotate", payload=payload, resource="cpu")
    print(f"Reserves ${estimate.cost:.2f}")
    
    job = client.jobs.submit(
        job_name="my-antibody-annotate-run",
        job_type="antibody-annotate",
        payload=payload,
        resource="cpu",
    )
    status = client.jobs.wait(job.process_id)
    if status.status == "completed":
        client.jobs.result(job.process_id, save_path=".")

    Sample data from the job catalog; long values are shortened here. Each job_name must be unique among your jobs.

    Workflow inputs

    • Protein sequences (list) · optionalFASTA, RAW
    • Structures (list) · optionalPDB, CIF

    Workflow outputs

    • TableCSV
    • ArchiveZIP
    • Protein sequencesFASTA
    • TableCSV
    • Protein sequencesFASTA