Type:	Package
Title:	Fit Neutral Community Model to Microbiome or Ecological Data
Version:	0.2.0
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:	dplyr, ggplot2 (≥ 4.0.0), ggtext, Hmisc, minpack.lm, showtext
RoxygenNote:	7.3.3
URL:	https://github.com/h-xuanjiu/ncmR
NeedsCompilation:	no
Packaged:	2026-04-15 12:18:35 UTC; 15225
Author:	Yuxuan He [aut, cre, cph]
Maintainer:	Yuxuan He <heyuxuan0525@outlook.com>
Repository:	CRAN
Date/Publication:	2026-04-19 14: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

Save a ggplot with Unicode support using showtext

Description

This function is a wrapper around ggplot2::ggsave() that temporarily activates the showtext graphics engine before saving. It ensures that Unicode characters (e.g., Chinese, special symbols) are rendered correctly in the saved file, regardless of the output format (vector or raster).

Usage

ggsave_unicode(plot, filename, ...)

Arguments

Details

The function calls showtext::showtext_begin() before saving and ensures showtext::showtext_end() is called afterwards, even if an error occurs. It then passes all arguments to ggplot2::ggsave().

Value

Invisibly returns the filename (as ggsave does).

See Also

scatter_plot for creating plots that display correctly, print.unicode_ggplot for automatic display support.

Examples

## Not run: 
p <- scatter_plot(...)
ggsave_unicode(p, "myplot.png", width = 6, height = 4, dpi = 300)

## End(Not run)

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.

Print a unicode_ggplot object with automatic showtext support

Description

This method temporarily activates the showtext graphics engine to ensure that Unicode characters (e.g., Chinese, special symbols) are rendered correctly when the plot is displayed. After printing, the original graphics device state is restored.

Usage

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

Arguments

Details

The method calls showtext::showtext_begin(), then uses NextMethod() to invoke the original print.ggplot method, which actually draws the plot. Finally, showtext::showtext_end() is called to restore the device. This all happens automatically when a unicode_ggplot object is printed (e.g., when its name is typed at the console or when print() is explicitly called).

Value

The input object x, returned invisibly.

See Also

scatter_plot for creating such objects, ggsave_unicode for saving them with Unicode support.

Examples

## Not run: 
p <- scatter_plot(...)   # returns a unicode_ggplot object
p                             # automatically uses this print method

## 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.