ACMG Assistant

• Added integration validation report (JSON/Markdown) with reference dataset checks
• Added optional ENA metadata validation (ENA Browser API)
• Expanded CLI end-to-end test coverage with mocked inputs
• Improved predictor/population fallbacks and cache keying for dataset variants
• Normalized applied criteria in reports and classification summaries
• Fixed external data fetch gating, HGVS c. fallback, gnomAD AF calc + v3 fallback
• Fixed CADD list responses and AlphaMissense mapping

ACMG Variant Classification Assistant

ACMG Assistant v4.0.0 – Release Notes

Release Date: December 2025

---

Highlights

• Multi-source predictor pipeline: Predictor scores (REVEL, CADD, AlphaMissense, SIFT, PolyPhen-2, etc.) are now fetched from external APIs (myvariant.info/dbNSFP, dedicated AlphaMissense/CADD endpoints) via PredictorAPIClient. No predictor values are hardcoded.
• Population AF from gnomAD GraphQL: PopulationAPIClient queries gnomAD v4 directly; BA1/BS1/PM2 derived from live data, not static tables.
• Validated caching layer: New ResultCache with TTL-based expiration and strict validation. Invalid entries (e.g., REVEL > 1.0, AF > 1.0) are rejected and auto-invalidated.
• PM1 via external APIs: Hardcoded hotspot/domain regions removed. DomainAPIClient queries CancerHotspots.org and UniProt for functional annotations.
• PhenotypeMatcher wired to CLI: PP4/BP5 now derived from weighted Jaccard similarity over gene–phenotype associations and HPO synonyms. Users can input HPO IDs or free-text phenotypes interactively.
• InteractiveEvidenceCollector: Structured prompts for PS3/BS3, PS4, PP1/BS4, PS1/PM5, and deprecated PP5/BP6. Responses encoded as ManualEvidence and merged with automatic evidence.
• CLI transparency: Revised welcome banner explains automatic vs. interactive evidence, data sources, and research-only disclaimer.
• ~198 tests passing: Comprehensive coverage of caching, API clients, PM1, phenotype matching, interactive evidence, and classification logic.

---

Detailed Changes

Multi-source Predictors & PP3/BP4

PredictorAPIClient fetches scores from multiple backends with configurable priority (PREDICTOR_SOURCE_PRIORITY). Each score is wrapped in a PredictorScore dataclass that tracks source, version, and whether the predictor is inverted (e.g., SIFT: lower = more damaging).

• Primary source: myvariant.info (aggregates dbNSFP 4.x).
• Fallback sources: AlphaMissense API, CADD API.
• MissenseEvaluator is now a pure interpreter: it consumes pre-fetched PredictorScore objects, computes a weighted composite score, and maps to PP3/BP4 based on thresholds.
• Weight renormalization handles partial data (e.g., if only REVEL and CADD are available).

Population AF & BA1/BS1/PM2

PopulationAPIClient queries gnomAD v4 via GraphQL. Responses are parsed into PopulationStats dataclass (AF, AC, AN, homozygote count, subpopulation breakdown, popmax).

• PopulationAnalyzer and EthnicityAwarePopulationAnalyzer consume typed population data.
• BA1 (stand-alone benign), BS1 (strong benign), PM2 (absent from controls) derived from live AF values.
• No static frequency tables remain in the codebase.

Validated Caching Layer

ResultCache (in cache.py) provides file-based, thread-safe caching with:

• CacheKey: category + source + normalized variant ID.
• CacheEntry: value + timestamp + TTL.
• Default TTLs: 7 days (predictors), 30 days (population).

Validation rules enforced on cache read:

Data Type	Validation
REVEL	∈ [0, 1]
CADD_PHRED	∈ [0, 60]
AF	∈ [0, 1]
AC	≤ AN

Invalid entries → cache miss → re-fetch from API.

PM1 via External Hotspots/Domains

DomainAPIClient queries:

• CancerHotspots.org: Returns tumor count and mutation frequency at a given position.
• UniProt REST API: Returns functional domains (DNA-binding, kinase, etc.) overlapping the variant position.

GeneSpecificRules.evaluate_pm1() maps annotation confidence to PM1 or PM1_supporting via thresholds. No hardcoded KNOWN_HOTSPOTS or hotspot_regions remain.

PhenotypeMatcher & PP4/BP5

PhenotypeMatcher is now fully integrated into the interactive CLI:

