### Build and Install Dowser from Source using devtools (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Installs build dependencies, generates documentation, builds, and installs the 'dowser' package from its source code repository using 'devtools'. This is for building the latest development code with documentation.

```R
library(devtools)
install_deps()
document()
build()
install()
```

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

### Install Dowser from a local source file (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Installs the 'dowser' package from a downloaded source archive file (e.g., a .tar.gz file). This is useful for installing specific versions or when direct CRAN installation is not feasible.

```R
install.packages("dowser_x.y.z.tar.gz", repos = NULL, type = "source")
```

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

### Example Usage of testSC

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/testSC.md

This example demonstrates how to use the testSC function. It involves loading necessary data, formatting clones, finding switches using findSwitches, and then applying testSC to the resulting switch data. Note that this example requires external data and setup, and is marked as not run.

```R
### Not run:
igphyml <- "~/apps/igphyml/src/igphyml"
# data(ExampleAirr)
# ExampleAirr$sample_id = sample(ExampleAirr$sample_id)
# clones = formatClones(ExampleAirr, trait="sample_id")
# btrees = findSwitches(clones[1:2], bootstraps=100, nproc=1,
# igphyml=igphyml, trait="sample_id", id="temp", dir="temp")
# testSC(btrees$switches)
```

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

### Install Dowser Development Version using devtools (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Installs the latest development version of the 'dowser' package directly from its GitHub repository using the 'devtools' package. This method installs the code but not the documentation.

```R
library(devtools)
install_github("immcantation/dowser@master")
```

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

### Install BEAST2 and Packages on Linux

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Time-Trees-Vignette.md

This snippet provides the bash commands to download, install, and configure BEAST2, along with the necessary packages (BEAST Classic, TyCHE, rootfreqs) on a Linux machine. It includes steps for setting up package repositories and running the package manager.

```bash
# Choose appropriate version for your architecture (x86 or aarch64)
BEAST=BEAST.v2.7.7.Linux.x86.tgz # or BEAST=BEAST.v2.7.7.Linux.aarch64.tgz

# download file and uncompress
curl -O https://github.com/CompEvol/beast2/releases/download/v2.7.7/$BEAST
tar -xvzf $BEAST

# optionally remove the compressed file
rm $BEAST

# run BEAST, at least with help, to allow it to set up its directories
~/beast/bin/beast -help

# install BEAST Classic package
~/beast/bin/packagemanager -add BEAST_CLASSIC

# add "extra packages" package repo
echo "packages.url=https\://raw.githubusercontent.com/CompEvol/CBAN/master/packages-extra-2.7.xml" >> ~/.beast/2.7/beauti.properties

# install TyCHE package
~/beast/bin/packagemanager -add TyCHE

# install rootfreqs package
~/beast/bin/packagemanager -add rootfreqs

```

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

### Load and Reconstruct Lineage Trees with Dowser (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Quickstart-Vignette.md

This R code snippet demonstrates the process of loading example AIRR data, formatting it for lineage reconstruction, building phylogenetic trees using the phangorn package, and plotting these trees with the ggtree package. It requires the alakazam and dowser R packages.

```r
# Load required packages
library(alakazam)
library(dowser)

# load example AIRR tsv data
data(ExampleAirr)

# subset data for this example
ExampleAirr = ExampleAirr[ExampleAirr$clone_id %in% c("3170", "3184"),]

# Process example data into proper format, store isotype (optional)
clones = formatClones(ExampleAirr, traits="c_call")

# Build maxmimum parsimony trees for first two clones using 
# phangorn package in R
trees <- getTrees(clones)

# simple tree plotting with ggtree R package with isotypes at tips
plots <- plotTrees(trees, tips="c_call",tipsize=2)

# plot tree of largest clone
plots[[1]]
```

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

### Install Dowser using BiocManager (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Installs the 'dowser' package and its Bioconductor dependencies using the BiocManager package. This is the recommended method for installing released versions.

```R
install.packages("BiocManager")

BiocManager::install("dowser")
```

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

### Install Dowser directly from CRAN (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Installs the 'dowser' package directly from CRAN. Note that this method may not install all necessary Bioconductor dependencies.

```R
install.packages("dowser")
```

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

### R Example: Using findSwitches for Phylogenetic Analysis

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/findSwitches.md

