abcat

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, CDR2, CDR3 루프 분리를 수행하고, Constant Domain에 대해서는 정밀 서열 비교를 통해 Isotype, Subclass, Isoallotype, Allotype을 판정합니다.

Key Features

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

   • 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, 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.
   • 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

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      │    │ - Allotype/Isoallotype Fingerprint│
└────────┬─────────┘    └─────────────────┬─────────────────┘
         │                                │
         └────────────────┬───────────────┘
                          ▼
            ┌──────────────────────────┐
            │ Unified Result (JSON/CSV)│
            └──────────────────────────┘

Key Allotype Fingerprints (Reference)

Note on Engineered Antibodies (e.g., Trastuzumab): Trastuzumab의 Heavy Chain Fc는 자연형 G1m1,17 형태가 아닌, CH3 영역이 E356-M358로 엔지니어링되어 G1m1 에피토프가 제거된 비정상(allotypic / engineered) 형태입니다. 따라서 판정 시스템은 G1m17 알로타입만 감지하며(G1m17 only), CH3의 E356/M358 서열은 nG1m1 isoallotype으로 분류됩니다.

Installation

1. From PyPI (Recommended)

PyPI에서 abcat 패키지를 직접 설치하여 바로 사용하실 수 있습니다:

uv pip install abcat

2. Development Setup (using uv)

소스 코드 개발 및 기여를 위한 개발 버전 구축 시 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)를 통해 최신 버전을 PyPI에 자동 게시하는 GitHub Action 워크플로우를 제공합니다.

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.