1. User provides phenotypes (HPO IDs or free-text).
2. HPOClient normalizes text to HPO terms via hpo_synonyms.json.
3. Weighted Jaccard similarity computed against gene-specific phenotype profiles (gene_phenotypes.json).
4. Evidence assignment:
   • PP4: similarity ≥ 0.8
   • PP4_supporting: similarity ≥ 0.5
   • BP5: similarity ≤ 0.2
   • Neutral: 0.2 < similarity < 0.5

The old phenotype_match yes/no flag has been removed from the interactive flow.

Interactive Evidence (PS3/PS4/PP1/PS1/PP5)

InteractiveEvidenceCollector provides structured prompts for criteria that require literature review:

Criterion	User Input
PS3/BS3	Functional study count, quality, direction
PS4	Case-control counts → OR computed
PP1/BS4	Segregation pattern, affected carriers
PS1/PM5	Same codon pathogenic variant presence
PP5/BP6	Reputable source assertion (deprecated)

Responses are encoded as ManualEvidence and merged into the final evidence set. PP5/BP6 are labeled deprecated per ClinGen guidance.

CLI & Documentation

• Welcome banner displays version, guideline set (2015 or 2023), mode, and date.
• Explicit explanation of automatic evidence (API-derived) vs. interactive evidence (user-provided).
• Research/educational disclaimer shown at startup.
• README rewritten to document:
  • Data flow architecture (ASCII diagram).
  • Caching model.
  • Evidence types.
  • Limitations.

---

Upgrade Notes

1. PP4/BP5 derivation changed: Previously, users could set a manual phenotype_match flag. This is replaced by the PhenotypeMatcher pipeline. If no phenotypes are provided, PP4/BP5 will not be evaluated.

2. PM1 requires API availability: Without access to CancerHotspots.org or UniProt, PM1 will not be assigned. The tool does not fall back to hardcoded hotspot lists.

3. Stricter cache validation: Cached entries with out-of-range values (e.g., REVEL = 5.0) will be rejected. If you have old cache files, they may be auto-invalidated on first access.

4. Evidence may not trigger if data is missing: By design, the tool only assigns evidence when factual data is available from external sources or user input. This is intentional—absence of data ≠ absence of pathogenicity.

---

Breaking Changes / Incompatibilities

Change	Impact
phenotype_match flag removed	Replace with HPO ID / free-text phenotype input via collect_patient_phenotypes().
Hardcoded PM1 regions removed	PM1 now requires live API access to CancerHotspots.org / UniProt.
VariantData.patient_phenotypes type changed	Now Optional[List[str]] instead of Optional[str].
Old cache format	Legacy api_cache.json entries may be invalidated if they fail validation.

The public CLI interface (command-line flags, interactive prompts) remains backward-compatible. Internal behavior is stricter.

---

Known Limitations

• API dependency: Live classification requires internet access to gnomAD, myvariant.info, CancerHotspots.org, and UniProt. Offline mode relies on cached data only.
• Phenotype similarity is approximate: The weighted Jaccard approach is educational, not a production-grade semantic HPO engine.
• Missense composite score is heuristic: The weighted average of normalized predictor scores is a reasonable proxy but not a validated clinical metric.
• Not a clinical decision tool: All results require validation by qualified professionals. The tool is intended for research, education, and workflow augmentation.

---

Testing

• ~198 tests passing across:
  • test_cache_and_validation.py: Cache TTL, validation, corruption recovery.
  • test_predictor_population_api.py: Multi-source API clients with mocked responses.
  • test_gene_specific_pm1.py: PM1 evaluation via mocked DomainAPIClient.
  • test_acmg_classifier.py: End-to-end classification scenarios (pathogenic, benign, VUS, conflicting).
  • test_interactive_evidence.py: ManualEvidence mapping and merging.
  • tests/conftest.py: Fixtures for offline testing with mocked APIClient.

No regressions detected in prior classification scenarios.

ACMG Variant Classification Assistant

ACMG Assistant v3.5.0 Release Notes

Overview

Version 3.5.0 improves gene lookup reliability and fixes ClinVar classification handling for pharmacogenomic variants.

What's New

Gene Lookup Improvements

• MyGene.info Fallback: Automatic fallback when Ensembl API times out
• 100% Success Rate: All genes now successfully retrieve chromosome information
• Fixed: APOE and other genes that previously failed due to API timeouts

ClinVar Classification Fix

• Drug Response Handling: Correctly identifies pharmacogenomic variants
• Non-Pathogenicity Filter: Prevents misclassification of drug response, risk factor, and other non-pathogenicity annotations
• Fixed: MTHFR c.665C>T now correctly identified as "drug response" (not benign)

