IgPhyML

https://igphyml.readthedocs.io/en/latest/
Admin
IgPhyML is a phylogenetic inference package designed to build B cell lineage trees and test...
Tokens:21,805
Snippets:194
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with Homebrew

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Install autoconf, automake, and llvm using Homebrew. Ensure Homebrew is up to date with 'brew update' before running these commands.

```bash
brew install autoconf
brew install automake
brew install llvm
```

--------------------------------

### Load Docker container with examples directory

Source: https://igphyml.readthedocs.io/en/latest/install.html

Moves into the examples directory and loads the Docker container, providing separate commands for Linux/Mac OS X and Windows. The Linux/Mac command uses $(pwd) while the Windows command uses %cd%.

```bash
# move to examples directory
cd igphyml/examples

# load Docker, Linux/ Mac OS X:
docker run -it --workdir /data -v $(pwd):/data:z immcantation/suite:4.5.0 bash

# or load Docker, Windows:
docker run -it --workdir /data -v %cd%:/data:z immcantation/suite:4.5.0 bash

```

--------------------------------

### Install automake and BLAS/LAPACK packages on Ubuntu

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Install the required build tools and optional BLAS/LAPACK libraries on Debian/Ubuntu systems with apt-get. May require sudo permission.

```bash
apt-get install automake autoconf libblas-dev liblapack-dev libatlas-base-dev
```

--------------------------------

### Install Xcode command line tools

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

On some OS X versions, it may be necessary to install Xcode command line tools and the macOS SDK headers package.

```bash
xcode-select --install
cd /Library/Developer/CommandLineTools/Packages/
open macOS_SDK_headers_for_macOS_<OS X version>.pkg
```

--------------------------------

### Install build dependencies on Ubuntu

Source: https://igphyml.readthedocs.io/en/latest/install.html

Install the required build tools and BLAS/LAPACK libraries on Ubuntu systems. This command may require sudo permission. Other Linux distributions have similar package names.

```bash
apt-get install automake autoconf libblas-dev liblapack-dev libatlas-base-dev

```

--------------------------------

### View BuildTrees help options

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

Run BuildTrees.py with the --help flag to display all available options. Works with Change-O 0.4.6 or higher and IgPhyML installed in PATH.

```bash
BuildTrees.py --help


```

--------------------------------

### Change directory and load Docker image for Linux/macOS or Windows

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

After cloning the repository, move to the examples directory and load the Docker image. Use the Linux/macOS '$(pwd)' syntax or the Windows '%cd%' syntax. The volome mount flag '-v $(pwd):/data:z' mounts the current directory as /data.

```bash
# move to examples directory
 cd igphyml/examples

 # load Docker, Linux/ Mac OS X:
 docker run -it --workdir /data -v $(pwd):/data:z immcantation/suite:4.5.0 bash

 # or load Docker, Windows:
 docker run -it --workdir /data -v %cd%:/data:z immcantation/suite:4.5.0 bash
```

--------------------------------

### Install build tools with Homebrew on macOS

Source: https://igphyml.readthedocs.io/en/latest/install.html

Install autoconf, automake, and llvm via Homebrew on macOS. This is the first step for compiling IgPhyML on Mac OS X, which requires OpenMP support and GNU command line tools.

```bash
brew install autoconf
brew install automake
brew install llvm

```

--------------------------------

### Build repertoire lineage trees with GY94

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/standalone.rst.txt

Generates starting topologies for a repertoire using the fast GY94 model.

```bash
igphyml --repfile ex_lineages.tsv -m GY --outrep ex_lineages_gy.tsv --run_id gy
```

--------------------------------

### Pull Immcantation Docker image and clone IgPhyML repository

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Use this snippet to pull the Immcantation Docker image version 4.5.0 and clone the IgPhyML repository. It is a necessary step to obtain the example files and run commands. Docker must be installed and may need to be running before executing these commands.

```bash
# pull Immcantation Docker image
 docker pull immcantation/suite:4.5.0

 # clone IgPhyML repository to get example files
 git clone https://github.com/immcantation/igphyml
```

--------------------------------

### Verify Docker container environment (ls and igphyml --version)

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

After entering the Docker container, run 'ls' to confirm the example files (example.fasta, example.tab, part.example.txt) are present, and run 'igphyml --version' to check the IgPhyML version (expected IgPhyML 2.0.0 092223).

