Gene-Variant-Analyzer

Gene-Variant-Analyzer is a Python-based bioinformatics tool that retrieves clinically annotated genetic variants associated with any human gene using the Ensembl REST API. The program supports reproducible random sampling, summarizes variant annotations, and generates publication-quality visualizations for exploratory variant analysis.

---

Features

• Retrieve genetic variants for any human gene available using the Ensembl REST API.
• Filter variants to include only clinically classified annotations.
• Analyze all clinically classified variants or a reproducible random sample.
• Generate reproducible random samples using a user-defined seed.
• Summarize clinical significance classifications.
• Summarize consequence types.
• Generate three publication-quality visualizations:
  • Clinical Significance Bar Chart
  • Consequence Type Bar Chart
  • Clinical Significance × Consequence Type Bubble Matrix
• Automatically organize all output files into descriptive analysis directories.

---

Requirements

This project was developed and tested using Python 3.12.3.

Requirements:

• Python 3.12 or newer
• Internet connection (required for Ensembl REST API access)

Required Python packages:

• requests
• matplotlib

---

Installation

Clone the repository:

git clone https://github.com/savannastuart/Gene-Variant-Analyzer.git

Move into the project directory:

cd Gene-Variant-Analyzer

Install the required packages:

pip install -r requirements.txt

---

Usage

Analyze all clinically classified variants for BRCA1:

python GeneVariantAnalyzer.py BRCA1

Analyze a reproducible random sample of 100 clinically classified variants using seed 42:

python GeneVariantAnalyzer.py BRCA1 -n 100 -s 42

Command-Line Arguments

Argument	Description
gene	Human gene symbol (required)
-n, --sample-size	Number of clinically classified variants to analyze (optional)
-s, --seed	Random seed used for reproducible sampling (optional, default = 42)

If no sample size is provided, the program analyzes all clinically classified variants for the selected gene.

---

Output

Each analysis creates a new directory using the format:

GENE_n<sample size>_s<seed>

or

GENE_n<variant count>_all

Example:

BRCA1_n100_s42/

Each analysis directory contains:

BRCA1_n100_s42_Variants.json
BRCA1_n100_s42_Summary.json
BRCA1_n100_s42_ClinSig_Bar.png
BRCA1_n100_s42_Consequence_Bar.png
BRCA1_n100_s42_ClinCon_Matrix.png

Output Files

File	Description
Variants.json	Selected Ensembl variant records used in the analysis.
Summary.json	Metadata and analysis summary, including category counts.
ClinSig_Bar.png	Clinical significance bar chart.
Consequence_Bar.png	Consequence type bar chart.
ClinCon_Matrix.png	Bubble matrix comparing clinical significance and consequence type.

---

Example Output

A complete example analysis is included in:

example_output/
└── BRCA1_n100_s42/

This folder contains a reproducible random sample of 100 clinically classified BRCA1 variants (seed = 42), along with the generated summary and visualizations.

---

Generated Figures

Clinical Significance Bar Chart

Displays the frequency of each clinical significance classification reported by Ensembl.

Consequence Type Bar Chart

Displays the frequency of each consequence type observed in the analyzed variants.

Clinical Significance × Consequence Type Bubble Matrix

Displays the relationship between clinical significance and consequence type. Bubble size and color correspond to the number of variants within each category combination.

---

Interpretation Notes

Clinical Significance Counts

Clinical significance classifications are reported directly from Ensembl variant annotations.

Some variants contain multiple clinical significance classifications (for example, a variant may be annotated as both Pathogenic and Uncertain Significance). When this occurs, each classification is counted separately.

As a result:

• The sum of all clinical significance counts may be greater than the total number of analyzed variants.
• This behavior preserves all clinical annotations reported by Ensembl rather than assigning each variant to only one classification.

Consequence Type Counts

Each analyzed variant contributes one consequence type to the consequence summary and bubble matrix.

Consequently, the total consequence type counts equal the number of analyzed variants.

---

Data Source

Variant annotations are retrieved from the Ensembl REST API.

Ensembl Homepage:

https://www.ensembl.org/

Ensembl REST API Documentation:

https://rest.ensembl.org/

If this software is used in research, please cite Ensembl according to their recommended citation guidelines.

---

Project Motivation

Gene-Variant-Analyzer was developed as a reusable bioinformatics workflow for exploring clinically annotated human genetic variants through programmatic access to the Ensembl REST API.

The project emphasizes reproducible analyses, clear data visualization, and flexible command-line usage while remaining applicable to any human gene supported by Ensembl.

---

Future Improvements

Potential future enhancements include:

• Support for additional Ensembl species.
• Export summary tables as CSV.
• Optional filtering by clinical significance.
• Optional filtering by consequence type.
• Additional visualization types.
• Interactive visualizations.
• Support for additional public variant databases.

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

Author

Savanna Stuart

GitHub: https://github.com/savannastuart