Technical Details

Modified Files

• src/utils/api_client.py: Added MyGene.info fallback logic
• src/core/evidence_evaluator.py: Added non-pathogenicity filter to PP5/BP6 criteria
• src/utils/api_error_handler.py: New centralized error handling
• src/utils/gene_rules_engine.py: Gene-specific threshold engine

Non-Pathogenicity Classifications (Now Filtered)

• Drug response
• Risk factor
• Protective
• Association
• Affects
• Confers sensitivity
• Other

Bug Fixes

• Fixed APOE gene chromosome lookup failure
• Fixed MTHFR drug response misclassification
• Improved API timeout handling
• Enhanced error messages for non-pathogenicity variants

---

[Archived] Detailed Technical Documentation

The following sections contain detailed technical information from the development process.

Major Updates

✅ MyGene.info Fallback Integration

• Problem Solved: Ensembl API timeouts causing gene lookup failures
• Solution: Automatic fallback to MyGene.info API
• Impact: gene lookup success rate
• Implementation: Two-tier strategy in get_chromosome_from_ensembl() and get_gene_info()

How It Works:

1. Primary: Try Ensembl REST API (comprehensive data)
2. Fallback: If timeout/error, query MyGene.info (faster, simpler)
3. Caching: Result cached regardless of source
4. Transparency: Logs show which API succeeded

Test Results:

• ✅ APOE (chr19): Previously failed → Now succeeds via MyGene.info
• ✅ BRCA1 (chr17): Works via Ensembl (primary)
• ✅ MTHFR (chr1): Works via Ensembl (primary)

✅ ClinVar Non-Pathogenicity Classification Filter

• Problem Solved: Drug response and pharmacogenomic variants incorrectly interpreted
• Example: MTHFR c.665C>T (p.Ala222Val) "drug response" → suggested as "likely benign"
• Root Cause: PP5/BP6 criteria didn't filter non-pathogenicity classifications
• Solution: Early detection and exclusion in evidence evaluation

Non-Pathogenicity Classifications (Now Filtered):

1. drug response - Pharmacogenomic variants (e.g., MTHFR, CYP2C19)
2. risk factor - Disease susceptibility modifiers
3. protective - Protective genetic variants
4. affects - Trait/phenotype associations
5. association - Statistical associations
6. confers sensitivity - Environmental/drug sensitivity
7. other / not provided - Miscellaneous annotations

Implementation:

# Check for non-pathogenicity classifications
non_pathogenicity_terms = ['drug response', 'risk factor', 'protective', 
                          'affects', 'association', 'confers sensitivity',
                          'other', 'not provided']
is_non_pathogenicity = any(term in classification for term in non_pathogenicity_terms)

if is_non_pathogenicity:
    result['details'] = (
        f"ClinVar classification '{classification}' is not a pathogenicity assessment. "
        f"This is a {classification} annotation and does not apply to PP5/BP6 criteria."
    )
    result['data_source'] = 'clinvar_non_pathogenicity'
    return result  # Early return prevents false PP5/BP6

Result:

• ✅ MTHFR c.665C>T: Correctly identified as "drug response" (not benign)
• ✅ PP5 (Pathogenic): Does NOT apply ✓
• ✅ BP6 (Benign): Does NOT apply ✓
• ✅ Clear message: "not a pathogenicity assessment"

🔄 Modified Files

src/utils/api_client.py:

• Lines 236-327: Enhanced get_chromosome_from_ensembl() with MyGene.info fallback
• Lines 530-629: Enhanced get_gene_info() with MyGene.info fallback
• Added genomic_pos parsing for both single dict and list formats

src/core/evidence_evaluator.py:

• Lines 1813-1825: PP5 non-pathogenicity filter (before pathogenic check)
• Lines 2650-2662: BP6 non-pathogenicity filter (before benign check)
• New data source: clinvar_non_pathogenicity

🧪 Testing & Validation

Gene Lookup Tests:

# APOE (previously failing)
client.get_chromosome_from_ensembl('APOE')  # ✅ Returns '19'

# BRCA1 (always working)
client.get_chromosome_from_ensembl('BRCA1')  # ✅ Returns '17'

# MTHFR (test gene)
client.get_chromosome_from_ensembl('MTHFR')  # ✅ Returns '1'

ClinVar Classification Tests:

# MTHFR drug response
clinvar_result = client.get_clinvar_classification(
    variant_id='VCV000003520'
)
# ✅ classification: 'drug response'
# ✅ PP5 applies: False
# ✅ BP6 applies: False
# ✅ Message: "not a pathogenicity assessment"

