Package {ncmR}

Type:	Package
Title:	Fit Neutral Community Model to Microbiome or Ecological Data
Version:	0.3.1
Description:	Provides tools for fitting the neutral community model (NCM) to assess the role of stochastic processes in community assembly. The package implements the framework of Sloan et al. (2006) <doi:10.1111/j.1462-2920.2005.00956.x>, enabling users to evaluate neutral dynamics in ecological and microbial communities.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
Depends:	R (≥ 3.5)
Imports:	bslib, colourpicker, dplyr, DT, ggplot2 (≥ 4.0.0), ggtext, Hmisc, minpack.lm, shiny, shinyjs, zip
RoxygenNote:	7.3.3
URL:	https://github.com/h-xuanjiu/ncmR
NeedsCompilation:	no
Packaged:	2026-05-10 10:30:43 UTC; 15225
Author:	Yuxuan He [aut, cre, cph]
Maintainer:	Yuxuan He <heyuxuan0525@outlook.com>
Repository:	CRAN
Date/Publication:	2026-05-10 10:40:02 UTC

Example OTU table and grouping information for NCM demonstration

Description

A simulated dataset containing an OTU table (ASV counts) and corresponding group labels. The data are intended to illustrate the usage of the fit_ncm function.

Usage

example_data

Format

A list with two components:

otu

A data frame with 15 rows (samples) and 2000 columns (ASVs). Row names are sample identifiers, column names are ASV identifiers. Values represent counts of each ASV in each sample.

grp

A data frame with 15 rows and 1 column named group. Row names correspond to the samples in otu. The group column contains character labels ("A", "A", ..., etc.) indicating group membership for each sample.

Source

Simulated data for package examples.

Fit Neutral Community Model (NCM) with optional grouping and total pooling

Description

Fit Neutral Community Model (NCM) with optional grouping and total pooling

Usage

fit_ncm(
  otu,
  grp = NULL,
  group_col = "group",
  groups = NULL,
  simplify = TRUE,
  return_model = FALSE,
  ...
)

Arguments

Value

A list containing model results. If multiple models, a named list with keys: - "all" (if total model fitted) and group names. Each value is a list with: m, N, Nm, ci, rsqr, predictions, (model optional).

Examples

# Load example data
data(example_data)
otu <- example_data$otu
grp <- example_data$grp

# 1. No grouping: fit the total model using all samples
res_total <- fit_ncm(otu)
print(paste("m =", round(res_total$m, 4)))
print(paste("R^2 =", round(res_total$rsqr, 4)))
head(res_total$predictions)

# 2. With grouping: fit models for all groups + total
res_all <- fit_ncm(otu, grp)

# 3. Only specific groups (no total model), returns a single model object
res_sub <- fit_ncm(otu, grp, groups = "A")
res_sub$status_summary

Print summary of NCM model

Description

Print summary of NCM model

Usage

## S3 method for class 'summary_ncm'
print(x, ...)

Arguments

Value

No return value, called for side effects. Prints a formatted table of NCM results to the console.

Print summary of NCM group results

Description

Print summary of NCM group results

Usage

## S3 method for class 'summary_ncm_group'
print(x, ...)

Arguments

Value

No return value, called for side effects. Prints a formatted table of NCM group results to the console.

Launch the ncmR Shiny Application

Description

Starts the interactive Shiny web application for fitting and visualizing Neutral Community Models (NCM). The app provides a user-friendly interface for uploading abundance data, fitting NCM models, and generating publication-quality plots.

Usage

run_app()

Details

The Shiny app includes two main modules:

• Fit NCM: Upload abundance data (samples as rows, species as columns) and optional group metadata to fit neutral community models. Supports grouped analyses and provides model parameters, fit statistics, and species-level predictions.

• Plotting: Visualize fitting results or upload pre-computed NCM results to generate customizable scatter plots with fitted curves and confidence intervals.

The app automatically detects sample IDs from the first column and handles large datasets with column pagination. Results can be downloaded as ZIP archives containing summary statistics and predictions.