This example demonstrates how to use the findSwitches function with example data. It first formats clone data, then calls findSwitches with specified parameters including the igphyml executable path and trait. The output can be used to plot trees and test trait values.

```r
### Not run:
data(ExampleAirr)
# ExampleAirr$sample_id <- sample(ExampleAirr$sample_id)
# clones <- formatClones(ExampleAirr, trait="sample_id")
# 
igphyml <- "~/apps/igphyml/src/igphyml"
btrees <- findSwitches(clones[1:2,], permutations=10, nproc=1,
igphyml=igphyml, trait="sample_id")
plotTrees(btrees$trees[[4]])[[1]]
testPS(btrees$switches)
```

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

### Create airrClone Object from Example Data (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/makeAirrClone.md

This example demonstrates how to create an airrClone object using the makeAirrClone function with sample data. It loads the ExampleAirr dataset and filters it for a specific clone ID before passing it to the function.

```r
data(ExampleAirr)
airr_clone <- makeAirrClone(ExampleAirr[ExampleAirr$clone_id=="3184",])
```

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

### Generate BEAST2 XML for Starting Tree (Python)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/create_starting_tree.md

This function takes an airr clone object and a tree (either a phylo object or newick string) to generate BEAST2 XML. It allows customization of germline inclusion, tree states, and starting edge length. The output is a string containing the BEAST2 XML configuration for the starting tree.

```python
create_starting_tree(
    clone,
    id,
    tree,
    include_germline_as_tip,
    tree_states,
    start_edge_length
)
```

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

### Download IMGT Reference Database using Bash

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Germlines-Vignette.md

This bash script downloads the Immcantation repository and then executes a helper script to fetch and format the IMGT reference database for various species. The output includes species-specific directories and an IMGT.yaml file. Ensure you have git installed.

```bash
# Enter these commands in a terminal, not an R session!

# Move to the directory of interest
mkdir germlines

# Download the Immcantation repository
git clone https://github.com/immcantation/immcantation

# Run script to obtain IMGT gapped sequences
immcantation/scripts/fetch_imgtdb.sh -o germlines

# View added directories
ls germlines
# human  IMGT.yaml  immcantation  mouse  rabbit  rat  rhesus_monkey
```

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

### Check Dowser Imports (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/install.md

Retrieves information about the packages imported by the 'dowser' package. This can help identify missing dependencies.

```R
available.packages()["dowser", "Imports"]
```

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

### Format Clones and Prepare Data for Analysis

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Time-Trees-Vignette.md

This R code snippet demonstrates how to load example AIRR TSV data, set up time/date traits, and format the data using the `formatClones` function for subsequent phylogenetic analysis. It specifies the traits to be analyzed and the germline alignment column, and then prints a table of trait values.

```r
library(dowser)
library(dplyr)
library(ggtree)

# load example AIRR tsv data
data(ExampleAirrTyCHE)

# set up time/date trait
ExampleAirrTyCHE$sample_time <- as.numeric(ExampleAirrTyCHE$sample_time)

# trait value of interest
trait="location"

clones <- formatClones(
  ExampleAirrTyCHE,
  traits = c(trait, "sample_time"),
  germ   = "germline_alignment"
)

# Column shows which location the B cell was obtained from
print(table(ExampleAirrTyCHE[[trait]]))

```

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

### Format Clones and Build Trees with Dowser (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Measurable-Evolution.md

This R code snippet demonstrates how to load example AIRR data, format it into clone objects specifying time traits, filter for multi-timepoint trees, and build phylogenetic trees using maximum likelihood. It requires the 'dowser' library.

```r
library(dowser)

# load example AIRR tsv data
data(ExampleAirr)

# Process example data using default settings
clones = formatClones(ExampleAirr, traits="timepoint", minseq=3)

# Column shows timepoints in dataset
print(table(ExampleAirr$timepoint))
#0   7  14 
#62 102 225 

# Calculate number of tissues sampled in tree
timepoints = unlist(lapply(clones$data, function(x)
  length(unique(x@data$timepoint))))

# Filter to multi-type trees
clones = clones[timepoints > 1,]

# Build trees using maximum likelihood (can use alternative builds if desired)
trees = getTrees(clones, build="pml")
```

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

### buildPratchet

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildPratchet.md

Wrapper for phangorn::pratchet to build phylogenetic trees.