ACMG Variant Classification Assistant

ACMG Assistant v3.4.0 Release Notes

Version 3.4.0 implements a configuration-based dual guidelines system supporting both ACMG/AMP 2015 and 2023 standards. This architecture allows users to select between guideline versions while maintaining backward compatibility with existing workflows.

---

Technical Changes

ACMG 2023 Guidelines Implementation

The following criteria have been updated to reflect ClinGen Sequence Variant Interpretation (SVI) Working Group 2023 recommendations:

PS4 - Case-Control Evidence

ACMG 2015 Requirements:

• Odds Ratio (OR) ≥ 2.0
• Minimum 5 affected probands
• Minimum 1,000 controls
• Statistical significance (p < 0.05)

ACMG 2023 Requirements:

• Odds Ratio (OR) ≥ 5.0
• Minimum 10 affected probands
• Minimum 2,000 controls
• Statistical significance (p < 0.05)

Rationale: Increased thresholds reduce false positive classifications from underpowered studies.

PP1 - Segregation Analysis

ACMG 2015:

• LOD score ≥ 3.0 applies PP1 at Moderate strength

ACMG 2023:

• LOD score 1.5-2.99: PP1_Supporting
• LOD score 3.0-4.99: PP1_Moderate
• LOD score ≥ 5.0: PP1_Strong

Rationale: Tiered strength assignment reflects statistical confidence levels in segregation data.

PS2 - De Novo Evidence

ACMG 2015:

• Confirmed de novo (maternity and paternity tested): PS2 (Strong)

ACMG 2023:

• Confirmed de novo (both parents tested): PS2_Very_Strong

Rationale: High confidence in de novo status when both parents are tested justifies strength upgrade.

PP5 - Reputable Source

ACMG 2023 Only:

• Available when --acmg-2023 flag is used
• Applies when variant reported as pathogenic by reputable sources without detailed evidence available for independent review

---

Architecture

Architecture

Configuration System

Threshold values for both guideline versions are stored in separate configuration dictionaries:

# config/constants.py
STATISTICAL_THRESHOLDS_2015 = {
    'case_control_odds_ratio': 2.0,
    'case_control_min_cases': 5,
    'case_control_min_controls': 1000,
    'segregation_lod_score': 3.0,
    'pm5_min_pathogenic_variants': 1
}

STATISTICAL_THRESHOLDS_2023 = {
    'case_control_odds_ratio': 5.0,
    'case_control_min_cases': 10,
    'case_control_min_controls': 2000,
    'segregation_lod_supporting': 1.5,
    'segregation_lod_moderate': 3.0,
    'segregation_lod_strong': 5.0,
    'pm5_min_pathogenic_variants': 2
}

# Default: ACMG 2015
STATISTICAL_THRESHOLDS = STATISTICAL_THRESHOLDS_2015

Evidence Evaluator

The EvidenceEvaluator class accepts a use_2023_guidelines boolean parameter that controls threshold selection:

# Version-aware initialization
evaluator = EvidenceEvaluator(use_2023_guidelines=False)  # ACMG 2015
evaluator = EvidenceEvaluator(use_2023_guidelines=True)   # ACMG 2023

Criteria evaluation methods dynamically select appropriate thresholds:

• _evaluate_ps4(): Selects OR and sample size thresholds based on version
• _evaluate_pp1(): Applies tiered strength modifiers in 2023 mode
• _evaluate_ps2(): Upgrades to Very Strong when applicable in 2023 mode
• _evaluate_pp5(): Only evaluates in 2023 mode

---

Bug Fixes

Classification Rules

Issue: Benign classification incorrectly applied with BS1 + 1 BP
Fix: Corrected classification rules to require BS1 + ≥2 BP for Benign classification
Impact: BS1 + BP4 now correctly classified as Likely Benign per ACMG 2015 standards

PP2 Criterion

Issue: Automatic application caused false positives in genes with low benign missense rates
Fix: Converted to interactive mode requiring user confirmation
Implementation:

• Test mode: Returns manual review flag with guidance
• Interactive mode: Prompts user with context-specific warnings
• Added frequency filter: Variants with gnomAD AF > 0.001 excluded

Test Expectations

Issue: Test cases expected "Likely Pathogenic" for variants meeting Pathogenic criteria
Fix: Aligned test expectations with ACMG Rule (iii): 1 Strong + ≥3 Moderate = Pathogenic
Example: PS1 + PM1 + PM2 + PM5 now correctly expected to classify as Pathogenic

