biyelunwen/99.scripts/workflow/coalescence_network/bpp/README.md

BPP Coalescence Network Analysis Scripts

This directory contains scripts for running BPP (Bayesian Phylogenetics & Phylogeography) analysis using the A00 method for coalescence network inference.

Files

1. run_bpp_a00.ctl - Control file for BPP A00 analysis
2. run_bpp.sh - Shell script to execute the BPP analysis
3. generate_and_run_bpp.py - Python script to generate control file and run BPP analysis
4. README.md - This file

Prerequisites

1. BPP software must be installed and available in your PATH
2. Input sequence data in PHYLIP format
3. Imap file mapping sequences to species
4. Known species tree topology

Usage

Method 1: Manual Control File Editing

1. Update the control file (run_bpp_a00.ctl) with your specific:

   • Sequence file path (seqfile)
   • Imap file path (Imapfile)
   • Species names, counts, and tree topology in species&tree block
   • Number of loci (nloci)
   • Other parameters as needed

2. Prepare your input files:

   • Sequence file in PHYLIP format with multiple loci
   • Imap file mapping individual sequences to species
   • Ensure your species tree topology is correct

3. Run the analysis:

   ./run_bpp.sh
   

Method 2: Automated Python Script (Recommended)

Use the Python script to automatically generate the control file and run the analysis:

python generate_and_run_bpp.py \
  --seqfile sequences.txt \
  --imapfile species_map.txt \
  --species sp1 sp2 sp3 sp4 sp5 \
  --nloci 100 \
  --output my_analysis_result \
  --threads 8 \
  --burnin 20000 \
  --nsample 100000 \
  --sampfreq 5

BPP A00 Analysis Mode

The A00 analysis mode is appropriate for your use case because:

• You have one sample per species
• You have a known species tree (systematic network)
• You want to estimate population size (θ) and divergence time (τ) parameters

In this mode:

• speciesdelimitation = 0 - Species delimitation is fixed
• speciestree = 0 - Species tree is fixed
• Parameters θ and τ are estimated on the fixed tree

Key Parameters in Control File

• thetaprior: Inverse gamma prior for population size parameters (θ)
• tauprior: Inverse gamma prior for root divergence time, Dirichlet for others
• burnin: Number of burn-in iterations for MCMC
• nsample: Number of samples to collect
• sampfreq: Sampling frequency
• threads: Number of CPU threads to use

Output Files

After successful execution, you will get:

• Main output file (default: bpp_a00_results.txt)
• MCMC samples file (default: bpp_a00_results.mcmc.txt)
• Seed information file (default: bpp_a00_results.SeedUsed)

Customization

Depending on your data characteristics, you may want to adjust:

• Prior parameters for θ and τ
• MCMC settings (burnin, nsample, sampfreq)
• Threading options
• Output options in the print line