PhyMapNet

PhyMapNet is an R package for phylogeny-guided Bayesian microbial network inference. This repository contains the package source and the reproducible analysis workflow for the revised PhyMapNet study, including filtering, sensitivity analyses, bootstrap/noisy-data stability analyses, CMiNet overlap comparisons, HMP biological evaluation, and runtime scripts.

Figure. Overview of the PhyMapNet workflow. Microbiome abundance data and a phylogenetic tree are used to construct kernel-informed priors for Bayesian Gaussian graphical model inference. Networks inferred across hyperparameter configurations are aggregated into a reliability matrix to construct a consensus microbiome network.

Main Features

• Inference of microbial association networks using a phylogenetic tree or a named phylogenetic distance matrix.
• Single-model network estimation with phymapnet_fit().
• Ensemble edge reliability estimation with phymapnet_reliability().
• Supported normalizations: "log", "clr", and "tss".
• Supported phylogenetic kernels: "gaussian" and "laplacian".
• Taxon alignment and optional tree pruning before kernel construction.

Installation

Install from CRAN

install.packages("phymapnet")
library(phymapnet)
packageVersion("phymapnet")

The current CRAN release is version 0.1.3.

Install from GitHub

Because the R package source is stored in the phymapnet/ subdirectory:

# Install once if needed:
install.packages("remotes")

# Install PhyMapNet v0.1.3 from GitHub:
remotes::install_github(
  "rosaaghdam/PhyMapNet",
  subdir = "phymapnet",
  upgrade = "never"
)

library(phymapnet)
packageVersion("phymapnet")

Package Dependencies

The R package imports:

stats
ape
compositions

Paper-analysis scripts additionally require selected packages including dplyr, tibble, tidyr, ggplot2, patchwork, igraph, influential, SpiecEasi, and CMiNet.

Input Data

OTU/ASV table

otu is a numeric matrix or data frame:

• rows: samples;
• columns: taxa or ASVs;
• column names: taxon identifiers.

Phylogenetic tree input

The second input may be an ape::phylo tree:

fit <- phymapnet_fit(otu = otu, tree = tree)

When prune_tree = TRUE, nonshared OTU/tree taxa are removed and the OTU columns and tree tip labels are aligned before phylogenetic distances are computed.

Phylogenetic distance-matrix input

The second input may alternatively be a named, symmetric distance matrix:

fit <- phymapnet_fit(otu = otu, tree = DIS)

DIS must have matching row and column taxon names, nonnegative values, a zero diagonal, and taxa compatible with the OTU columns. The public argument name remains tree, but the function recognizes either a tree or distance matrix.

Single-Model Inference

library(phymapnet)

fit <- phymapnet_fit(
  otu = otu,
  tree = tree,
  alpha = 0.1,
  k = 10,
  epsilon1 = 0.5,
  epsilon2 = 0.,
  kernel = "gaussian",
  th_sparsity = 0.95,
  normalization = "log",
  prune_tree = TRUE
)

fit$adjacency
fit$precision
fit$edge_list

The same call may use tree = DIS when a named phylogenetic distance matrix is already available.

Reliability Ensemble Inference

res <- phymapnet_reliability(
  otu = otu,
  tree = tree,
  th_fixed = 0.95,
  alpha_range = c(0.01, 0.1),
  k_range = 2:10,
  epsilon1_range = c(0, 1),
  epsilon2_range = c(0, 1),
  kernels = c("gaussian"),
  normalizations = c("log"),
  consensus_cut = 0.50,
  prune_tree = TRUE,
  progress = FALSE
)

res$rel_mat
res$consensus_mat
res$edge_list

For distance-matrix input, replace tree = tree with tree = DIS.

Main Parameters

Parameter	Meaning
alpha / alpha_range	Kernel bandwidth controlling decay with phylogenetic distance.
k / k_range	Prior degree-of-freedom multiplier; internally used as k * p, where p is the number of taxa.
epsilon1 / epsilon1_range	Regularization term applied during prior covariance construction.
epsilon2 / epsilon2_range	Additional numerical regularization in precision estimation.
kernel / kernels	"gaussian" or "laplacian" phylogenetic kernel.
normalization / normalizations	"log", "clr", or "tss" transformation.
th_sparsity	Quantile threshold for sparsifying a single-model precision estimate.
th_fixed	Fixed quantile threshold applied to each model in an ensemble.
consensus_cut	Minimum edge-selection reliability required in the binary consensus network.
prune_tree	If TRUE, retains and aligns taxa shared by the OTU table and phylogenetic tree.

Reproduce Paper Outputs

The GitHub repository retains the precomputed result sets needed for the reported downstream analyses, result/reliable_score_all/ and result/reliability_master/, together with the genus-level important-taxa table from the HMP biological network: result/selected_important_otus.csv. Generated figures and other derived output tables can be regenerated locally from the retained results.

From a terminal, install the plotting dependencies and run the reproducibility script:

Rscript -e 'install.packages(c("ape", "dplyr", "tibble", "tidyr", "ggplot2", "patchwork", "igraph", "influential"))'
bash scripts/reproduce_paper_outputs.sh

This command regenerates filtered OTU/distance inputs, sensitivity Figure 2 and Tables S3/S4, CMiNet overlap outputs, and the HMP biological outputs from the included precomputed result files.

The script intentionally does not rerun multi-day network generation, the complete bootstrap analysis, or full runtime benchmarks. The bootstrap script is supplied for reproducibility, but its completed summary results are not included in the GitHub upload.

For a complete file-by-file guide and commands for expensive optional regeneration, see README_FILES.md.

Quick Package Tests

Rscript test_local_phymapnet_0.1.3.R
Rscript example_run_phymapnet_tree_and_distance.R

The real-data test uses the three filtered study datasets and checks agreement between tree-based and distance-matrix-based package calls with small test grids.

Citation

Please cite the PhyMapNet manuscript when using this package or its study workflow.

@article{shahdoust2026phymapnet,
  title={PhyMapNet: A Phylogeny-Guided Bayesian Framework for Reliable Microbiome Network Inference},
  author={Shahdoust, Maryam and Aghdam, Rosa and Taheri, Golnaz},
  journal={bioRxiv},
  pages={2026--02},
  year={2026},
  publisher={Cold Spring Harbor Laboratory}
}