Quickstart

Get started with AlleleFlux in minutes.

Prerequisites

Ensure you have:

  • AlleleFlux installed (see Installation)

  • Input files prepared:

    • BAM files (sorted and indexed)

    • Reference FASTA (MAG contigs)

    • Prodigal gene predictions

    • Sample metadata TSV (with bam_path column)

    • MAG mapping file (contig → MAG assignments)

Configuration

Copy the configuration template and edit for your data:

cp alleleflux/smk_workflow/config.template.yml my_config.yml

Minimal configuration:

data_type: "longitudinal"  # or "single"

input:
  fasta_path: "reference.fa"
  prodigal_path: "genes.fna"
  metadata_path: "metadata.tsv"
  mag_mapping_path: "mag_mapping.tsv"

output:
  root_dir: "output/"

analysis:
  use_significance_tests: true
  use_lmm: true
  use_cmh: true

See Configuration Reference for all options.

Run the Pipeline

alleleflux run --config my_config.yml --threads 16

This command profiles samples, runs quality control, performs statistical tests, calculates scores, and identifies outliers.

Output

Results are organized in the output directory:

output/
├── profiles/               # Allele frequency profiles
├── metadata/               # Per-MAG metadata
├── eligibility/            # MAG eligibility tables
├── allele_analysis/        # Frequency analysis results
├── significance_tests/     # Statistical test results
├── scores/                 # Parallelism/divergence scores
└── outliers/               # High-scoring genes

Key output files:

  • scores/processed/combined/scores_*.tsv - MAG-level scores

  • outliers/*/outlier_genes_*.tsv - Genes under selection

  • significance_tests/cmh/*.tsv.gz - Position-level p-values

See Output Files Reference for complete specifications.

Individual CLI Tools

Run individual analysis steps:

# Prepare MAG mapping
alleleflux-create-mag-mapping --dir mag_fastas/ --extension fa \
    --output-fasta combined.fasta --output-mapping mapping.tsv

# Profile a single sample
alleleflux-profile --bam_path sample.bam --fasta_path reference.fa \
    --prodigal_fasta genes.fna --output_dir profiles/

# Quality control
alleleflux-qc --rootDir profiles/ --fasta reference.fa \
    --breadth_threshold 0.1 --output_dir qc/

For complete CLI reference, see CLI Reference.

Next Steps