DNA Analysis

Analyzes AncestryDNA raw data and produces markdown reports using genotype interpretations from SNPedia and NCBI. Runs locally; your DNA files stay on your machine except for lookups to SNPedia and NCBI (and optional LLM if you use deep_analyze --llm).

Requirements

• Python 3.9+
• requests (pip install -r requirements.txt)

Setup

git clone https://github.com/jcm098/myDNA.git
cd myDNA
pip install -r requirements.txt

Try it without your data

You can run the tool on the included sample data (no real DNA) to see how it works:

python analyze.py --data-dir tests/sample_data --output reports/sample_report.md --limit 5

Then open reports/sample_report.md. For a fuller run on the same sample: python analyze.py --data-dir tests/sample_data --all --max-snps 10.

Data

Place one or more AncestryDNA raw data exports in the data/ folder:

• Format: Tab-delimited .txt (rsid, chromosome, position, allele1, allele2)
• Source: Ancestry.com → DNA → Settings → Download Raw DNA Data
• Privacy: Files in data/*.txt are gitignored and never committed

When multiple files are present, the one with the most SNPs is treated as the current (newest) export.

Usage

Quick: notable SNPs only (default)

Looks up a curated list of ~20 well-known SNPs (e.g. lactose tolerance, ApoE, MTHFR). Fast; includes NCBI metadata.

python analyze.py                    # default: 25 SNPs
python analyze.py --limit 15          # fewer SNPs

Full: all SNPs in your file

Batch lookups for every SNP; report lists only those with a SNPedia interpretation for your genotype. Can take hours for large files (rate-limited).

python analyze.py --all

Output defaults to reports/report_YYYYMMDD_HHMMSS.md unless you set -o.

New SNPs only (after a newer export)

Process only SNPs that appear in your newer file but not in an older baseline. Use after downloading a new Ancestry export.

python analyze.py --all --baseline data/older_export.txt

Options

Option	Description
--all	Process all SNPs (batch mode); report only those with SNPedia interpretations
--baseline FILE	Compare to older export; process only new SNPs (use with --all)
--data-dir DIR	Directory containing .txt exports (default: data/)
--output, -o FILE	Report path (default: reports/report_YYYYMMDD_HHMMSS.md)
--limit N	Max notable SNPs when not using --all (default: 25)
--max-snps N	When using --all, process only first N SNPs (e.g. for testing)

Reports

• Default path: reports/report_YYYYMMDD_HHMMSS.md (timestamped when no -o is given)
• Custom path: python analyze.py -o reports/my_report.md
• The reports/ directory is created automatically. Its contents are gitignored.

Deeper analysis (secondary pass)

Run a secondary analysis on an existing report: rule-based summary (by topic, risk/drug mentions) and optional LLM-powered narrative summary.

# Rule-based only (no API key needed)
python deep_analyze.py reports/report_20250214_120000.md

# With LLM summary (pip install openai; use --api-key or env var)
python deep_analyze.py reports/report_20250214_120000.md --llm openai   # OpenAI (OPENAI_API_KEY)
python deep_analyze.py reports/report_20250214_120000.md --llm xai     # xAI/Grok (XAI_API_KEY)
python deep_analyze.py report.md --llm xai --api-key YOUR_XAI_KEY

# Custom output path
python deep_analyze.py report.md -o reports/report_deep.md

Output is written to <report_stem>_deep.md by default (or -o path). It includes the original report plus:

• Deeper analysis (rule-based): Summary stats, SNPs grouped by topic (curated list), interpretations mentioning risk/association, drug/treatment relevance.
• Deeper analysis (LLM summary): Short narrative summary (if --llm openai or --llm xai with --api-key or OPENAI_API_KEY / XAI_API_KEY). Uses GPT-4o-mini (OpenAI) or Grok-3-mini (xAI); prompt asks for 3–5 themes and a reminder that the report is not medical advice.

Online sources

• SNPedia (https://snpedia.com): Genotype interpretations via MediaWiki API at bots.snpedia.com. Requests are rate-limited (~1.5 s between batch lookups).
• NCBI Clinical Tables SNP API: dbSNP metadata (used in notable-SNP mode only).

Using public services

When you run analysis, the tool sends requests to third-party services. Be aware of the following:

Concern	Details
What is sent	SNPedia & NCBI: Only the rsids (e.g. rs12913832) you look up—i.e. which SNPs are in your file or in the notable list. No raw sequence; the APIs return public reference information. LLM (optional): If you use --llm openai or --llm xai, the report text (SNP ids, genotypes, interpretations) is sent to that provider to generate a summary.
Terms of use	Each service has its own terms. SNPedia and NCBI are commonly used for research and personal use; check their sites if you use the tool at scale or commercially. LLM providers (OpenAI, xAI) have API ToS and privacy policies—review them before sending report content.
Rate limits	The tool throttles SNPedia requests (~1.5 s between batches). Heavy or automated use could still hit limits or get blocked; use responsibly. NCBI and LLM providers have their own limits.
Availability	These are public APIs; we do not control their uptime, rate limits, or policy changes. The tool may fail if a service is down or changes.

For maximum privacy, use only the local rule-based flow (no --llm) and be aware that SNPedia/NCBI still receive the rsids you query.

Note for users: This project is not affiliated with, endorsed by, or operated by SNPedia or NCBI. Requests from this tool identify the project (via User-Agent) so the services can reach the maintainer if needed. If many people use the tool, heavy traffic could lead to rate-limiting or blocking that affects everyone; please use responsibly and in line with each service’s terms of use. You are responsible for your own use of those services.

Testing

The project uses test-driven development: a pytest suite runs on sample data (no real DNA files or network required for unit tests). Run tests whenever you change code, and add tests for new functions.

pip install -r requirements-dev.txt   # installs pytest
pytest                               # run all tests (from project root)
pytest tests/ -v                     # verbose
pytest tests/test_dna_loader.py       # run one module

• Sample data: tests/sample_data/ contains minimal Ancestry-format .txt files used by tests (e.g. sample_small.txt, sample_baseline.txt, sample_current.txt).
• No network: Parsing and report-building tests use mocks or fixture wiki text; only integration tests that you opt into would call SNPedia/NCBI.
• When adding features: Add or extend tests in tests/test_*.py (and new sample data in tests/sample_data/ if needed), then run pytest before committing.

Project layout

myDNA/
├── analyze.py         # Entry point; CLI and report generation
├── deep_analyze.py    # Secondary analysis on a report (rule-based + optional LLM)
├── report_parser.py   # Parse report markdown for deep_analyze
├── dna_loader.py      # Parse AncestryDNA .txt files
├── notable_snps.py    # Curated SNP list and descriptions
├── snp_sources.py     # SNPedia + NCBI fetch and parsing
├── data/              # Put Ancestry .txt exports here (gitignored)
├── reports/           # Generated reports (gitignored)
├── tests/             # Pytest suite
│   ├── sample_data/   # Minimal .txt fixtures for tests
│   ├── conftest.py    # Fixtures and shared test data
│   ├── test_dna_loader.py
│   ├── test_notable_snps.py
│   ├── test_snp_sources.py
│   ├── test_report_parser.py
│   ├── test_deep_analyze.py
│   └── test_analyze.py
├── requirements.txt
├── requirements-dev.txt   # pytest, etc.
├── pytest.ini
├── LICENSE
├── .env.example           # optional env vars for LLM (OPENAI_API_KEY, XAI_API_KEY)
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md

Troubleshooting

Issue	What to check
No .txt files in data directory	Put your AncestryDNA export(s) in data/. Filenames must end in .txt.
Report is empty or very short	In default mode only notable SNPs are listed; use --all to scan all SNPs. SNPedia may not have a page or genotype interpretation for every SNP.
Rate limited / slow	SNPedia requests are throttled (~1.5 s between batches). Use --limit for a quick run or --max-snps when testing with --all.
Wrong format	File must be tab-delimited: rsid, chromosome, position, allele1, allele2. Download "Raw DNA Data" from Ancestry, not the ZIP summary.

License

MIT. This project follows the Contributor Covenant Code of Conduct.

Disclaimer

This tool is for genealogical and educational use only. It is not intended for medical, diagnostic, or health purposes. SNP interpretations are from SNPedia and NCBI and may be incomplete or outdated. Consult a healthcare provider for any health-related decisions.