ncmR

Overview

ncmR fits the neutral community model of Sloan et al. (2006) doi:10.1111/j.1462-2920.2005.00956.x to ecological and microbial abundance data. Estimate migration rate (m), inspect model fit, and visualize taxa classified as Above, Below or Neutral relative to model predictions.

Installation

# Stable release from CRAN
install.packages("ncmR")

# Development version from GitHub
# install.packages("remotes")
remotes::install_github("h-xuanjiu/ncmR")

Fit and plot a model

Abundance tables use samples as rows and taxa as columns. For grouped analyses, sample row names in the metadata must match the abundance table; the default group column is group.

library(ncmR)
data(example_data)

res <- fit_ncm(example_data$otu)
summary(res)

scatter_plot(res)
pie_plot(res)

# Fit each group and a combined model
results <- fit_ncm(example_data$otu, example_data$grp)
summary(results)
scatter_plot(results[["A"]])

# Fit only one selected group
group_a <- fit_ncm(example_data$otu, example_data$grp, groups = "A")

Grouped results store the combined model as results$.ncm_total; this name is reserved for the combined fit. Samples with missing group labels are excluded from individual group fits and retained in the combined fit.

Shiny app

Launch the app to upload data and fit models, or pass existing results to open Figure studio directly:

run_app()

# An existing NCM result
run_app(ncm = res)

# Grouped NCM_group results
run_app(ncm = results)

The app provides:

• A model workspace with parameter summaries, confidence intervals, taxon-level predictions and result downloads.
• Scatter and pie charts with live preview, font and color controls, and a theme inspector for the selected chart.
• PDF, SVG, PNG, TIFF and JPEG exports with size, resolution and background options, plus reproducible R recipes.

Use Update figure to apply changes when live preview is disabled. Figure exports and R recipes use the last applied settings. Font choices use fonts installed on the computer running the app.

Uploaded scatter-plot predictions require p, freq, freq.pred, lower and upper columns. Pie charts accept freq, lower and upper, or a status column containing Above, Below and Neutral. Alternative column names can be mapped in the app.

Customize plots in R

Use a complete base_theme for the starting style and theme for additional ggplot2 settings:

scatter_plot(
  res,
  point_size = 2,
  fit_para_size = 3.5,
  base_theme = ggplot2::theme_classic(base_size = 12),
  theme = ggplot2::theme(
    text = ggplot2::element_text(family = "sans"),
    axis.title = ggplot2::element_text(size = 14),
    axis.text = ggplot2::element_text(size = 10),
    legend.position = "bottom"
  )
)

pie_plot(
  res,
  label_type = "both",
  theme = ggplot2::theme(legend.position = "bottom")
)

pie_plot() counts taxa rather than weighting proportions by abundance. It also accepts prediction tables or data frames with one status value per taxon.

Theme text sizes use points; point_size, fit_para_size and pie label_size use millimeters. Model annotations inherit the final theme’s global text family and color. Earlier standalone font, axis-size and legend-placement arguments have been replaced by native theme settings.