```APIDOC
## buildPratchet

### Description
Wrapper for phangorn::pratchet to build phylogenetic trees.

### Method
POST

### Endpoint
/immcantation/dowser/buildPratchet

### Parameters
#### Request Body
- **clone** (airrClone) - Required - An airrClone object.
- **seq** (string) - Optional - Sequence column in the airrClone object. Defaults to "sequence".
- **asr** (string) - Optional - Determines whether to return sequence or probability matrix. Defaults to "seq".
- **asr_thresh** (numeric) - Optional - Threshold for including a nucleotide as an alternative. Defaults to 0.05.
- **tree** (phylo) - Optional - A fixed tree topology if desired.
- **asr_type** (string) - Optional - Type of ancestral state reconstruction (MPR or ACCTRAN). Defaults to "MPR".
- **verbose** (integer) - Optional - Amount of rubbish to print. Defaults to 0.
- **resolve_random** (boolean) - Optional - Whether to randomly resolve polytomies. Defaults to TRUE.
- **data_type** (string) - Optional - Type of sequences (DNA or AA). Defaults to "DNA".

### Response
#### Success Response (200)
- **phylo** (phylo object) - A phylo object created by phangorn::pratchet with nodes attribute containing reconstructed sequences.
```

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

### Get Germline Segment (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getGermline.md

Retrieves a germline segment from a specified receptor and segment. This function requires detailed column names for germline start, end, and length, and can optionally operate on amino acid sequences.

```R
getGermline(
  receptor,
  references,
  segment,
  field,
  germ_start,
  germ_end,
  germ_length,
  germ_aa_start,
  germ_aa_length,
  amino_acid = FALSE
)
```

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

### Get Subtree Taxa using R

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getSubTaxa.md

The getSubTaxa function retrieves tip labels from a clade defined by an internal node in a phylogenetic tree. It requires a node number and a phylo object as input, returning a vector of tip labels. The example demonstrates how to apply this function to all subtrees within a given tree.

```R
getSubTaxa(node, tree)
```

```R
# Get taxa from all subtrees
data(BiopsyTrees)
tree <- BiopsyTrees$trees[[8]]
all_subtrees <- lapply(1:length(tree$nodes), function(x)getSubTaxa(x, tree))
```

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

### List All Logged Parameters

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Time-Trees-Vignette.md

Prints a list of all logged parameter items from the BEAST2 analysis results. This is useful for understanding what metrics are available for convergence diagnostics and further analysis. The output is a character vector of parameter names.

```r
print(mixed_trees$parameters[[2]]$item)
```

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

### Build Phylogenetic Trees using PML

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Time-Trees-Vignette.md

This R code snippet uses the `getTrees` function from the `dowser` package to build phylogenetic trees for the formatted GC B cell data (`gcf`). It specifies the `pml` method for tree building and the `HKY` substitution model. The resulting trees are then plotted, with tips colored by sample time, using `plotTrees` and `ggtree`.

```r
gctrees = getTrees(gcf, build="pml", sub_model="HKY")

plotTrees(gctrees)[[1]] + geom_tippoint(aes(color=sample_time))

```

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

### Build IgPhyML Trees with Partitions in R

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Resolve-Light-Chains-Vignette.md

This code snippet demonstrates how to build phylogenetic trees using IgPhyML with specified partitions and execution path. It utilizes the `getTrees` function from the Dowser package, setting the build method to 'igphyml' and specifying the executable path, number of processors, and partition scheme.

```r
clones <- getTrees(clones, build="igphyml", nproc=1, partition="hl",
                   exec="/usr/local/share/igphyml/src/igphyml")
```

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

### GET /immcantation/dowser/getSeq

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getSeq.md

Retrieves sequences for a given node in a tree. This function is deprecated and getNodeSeq should be used instead.