```bash
# should give example.fasta  example.tab  part.example.txt
 ls

 # should be IgPhyML 2.0.0 092223
 igphyml --version
```

--------------------------------

### Build lineage trees with --optimize n

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Fastest option for getting tree topologies: uses GY94 without estimating parameters under HLP19. Trees can be visualized using igraph and Alakazam.

```bash
BuildTrees.py -d example.tsv --collapse --igphyml --clean all --optimize n
```

--------------------------------

### Create IgPhyML input files from example.tsv

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

Run BuildTrees.py on the AIRR formatted example with the --collapse flag to collapse identical sequences, which improves performance without affecting likelihood. IgPhyML requires at least three sequences per lineage; if only one is observed, it is duplicated.

```bash
cd examples
BuildTrees.py -d example.tsv --outname ex --log ex.log --collapse

```

--------------------------------

### Compile IgPhyML from source on Linux (make_phyml_omp)

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

On Linux with the required dependencies installed, run this script to compile IgPhyML with OpenMP support.

```bash
./make_phyml_omp
```

--------------------------------

### Install Xcode command line tools on macOS

Source: https://igphyml.readthedocs.io/en/latest/install.html

Install Xcode command line tools on some versions of OS X. This is necessary for compiling IgPhyML on macOS. Replace <OS X version> with your specific macOS version.

```bash
xcode-select --install
cd /Library/Developer/CommandLineTools/Packages/
open macOS_SDK_headers_for_macOS_<OS X version>.pkg

```

--------------------------------

### Set clang, OpenMP, and LLVM paths in src/Makefile.am

Source: https://igphyml.readthedocs.io/en/latest/install.html

Add these lines to src/Makefile.am to specify the LLVM clang compiler, OpenMP header, and LLVM library paths. The example uses LLVM 19.1.4; your paths may differ. Check /usr/local/Cellar/llvm/ for the correct locations.

```bash
CC=/usr/local/Cellar/llvm/19.1.4/bin/clang
MACOMP=/usr/local/Cellar/llvm/19.1.4/lib/clang/19/include/omp.h
MACLLVM=/usr/local/Cellar/llvm/19.1.4/lib

```

--------------------------------

### Load Docker image for current directory (Linux/macOS and Windows)

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Use this command to load the Docker image and mount the current directory as /data. The Linux/macOS variant uses '$(pwd)' and the Windows Command Prompt variant uses '%cd%'. To use this command, you must be running Docker with the current directory containing the example files.

```bash
docker run -it --workdir /data -v $(pwd):/data:z immcantation/suite:4.5.0 bash
```

--------------------------------

### Edit src/Makefile.am to set clang, omp.h, and llvm lib paths

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Add the lines 'CC=<path to llvm clang>', 'MACOMP=<path to omp.h>', and 'MACLLVM=<path to llvm lib>' to src/Makefile.am. Example shown for llvm 19.1.4.

```bash
CC=/usr/local/Cellar/llvm/19.1.4/bin/clang
MACOMP=/usr/local/Cellar/llvm/19.1.4/lib/clang/19/include/omp.h
MACLLVM=/usr/local/Cellar/llvm/19.1.4/lib
```

--------------------------------

### Compile IgPhyML with BLAS and LAPACK support

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

If BLAS and LAPACK libraries are installed (e.g. libblas-dev, liblapack-dev), use this script to compile with those optimizations.

```bash
./make_phyml_blas_omp
```

--------------------------------

### Build trees and estimate model parameters with IgPhyML in Dowser

Source: https://igphyml.readthedocs.io/en/latest/usage/quickstart.html

First block: loads an AIRR-formatted example dataset, formats clones, and builds trees with IgPhyML using the GY94 model. Requires Dowser 1.0.0+ and IgPhyML available in the Docker container or compiled locally. Second block: visualizes the trees, saves them, and prints parameter estimates from the fitted HLP19 model.

```R
#!/usr/bin/R
library(dowser)
library(airr)
library(tidyr)
library(dplyr)

# read in data after clonal clustering and germline reconstruction
data <- read_rearrangement("/usr/local/share/igphyml/examples/example.tsv")

# format clones for tree building (only 1 clone has >1 unique sequence)
clones <- formatClones(data)

# build tree using IgPhyML
# executable location will be different different if locally compiled
igphyml_exec <- "/usr/local/share/igphyml/src/igphyml"
trees <- getTrees(clones, build="igphyml", exec=igphyml_exec)

```

