# Introduction to STOICH Utilities

# Getting Started with the Utilities

The STOICH-utilities R package provides user tools for working with STOICH database files. This package is designed to enable easier and more robust access to the data files from STOICH database releases.

The STOICH API “stoichUtilities” is an R library, as such you will need to have R installed. It is recommended to install RStudio (https://posit.co/) to help manage packages and provide an integrated development environment (IDE).

## Installation

There are 3 options for installing the stoichUtilities package. Installing a prebuilt package contains the vignette, while a standard “Install and Restart” won’t contain the vignette. Instructions for building your own package from source to get the vignette are also included.

### Option 1: Install Through CRAN

    install.packages(“stoichUtilties”)

### Option 2: Install a PreBuilt Package

Download the stoichUtilities_x.x.x.xxxx.tar.gz file.

Select the menu option Tools -> Install Packages

A window should pop up. For Install from: choose Package Archive File and navigate to the location of the tar.gz file.

Click “Install” ### Option 3: Install from Source #### Download Source Files There are 2 options to get the source files: * From the GitHub project page click the green Code button and choose “Download Zip” * Use GitHub Desktop or CLI programs to Clone the STOICH-Utilities repository (click the green Code button to copy the URL from the GitHub project page). #### Simple Install: Open and Build the R Library Navigate to the source code location and open stoichUtilities.Rproj in RStudio.

Build the documentation: ctrl + shift + D or with the menu Build -> Document

Install the library and restart the R session: ctrl + shift + B or with the menu Build -> Install and Restart

#### Build Package Method: Build and Install Package from Source

Navigate to the source code location and open stoichUtilities.Rproj in RStudio.

Select the menu option Build -> Build Source Package

To install the package, follow instructions for Installing a PreBuilt Package.

### Installing Required Packages (required for options 2 & 3)

The stoichUtilities uses several other packages. Install the required packages.

    install.packages(“tidyverse”)
    install.packages(“lubridate”)
    install.packages(“sf”)
    install.packages(“units”)

## Unpacking the Data

The Beta STOICH-utilities GitHub code comes with a file: Beta_Release_Data.zip, please unzip this file to a director (later assumed to be in the users home directory with the folder name Data).

## Using the R Library

### Load the Required Libraries.

    # Tidyverse and other support libraries
    library(tidyverse)
    library(lubridate)
    library(sf)
    library(units)

    # Load stoichUtilities
    library(stoichUtilities)

### Working with STOICH Data

    # Load the STOICH data (assumed to be in a directory named "data" inside the home directory)
    stoichData <- loadSTOICH(dataPath=file.path(path.expand("~"), "data"))

    # Filter the STOICH data
    stoichFiltered <- filterSTOICH(dataTables=stoichData,
                                   var="State",
                                   val="North Dakota",
                                   condition="Equal")

    # Match organism stoichiometry data with water chemsitry data for samples that weren't taken at the exact same time
    stoichPaired <- locateDataPairsSTOICH(stoichData,
                                          timeDiff=2,
                                          timeUnits="weeks",
                                          distance=2,
                                          pairMethod="Min Time",
                                          ignoreExisting=TRUE)

    # Join all the tables into one large wide table
    stoichTable <- joinSTOICH(stoichPaired)

### Example of Mapping STOICH Data

Use the tbl_Site table from stoichData for Site information for mapping.

    # Count how many sites are in each state.
    stateCounts <- stoichData$tbl_Site |>
      select(c("State")) |>
      drop_na(State) |>
      # Change the data to lowercase to allow the table to merge with the Tidyverse state data
      mutate(State=str_to_lower(State)) |>
      group_by(State) |>
      # Summarise to get the number of sites for each state.
      summarise(nSites=n(), .groups="keep")

    # Use state data from Tidyverse and join the site data to it.
    us_states <- map_data("state") |>
      left_join(stateCounts, by=c("region"="State"))

    # Create a list of states in the Tidyverse dataset so only data from states with boundaries are used.
    stateList <- unique(us_states$region)

    # Split out the GPS data to map individual sites.
    gpsSites <- stoichData$tbl_Site |>
      filter(str_to_lower(State) %in% stateList) |>
      select(c("Latitude", "Longitude")) |>
      drop_na(Latitude, Longitude) |>
      # Round the gps coordinates so points that are close will be merged into a single point.
      mutate(across(everything(), ~round(.x, 2))) |>
      unique()

    # Start building the map.
    ggplot(data=us_states, mapping=aes(x=long, y=lat, group=group, fill=nSites)) +
      geom_polygon(color="black") +
      theme(legend.position = "bottom") +
      geom_point(data=gpsSites, aes(x=Longitude, y=Latitude, group=NA), size=2, shape=23, fill="orange")

### Help Documentation

You can also access documentation for any function using the help command.

    help(loadSTOICH)

# Guide to the STOICH Data

## Data Structure

Data structure and relationship for STOICH data tables.

## Table Structure View

STOICH Data Table Structure
(variables for each table in the data set)
tbl_InputFile | tbl_Contact | tbl_Source | tbl_Site | tbl_SampleEvent | tbl_OrganismStoichiometry | tbl_WaterChemistry
--- | --- | --- | --- | --- | --- | ---
Id | Id | Id | Id | Id | Id | Id
EntryName | FirstName | ContactId | Name | SampleDay | SampleEventId | SampleEventId
EntryDate | LastName | Type | Latitude | SampleMonth | InputFileId | InputFileId
FilePath | Email | Citation | Longitude | SampleYear | Type | SpecConductivity
ImportDate |  | DOI | State | SiteId | Origin | pHValue
|  | Url | Country | SourceId | TrophicMode | DO
|  | Title | EcosystemType | Habitat | TaxonomicKingdom | DOUnits
|  | FirstAuthor | Elevation | TrophicStatus | TaxonomicOrder | DOC
|  | YearPublished | Notes | Depth | TaxonomicFamily | DOCUnits
|  | Journal |  | AirTemp | TaxonomicGenus | NH4
|  | Publisher |  | WaterTemp | TaxonomicSpecies | NH4Units
|  | License |  | CloudCover | SamplePooling | SRP
|  | LitSurveyId |  | CanopyCover | StatisticalPooling | SRPUnits
|  | Organization |  | Light | SampleSize | NO3
|  | Notes |  | LightUnits | DevelopmentStage | NO3Units
|  |  |  | Notes | GutClearance | TDN
|  |  |  | SampleDate | OrganismMass | TDNUnits
|  |  |  |  | OrganismMassType | TN
|  |  |  |  | OrganismMassUnits | TNUnits
|  |  |  |  | OrganismSizeNotes | TDP
|  |  |  |  | OrganismSampled | TDPUnits
|  |  |  |  | TissueSampled | TP
|  |  |  |  | CarbonMean | TPUnits
|  |  |  |  | CarbonStdev | OtherElementsReported
|  |  |  |  | CarbonUnits | StatisticalPooling
|  |  |  |  | CarbonMethod | SampleSize
|  |  |  |  | CarbonMethodUrl | WaterSampleId
|  |  |  |  | NitrogenMean | Notes
|  |  |  |  | NitrogenStdev |
|  |  |  |  | NitrogenUnits |
|  |  |  |  | NitrogenMethod |
|  |  |  |  | NitrogenMethodUrl |
|  |  |  |  | PhosphorusMean |
|  |  |  |  | PhosphorusStdev |
|  |  |  |  | PhosphorusUnits |
|  |  |  |  | PhosphorusMethod |
|  |  |  |  | PhosphorusMethodUrl |
|  |  |  |  | CarbonToNitrogenRatio |
|  |  |  |  | CarbonToPhosphorusRatio |
|  |  |  |  | NitrogenToPhosphorusRatio |
|  |  |  |  | OtherElementsReported |
|  |  |  |  | Isotope13C |
|  |  |  |  | Isotope13CStDev |
|  |  |  |  | Isotope15N |
|  |  |  |  | Isotope15NStDev |
|  |  |  |  | OtherIsotopesReported |
|  |  |  |  | Chlorophyll |
|  |  |  |  | ChlorophyllUnits |
|  |  |  |  | ResourceQuantityReported |
|  |  |  |  | OrganismSampleId |
|  |  |  |  | Notes |

## Sample Table

Columns are labeled using the following format {variable name}.{table name} where {table name} doesn’t include the tbl_ from the start of the table name.

Sample of the STOICH Data
Id.Contact | FirstName.Contact | LastName.Contact | Email.Contact | Id.Source | Type.Source | Citation.Source | DOI.Source | Url.Source | Title.Source | FirstAuthor.Source | YearPublished.Source | Journal.Source | Publisher.Source | License.Source | LitSurveyId.Source | Organization.Source | Notes.Source | Id.SampleEvent | SampleDay.SampleEvent | SampleMonth.SampleEvent | SampleYear.SampleEvent | Id.Site | Habitat.SampleEvent | TrophicStatus.SampleEvent | Depth.SampleEvent | AirTemp.SampleEvent | WaterTemp.SampleEvent | CloudCover.SampleEvent | CanopyCover.SampleEvent | Light.SampleEvent | LightUnits.SampleEvent | Notes.SampleEvent | SampleDate.SampleEvent | Name.Site | Latitude.Site | Longitude.Site | State.Site | Country.Site | EcosystemType.Site | Elevation.Site | Notes.Site | Id.WaterChemistry | InputFileId.WaterChemistry | SpecConductivity.WaterChemistry | pHValue.WaterChemistry | DO.WaterChemistry | DOUnits.WaterChemistry | DOC.WaterChemistry | DOCUnits.WaterChemistry | NH4.WaterChemistry | NH4Units.WaterChemistry | SRP.WaterChemistry | SRPUnits.WaterChemistry | NO3.WaterChemistry | NO3Units.WaterChemistry | TDN.WaterChemistry | TDNUnits.WaterChemistry | TN.WaterChemistry | TNUnits.WaterChemistry | TDP.WaterChemistry | TDPUnits.WaterChemistry | TP.WaterChemistry | TPUnits.WaterChemistry | OtherElementsReported.WaterChemistry | StatisticalPooling.WaterChemistry | SampleSize.WaterChemistry | WaterSampleId.WaterChemistry | Notes.WaterChemistry | EntryName.InputFile.WaterChemistry | EntryDate.InputFile.WaterChemistry | FilePath.InputFile.WaterChemistry | ImportDate.InputFile.WaterChemistry | Id.OrganismStoichiometry | InputFileId.OrganismStoichiometry | Type.OrganismStoichiometry | Origin.OrganismStoichiometry | TrophicMode.OrganismStoichiometry | TaxonomicKingdom.OrganismStoichiometry | TaxonomicOrder.OrganismStoichiometry | TaxonomicFamily.OrganismStoichiometry | TaxonomicGenus.OrganismStoichiometry | TaxonomicSpecies.OrganismStoichiometry | SamplePooling.OrganismStoichiometry | StatisticalPooling.OrganismStoichiometry | SampleSize.OrganismStoichiometry | DevelopmentStage.OrganismStoichiometry | GutClearance.OrganismStoichiometry | OrganismMass.OrganismStoichiometry | OrganismMassType.OrganismStoichiometry | OrganismMassUnits.OrganismStoichiometry | OrganismSizeNotes.OrganismStoichiometry | OrganismSampled.OrganismStoichiometry | TissueSampled.OrganismStoichiometry | CarbonMean.OrganismStoichiometry | CarbonStdev.OrganismStoichiometry | CarbonUnits.OrganismStoichiometry | CarbonMethod.OrganismStoichiometry | CarbonMethodUrl.OrganismStoichiometry | NitrogenMean.OrganismStoichiometry | NitrogenStdev.OrganismStoichiometry | NitrogenUnits.OrganismStoichiometry | NitrogenMethod.OrganismStoichiometry | NitrogenMethodUrl.OrganismStoichiometry | PhosphorusMean.OrganismStoichiometry | PhosphorusStdev.OrganismStoichiometry | PhosphorusUnits.OrganismStoichiometry | PhosphorusMethod.OrganismStoichiometry | PhosphorusMethodUrl.OrganismStoichiometry | CarbonToNitrogenRatio.OrganismStoichiometry | CarbonToPhosphorusRatio.OrganismStoichiometry | NitrogenToPhosphorusRatio.OrganismStoichiometry | OtherElementsReported.OrganismStoichiometry | Isotope13C.OrganismStoichiometry | Isotope13CStDev.OrganismStoichiometry | Isotope15N.OrganismStoichiometry | Isotope15NStDev.OrganismStoichiometry | OtherIsotopesReported.OrganismStoichiometry | Chlorophyll.OrganismStoichiometry | ChlorophyllUnits.OrganismStoichiometry | ResourceQuantityReported.OrganismStoichiometry | OrganismSampleId.OrganismStoichiometry | Notes.OrganismStoichiometry | EntryName.InputFile.OrganismStoichiometry | EntryDate.InputFile.OrganismStoichiometry | FilePath.InputFile.OrganismStoichiometry | ImportDate.InputFile.OrganismStoichiometry
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | Chad | Petersen | cpetersen4@unl.edu | 3 | raw_repository | NEON (National Ecological Observatory Network). Periphyton, seston, and phytoplankton chemical properties (DP1.20163.001), RELEASE-2025. https://doi.org/10.48443/gr95-1c82. Dataset accessed from https://data.neonscience.org/data-products/DP1.20163.001/RELEASE-2025 on July 17, 2025. | 10.48443/j0k0-cv96 | https://data.neonscience.org/data-products/DP1.20163.001 | periphyton, seston, and phytoplankton chemical properties | Neon (National Ecological Observatory Network) | 2025 | NA | Neon (National Ecological Observatory Network) | CC0 1.0 | NA | NEON | NA | 6197 | 5 | 4 | 2017 | 119 | Benthic | NA | NA | NA | NA | NA | NA | NA | NA | NA | 2017-04-05 | red butte creek neon | 40.78393 | -111.79789 | Utah | United States Of America | Stream | 1694.2 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | 4251 | 3 | Periphyton | Epipelon | other | NA | NA | NA | NA | NA | NA_unknown | NA_unknown | 1 | NA | NA | 0.01010441 | AFDM | g_cm2 | NA | whole_organism | NA | 24.94079 | NA | ugC_cm2 | CHN_analysis | https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a | 261.2626 | NA | ugN_cm2 | CHN_analysis | https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a | 57.6973 | NA | ugP_cm2 | ICP_OMS | https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1.2/9788982b-217f-4217-9708-6607a679c957 | 0.111327 | 1.114759 | 10.01337 | TRUE | -25.22 | NA | 6.47 | NA | TRUE | NA | NA | FALSE | {"parentSampleID":["REDB.20170405.EPIPELON.3"]} | NA | Chad Petersen | 2025-07-18 | 20163NEON-as_Stoich_template2025-07-18-with_Ids.csv | 2025-09-09
1 | Chad | Petersen | cpetersen4@unl.edu | 2 | raw_repository | NEON (National Ecological Observatory Network). Chemical properties of surface water (DP1.20093.001), RELEASE-2025. https://doi.org/10.48443/a8cf-fj36. Dataset accessed from https://data.neonscience.org/data-products/DP1.20093.001/RELEASE-2025 on July 17, 2025. | 10.48443/wf2d-h925 | https://data.neonscience.org/data-products/DP1.20093.001 | chemical properties of surface water | Neon (National Ecological Observatory Network) | 2025 | NA | Neon (National Ecological Observatory Network) | CC0 1.0 | NA | NEON | NA | 1042 | 13 | 6 | 2017 | 87 | NA | NA | NA | NA | 22.9 | NA | NA | NA | NA | NA | 2017-06-13 | río cupeyes neon | 18.11026 | -66.98641 | Puerto Rico | United States Of America | Stream | 149.9 | NA | 793 | 2 | 311.2 | 8.340 | NA | NA | 62.84 | umol_L | -1.000e+09 | umol_L | -1e+09 | umol_L | 1.97e+01 | umol_L | 2.923e+01 | umol_L | 2.946e+01 | umol_L | -1.0e+09 | umol_L | 0.032 | umol_L | TRUE | NA | NA | {"parentSampleID":["CUPE.SS.20170613"]} | {"sample date and time":["2017-06-13T11:34:00"]} | Chad Petersen | 2025-07-18 | 20093NEON-as_Stoich_template2025-07-18-with_Ids.csv | 2025-09-09 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA
1 | Chad | Petersen | cpetersen4@unl.edu | 2 | raw_repository | NEON (National Ecological Observatory Network). Chemical properties of surface water (DP1.20093.001), RELEASE-2025. https://doi.org/10.48443/a8cf-fj36. Dataset accessed from https://data.neonscience.org/data-products/DP1.20093.001/RELEASE-2025 on July 17, 2025. | 10.48443/wf2d-h925 | https://data.neonscience.org/data-products/DP1.20093.001 | chemical properties of surface water | Neon (National Ecological Observatory Network) | 2025 | NA | Neon (National Ecological Observatory Network) | CC0 1.0 | NA | NEON | NA | 1563 | 6 | 6 | 2017 | 91 | NA | NA | NA | NA | 16.8 | NA | NA | NA | NA | NA | 2017-06-06 | kings creek neon | 39.10507 | -96.60339 | Kansas | United States Of America | Stream | 324.9 | NA | 1314 | 2 | 1231.0 | 7.755 | NA | NA | 79.78 | umol_L | -1.000e+09 | umol_L | -1e+09 | umol_L | 6.00e+00 | umol_L | 1.163e+01 | umol_L | 1.211e+01 | umol_L | 5.5e-01 | umol_L | 0.610 | umol_L | TRUE | NA | NA | {"parentSampleID":["KING.SS.20170606"]} | {"sample date and time":["2017-06-06T15:20:00"]} | Chad Petersen | 2025-07-18 | 20093NEON-as_Stoich_template2025-07-18-with_Ids.csv | 2025-09-09 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA
1 | Chad | Petersen | cpetersen4@unl.edu | 2 | raw_repository | NEON (National Ecological Observatory Network). Chemical properties of surface water (DP1.20093.001), RELEASE-2025. https://doi.org/10.48443/a8cf-fj36. Dataset accessed from https://data.neonscience.org/data-products/DP1.20093.001/RELEASE-2025 on July 17, 2025. | 10.48443/wf2d-h925 | https://data.neonscience.org/data-products/DP1.20093.001 | chemical properties of surface water | Neon (National Ecological Observatory Network) | 2025 | NA | Neon (National Ecological Observatory Network) | CC0 1.0 | NA | NEON | NA | 3768 | 7 | 11 | 2017 | 120 | NA | NA | NA | NA | 6.4 | NA | NA | NA | NA | NA | 2017-11-07 | martha creek neon | 45.79233 | -121.92942 | Washington | United States Of America | Stream | 333.7 | NA | 3519 | 2 | 36.4 | 7.130 | NA | NA | 82.82 | umol_L | 9.826e+00 | umol_L | -1e+09 | umol_L | -1.00e+09 | umol_L | -1.000e+09 | umol_L | -1.000e+09 | umol_L | 7.1e-01 | umol_L | 0.870 | umol_L | TRUE | NA | NA | {"parentSampleID":["MART.SS.20171107"]} | {"externalLabDataByAnalyte":["Source value of Ortho-P may be below detection limit but was not flagged in source data."],"sample date and time":["2017-11-07T19:55:00"]} | Chad Petersen | 2025-07-18 | 20093NEON-as_Stoich_template2025-07-18-with_Ids.csv | 2025-09-09 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA
1 | Chad | Petersen | cpetersen4@unl.edu | 1 | raw_repository | NEON (National Ecological Observatory Network). Aquatic plant bryophyte chemical properties (DP1.20063.001), RELEASE-2025. https://doi.org/10.48443/7ddc-qs67. Dataset accessed from https://data.neonscience.org/data-products/DP1.20063.001/RELEASE-2025 on July 17, 2025. | 10.48443/f1f5-rq28 | https://data.neonscience.org/data-products/DP1.20063.001 | aquatic plant bryophyte chemical properties | Neon (National Ecological Observatory Network) | 2025 | NA | Neon (National Ecological Observatory Network) | CC0 1.0 | NA | NEON | NA | 45 | 1 | 7 | 2016 | 13 | Benthic | NA | NA | NA | NA | NA | NA | NA | NA | NA | 2016-07-01 | walker branch neon | 35.95627 | -84.27873 | Tennessee | United States Of America | Stream | 261.1 | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA | 257 | 1 | Bryophyte | Benthic | photoautotroph | plantae | porellales | porellaceae | porella | pinnata | NA_unknown | NA_unknown | 1 | NA | NA | NA | NA | NA | NA | whole_organism | NA | 42.89000 | NA | percent_dm | NA | NA | 3.6500 | NA | percent_dm | NA | NA | NA | NA | NA | NA | NA | 13.703474 | NA | NA | FALSE | NA | NA | NA | NA | FALSE | NA | NA | FALSE | {"fieldID":["WALK.20160701.MINI.Q3"],"chemSubsampleID":["WALK.20160701.POPI14.Q3"]} | {"sample date and time":["2016-07-01T16:00:00"]} | Chad Petersen | 2025-07-17 | 20063NEON-as_Stoich_template2025-07-17-with_Ids.csv | 2025-09-09