```APIDOC
## GET /immcantation/dowser/getSeq

### Description
Retrieves sequences for a given node in a tree. This function is deprecated and getNodeSeq should be used instead.

### Method
GET

### Endpoint
/immcantation/dowser/getSeq

### Parameters
#### Query Parameters
- **data** (tibble) - Required - A tibble of `airrClone` objects, the output of [getTrees](getTrees.md)
- **node** (numeric) - Required - Numeric node in tree (see details)
- **tree** (phylo) - Optional - A `phylo` tree object containing `node`
- **clone** (character) - Optional - If `tree` not specified, supply clone ID in `data`
- **gaps** (boolean) - Optional - Add IMGT gaps to output sequences? (default: TRUE)

### Request Example
```
GET /immcantation/dowser/getSeq?data=<tibble_data>&node=1&gaps=true
```

### Response
#### Success Response (200)
- **sequences** (vector) - A vector with sequence for each locus at a specified `node` in `tree`.

#### Response Example
```json
{
  "sequences": [
    "SEQUENCE1",
    "SEQUENCE2"
  ]
}
```
```

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

### Get Specific Node Sequence

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Sequences-Vignette.md

Retrieves the IMGT-gapped sequence for a specific reconstructed node within a dowser tree object. Requires the tree object, node number, and clone ID.

```r
sequence = getNodeSeq(trees, node=50, clone=3128)

print(sequence)
```

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

### Build RAxML Trees with Partitions in R

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Resolve-Light-Chains-Vignette.md

This code snippet shows how to build phylogenetic trees using RAxML, a common alternative for maximum likelihood tree building. It employs the `getTrees` function, specifying 'raxml' as the build method and providing the RAxML executable path, number of processors, and a 'scaled' partition.

```r
clones = getTrees(clones, build="raxml", 
    exec="/usr/local/bin/raxml-ng", nproc=1, partition="scaled")
```

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

### GET /immcantation/dowser/getSkylines

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getSkylines.md

Generates data frames for Bayesian skyline plots using BEAST tree files. This function processes tree data to produce values suitable for plotting Bayesian skyline reconstructions.

```APIDOC
## GET /immcantation/dowser/getSkylines

### Description
Generates data frames for Bayesian skyline plots. This endpoint processes BEAST tree files to create the necessary data structures for visualizing Bayesian skyline reconstructions.

### Method
GET

### Endpoint
/immcantation/dowser/getSkylines

### Parameters
#### Query Parameters
- **clones** (tibble) - Required - A tibble containing clone information.
- **dir** (string) - Required - The directory path to the BEAST trees file.
- **id** (string) - Required - A unique identifier for the analysis.
- **time** (string) - Required - The name of the column representing time in the dataset.
- **burnin** (numeric) - Optional - The percentage of burn-in to exclude from the analysis. Defaults to 10.
- **bins** (integer) - Optional - The number of bins to use for plotting. Defaults to 100.
- **verbose** (integer) - Optional - If set to 1, prints the name of the clones. Defaults to 0.
- **forward** (boolean) - Optional - Determines whether to plot in forward time (TRUE) or backward time (FALSE). Defaults to TRUE.
- **nproc** (integer) - Optional - The number of processors to use for parallelization, specified per clone. Defaults to 1.
- **max_height** (array) - Optional - Specifies the maximum height to use for plotting. Accepted values are "min", "median", "mean", "max". Defaults to c("min", "median", "mean", "max").

### Request Example
```
GET /immcantation/dowser/getSkylines?clones=<tibble_data>&dir=/path/to/trees&id=analysis1&time=TimeColumn&burnin=5&bins=200&forward=FALSE
```

### Response
#### Success Response (200)
- **Bayesian Skyline values** (object) - Contains the calculated Bayesian skyline values for the specified clone.

#### Response Example
```json
{
  "clone_id": "analysis1",
  "time_points": [100, 200, 300],
  "skyline_values": [0.5, 0.7, 0.6]
}
```
```

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

### Get All Observed and Reconstructed Sequences

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Sequences-Vignette.md

Retrieves all observed and reconstructed sequences for all clones from a dowser tree object. Returns a tibble containing clone ID, node ID, locus, sequence, and sequence alignment.

```r
# Get all sequences as a data frame
all_sequences = getAllSeqs(trees)

head(all_sequences)
```

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

### Build Pratchet Phylogenetic Tree

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildPratchet.md

This function wraps phangorn::pratchet to build a phylogenetic tree. It accepts an airrClone object, specifying sequence and ancestral state reconstruction columns, along with thresholds and tree topology options. The output is a phylo object with reconstructed sequences.

```r
buildPratchet(
  clone,
  seq = "sequence",
  asr = "seq",
  asr_thresh = 0.05,
  tree = NULL,
  asr_type = "MPR",
  verbose = 0,
  resolve_random = TRUE,
  data_type = "DNA"
)
```

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