---

Validation

Test Coverage

Test Suite	Tests	Pass Rate	Status
ACMG 2015 Comprehensive	30	100%	Validated
ACMG 2023 Mode	3	100%	Validated
Total	33	100%	Complete

ACMG 2023 Test Scenarios

1. PS4 with high OR (6.5): Both 2015 and 2023 modes correctly apply PS4
2. PS4 with low OR (3.5): 2015 applies PS4, 2023 correctly rejects insufficient evidence
3. PP1 with LOD=5.5: 2015 applies at Moderate strength, 2023 upgrades to Strong

---

Changelog Summary

Added

• PP1 LOD-based strength modifiers (Supporting/Moderate/Strong)
• PS4 enhanced validation (OR≥5.0, sample size requirements)
• PS2 Very Strong upgrade capability
• PP5 criterion (ACMG 2023 only)
• Test suite for ACMG 2023 mode validation

Changed

• Evidence evaluator accepts use_2023_guidelines parameter
• PS4/PP1 criteria use version-specific thresholds
• Classification engine reports guidelines version in metadata

Fixed

• Benign classification rule (BS1 + ≥2 BP required)
• PP2 false positive rate (interactive mode implementation)
• Test case expectations aligned with ACMG standards

Removed

• Temporary diagnostic output files
• Obsolete documentation files

---

Known Limitations

1. PM5 threshold: Currently requires ≥1 pathogenic variant at same residue in 2015 mode, ≥2 in 2023 mode. Full implementation of PM5 2023 updates pending.

2. PVS1 pLI integration: Gene constraint scores (pLI) not yet integrated into PVS1 evaluation for 2023 mode.

3. PP4 phenotype specificity: Quantitative phenotype specificity scoring not yet implemented for 2023 mode.

---

ACMG Variant Classification Assistant

Release Notes - Version 3.3.0

Release Date: October 2025

---

🎯 What's New

New Features

1. Confidence & Provenance Tracking

Every ACMG criterion now reports:

• Confidence Level: high | medium | low | very_low
• Data Source: Evidence origin (e.g., parental_testing, expert_panel, case_control_study)

2. Statistical Automation

PS4 - Automated Fisher's Exact Test:

• Automatically calculates when case-control data provided
• Applies PS4 when: p-value < 0.05 AND odds ratio ≥ 2.0
• Reports statistical significance and sample adequacy

PP1/BS4 - Automated LOD Scoring:

• Auto-calculates LOD scores from family segregation data
• PP1 applies when LOD ≥ 1.5 (Supporting) or ≥ 3.0 (Moderate/Strong)
• BS4 applies when LOD ≤ -1.5 (non-segregation)
• Requires minimum 3 families for validity

3. Stricter Validation Rules

PS2 2023 Upgrade (Breaking Change):

• Previous: De novo confirmed → Automatic Very Strong
• Now: Requires BOTH maternity AND paternity confirmed
• Downgrade: Single parent or assumed → PM6 Moderate

PP5/BP6 Source Requirements (Breaking Change):

• Previous: Any ClinVar entry accepted
• Now: Requires expert panel OR ≥2★ ClinVar
• Rejected: Single submitter (1★) or no assertion (0★)
• Age Limit: Classifications must be ≤5 years old

---

🆕 New Modules

Core Enhancements

• statistical_utils.py - Fisher's exact test, LOD calculation, sample size assessment
• functional_studies_evaluator.py - PS3/BS3 dedicated evaluation
• gene_rules_engine.py - Gene-specific rule management
• gene_specific_rules.py - BRCA1/2, TTN, MUC16, OBSCN thresholds
• missense_evaluator.py - PS1/PM5/PP2/BP1 missense analysis
• phenotype_matcher.py - PP4/BP5 phenotype correlation
• population_analyzer.py - BA1/BS1/PM2/BS2 frequency analysis

---

⚠️ Changes

1. PS2 Very Strong Requirements

Impact: Some de novo variants may downgrade from PS2 Very Strong → PM6 Moderate

Migration:

# Old (v3.2.0)
genetic_data = {'de_novo': 'confirmed'}  # → PS2 Very Strong

# New (v3.3.0)
genetic_data = {
    'de_novo': 'confirmed',
    'maternity_confirmed': True,  # Both required!
    'paternity_confirmed': True
}  # → PS2 Very Strong

2. PP5/BP6 Source Validation

Impact: Single-submitter ClinVar entries no longer apply PP5/BP6

Requirements:

