docs

PANICLE Documentation

Welcome to the PANICLE documentation! This guide will help you perform genome-wide association studies (GWAS) with PANICLE.

Documentation Index

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
  • Basic GWAS workflow
  • Common analysis scenarios
  • Troubleshooting tips

Reference Documentation

• API Reference - Complete API documentation

  • GWASPipeline class methods
  • Association testing functions
  • Data loaders and utilities

• Output Files - Understanding your results

  • File formats and column descriptions
  • How to read and analyze results
  • Working with output in Python/R

Tutorials & Examples

• GWAS Tutorial notebook - Interactive Jupyter notebook on bundled demo data

  • Complete GWAS workflow with real sorghum data (725 samples, 170K markers)
  • Demonstrates GLM, MLM, FarmCPU, and BLINK methods
  • Visualizations and result interpretation

• Multi-Trait eQTL Acceleration Tutorial - Interactive Jupyter notebook

  • Demonstrates eQTL-style many-traits LOCO MLM workflow
  • Shows chromosome-major acceleration (PANICLE_MLM_LOCO_MULTI)
  • Includes writing top QTL hits to CSV output

• Example Scripts - Runnable Python scripts

  • 01: Basic GWAS with GLM
  • 02: MLM with population structure
  • 04: Including covariates (flowering time example)
  • 05: Reading and analyzing results
  • 06: FarmCPU resampling with RMIP output

Quick Links

Installation

git clone https://github.com/jschnable/PANICLE.git
cd PANICLE
pip install -e .

Minimal Example

from panicle import PANICLE

results = PANICLE(
    phe='phenos.csv',
    geno='genos.vcf.gz',
    map_data='markers.map.csv',   # optional for VCF/BCF; extracted automatically when embedded
    n_pcs=3,                      # compute 3 genotype PCs internally
    method=['MLM'],
    output_prefix='results/GWAS',
)

Use GWASPipeline when you want a stepwise workflow with explicit load_data(), align_samples(), and compute_population_structure(). Use PANICLE() when you want the high-level one-call API and still want internal PCA via n_pcs.

CLI Quick Start

panicle-gwas \
  --phenotype examples/example_phenotypes.csv \
  --genotype examples/example_genotypes.vcf.gz \
  --traits PlantHeight \
  --methods GLM \
  --outputdir ./results

(python -m panicle ... and python scripts/run_GWAS.py ... are equivalent.)

Workflow Overview

1. Initialize Pipeline
   ↓
2. Load Data (phenotypes, genotypes, optional covariates)
   ↓
3. Align Samples (match individuals across datasets)
   ↓
4. Compute Population Structure (PCs and optional kinship)
   ↓
5. Run Analysis (choose methods: GLM, MLM, BAYESLOCO, FarmCPU, BLINK, FarmCPUResampling)
   ↓
6. Results saved to output directory

For the high-level PANICLE() API, steps 2-5 are handled inside the function. Set n_pcs > 0 to compute genotype PCs internally and append them to any external covariates passed through CV.

Available Methods

Method	Speed	Population Control	Best For
GLM	Very Fast	PCs (optional)	Quick screening, homogeneous populations
MLM	Moderate	LOCO (if map) or Kinship + PCs	Diverse populations, related individuals
BAYESLOCO	Moderate	Chromosome-aware Bayesian model + PCs	Sparse signals and chromosome-aware shrinkage
FarmCPU	Slow	Iterative pseudo-QTN model + PCs	Controlling false positives
BLINK	Slow	Iterative pseudo-QTN model + PCs	Sparse signals with large marker sets
FarmCPUResampling	Very Slow	FarmCPU resampling + PCs	Stability via RMIP resampling

File Formats

Input Files

Phenotype (CSV)

ID,Height,FloweringTime
Sample1,1.85,72
Sample2,1.92,68

Genotype (VCF/HapMap/Plink/CSV/TSV)

• VCF: Standard variant call format (.vcf or .vcf.gz)
• CSV/TSV: Numeric matrix (rows=samples, cols=markers)
• HapMap: TASSEL HapMap format
• Plink: Binary format (.bed/.bim/.fam)

Covariates (CSV, optional)

ID,Field,Year
Sample1,A,2023
Sample2,B,2023

Genetic Map (CSV/TSV, optional but recommended) CSV/TSV with MARKER, CHROM, and POS columns (legacy SNP and aliases like Chr, Pos are accepted). Recommended for numeric genotype matrices and chromosome-aware methods like MLM and BAYESLOCO.

Output Files

• GWAS_{trait}_all_results.csv - Full association results
• GWAS_{trait}_significant.csv - Significant markers only
• GWAS_{trait}_{method}_manhattan.png - Manhattan plot
• GWAS_{trait}_{method}_qq.png - QQ plot

See Output Files for detailed format specifications.

Common Questions

Q: Which method should I use?

• Start with GLM for quick screening
• Use MLM if you have population structure or relatedness
• Use MLM with map data when you want LOCO + exact top-hit refinement in the pipeline

Q: How many PCs should I include?

• Typically 3-10 PCs depending on population structure
• Check QQ plots: λ_GC should be close to 1.0
• More PCs if you have strong stratification

Q: Why are my results files large?

• Full results contain all markers × all methods
• Compress with gzip: gzip GWAS_*_all_results.csv
• Or only output significant markers: outputs=['significant_marker_pvalues']

Q: Sample IDs don't match?

• IDs must match exactly (case-sensitive)
• Check first column of phenotype file is 'ID'
• Run pipeline.align_samples() and check the output

Performance Tips

1. Use binary genotype formats - Genotype files are cached automatically (VCF/BCF/PLINK/HapMap/CSV/TSV)
2. Filter low MAF variants before analysis
3. Start with GLM for initial screening
4. Prefer MLM with map data to enable LOCO + exact top-hit refinement
5. Run methods in parallel - pipeline handles this automatically

Getting Help

• Check examples: See examples/ directory
• Read docs: Start with quickstart.md
• Run tests: pytest tests/ (if available)
• Open an issue: GitHub issues for bugs/questions

Citation

If you use PANICLE in your research, cite the software version you used, for example:

PANICLE v0.4.0. https://github.com/jschnable/PANICLE

See Also

• Example Scripts - Runnable example code with test data
• Main README - Project overview and algorithm descriptions
• GitHub Repository - Source code and issues

---