Skip to content
BranchesTags

Latest commit

 

History

29 Commits

Folders and files

NameName
Last commit message
Last commit date
.github
.github
 
 
data
data
 
 
examples
examples
 
 
src/abcat
src/abcat
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
.python-version
.python-version
 
 
LICENSE
LICENSE
 
 
README.en.md
README.en.md
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 
uv.lock
uv.lock
 
 

Repository files navigation

abcat

English | 한국어

abcat는 ANARCII를 기반으로 항체 Heavy chain과 Light chain의 Variable Domain(VH, VL) 및 Constant Domain(CH1, CH2, CH3, CL)을 함께 분석하는 Python CLI/라이브러리입니다.

Variable Domain은 ANARCII로 넘버링(IMGT, Kabat, Chothia 등)과 CDR1/2/3 루프 구간을 추출하고, Constant Domain은 서열 비교를 거쳐 Isotype, Subclass, Isoallotype, Allotype을 판정합니다.

Key Features

  1. Variable Domain (VH / VL) 분석 (ANARCII 기반):

    • Variable Domain 경계 인식 및 IMGT/Kabat/Chothia/AHo 번호 부여
    • CDR1, CDR2, CDR3 및 Framework(FR1, FR2, FR3, FR4) 구간 서열·길이 추출
    • Heavy chain(VH), Light chain(VK, VL) 자동 분류 및 confidence score 산출

  2. Constant Domain 분석 (Isotype, Subclass, IMGT Allele, Isoallotype, Allotype):

    • Constant Region (CH1, Hinge, CH2, CH3 / CL) 자동 도출
    • Isotype 판정: Heavy chain (IgG, IgA, IgM, IgE, IgD), Light chain (Kappa, Lambda)
    • Subclass 판정: IgG1, IgG2, IgG3, IgG4, IgA1, IgA2, IGKC, IGLC1~IGLC7
    • IMGT Allele 판정: EU 넘버링 핵심 다형성 위치 조합을 통한 IMGT 대립유전자(Allele) 자동 분류
      • IGHG1*01IGHG1*13, IGHG2*01IGHG2*06, IGHG3*01IGHG3*19, IGHG4*01IGHG4*04, IGKC*01IGKC*04, IGHE*01IGHE*04
    • Allotype 및 Isoallotype 판정: IMGT 다형성 위치(Polymorphic positions) 기반 알로타입 마커 추출
      • Heavy chain: G1m1, G1m2, G1m3, G1m17, G1m27, G1m28, G2m.., G2m23, G3m5G3m28, nG1m1, nG1m17, nG3m5, nG3m11, nG3m21, nG4m(a), nG4m(b), IGHE*01IGHE*04 등
      • Light chain: Km1, Km1,2, Km3 등

  3. CLI 및 Python API 지원:

    • 단일 서열 및 FASTA 배치 파일 분석
    • CSV, JSON, 콘솔 테이블 출력