```R
# generate plot objects
plots <- plotTrees(trees)

# plot tree in console (might not work in Docker)
plots[[1]]

# plot trees as a  pdf
treesToPDF(plots, file="igphyml_example_trees.pdf")

# save trees for later
saveRDS(trees, "trees.rds")

# look at parameters
print(gather(bind_rows(trees$parameters)))

# A tibble: 13 × 2
#   key         value
#   <chr>       <chr>
# 1 clone       1
# 2 nseq        2
# 3 nsite       106
# 4 tree_length 0.2865
# 5 lhood       -147.7453
# 6 kappa_mle   1.9527
# 7 omega_mle   0.7074
# 8 wrc_2_mle   4.3296
# 9 gyw_0_mle   2.6478
#10 wa_1_mle    5.5308
#11 tw_0_mle    0.7451
#12 syc_2_mle   -0.99
#13 grs_0_mle   0.2133

```

--------------------------------

### Constrain motif mutabilities

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Example of using the --motifs and --hotness options to constrain specific motifs to share the same mutability values.

```bash
 BuildTrees.py -d example.tsv --collapse --igphyml \
  --motifs WRC_2:0,GYW_0:0,WA_1:1,TW_0:1,SYC_2:2,GRS_0:2 \
  --hotness e,e,e
```

--------------------------------

### Build lineage trees using the HLP19 model

Source: https://igphyml.readthedocs.io/en/latest/usage/standalone.html

These commands use the HLP19 model to correct for SHM mutation biases. The first option optimizes topology, branch lengths, and parameters, while the second uses GY94 starting trees for faster execution.

```bash
#HLP topology, branch lengths, and parameters (slow)
igphyml --repfile ex_lineages_gy.tsv -m HLP --threads 1

#GY94 topology, HLP19 branch lengths and parameters (faster)
igphyml --repfile ex_lineages_gy.tsv -m HLP --optimize lr --threads 1
```

--------------------------------

### View BuildTrees help options

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Run this command to display all available options for BuildTrees.py.

```bash
BuildTrees.py --help
```

--------------------------------

### Equivalent BuildTrees.py commands

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Demonstrates that default parameter settings are equivalent to explicitly specifying parameters.

```bash
BuildTrees.py -d example.tsv --collapse --igphyml

BuildTrees.py -d example.tsv --collapse --igphyml -t e --omega e,e \
  --motifs WRC_2:0,GYW_0:1,WA_1:2,TW_0:3,SYC_2:4,GRS_0:5 \
  --hotness e,e,e,e,e,e --optimize lr
```

--------------------------------

### View IgPhyML help options

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/standalone.rst.txt

Displays all available command-line options for the IgPhyML executable.

```bash
igphyml --help
```

--------------------------------

### Compile IgPhyML from source

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Download the development source with git, change into the igphyml directory, and run the make_phyml_omp script to compile. If compilation succeeds, the executable 'src/igphyml' is produced.

```bash
git clone https://github.com/immcantation/igphyml
    cd igphyml
    ./make_phyml_omp
```

--------------------------------

### Edit Makefile.am to set clang path

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Add the line 'CC=<path to llvm clang>' to the beginning of Makefile.am. Example shown for llvm 19.1.4.

```bash
CC=/usr/local/Cellar/llvm/19.1.4/bin/clang
```

--------------------------------

### Equivalent IgPhyML commands with default parameters

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

These two commands are equivalent because of default parameter settings. The first uses defaults; the second explicitly sets the same values with -t e, --omega e,e, --motifs, --hotness, and --optimize lr. Use --optimize lr to keep tree topologies fixed and only estimate branch lengths and substitution parameters.

```bash
BuildTrees.py -d example.tsv --collapse --igphyml
```

```bash
BuildTrees.py -d example.tsv --collapse --igphyml -t e --omega e,e \
 --motifs WRC_2:0,GYW_0:1,WA_1:2,TW_0:3,SYC_2:4,GRS_0:5 \
 --hotness e,e,e,e,e,e --optimize lr
```

--------------------------------

### Analyze a single lineage with partition files

Source: https://igphyml.readthedocs.io/en/latest/usage/standalone.html

Estimate separate omega values for CDR and FWR partitions using a partition file.

```bash
igphyml -i example.fasta -m HLP --root V4-59 --partfile part.example.txt
```

--------------------------------

### Clone and compile IgPhyML with OpenMP