• ✅ Expert panel classification (ClinGen, etc.)
• ✅ ClinVar ≥2★ ("multiple submitters" or higher)
• ✅ Classification within 5 years
• ❌ Single submitter (1★)
• ❌ No assertion criteria (0★)

---

🔧 Changes

Updated Criteria Evaluations

Criterion	Enhancement	Confidence Levels
PS2	Strict 2023 upgrade, both parents required	high
PS4	Automated Fisher's exact test	high / medium
PM2	Added confidence tracking	high
PM6	Clear separation from PS2	low / medium
PP1	Automated LOD scoring	medium / high
PP5	Stricter source validation	high / medium / low
BS4	Automated LOD scoring	medium / high
BP6	Stricter source validation	high / medium / low

---

3. Review ClinVar Classifications:

• Verify expert panel status
• Check review status (≥2★ required)
• Confirm classification age (<5 years)

---

🐛 Bug Fixes

• Fixed PS2/PM6 confusion in de novo variant handling
• Improved PM2 confidence assessment
• Enhanced error handling in statistical functions

---

Classification Behavior:

• Some PS2 Very Strong → PM6 Moderate (single parent confirmation)
• Some PP5/BP6 no longer apply (1★ ClinVar entries)
• PS4 requires statistical significance (p-value < 0.05)
• All criteria report confidence levels and data sources

Methodology Changes:

Criterion	Previous	Current
PS2	De novo assumed sufficient	Both parents required for Very Strong
PS4	User judgment	Fisher's exact test (p-value)
PP1/BS4	Qualitative assessment	LOD score calculation
PP5/BP6	Any ClinVar entry	Expert panel or ≥2★ required

---

📦 Installation

New Installation:

# Download from Google Drive
https://drive.google.com/file/d/16azUiNQtNrkwnyK_DpQ7yGkJmAL1GbRn/view?usp=sharing

# Or clone from GitHub
git clone https://github.com/Bilmem2/ACMG_Assistant.git
cd ACMG_Assistant
pip install -r requirements.txt
cd src
python acmg_assistant.py

---

• New Dependency: scipy required for statistical functions

---

Download: Google Drive - v3.3.0
Repository: GitHub Releases

ACMG Variant Classification Assistant

Release Notes - Version 3.2.0

Release Date: July 18, 2025

Major New Features

• Interactive Mode Selection:
  • Initial welcome page now includes a clear and interactive mode selection screen.
  • User can select ACMG/AMP 2015, ACMG/AMP 2023, or Batch Mode interactively.
  • Invalid mode selections are handled gracefully; user is prompted until a valid choice is made.
• Batch Mode:
  • New feature: Analyze multiple variants automatically from a CSV file.
  • No manual input required for each variant; all data is read from the file.
  • CSV file path is validated interactively; user is guided if file is not found.
• User Experience Improvements:
  • Mode-specific feedback and guidance for each selection.
  • Clear error messages and instructions for batch file usage.
• Test Mode Handling:
  • Test Mode is hidden and blocked in executable version; only available via terminal.
• Version updated to 3.2.0.

Improvements

• Interactive mode selection logic refactored for clarity and robustness.
• User-friendly error handling for batch file path and mode selection.
• Clear instructions and guidance for batch mode usage and CSV format.
• Enhanced feedback and guidance for users in interactive CLI.

Bug Fixes

• Invalid mode selection no longer starts default mode automatically; user must select a valid mode.
• Batch mode does not activate if the CSV file does not exist; user is prompted to provide a valid path.
• Repeated disclaimer/important note messages removed; now only shown on initial welcome.

Documentation

• Added BATCH_MODE_GUIDE.md for batch mode usage and CSV format instructions.

---

This release marks a major step forward in usability and batch mode automation for ACMG Assistant.

ACMG Variant Classification Assistant

ACMG Variant Classification Assistant v3.1.0

Summary

Version 3.1.0 addresses critical stability issues and enhances user experience with improved input validation, API integration, and error handling. All 28 ACMG/AMP evidence criteria remain fully implemented with enhanced reliability.

Critical Bug Fixes

• Gene symbol validation: Fixed KeyError for gene symbol input validation pattern
• Ensembl API integration: Added missing REST API endpoint for chromosome lookup
• Color output consistency: Unified color codes across all modules using COLORAMA_COLORS
• Import optimization: Removed unused colorama dependencies and cleaned up imports

Enhanced Functionality

• Improved gene input: Normal mode now properly accepts gene symbols (MAPT, BRCA1, etc.)
• Automatic chromosome detection: Enhanced Ensembl integration for chromosome lookup
• Better error handling: More robust input validation with user-friendly error messages
• Streamlined constants: All required constants properly defined and accessible

