---
title: Humatch outputs and interpretation
description: Humanness scores, flagged positions, and closest germline from Humatch.
tags:
  - humatch
  - outputs
---

Humatch returns, per sequence, an overall humanness score, a pass/fail against your threshold, per-V-gene and per-position scores, the closest human germline V gene, and a list of the positions that pull the score down. Read the flagged positions alongside the overall score: the score tells you *whether* to humanize, the flagged positions tell you *where*.

## Per-sequence result

Each scored sequence carries these fields:

| Field | Type | What it tells you |
|---|---|---|
| `sequence_name` | string | The name you gave the sequence. |
| `humanness_score` | float | Overall humanness (0–1). |
| `is_human` | bool | Whether the score clears your threshold. |
| `chain_type` | string | The chain type scored (`H` or `L`). |
| `v_gene_scores` | map gene→float | Per-V-gene humanness scores. |
| `top_human_germline` | string \| null | Closest human germline V gene. |
| `positional_scores` | map position→float | Per-position humanness, on the numbering scheme used. |
| `flagged_positions` | string[] | Positions with low humanness — the humanization targets. |

## Paired result

A request that used `chain_pairs` also returns `paired_results`, one entry per pair. For a single-chain request the list is empty.

| Field | Type | What it tells you |
|---|---|---|
| `pair_name` | string | The name you gave the pair. |
| `paired_score` | float \| null | The paired classifier's score for this heavy/light combination (0–1). `null` when the pair failed, with `error` saying why. |
| `paired_score_class` | string \| null | Which class `paired_score` is the probability of. |
| `heavy` | object \| null | The full per-chain result for the heavy chain, in the shape above. |
| `light` | object \| null | The same for the light chain. |
| `error` | string \| null | Why this pair has no paired score. |

### Reading the paired score

`paired_score` is the probability Humatch's paired CNN assigns to its `true` class — the classifier's two classes are `fake` and `true`. The returned `paired_score_class` names which one the number refers to, so read it rather than assuming.

⚠ **Humatch publishes no interpretation bands for the paired score, so none are applied.** There is no pass/fail on it, and no threshold: `score_threshold` governs the per-chain humanness classification only. The number is reported as measured, with no verdict attached, and inventing a cutoff for it means inventing a standard the model's authors did not set.

## Job-level summary

| Field | Type | Meaning |
|---|---|---|
| `failed_sequences` | string[] | Sequences Humatch could not score. |
| `success_count` | int | Sequences scored successfully. |
| `fail_count` | int | Sequences that failed. |
| `paired_success_count` | int \| null | Pairs that produced a paired score. `null` — not `0` — when no pair was requested. |
| `paired_fail_count` | int \| null | Pairs that did not. `null` when no pair was requested. |
| `partial` | boolean | `true` when at least one sequence or pair failed. Check it before treating the run as complete. |
| `scheme_used` | string | Numbering scheme applied. |
| `requested_scheme` | string \| null | The scheme you asked for. Recorded, not applied. |
| `threshold_used` | float | Classification threshold used. |
| `paired_score_method` | string \| null | How `paired_score` was computed. `null` when no pair was requested. |

> **Humatch always aligns to IMGT**

> `numbering_scheme` reports the numbering that was actually used, and it is always IMGT. A `chothia` or `kabat` request is recorded in `requested_scheme` and not applied, so position numbers in the result are IMGT whatever you asked for. Compare the two fields before reading a position number across tools.

## Reading the result card

The Humatch result renders on the canvas as an antibody-structure card, surfacing the humanness score and per-chain read so you can judge the candidate at a glance.

## What to do next

- Take the `flagged_positions` to [BioPhi](/docs/biophi) and humanize them — Humatch scores, BioPhi rewrites.
- Cross-check the flagged positions against the [paratope](/docs/paragraph) so you humanize away from binding residues.
- Run [antibody developability](/docs/antibody-developability) before committing a candidate.

## Read next