Source: https://igphyml.readthedocs.io/en/latest/install.html

Clone the IgPhyML repository and compile it with OpenMP support. Run this on Linux or when the Docker image is not available. Successful compilation produces the executable file src/igphyml.

```bash
git clone https://github.com/immcantation/igphyml
cd igphyml
./make_phyml_omp

```

--------------------------------

### Convert Change-O files for IgPhyML

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/standalone.rst.txt

Prepares repertoire data by creating lineage files and partition information required for IgPhyML input.

```bash
BuildTrees.py -d example.tsv --outname ex --log ex.log --collapse
```

--------------------------------

### Compare ωCDR estimates across samples with IgPhyML and R

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

This workflow runs IgPhyML on an example file with confidence intervals on ωCDR, then loads the result and two other samples in R using alakazam's readIgphyml and combineIgphyml. The ggplot code plots the MLE and confidence intervals for ωCDR across samples; run dev.off() after plotting if using the Docker image to create a pdf.

```bash
BuildTrees.py -d example.tsv --collapse --nproc 2 --ncdr3 --clean all --igphyml --omega e,ce

```

```r
#!/usr/bin/R
library(alakazam)
library(ggplot2)

#read in three different samples
ex = readIgphyml("example_igphyml-pass.tab",id="EX")
s1 = readIgphyml("sample1_igphyml-pass.tab",id="S1")
s2 = readIgphyml("sample2_igphyml-pass.tab",id="S2")

#combine objects into a dataframe
comb = combineIgphyml(list(ex,s1,s2),format="wide")

#compare CDR dN/dS for three samples
ggplot(comb,aes(x=ID,y=OMEGA_CDR_MLE, ymin=OMEGA_CDR_LCI,
  ymax=OMEGA_CDR_UCI)) + geom_point() +
  geom_errorbar(width=0.1) + theme_bw()

```

--------------------------------

### Estimating ML tree topologies with HLP19

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Runs BuildTrees.py to estimate ML tree topologies using the HLP19 model.

```bash
BuildTrees.py -d example.tsv --collapse --igphyml --clean all --optimize tlr
```

--------------------------------

### Build trees and estimate model parameters in R

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/quickstart.rst.txt

Load necessary libraries, read the rearrangement data, format clones, and execute the IgPhyML tree building process.

```R
#!/usr/bin/R
library(dowser)
library(airr)
library(tidyr)
library(dplyr)

# read in data after clonal clustering and germline reconstruction
data <- read_rearrangement("/usr/local/share/igphyml/examples/example.tsv")

# format clones for tree building (only 1 clone has >1 unique sequence)
clones <- formatClones(data)

# build tree using IgPhyML
# executable location will be different different if locally compiled
igphyml_exec <- "/usr/local/share/igphyml/src/igphyml"
trees <- getTrees(clones, build="igphyml", exec=igphyml_exec)
```

--------------------------------

### Check compilation success

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Run './src/igphyml -version' to verify that the compilation was successful.

```bash
./src/igphyml -version
```

--------------------------------

### Load Docker image for Windows Command Prompt

Source: https://igphyml.readthedocs.io/en/latest/_sources/install.rst.txt

Use this command to load the Docker image for the current directory on Windows Command Prompt. Replace '%cd%' with the current directory variable.

```bash
docker run -it --workdir /data -v %cd%:/data:z immcantation/suite:4.5.0 bash
```

--------------------------------

### Estimate confidence intervals for GYW mutability

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Demonstrates estimating confidence intervals for GYW mutability using two equivalent command configurations.

```bash
 BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml --hotness e,ce,e,e,e,e
```

```bash
 BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml \
  --motifs WRC_2:0,GYW_0:1,WA_1:2,TW_0:3,SYC_2:4,GRS_0:5 \
  --hotness e,ce,e,e,e,e
```

--------------------------------

### Run IgPhyML for visualization

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Command to run IgPhyML with confidence interval estimation on omega_CDR.

```bash
 BuildTrees.py -d example.tsv --collapse --nproc 2 --ncdr3 --clean all --igphyml --omega e,ce
```

--------------------------------

### Visualize trees and print parameter estimates

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/quickstart.rst.txt

Generate plot objects, visualize trees, export to PDF, save the tree object, and display the estimated parameters.

