BCGcalc-README
================
<Erik.Leppo@tetratech.com>
2026-07-23 12:34:37.318709

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

# BCGcalc <a href='https://github.com/leppott/BCGcalc'><img src='inst/figures/logo.png' align="right" height="139" /></a>

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

## Badges

[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/leppott/BCGcalc/graphs/commit-activity)
[![lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)

[![GitHub
license](https://img.shields.io/github/license/leppott/BCGcalc.svg)](https://github.com/leppott/BCGcalc/blob/master/LICENSE)

[![CodeFactor](https://www.codefactor.io/repository/github/leppott/BCGcalc/badge)](https://www.codefactor.io/repository/github/leppott/BCGcalc)
[![codecov](https://codecov.io/gh/leppott/BCGcalc/branch/master/graph/badge.svg)](https://app.codecov.io/gh/leppott/BCGcalc)
[![R-CMD-check](https://github.com/leppott/BCGcalc/workflows/R-CMD-check/badge.svg)](https://github.com/leppott/BCGcalc/actions)

[![GitHub
issues](https://img.shields.io/github/issues/leppott/BCGcalc.svg)](https://GitHub.com/leppott/BCGcalc/issues/)

[![GitHub
release](https://img.shields.io/github/release/leppott/BCGcalc.svg)](https://GitHub.com/leppott/BCGcalc/releases/)
[![Github all
releases](https://img.shields.io/github/downloads/leppott/BCGcalc/total.svg)](https://GitHub.com/leppott/BCGcalc/releases/)

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

``` r
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.

``` r
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.

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

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

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

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

``` r
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.

``` r
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.

``` r
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")
```
