| Title: | Fit Neutral Community Model to Microbiome or Ecological Data |
|---|---|
| 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. |
| Authors: | Yuxuan He [aut, cre, cph] (ORCID: <https://orcid.org/0009-0007-1149-5554>) |
| Maintainer: | Yuxuan He <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.3.1 |
| Built: | 2026-05-21 07:07:13 UTC |
| Source: | https://github.com/h-xuanjiu/ncmr |
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.
example_dataexample_data
A list with two components:
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.
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.
Simulated data for package examples.
Fit Neutral Community Model (NCM) with optional grouping and total pooling
fit_ncm( otu, grp = NULL, group_col = "group", groups = NULL, simplify = TRUE, return_model = FALSE, ... )fit_ncm( otu, grp = NULL, group_col = "group", groups = NULL, simplify = TRUE, return_model = FALSE, ... )
otu |
OTU table, rows = samples, columns = species (data.frame or matrix) |
grp |
Optional data.frame with rownames = sample IDs, and one column specifying group membership. If NULL, all samples in otu are used as one group. |
group_col |
Column name in grp that contains group labels (default "group"). |
groups |
Character vector of group names to analyze. If NULL and grp is provided, the function fits models for each group AND for all samples combined (total). If non-NULL, only those groups are analyzed (no total model). |
simplify |
If TRUE and only one model is fitted, return the model list directly (not nested). |
return_model |
Whether to return the nlsLM model object (default FALSE to save space). |
... |
Additional arguments passed to nlsLM (e.g., lower, upper, control). |
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).
# 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# 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
## S3 method for class 'summary_ncm' print(x, ...)## S3 method for class 'summary_ncm' print(x, ...)
x |
An object of class "summary_ncm". |
... |
Additional arguments (not used). |
No return value, called for side effects. Prints a formatted table of NCM results to the console.
Print summary of NCM group results
## S3 method for class 'summary_ncm_group' print(x, ...)## S3 method for class 'summary_ncm_group' print(x, ...)
x |
An object of class "summary_ncm_group". |
... |
Additional arguments (not used). |
No return value, called for side effects. Prints a formatted table of NCM group results to the console.
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.
run_app()run_app()
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.
This function does not return a value; it launches a Shiny application interactively in the default web browser.
fit_ncm for programmatic NCM fitting,
scatter_plot for generating NCM plots in R scripts
## Not run: # Launch the app ncmR::run_app() ## End(Not run)## Not run: # Launch the app ncmR::run_app() ## End(Not run)
Generic function for creating scatter plots. Methods available for NCM result objects and data frames.
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, ...)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, ...)
object |
An object to plot: NCM result or data.frame |
... |
Additional arguments passed to methods |
point_alpha |
Alpha transparency for points (default: 0.8) |
point_size |
Point size (default: 3) |
point_colors |
Named vector of colors for Above/Below/Neutral status |
fit_line_color |
Fitted line color (default: "#335399") |
fit_line_type |
Line type for fitted curve (default: "solid") |
fit_line_size |
Line width for fitted curve (default: 1) |
ci_line_color |
Confidence interval line color (default: "#335399") |
ci_line_type |
Confidence interval line type (default: "dashed") |
ci_line_size |
Confidence interval line width (default: 1) |
axis_title_x_text |
X-axis title text |
axis_title_y_text |
Y-axis title text |
axis_title_x_size |
X-axis title font size (default: 25) |
axis_title_y_size |
Y-axis title font size (default: 25) |
axis_text_x_size |
X-axis tick label font size (default: 20) |
axis_text_y_size |
Y-axis tick label font size (default: 20) |
legend_title_text |
Legend title text (default: NA) |
legend_size |
Legend text size (default: 6) |
legend_position |
Legend position as NPC coordinates c(x, y) (default: c(0.80, 0.40)) |
legend_hjust |
Legend horizontal justification (default: 0) |
legend_vjust |
Legend vertical justification (default: 1) |
fit_para_size |
Fitting parameter text size (default: 6) |
fit_para_position |
Parameter annotation position as NPC coordinates c(x, y) (default: c(0.02, 0.98)) |
fit_para_hjust |
Parameter horizontal justification (default: 0) |
fit_para_vjust |
Parameter vertical justification (default: 1) |
font_family |
Font family (default: "sans") |
rsqr |
R-squared value from NCM fit |
Nm |
Nm parameter from NCM fit |
m |
m parameter from NCM fit |
map |
Named vector for column name mapping (e.g., c(p = "abundance")) |
A ggplot object
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.
# 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)# 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
## S3 method for class 'NCM' summary(object, ...)## S3 method for class 'NCM' summary(object, ...)
object |
An object of class "NCM" (single model). |
... |
Additional arguments (not used). |
An object of class "summary_ncm" containing key model statistics.
Summary method for NCM group results
## S3 method for class 'NCM_group' summary(object, ...)## S3 method for class 'NCM_group' summary(object, ...)
object |
An object of class "NCM_group" (list of NCM objects). |
... |
Additional arguments (not used). |
An object of class "summary_ncm_group" containing summary for each group.