Biological Condition Gradient, Calculator

Functions to calculate Biological Condition Gradient (BCG) using input files with one row per sample with metric values and site classes as columns. A second file with the BCG Rules (example included) to define the memberships is also needed. The three main functions convert metric scores to metric memberships following fuzzy set BCG Rules (BCG.Level.Assignment), combine metric memberships to level memberships according to BCG Rules (BCG.Level.Membership), and then assign a BCG primary and secondary level based on level memberships (BCG.Level.Assignment). Originally developed as a package for use with BCG for Puget Lowland/Willamette Valley but has been further enhanced for use with multiple communities (benthic macroinvertebrates, fish, periphyton, or coral) and different rule sets. Oregon and Washington reference - "Stamp, J. and J. Gerritsen. 2018. Calibration of the Biological Condition Gradient (BCG) for Macroinvertebrate Assemblages in Puget Lowland/Willamette Valley Freshwater Wadeable Streams. Prepared by Tetra Tech for the US EPA Office of Water, Office of Science and Technology and US EPA Region 10." BCG process documentation - "USEPA. 2016. A Practitioner’s Guide to the Biological Condition Gradient - A Framework to Describe Incremental Change in Aquatic Ecosystems. EPA 842-R-16-001. Office of Science and Technology, Washington, DC 20460."

BCGcalc-README

[email protected] 2026-07-23 12:34:37.318709

#> Last Update: 2026-07-23 12:34:37.377737

BCGcalc

Biological Condition Gradient (BCG) calculator. Perform basic functions needed for metric calculation and model (level) assignments.

Badges

Installation

To install the current version use the code below to install from GitHub. The use of “force = TRUE” ensures the package is installed even if already present. If the package pak is missing the code below will install it.

if(!require(pak)){install.packages("pak")}  #install if needed
pkg_install("leppott/BCGcalc")

The default for pak::pkg_install does the minimum. If need to update the package and all dependencies use the code below.

if(!require(pak)){install.packages("pak")}  #install if needed
pkg_install("leppott/BCGcalc", upgrade = TRUE)

Purpose

To aid users in data tasks related to the Biological Condition Gradient (BCG). The package is generic and can be used with any region with a BCG. If the region is not one of the pre-programmed BCGs the user will need to supply their own Rules.xlsx.

Usage

Everytime R is launched the BCGcalc package needs to be loaded.

# load library and dependant libraries
library("BCGcalc")

The default working directory is based on how R was installed but is typically the user’s ‘MyDocuments’ folder. You can change it through the menu bar in R (File - Change dir) or RStudio (Session - Set Working Directory). You can also change it from the command line.

# if specify directory use "/" not "\" (as used in Windows) and leave off final "/" (example below).
#myDir.BASE  <- "C:/Users/Erik.Leppo/Documents/ProjectName"
myDir.BASE <- getwd()
setwd(myDir.BASE)

Shiny

The Shiny app code is no longer included in the package but is available for a number of regions.

Help

Every function has a help file with a working example. There is also a vignette with descriptions and examples of all functions in the BCGcalc library.

# To get help on a function
# library(BCGcalc) # the library must be loaded before accessing help
?BCGcalc

To see all available functions in the package use the command below.

# To get index of help on all functions
# library(BCGcalc) # the library must be loaded before accessing help
help(package = "BCGcalc")

The vignette file is located in the “doc” directory of the library in the R install folder. But it is much easier to use the code below to call the vignette by name. There is also be a link to the vignette at the top of the help index for the package.

vignette("vignette_BCGcalc", package = "BCGcalc")

If the vignette fails to show on your computer the remotes package does not install the vignettes by default. Run the code below to reinstall using remotes and specify the creation of the vignette.

library(remotes)
remotes::install_github("leppott/BCGcalc", 
                        force = TRUE, 
                        build_vignettes = TRUE)

Example

A quick example showing the calculation of metrics on a dataset but returning only a select few (e.g., the 12 metrics used in the BCG model for the Pacific NW). This functionality is built into the metric.values function as an optional parameter.

library(BCGcalc)
library(readxl)
library(reshape2)
library(knitr)
library(BioMonTools)

df.samps.bugs <- read_excel(system.file("./extdata/Data_BCG_PacNW.xlsx",
                                        package="BCGcalc"))
myDF <- df.samps.bugs

# Columns to keep
myCols <- c("Area_mi2", 
            "SurfaceArea", 
            "Density_m2", 
            "Density_ft2")

# Metrics to Keep
met2keep <- c("ni_total", "nt_total", "nt_BCG_att1i2", "pt_BCG_att1i23",
              "pi_BCG_att1i23", "pt_BCG_att56", "pi_BCG_att56",
              "nt_EPT_BCG_att1i23", "pi_NonInsJugaRiss_BCG_att456",
              "pt_NonIns_BCG_att456", "pi_NonIns_BCG_att456", "nt_EPT")

# Run Function
df.metric.values.bugs <- metric.values(myDF, 
                                       "bugs", 
                                       fun.MetricNames = met2keep,
                                       fun.cols2keep = myCols)

# View Results
#View(df.metric.values.bugs)
kable(head(df.metric.values.bugs), caption = "Selected metric results")