System Stability

• API endpoints: Complete configuration for ClinVar, gnomAD, Varsome, and Ensembl
• Report generation: Consistent and error-free output

Technical Improvements

• Module imports: Resolved all import dependencies and circular references
• Validation patterns: Added gene_symbol alias for compatibility
• Code consistency: Eliminated legacy Fore/Style usage throughout codebase
• Error reporting: Enhanced debugging and user feedback systems

Tested Components

Core Features Verified

• Gene input validation (BRCA1, BRCA2, MAPT, TP53)
• Test mode with BRCA1 c.1066C>T (p.Gln356Ter) variant
• Interactive normal mode for all required fields
• All 28 ACMG/AMP criteria evaluation
• Report generation with Varsome URLs
• API connectivity (ClinVar, gnomAD, Ensembl)

Quality Assurance

• Import testing across all modules
• Input validation for genes, chromosomes, positions
• Color output consistency verification
• Error handling for invalid inputs and API failures

Implementation Status

Pathogenic Evidence Criteria (16/16)
PVS1, PS1, PS2, PS3, PS4, PM1, PM2, PM3, PM4, PM5, PM6, PP1, PP2, PP3, PP4, PP5

Benign Evidence Criteria (12/12)
BA1, BS1, BS2, BS3, BS4, BP1, BP2, BP3, BP4, BP5, BP6, BP7

System Requirements

• Python 3.8 or higher
• Dependencies: scipy, requests, colorama
• Cross-platform support (Windows, macOS, Linux)
• Minimum 512MB RAM, 50MB storage

Usage

# Test mode
python src/acmg_assistant.py --test

# Normal mode
python src/acmg_assistant.py

# ACMG 2023 guidelines
python src/acmg_assistant.py --acmg-2023

# Version info
python src/acmg_assistant.py --version

ACMG Variant Classification Assistant

ACMG Variant Classification Assistant v3.0.0

Release Date: July 9, 2025

Summary

Version 3.0.0 completes the implementation of all 28 ACMG/AMP evidence criteria as specified in the 2015 and 2023 guidelines.

Implementation Status

Pathogenic Evidence Criteria (16/16)

• PVS1: Null variants in loss-of-function intolerant genes
• PS1: Same amino acid change as established pathogenic variant
• PS2: De novo occurrence in patient with disorder and no family history
• PS3: Well-established in vitro or in vivo functional studies
• PS4: Case-control studies showing increased prevalence in affected individuals
• PM1: Located in mutational hot spot or critical functional domain
• PM2: Absent from controls or at extremely low frequency
• PM3: For recessive disorders, detected in trans with pathogenic variant
• PM4: Protein length changes as result of in-frame deletions/insertions
• PM5: Novel missense change at amino acid residue where different missense change is pathogenic
• PM6: Assumed de novo, but without confirmation of paternity and maternity
• PP1: Cosegregation with disease in multiple affected family members
• PP2: Missense variant in gene that has low rate of benign missense variation
• PP3: Multiple lines of computational evidence support deleterious effect
• PP4: Patient's phenotype or family history highly specific for gene
• PP5: Reputable source recently reports variant as pathogenic

Benign Evidence Criteria (12/12)

• BA1: Allele frequency >5% in population databases
• BS1: Allele frequency greater than expected for disorder
• BS2: Observed in healthy adult individual for recessive disorder
• BS3: Well-established in vitro or in vivo functional studies show no effect
• BS4: Lack of segregation in affected members of family
• BP1: Missense variant in gene for which primarily truncating variants cause disease
• BP2: Observed in trans with pathogenic variant for fully penetrant dominant gene
• BP3: In-frame deletions/insertions in repetitive region without known function
• BP4: Multiple lines of computational evidence suggest no impact
• BP5: Variant found in case with alternate molecular basis for disease
• BP6: Reputable source recently reports variant as benign
• BP7: Synonymous variant for which splicing prediction algorithms predict no impact

Technical Changes

Evidence Evaluation System

• Centralized evaluation logic in EvidenceEvaluator class
• Interactive user input for criteria requiring literature review (PS1, PS4, PM3, PM5, PP4, BP2, BP5, BP6)
• Automated assessment for data-driven criteria (population frequencies, computational predictions)
• Test mode support for non-interactive validation

Computational Framework

• Enhanced metascore calculation using multiple prediction algorithms
• Population frequency analysis with gene-specific thresholds
• SpliceAI integration for splice impact assessment
• Conservation score analysis across multiple species