### Collapse Nodes and Plot Trees with Node IDs

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Sequences-Vignette.md

Collapses internal nodes with identical sequences in a dowser object and then plots the trees, displaying the ID number of each internal node. Requires the 'dowser' library and example data.

```r
library(dowser)

data(ExampleClones)

# Collapse nodes with identical sequences. This will 
trees = collapseNodes(ExampleClones[1:2,])

# Plot trees with node ID numbers
plots = plotTrees(trees, tips="c_call", tipsize=2, node_nums=TRUE, labelsize=7)

plots[[1]]
```

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

### Prepare Clones for GC B Cell Analysis

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Time-Trees-Vignette.md

This R code filters the `ExampleAirrTyCHE` dataset to include only germinal center (GC) B cells and then formats this subset of data using the `formatClones` function. It specifies 'location' and 'sample_time' as traits and 'germline_alignment' as the germline reference, preparing the data for GC-specific phylogenetic analysis.

```r
gc_cells = filter(ExampleAirrTyCHE, location=="germinal_center")
gcf = formatClones(gc_cells, traits=c("location","sample_time"),
	germ="germline_alignment")

```

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

### Create Height Prior with Python

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/create_height_prior.md

This function generates BEAST2 XML to set a height prior. It requires an airr clone object, a unique identifier for the analysis, and a starting date. The output is a string containing the BEAST2 XML configuration.

```python
def create_height_prior(clone, id, start_date):
    """
    Takes an airr clone object and returns BEAST2 XML to set a height prior

    Arguments:
        clone: an `airrClone` object
        id: unique identifer for this analysis
        start_date: starting date to use as prior, in forward time

    Returns:
        String of XML setting the height prior
    """
    # Implementation details would go here to construct the XML string
    return "<beast2_xml_height_prior>"
```

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

### Format Clones for Lineage Construction (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/formatClones.md

The formatClones function takes a data.frame or tibble with AIRR or Change-O style columns as input. It masks gap positions, ragged ends, removes duplicate sequences, and merges annotations. It returns a list of airrClone objects ordered by the number of sequences, suitable for lineage reconstruction.

```r
library(immcantation)

# Assuming 'airr_data' is a data.frame or tibble with AIRR/Change-O data
# Example usage:
# formatted_clones <- formatClones(data = airr_data)

# Example with specific column names and options:
# formatted_clones <- formatClones(
#   data = airr_data,
#   seq = "sequence_alignment",
#   clone = "clone_id",
#   germ = "germline_alignment_d_mask",
#   v_call = "v_call",
#   j_call = "j_call",
#   junc_len = "junction_length",
#   traits = c("trait1", "trait2"),
#   collapse = TRUE,
#   nproc = 4
# )
```

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

### Get Divergence from Tree Root (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getDivergence.md

Calculates the sum of branch lengths from the root of a phylogenetic tree to each tip. This function takes a tree object and an optional minimum branch length for collapsing as input, returning a named vector of divergences.

```R
getDivergence(phy, minlength = 0.001)
```

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

### Get Color Palette for Trait Values (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/getPalette.md

Retrieves a color palette for a given set of states in a model, using a specified ColorBrewer palette. The function returns a named vector where each state is mapped to a color. 'Germline' defaults to black if not explicitly provided.

```r
getPalette(states, palette)
```

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

### Build IgPhyML Trees and Infer Nodes with buildIgphyml

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildIgphyml.md

The buildIgphyml function serves as a wrapper to build IgPhyML trees and infer intermediate nodes. It takes a list of airrClone objects and the path to the igphyml executable as primary arguments. Optional arguments control parallelization, temporary file management, random seeding, output verbosity, and various IgPhyML specific parameters like omega partitioning, rate optimization, and motif selection. The function returns a 'phylo' object with reconstructed sequences in its nodes attribute.

```r
buildIgphyml(
  clone,
  igphyml,
  trees = NULL,
  nproc = 1,
  temp_path = NULL,
  id = NULL,
  rseed = NULL,
  quiet = 0,
  rm_files = TRUE,
  rm_dir = NULL,
  partition = c("single", "cf", "hl", "hlf", "hlc", "hlcf"),
  omega = NULL,
  optimize = "lr",
  motifs = "FCH",
  hotness = "e,e,e,e,e,e",
  rates = NULL,
  asrc = 0.95,
  splitfreqs = FALSE,
  asrp = FALSE,
  make_gyrep = TRUE,
  ...
)
```

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