```R
# generate plot objects
plots <- plotTrees(trees)

# plot tree in console (might not work in Docker)
plots[[1]]

# plot trees as a  pdf 
treesToPDF(plots, file="igphyml_example_trees.pdf")

# save trees for later
saveRDS(trees, "trees.rds")

# look at parameters
print(gather(bind_rows(trees$parameters)))

# A tibble: 13 × 2
#   key         value    
#   <chr>       <chr>    
# 1 clone       1        
# 2 nseq        2        
# 3 nsite       106      
# 4 tree_length 0.2865   
# 5 lhood       -147.7453
# 6 kappa_mle   1.9527   
# 7 omega_mle   0.7074   
# 8 wrc_2_mle   4.3296   
# 9 gyw_0_mle   2.6478   
#10 wa_1_mle    5.5308   
#11 tw_0_mle    0.7451   
#12 syc_2_mle   -0.99    
#13 grs_0_mle   0.2133  
```

--------------------------------

### Create IgPhyML input files from example.tsv

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/buildtrees.rst.txt

Use BuildTrees.py to process an AIRR file, filtering nonfunctional sequences, masking split codons, separating clonal groups, and creating repertoire files. The --collapse flag collapses identical sequences, which is recommended to speed up calculations without affecting likelihood values.

```bash
cd examples
BuildTrees.py -d example.tsv --outname ex --log ex.log --collapse
```

--------------------------------

### Analyze a single lineage with a fixed tree topology

Source: https://igphyml.readthedocs.io/en/latest/usage/standalone.html

Use a pre-existing tree file to fix the topology during analysis.

```bash
igphyml -i example.fasta -m HLP --root V4-59 -u example.fasta_igphyml_tree_gy.txt
```

--------------------------------

### Visualize interesting tree from sample1 dataset

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

Visualizes a more interesting lineage tree from a different provided dataset. Uses ladderize to improve layout and adjusts plot parameters for better visualization.

```r
library(alakazam)
library(ape)

db = readIgphyml("sample1_igphyml-pass.tab",format="phylo")

#plot largest lineage tree
plot(ladderize(db$trees[[1]]),cex=0.7,no.margin=TRUE)

```

--------------------------------

### Verify IgPhyML compilation with -version

Source: https://igphyml.readthedocs.io/en/latest/install.html

Check if the compilation was successful by running the igphyml executable with the -version flag. This should output the version information if the build succeeded.

```bash
./src/igphyml -version

```

--------------------------------

### Estimate confidence intervals with BuildTrees.py --omega and --hotness

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

These BuildTrees.py commands show how to request 95% confidence intervals for IgPhyML parameter estimates. The first two toggle confidence intervals for ωCDR or ωFWR using the --omega flag with 'e,ce' or 'ce,e'. The last two are equivalent ways to estimate confidence intervals for GYW mutability using --hotness, with the second form explicitly listing the motif positions via --motifs.

```bash
BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml --omega e,ce

```

```bash
BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml --omega ce,e

```

```bash
BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml --hotness e,ce,e,e,e,e

```

```bash
BuildTrees.py -d example.tsv --collapse --ncdr3 --clean all --igphyml \
 --motifs WRC_2:0,GYW_0:1,WA_1:2,TW_0:3,SYC_2:4,GRS_0:5 \
 --hotness e,ce,e,e,e,e

```

--------------------------------

### Load Docker image on Linux/Mac OS X

Source: https://igphyml.readthedocs.io/en/latest/install.html

General command to load the Docker image on the current directory of a Linux/Mac OS X system.

```bash
docker run -it --workdir /data -v $(pwd):/data:z immcantation/suite:4.5.0 bash

```

--------------------------------

### Estimate ML trees with HLP19 using --optimize tlr

Source: https://igphyml.readthedocs.io/en/latest/usage/buildtrees.html

Estimates ML tree topologies using the HLP19 model. Slower than using the GY94 model but returns meaningful HLP19 parameter estimates. Results can be visualized with Alakazam.

```bash
BuildTrees.py -d example.tsv --collapse --igphyml --clean all --optimize tlr

```

--------------------------------

### Run igphyml with tab output format

Source: https://igphyml.readthedocs.io/en/latest/_sources/usage/standalone.rst.txt

Executes igphyml to generate a tab-delimited file compatible with the Alakazam readIgphyml function.

```bash
igphyml --repfile ex_lineages_gy.tsv -m HLP --optimize lr --threads 1 --oformat tab
```
Tokens:
Raw