Value

This function does not return a value; it launches a Shiny application interactively in the default web browser.

See Also

fit_ncm for programmatic NCM fitting, scatter_plot for generating NCM plots in R scripts

Examples

## Not run: 
# Launch the app
ncmR::run_app()

## End(Not run)

Scatter plot for NCM results and data frames

Description

Generic function for creating scatter plots. Methods available for NCM result objects and data frames.

Usage

scatter_plot(object, ...)

## S3 method for class 'NCM'
scatter_plot(
  object,
  point_alpha = 0.8,
  point_size = 3,
  point_colors = c(Above = "#ED7D70", Below = "#2B889B", Neutral = "#B57FAF"),
  fit_line_color = "#335399",
  fit_line_type = "solid",
  fit_line_size = 1,
  ci_line_color = "#335399",
  ci_line_type = "dashed",
  ci_line_size = 1,
  axis_title_x_text = "Mean relative abundance (log10)",
  axis_title_y_text = "Frequency of occupancy",
  axis_title_x_size = 25,
  axis_title_y_size = 25,
  axis_text_x_size = 20,
  axis_text_y_size = 20,
  legend_title_text = NA,
  legend_size = 6,
  legend_position = c(0.8, 0.4),
  legend_hjust = 0,
  legend_vjust = 1,
  fit_para_size = 6,
  fit_para_position = c(0.02, 0.98),
  fit_para_hjust = 0,
  fit_para_vjust = 1,
  font_family = "sans",
  ...
)

## S3 method for class 'data.frame'
scatter_plot(
  object,
  rsqr,
  Nm,
  m,
  map,
  point_alpha = 0.8,
  point_size = 3,
  point_colors = c(Above = "#ED7D70", Below = "#2B889B", Neutral = "#B57FAF"),
  fit_line_color = "#335399",
  fit_line_type = "solid",
  fit_line_size = 1,
  ci_line_color = "#335399",
  ci_line_type = "dashed",
  ci_line_size = 1,
  axis_title_x_text = "Mean relative abundance (log10)",
  axis_title_y_text = "Frequency of occupancy",
  axis_title_x_size = 25,
  axis_title_y_size = 25,
  axis_text_x_size = 20,
  axis_text_y_size = 20,
  legend_title_text = NA,
  legend_size = 6,
  legend_position = c(0.8, 0.4),
  legend_hjust = 0,
  legend_vjust = 1,
  fit_para_size = 6,
  fit_para_position = c(0.02, 0.98),
  fit_para_hjust = 0,
  fit_para_vjust = 1,
  font_family = "sans",
  ...
)

## Default S3 method:
scatter_plot(object, ...)

Arguments

Value

A ggplot object

Methods (by class)

• scatter_plot(NCM): Plot NCM result with fitted curve, confidence intervals, and parameter annotations. Supports full customization of visual elements.

• scatter_plot(data.frame): Plot data.frame by converting to NCM object. Requires manual specification of model parameters (rsqr, Nm, m) and optional column name mapping.

• scatter_plot(default): Default method for unsupported types.

Examples

# Load example data
data(example_data)
otu <- example_data$otu

# fit the total model using all samples
res_total <- fit_ncm(otu)

# plot
scatter_plot(res_total)

# Load example data
data(example_data)
otu <- example_data$otu

# fit the total model using all samples
res_total <- fit_ncm(otu)

df <- res_total$predictions

# Plot with manual parameters
scatter_plot(df, rsqr = 0.95, Nm = 500, m = 0.5678)

Summary method for NCM objects

Description

Summary method for NCM objects

Usage

## S3 method for class 'NCM'
summary(object, ...)

Arguments

Value

An object of class "summary_ncm" containing key model statistics.

Summary method for NCM group results

Description

Summary method for NCM group results

Usage

## S3 method for class 'NCM_group'
summary(object, ...)

Arguments

Value

An object of class "summary_ncm_group" containing summary for each group.