### Apply Plotting Modifications to All Trees Using lapply

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Plotting-Trees-Vignette.md

This example demonstrates how to apply consistent modifications to all tree plots generated by `plotTrees` using the `lapply` function. It iterates through each plot in the `plots` list and applies the same `geom_tiplab`, `geom_vline`, `xlim`, and `ggtitle` customizations.

```r
library(ggtree)

plots = plotTrees(ExampleClones, tips="c_call", tipsize=2)

#Manually adjust all trees
treeplots = lapply(plots, function(x)
  x + geom_tiplab(aes(label=c_call), offset = 0.02) + 
    geom_vline(xintercept=c(0.05,0.1,0.15,0.2,0.25),
        linetype="dashed",color="grey") + xlim(0,0.3) +
    ggtitle("Example B cell tree")
  )

# plot 2nd largest tree
treeplots[[2]]
```

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

### buildPhylo Wrapper for alakazam::buildPhylipLineage

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildPhylo.md

The buildPhylo function serves as a wrapper for the alakazam::buildPhylipLineage function, facilitating the construction of phylogenetic trees.

```APIDOC
## POST /immcantation/dowser/buildPhylo

### Description
This endpoint provides a wrapper for the `alakazam::buildPhylipLineage` function, enabling the construction of phylogenetic trees from sequence data.

### Method
POST

### Endpoint
/immcantation/dowser/buildPhylo

### Parameters
#### Request Body
- **clone** (object) - Required - An `airrClone` object containing the sequence data.
- **exec** (string) - Required - The path to the `dnapars` or `dnaml` executable.
- **temp_path** (string) - Optional - Path to a temporary directory for intermediate files.
- **verbose** (integer) - Optional - Controls the amount of output printed during execution (default: 0).
- **rm_temp** (boolean) - Optional - Whether to remove temporary files after execution (default: TRUE).
- **seq** (string) - Optional - The name of the sequence column within the `airrClone` object (default: "sequence").
- **tree** (object) - Optional - A fixed tree topology if desired (currently has no effect if specified).
- **onetree** (boolean) - Optional - If TRUE, only one tree is sampled if multiple are found (default: TRUE).

### Request Example
```json
{
  "clone": "<airrClone object>",
  "exec": "/path/to/dnapars",
  "temp_path": "/tmp/dowser_temp",
  "verbose": 1,
  "rm_temp": false,
  "seq": "sequence_column",
  "tree": null,
  "onetree": false
}
```

### Response
#### Success Response (200)
- **phylo_object** (object) - A `phylo` object created by dnapars or dnaml, with nodes attribute containing reconstructed sequences.

#### Response Example
```json
{
  "phylo_object": {
    "edge": [
      [1, 2],
      [1, 3],
      [4, 1]
    ],
    "edge.length": [
      0.1,
      0.2,
      0.05
    ],
    "tip.label": [
      "SeqA",
      "SeqB",
      "SeqC"
    ],
    "Nnode": 2,
    "root.edge": 0.1
  }
}
```
```

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

### Plotting Tip Metadata in Lineage Trees

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Plotting-Trees-Vignette.md

Illustrates how to display metadata associated with each tip of the lineage tree using the `tips` and `tipsize` arguments in the plotTrees function. Metadata fields must be pre-defined using the formatClones function.

```r
# Plot tree with sequence isotype at the tips.
plots = plotTrees(ExampleClones, tips="c_call")

#Plot the largest tree
plots[[1]]
```

```r
# Plot tree with sequence isotype at the tips, with sizes set to number of duplicates
plots = plotTrees(ExampleClones, tips="c_call", tipsize="duplicate_count")

#Plot the largest tree
plots[[1]]
```

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

### Format Clones for Tree Building with Dowser

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Resolve-Light-Chains-Vignette.md

The `formatClones` function converts data into `airrClone` objects suitable for tree building. Setting `chain = "HL"` concatenates paired heavy and light chains for a single alignment. `split_light = TRUE` ensures that distinct light chain rearrangements are maintained, and `minseq` filters out small subgroups. `collapse = FALSE` prevents merging identical sequences.