Tech Stack

  • Python: 3.14+
  • Dependency Management: uv
  • V-Domain Analysis: anarcii (https://github.com/oxpig/ANARCII)
  • C-Domain Alignment & Sequence Comparison: biopython
  • Data Models: pydantic
  • CLI Framework: typer / rich
  • Testing & Quality: pytest, ruff, mypy, ty

Architecture & Workflow

[Input Amino Acid Sequence (Full Heavy/Light Chain or V+C)]
                     │
                     ▼
       ┌──────────────────────────┐
       │     ANARCII Wrapper      │  (V-domain Numbering & Classification)
       └─────────────┬────────────┘
                     │
         ┌───────────┴───────────┐
         ▼                       ▼
┌──────────────────┐    ┌───────────────────────────────────┐
│ V-Domain Engine  │    │      Constant Domain Engine       │
│                  │    │                                   │
│ - VH / VL Check  │    │ - Constant Region Extraction      │
│ - IMGT Numbering │    │ - C-Gene Profile Alignment        │
│ - CDR1/2/3 Bounds│    │ - Isotype & Subclass Matching     │
│ - FR1/2/3/4      │    │ - IMGT Allele Classification      │
│                  │    │ - Allotype/Isoallotype Fingerprint│
└────────┬─────────┘    └─────────────────┬─────────────────┘
         │                                │
         └────────────────┬───────────────┘
                          ▼
            ┌──────────────────────────┐
            │ Unified Result (JSON/CSV)│
            └──────────────────────────┘

IMGT Constant Domain Alleles (Reference)

abcat는 EU numbering 기준의 핵심 아미노산 잔기 조합(Fingerprint)으로 IMGT 대립유전자(Alleles)를 판정합니다.

1. IGHG1 (IgG1) Alleles

IMGT Allele Subclass Allotype Association Key EU Positions & Residues
IGHG1*01 IgG1 G1m17,1 214K, 309L, 356D, 358L, 384N
IGHG1*02 IgG1 G1m17,1 214K, 309L, 356D, 358L, 384N (silent variant of *01)
IGHG1*03 IgG1 G1m3, nG1m1 199I, 214R, 309L, 356E, 358M, 384N
IGHG1*04 IgG1 G1m17,1,27 214K, 309L, 356D, 358L, 384N, 422I
IGHG1*05 IgG1 G1m17,1,28 214K, 309L, 356D, 358L, 384N, 435R, 436Y
IGHG1*07 IgG1 G1m17,1,2 214K, 309L, 356D, 358L, 384N, 431G
IGHG1*08 IgG1 G1m3,1 199I, 214R, 309L, 356D, 358L, 384N
IGHG1*11 IgG1 G1m17,1 (309V) 214K, 309V, 356D, 358L, 384N
IGHG1*13 IgG1 G1m17,1 (296F) 214K, 296F, 309L, 356D, 358L, 384N

2. IGHG2, IGHG3, IGHG4 & Light Chain Alleles

Subclass IMGT Allele Allotype / Marker Key Residues (EU numbering)
IgG2 IGHG2*01 G2m.. (G2m-) 192S, 193L, 282V, 309V
IGHG2*02 G2m23 282M
IGHG2*04 G2m(ny) 192N, 193F, 282V
IGHG2*06 - 282V
IgG3 IGHG3*01 G3m5,26 291P, 384S, 435R, 436F
IGHG3*04 G3m21 291L, 384S, 435H, 436Y
IGHG3*11 G3m5,13,14 397V, 419Q, 435R, 436F
IGHG3*12 G3m15,16 292W, 378M, 384N, 435H, 436Y
IGHG3*13 G3m6,24 384S, 419E, 435H, 436Y
IGHG3*14 G3m10,27,28 384S, 422I, 435R, 436Y
IGHG3*17 G3m11 384S, 435H, 436Y
IGHG3*18 nG3m11 384N, 435H, 436Y
IGHG3*19 G3m16,5 292W, 384S, 435R, 436F
IgG4 IGHG4*01 nG4m(a) 309L
IGHG4*02 nG4m(b) 309V
IGHG4*03 - 309L, 409K
IGHG4*04 - 309L, 445P
IGKC IGKC*01 / *04 Km3 153A, 191V
IGKC*02 Km1,2 153A, 191L
IGKC*03 Km1 153V, 191L

Key Allotype Fingerprints (Reference)

Subclass / Chain Marker / Allotype IMGT / EU Position Key Polymorphisms
IgG1 (CH1) G1m17 vs G1m3 CH1 IMGT 103, 120 (EU 199, 214) K214 = G1m17, I199/R214 = G1m3, R214 = nG1m17
IgG1 (CH3) G1m1 vs nG1m1 CH3 IMGT 12, 14 (EU 356, 358) D356/L358 = G1m1, E356/M358 = nG1m1
IgG1 (CH3) G1m2 CH3 IMGT 110 (EU 431) G431 = G1m2
IgG1 (CH3) G1m27 CH3 IMGT 101 (EU 422) I422 = G1m27
IgG1 (CH3) G1m28 CH3 IMGT 115, 116 (EU 435, 436) R435/Y436 = G1m28
IgG2 (CH2) G2m23 vs G2m.. CH2 EU 282 M282 = G2m23, V282 = G2m..
IgG3 (CH3) G3m5 vs nG3m5 CH3 EU 435, 436 R435/F436 = G3m5, H435/Y436 = nG3m5
IgG3 (CH3) G3m26 CH3 EU 436 R436 = G3m26
IgG4 (CH2) nG4m(a) vs nG4m(b) CH2 EU 309 L309 = nG4m(a), V309 = nG4m(b)
IgE (CH1, CH2) IGHE*01~IGHE*04 CH1 IMGT 41, CH2 IMGT 41 C141/W246 (*01), W141/W246 (*02), C141/L246 (*03)
Kappa (CL) Km1 vs Km1,2 vs Km3 CL IMGT 45, 83 (EU 153, 191) V153/L191 = Km1, A153/L191 = Km1,2, A153/V191 = Km3

엔지니어링 항체 참고 (예: Trastuzumab):
Trastuzumab의 Heavy Chain Fc는 자연형 G1m1,17과 달리 CH3 영역이 E356-M358로 변형되어 G1m1 에피토프가 제거된 엔지니어링 서열입니다. 따라서 G1m17 알로타입만 감지되며(G1m17 only), CH3의 E356/M358 구간은 nG1m1 isoallotype으로 분류됩니다.

Installation

1. PyPI 설치

uv pip install abcat

2. 개발 환경 설정 (uv 기준)

# 저장소 클론
git clone https://github.com/user/abcat.git
cd abcat

# 개발 의존성 포함 동기화
uv sync --extra dev

# 테스트 및 CLI 실행
uv run pytest
uv run abcat analyze --sequence EVQLVES...

CLI & Python API Usage Example

1. CLI Examples

# 기본 분석 (IMGT scheme)
abcat analyze --sequence EVQLVESGGGLVQPGGSLRLSCAASGFTFSDHYMDWVRQAPGKGLEWVGRIRSKANSYATAYAASVKGRFTISRDDSKNTLYLQMNSLRAEDTAVYYCARFDAYWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTHTCPPCPAPELLGGPSVFLFPPKPKDTLMISRTPEVTCVVVDVSHEDPEVKFNWYVDGVEVHNAKTKPREEQYNSTYRVVSVLTVLHQDWLNGKEYKCKVSNKALPAPIEKTISKAKGQPREPQVYTLPPSRDELTKNQVSLTCLVKGFYPSDIAVEWESNGQPENNYKTTPPVLDSDGSFFLYSKLTVDKSRWQQGNVFSCSVMHEALHNHYTQKSLSLSPGK

# 줄바꿈이 포함된 서열 분석 (큰따옴표 "..." 사용)
abcat analyze --sequence "EVQLLESGGGLVQPGGSLRLSCAASGIDLSTYAMGWVRQAPGKGLEWVGLIHRSGRTYYA
TWAKGRFTISKDSSKNTLYLQMNSLRAEDTAVYYCTRSYPDYSATASIWGQGTTVTVSSA
STKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSG
LYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTHTCPPCPAPELLGGP
SVFLFPPKPKDTLMISRTPEVTCVVVDVSHEDPEVKFNWYVDGVEVHNAKTKPREEQYNS
TYRVVSVLTVLHQDWLNGKEYKCKVSNKALPAPIEKTISKAKGQPREPQVYTLPPSREEM
TKNQVSLTCLVKGFYPSDIAVEWESNGQPENNYKTTPPVLDSDGSFFLYSKLTVDKSRWQ
QGNVFSCSVMHEALHNHYTQKSLSLSPGK"

# 넘버링 체계(Scheme) 지정 (imgt, kabat, martin, chothia, aho 지원)
abcat analyze --sequence EVQLVES... --scheme kabat
abcat vdomain --sequence EVQLVES... --scheme martin
abcat vdomain --sequence EVQLVES... --scheme chothia
abcat vdomain --sequence EVQLVES... --scheme aho

# FASTA 배치 파일 분석 및 CSV 저장
abcat batch --input examples/full_antibodies.fasta --output results.csv --format csv --scheme imgt

2. Python API Example

from abcat import analyze_chain, analyze_vdomain

seq = "EVQLVESGGGLVQPGGSLRLSCAASGFTFSDHYMDWVRQAPGKGLEWVGRIRSKANSYATAYAASVKGRFTISRDDSKNTLYLQMNSLRAEDTAVYYCARFDAYWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTHTCPPCPAPELLGGPSVFLFPPKPKDTLMISRTPEVTCVVVDVSHEDPEVKFNWYVDGVEVHNAKTKPREEQYNSTYRVVSVLTVLHQDWLNGKEYKCKVSNKALPAPIEKTISKAKGQPREPQVYTLPPSRDELTKNQVSLTCLVKGFYPSDIAVEWESNGQPENNYKTTPPVLDSDGSFFLYSKLTVDKSRWQQGNVFSCSVMHEALHNHYTQKSLSLSPGK"

# Martin scheme으로 분석
result_martin = analyze_chain(seq, scheme="martin")
print("Scheme:", result_martin.v_analysis.scheme)
print("CDR1:", result_martin.v_analysis.cdrs["CDR1"].sequence)
print("CDR2:", result_martin.v_analysis.cdrs["CDR2"].sequence)
print("CDR3:", result_martin.v_analysis.cdrs["CDR3"].sequence)

# Kabat scheme으로 V-Domain만 분석
v_kabat = analyze_vdomain(seq, scheme="kabat")
print("Kabat CDR3:", v_kabat.cdrs["CDR3"].sequence)

PyPI Deployment (GitHub Actions)

GitHub Release 생성 시 uv build를 거쳐 PyPI Trusted Publisher (OIDC)로 패키지를 자동 배포합니다.

License

MIT

References

  • GM Allotypes Reference: Currently testable (serologically) GM allotypes and amino acid substitutions. J Immunol. 2025 Dec 1;214(12):3181–3187. doi: 10.1093/jimmun/vkaf190.
  • Allelic Diversity & Isoallotypes Reference: Warrender AK, Kelton W. Beyond Allotypes: The Influence of Allelic Diversity in Antibody Constant Domains. Front Immunol. 2020 Aug 18;11:2016. doi: 10.3389/fimmu.2020.02016. PMID: 32973808; PMCID: PMC7461860.
  • Lefranc MP, Lefranc G. Using IMGT unique numbering for IG allotypes and Fc-engineered variants of effector properties and half-life of therapeutic antibodies. Immunol Rev. 2024 Nov;328(1):473-506. doi: 10.1111/imr.13399. Epub 2024 Oct 4. PMID: 39367563; PMCID: PMC11659927.

About

abcat is a Python CLI/library tool that uses ANARCII as a core dependency to perform integrated analysis of antibody heavy-chain and light-chain sequences, covering both variable domains (VH, VL) and constant domains (CH1, CH2, CH3, CL).

Topics

antibodyantibody-annotationantibody-designantibody-engineeringantibody-numberingantibody-optimizationantibody-sequenceantibody-sequencesbioinformaticspython

Resources

Readme
MIT license
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages