Humatch

What is HuMatch?

HuMatch humanizes, classifies humanness, or aligns paired antibody heavy- and light-chain variable domains. It combines gene-specific germline-likeness data with three lightweight convolutional neural networks:

• CNN-H scores the heavy chain against seven human V-gene families.
• CNN-L scores the light chain against ten lambda and seven kappa families.
• CNN-P scores whether the heavy/light combination resembles a naturally paired human antibody.

ProteinIQ runs HuMatch 1.0.1 from the reviewed source revision and uses the model weights and germline arrays published with Zenodo record 13764771.

How to use HuMatch online

ProteinIQ runs HuMatch online for a paired antibody variable domain. Submit one heavy-chain and one light-chain sequence, choose a task, then download the native HuMatch CSV and a reproducibility record. Each job costs 10 credits; the quote is shown before submission.

Tasks

Task	Result
Humanize pair	Jointly designed chains, selected V-gene families, CNN scores, and paired edit count
Classify humanness	Scores for the submitted pair without humanization; all seven heavy and seventeen light human families by default
Align IMGT positions	Native 200-position padded VH/VL sequences, or a separate column for each heavy and light IMGT position

Classification can return only the highest-scoring family for each chain and its score by enabling Only highest-scoring families. Pairing scores are included in both classification schemas. Alignment does not humanize or score sequences. The sequence-comparison FASTA remains a separate humanization output.

Inputs

Input	Requirement
Heavy Chain (VH)	One complete antibody heavy-chain variable domain, 50-200 standard amino acids
Light Chain (VL)	One complete antibody light-chain variable domain, 50-200 standard amino acids

Raw sequence text and single-record FASTA are accepted. Both inputs must use the 20 standard amino-acid one-letter codes. Lowercase input is normalized to uppercase. Ambiguous residues, gaps, stop symbols, and multiple FASTA records in one slot are rejected.

The input-format selector also accepts one-pair CSV or explicitly prealigned sequences. CSV must contain a header and exactly one pair row. The sequence column names default to VH and VL and can be changed with Heavy sequence column and Light sequence column. The file is passed to HuMatch unchanged; additional metadata columns are not copied into its native result table.

Prealigned inputs must follow HuMatch's exact 200-position IMGT order, using uppercase canonical residues and - for padding. Upload one TXT per chain or select one-pair prealigned CSV. Each chain still needs 50-200 biological residues; padding is excluded from that count. Humanization and classification reuse the alignment. The alignment task always runs native numbering. Single-chain jobs, multirow CSV and standalone batch submission are not available.

ANARCI must be able to recognize and number both variable domains. A protein-like sequence that is not an antibody variable domain may pass the alphabet and length checks but fail during numbering. Select Align IMGT positions for paired HuMatch numbering. ANARCI provides other antibody numbering schemes.

Settings

Germline-likeness targets

The heavy- and light-chain targets default to 0.40, matching HuMatch. These control the first mutation phase independently for each chain.

CNN targets

The heavy-chain, light-chain, and pairing targets each default to 0.95. Higher targets request more human-like designs but may require more substitutions or may not be reachable within the edit threshold.

Mutation controls

• Maximum total edit distance defaults to 60 across the paired heavy and light chains. HuMatch applies its initial germline-likeness mutations before checking this stopping threshold, so a returned best design can occasionally exceed it.
• Preserve CDR regions is enabled by default and excludes IMGT CDR1, CDR2, and CDR3 positions from both mutation phases.

Target V-gene families

Automatic selection uses the highest-scoring human family for each submitted chain. Advanced runs can force HV1-HV7 for the heavy chain or KV1-KV7 / LV1-LV10 for the light chain.

Fixed IMGT positions

Enter comma-separated positions such as 9, 81A, 120 to prevent HuMatch from changing those positions in either mutation phase. Heavy- and light-chain lists are configured separately.

Independent mutation controls

Enable Set mutation controls by chain and phase to configure GL and CNN mutation permissions separately for the heavy and light chains. Each phase has its own allow CDR mutations switch and fixed-position list. All four switches default to off and all four lists default to empty, matching HuMatch.

When advanced controls are enabled, they take precedence over Preserve CDR regions and the two shared fixed-position lists. With advanced controls off, the existing controls continue to apply to both phases. The effective YAML records the controls used for the run.

Output options

HuMatch's native CSV is always retained for each successful task. A run can additionally request a TSV or JSON conversion. The sequence-comparison option adds a FASTA file containing the original and humanized heavy and light chains.

Results

Humanization shows one row per chain in Results. Classification and alignment show Native table with the exact source column names and column order.

The humanization Results table contains:

Column	Meaning
Original Sequence	Submitted variable-domain sequence
Humanized Sequence	HuMatch design with padding removed
Target V-Gene Family	Selected HV, KV, or LV family
CNN Humanness Score	Probability assigned to the selected chain family
Edits	Substitutions in that chain
CNN Pairing Score	Probability that the paired design resembles natural human pairing
Total Paired Edits	Source aggregate edit count across both chains
Targets Reached	Whether all three configured CNN targets were reached
Warning	Visible explanation when targets are unmet or the source result exceeds the edit stopping threshold

Downloadable files

• humatch-results.csv: Native task result. Humanization returns Humatch_H, Humatch_L, Edit, HV, LV, CNN_H, CNN_L, and CNN_P. Classification returns padded VH/VL and family scores or its selected-family summary. Alignment returns padded VH/VL or 400 named heavy/light position columns.
• humatch-config.yaml: Exact effective humanization configuration; not produced by classification or alignment
• humatch-provenance.json: Source, ANARCI, model-data, runtime, and setting provenance
• humatch-run.log: HuMatch standard output and diagnostic messages
• humatch-sequence-comparison.fasta: Optional original/humanized sequence comparison for humanization
• humatch-results.tsv or humatch-results.json: Optional converted result

Native logs are also retained when the source exits unsuccessfully or times out. The user-facing message gives the exit status or timeout; download the run log for the full diagnostics. A failed run is not retried with different settings.

How humanization works

HuMatch first aligns each variable domain to 200 IMGT-numbered positions with ANARCI. It then applies two mutation phases.

• Germline-likeness phase: Common residues for the selected target V-gene family are introduced until each chain reaches its configured germline target.
• CNN-guided phase: HuMatch evaluates possible single substitutions and chooses changes that jointly improve the heavy-chain, light-chain, and pairing scores.

By default, IMGT CDR1, CDR2, and CDR3 positions are excluded from both phases. Humanization stops when all configured CNN targets are reached, the edit stopping threshold is crossed, or no novel design can be found. If every target cannot be reached, HuMatch returns the best-scoring design it observed and ProteinIQ reports a warning.

Limitations

• HuMatch evaluates sequence behavior; it does not model three-dimensional structures or binding affinity.
• CDR preservation reduces the chance of changing binding determinants but cannot guarantee preserved affinity or specificity.
• V-gene families with less training data may have less reliable classification scores.
• A high CNN-P score is a sequence-based pairing signal, not an experimental stability measurement.
• Designs should be reviewed structurally and validated experimentally before therapeutic use.