Code Structure

• Modular architecture with separate modules for each functional area
• Comprehensive input validation and error handling
• Enhanced reporting system with detailed evidence breakdown
• Test suite covering all implemented criteria

References

Implementation follows ACMG/AMP variant interpretation guidelines:

• Richards et al. (2015) Genetics in Medicine 17:405-424
• ClinGen SVI working group updates (2023)

ACMG Variant Classification Assistant

ACMG Variant Classification Assistant v2.2.0

What's New

Metascore Threshold Optimization

Updated computational evidence thresholds based on real-world clinical validation:

PP3 Thresholds (Supporting Pathogenic Evidence)

• Ultra-rare variants (AF ≤ 1e-5): 0.45 → 0.35
• Very rare variants (AF ≤ 1e-4): 0.55 → 0.45
• Moderate rare (1e-4 < AF ≤ 1e-3): 0.65 → 0.55
• Common variants (AF > 1e-3): 0.75 → 0.70

BP4 Thresholds (Supporting Benign Evidence)

• Ultra-rare: 0.55 → 0.60
• Very rare: 0.45 → 0.50
• Moderate rare: 0.35 → 0.40
• Common: 0.25 → 0.30

Key Improvements

1. Better detection of borderline pathogenic variants
2. Reduced false negatives for ultra-rare variants
3. More appropriate evidence application for real clinical scenarios
4. Enhanced conflict detection between pathogenic and benign computational evidence

Technical Changes

• Frequency-stratified threshold selection
• Improved VAMPP-score calculation for 14+ predictors
• Updated evidence evaluation logic
• Better handling of inconclusive functional studies

---

This version provides more accurate variant classification, particularly for borderline and ultra-rare variants commonly encountered in clinical practice.

ACMG Variant Classification Assistant

🧬 ACMG Assistant v2.1

What's New in v2.1

🔧 Major Bug Fixes

• Fixed Executable Report Generation: Resolved issue where standalone executable wasn't generating classification reports
• Enhanced Working Directory Handling: Improved file path management for executable compatibility
• Corrected Ensembl API Integration: Fixed chromosome fetching from gene symbols (API endpoint naming issue)

📊 Expanded Predictor Support

• Added Missing Conservation Predictors: phastCons (vertebrates/mammals/primates), SiPhy phylogenetic analysis
• New Functional Predictors: FITCONS, MutationAssessor, MutPred, LRT (Likelihood Ratio Test)
• Enhanced Ensemble Methods: MetaSVM, MetaLR integration with proper weighting
• Comprehensive Coverage: Now supports 26+ individual predictors as documented in README

🎯 Algorithm Improvements

• Enhanced VAMPP-Score Calculation: Improved metascore computation with all documented predictors
• Better Conservation Analysis: Multi-species phylogenetic conservation scoring with phastCons/PhyloP
• Robust Input Validation: Added _validate_numeric_range for predictor score validation
• Improved Error Handling: Better graceful failure management for missing data

🛠️ Technical Enhancements

• Absolute Path Report Generation: Reports now save with full paths for better executable compatibility
• Enhanced Constants Management: All predictor thresholds and weights properly defined
• Improved Debug Output: Better error tracking and troubleshooting capabilities
• Code Cleanup: Removed outdated test files and duplicate structures

📈 Performance & Reliability

• 100% Test Coverage: All 12 comprehensive test scenarios passing
• Robust Classification Logic: Verified accuracy for pathogenic, benign, and VUS classifications
• Enhanced API Integration: Improved ClinVar and Ensembl connectivity with better error handling
• Memory Optimization: Cleaner code structure with reduced redundancy

### 🐛 **Known Issues**
- Test mode is only available in Python version, not in standalone executable
- Large batch processing not yet implemented
- Some rare edge cases in splice prediction may require manual review

### 📚 **Documentation**
- [Main README](https://github.com/Bilmem2/acmg-assessor/blob/main/README.md)
- [Installation Guide](https://github.com/Bilmem2/acmg-assessor#installation--usage)
- [Predictor Documentation](https://github.com/Bilmem2/acmg-assessor#in-silico-predictors)
- [Citation Information](https://github.com/Bilmem2/acmg-assessor#citation--references)

---

**Full Changelog**: [v2.0.0...v2.1.0](https://github.com/Bilmem2/acmg-assessor/compare/v2.0.0...v2.1.0)

**Previous Release**: [v2.0.0](https://github.com/Bilmem2/acmg-assessor/releases/tag/v2.0.0)