```r
clones <- formatClones(ExampleMixedDb, chain="HL", nproc=1, collapse = FALSE, 
                       split_light = TRUE, minseq = 3)
print(clones)
```

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

### Build Maximum Likelihood Trees with Partitions using IgPhyML

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Resolve-Light-Chains-Vignette.md

This snippet demonstrates building maximum likelihood phylogenetic trees using IgPhyML v2.0.0 or later. The `partition = "hl"` option enables models that treat heavy and light chain data separately, allowing for different scalar branch length estimations. This approach improves accuracy, especially when light chains are missing.

```r
# Building maximum likelihood trees with multiple partitions using IgPhyML 
# Only the newest version of IgPhyML supports this option

```

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

### Get Color Palette for Trait Values (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/colorTrees.md

The colorTrees function generates a color palette for a predefined set of trait values within phylogenetic trees. It takes a list of phylo objects, a named vector of colors, and an option for handling ambiguous states. The function returns a list of colored trees.

```r
colorTrees(trees, palette, ambig = "blend")
```

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

### Create Germlines from AIRR Data and IMGT References (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/createGermlines.md

This R code snippet demonstrates how to use the createGermlines function. It first reads IMGT germline data from a specified directory and then calls createGermlines with example AIRR data and the loaded germline references. The function is designed to process sequences within a clone and reconstruct their germline sequences.

```R
vdj_dir <- system.file("extdata", "germlines", "imgt", "human", "vdj", package="dowser")
imgt <- readIMGT(vdj_dir)
db <- createGermlines(ExampleAirr[1,], imgt)
```

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

### Build IgPhyML Tree with 'cf' Partition Model (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Trees-Vignette.md

This R code snippet demonstrates how to build a maximum likelihood tree using IgPhyML with the 'cf' partition model. This model separates sequence sites into two partitions: one for CDRs and one for FWRs, allowing for separate estimation of omega values while using the same branch lengths. It requires IgPhyML v2.0.0 or newer and specifies the execution path for IgPhyML.

```r
# exec here is set to IgPhyML position in the Docker image.
# Only the newest version of IgPhyML (v2.0.0) supports multi-partition trees
clones = getTrees(clones, build="igphyml", 
    exec="/usr/local/share/igphyml/src/igphyml", nproc=1, partition="cf")

print(clones)
## A tibble: 2 x 7
#  clone_id data       locus  seqs subject_id trees        parameters       
#     <dbl> <list>     <chr> <int> <chr>      <named list> <named list>     
#1     3170 <airrClon> N        13 Subject_1  <phylo>      <named list [13]>
#2     3184 <airrClon> N        12 Subject_1  <phylo>      <named list [13]>
```

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

### Build Maximum Parsimony Trees using PHYLIP dnapars

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Building-Trees-Vignette.md

Builds maximum parsimony B cell lineage trees utilizing the 'dnapars' executable from the PHYLIP package. This method requires specifying 'build="dnapars"' and providing the path to the 'dnapars' executable via the 'exec' option. The output is similar to the phangorn method, with 'ape::phylo' objects in the 'trees' column.

```r
# exec here is set to dnapars position in the Docker image.
clones = getTrees(clones, build="dnapars", exec="/usr/local/bin/dnapars", nproc=1)

clones
```

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

### Perform Date Randomization Test with Dowser (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Measurable-Evolution.md

This R code snippet shows how to perform the date randomization test using the 'correlationTest' function in Dowser. It includes examples for both the default clustered permutation test and the uniform permutation test, along with printing the results. The 'dowser' library and pre-built trees are required.

```r
# correlation test with 10000 repetitions
test = correlationTest(trees, permutations=10000, time="timepoint")
print(test)

# use uniform correlaion test (more sensitive, but higher false positive rate)
utest = correlationTest(trees, permutations=10000, time="timepoint", perm_type="uniform")
print(utest)
```

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

### Build Phylogenetic Tree using buildPhylo (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildPhylo.md

The buildPhylo function, a wrapper for alakazam::buildPhylipLineage, constructs phylogenetic trees from an airrClone object. It requires the path to a dnapars or dnaml executable and returns a phylo object with reconstructed sequences in the nodes attribute. Options are available for specifying temporary file paths, verbosity, sequence column, and tree sampling.

```r
buildPhylo(
  clone,
  exec,
  temp_path = NULL,
  verbose = 0,
  rm_temp = TRUE,
  seq = "sequence",
  tree = NULL,
  onetree = TRUE
)
```

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

### Customize Tip Labels and Spacing in a Single Tree Plot

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Plotting-Trees-Vignette.md

This code snippet shows how to customize the tip labels displayed on a tree plot using `geom_tiplab` with specific aesthetic mappings (e.g., `aes(label=c_call)`) and adjust the text offset using the `offset` argument. Other plot elements like vertical lines and titles remain consistent with the previous example.

```r
library(ggtree)

plots = plotTrees(ExampleClones, tips="c_call", tipsize=2)

#Plot the largest tree
treeplot = plots[[1]] + geom_tiplab(aes(label=c_call), offset = 0.02) + 
    geom_vline(xintercept=c(0.05,0.1,0.15,0.2,0.25),
        linetype="dashed",color="grey") + xlim(0,0.3) +
    ggtitle("Example B cell tree")

treeplot
```

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

### Build Phylogenetic Tree with buildPML (R)

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildPML.md

The buildPML function is a wrapper for phangorn::optim.pml, used to construct phylogenetic trees. It takes an airrClone object and allows customization of substitution models, gamma rate variation, and tree optimization. The output is a phylo object containing reconstructed sequences.

```r
buildPML(
  clone,
  seq = "sequence",
  sub_model = "GTR",
  gamma = FALSE,
  asr = "seq",
  asr_thresh = 0.05,
  tree = NULL,
  data_type = "DNA",
  optNni = TRUE,
  optQ = TRUE,
  optEdge = TRUE,
  verbose = FALSE,
  resolve_random = TRUE,
  quiet = 0,
  rep = NULL,
  dir = NULL,
  id = NULL,
  asrp = FALSE
)
```

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

### Build BEAST Run Data with buildBeast

Source: https://github.com/immcantation/dowser/blob/master/docs/topics/buildBeast.md

The buildBeast function reads data from a BEAST run, executes treeannotator and loganalyser, and prepares data for downstream analysis. It requires BEAST binaries, a time column name, an XML template, and a directory for temporary files. Optional arguments control MCMC length, trait analysis, ancestral sequence logging, and parallelization.

```r
buildBeast(
  data,
  beast,
  time,
  template,
  dir,
  id,
  mcmc_length = 1e+06,
  resume_clones = NULL,
  trait = NULL,
  asr = FALSE,
  full_posterior = FALSE,
  log_every = "auto",
  include_germline = TRUE,
  nproc = 1,
  quiet = 0,
  burnin = 10,
  low_ram = TRUE,
  germline_range = c(-10000, 10000),
  java = TRUE,
  seed = NULL,
  log_target = 10000,
  trees = NULL,
  tree_states = FALSE,
  start_edge_length = 100,
  start_date = NULL,
  max_start_date = NULL,
  ...
)
```

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

### Control False Positive Rate with Downsampling in R

Source: https://github.com/immcantation/dowser/blob/master/docs/vignettes/Discrete-Trait-Vignette.md

This R code illustrates controlling the false positive rate of the SP test by downsampling trees. The `findSwitches` function, by default, downsamples trees to a maximum tip-to-switch ratio of 20. This example modifies the `tip_switch` parameter to 10, which can reduce false positives at the cost of statistical power. The `downsample=FALSE` option can turn off this feature but is not recommended.

```r
# Downsample each tree to a tip-to-switch ratio of 10 instead of 20 
# this will reduce the false positive rate but also (likely) power
switches = findSwitches(trees, permutations=100, trait=trait, 
  igphyml=igphyml_location, fixtrees=TRUE, tip_switch=10)

# didn't have much effect for this dataset
sp = testSP(switches$switches, alternative="greater")
print(sp$means)
# A tibble: 2 x 8
# Groups:   FROM [2]
#  FROM  TO    RECON PERMUTE   PGT  DELTA STAT   REPS
#  <chr> <chr> <dbl>   <dbl> <dbl>  <dbl> <chr> <int>
#1 Lung  Nose  0.168   0.358   1   -0.190 SP       10
#2 Nose  Lung  0.832   0.642   0.1  0.190 SP       10
```