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.
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 [email protected] 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 601 18 4 2017 81 NA NA NA NA 13.0 NA NA NA NA NA 2017-04-18 posey creek neon 38.89519 -78.14786 Virginia United States Of America Stream 271.9 NA 352 2 102.9 7.850 NA NA 139.6 umol_L -1.000e+09 umol_L -1.0e+09 umol_L 1.040e+01 umol_L 23.34 umol_L 27.50 umol_L 5.5e-01 umol_L 0.65 umol_L TRUE NA NA {"parentSampleID":["POSE.SS.20170418"]} {"externalLabDataByAnalyte":["Source value of Ortho-P may be below detection limit but was not flagged in source data."],"sample date and time":["2017-04-18T15:06: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 [email protected] 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 6080 18 7 2017 105 Benthic NA NA NA NA NA NA NA NA NA 2017-07-18 arikaree river neon 39.75821 -102.44715 Colorado United States Of America Stream 1179.5 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 3459 3 Periphyton Epiphyte other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.11250000 AFDM g_L NA whole_organism NA 31351.5500 NA ugC_L CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 3993.28000 NA ugN_L CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 449.230000 NA ugP_L ICP_OMS https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1.2/9788982b-217f-4217-9708-6607a679c957 9.15581 179.9768 19.65711 TRUE -31.37 NA 3.28 NA TRUE NA NA FALSE {"parentSampleID":["ARIK.20170718.EPIPHYTON.4"]} NA Chad Petersen 2025-07-18 20163NEON-as_Stoich_template2025-07-18-with_Ids.csv 2025-09-09
1 Chad Petersen [email protected] 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 849 17 10 2017 83 NA NA 0.5 NA 24.3 NA NA NA NA NA 2017-10-17 flint river neon 31.18461 -84.43844 Georgia United States Of America River 30.0 NA 600 2 123.7 7.735 NA NA 282.6 umol_L 7.805e+00 umol_L 1.2e+00 umol_L 3.511e+01 umol_L 40.45 umol_L 42.86 umol_L 7.7e-01 umol_L 2.10 umol_L TRUE NA NA {"parentSampleID":["FLNT.C0.20171017"]} {"sample date and time":["2017-10-17T15:01: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 [email protected] 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 3253 3 8 2015 113 NA NA NA NA 8.4 NA NA NA NA NA 2015-08-03 como creek neon 40.03494 -105.54442 Colorado United States Of America Stream 3023.0 NA 3004 2 28.1 6.795 NA NA 285.9 umol_L 7.100e+00 umol_L -1.0e+09 umol_L -1.000e+09 umol_L 11.20 umol_L 12.95 umol_L -1.0e+09 umol_L 0.26 umol_L TRUE NA NA {"parentSampleID":["COMO.SS.20150803"]} {"sample date and time":["2015-08-03T16:45: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 [email protected] 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 4710 18 7 2017 137 Benthic NA NA NA NA NA NA NA NA NA 2017-07-18 posey creek neon 38.89431 -78.14726 Virginia United States Of America Stream 275.8 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 1057 3 Periphyton Epilithon other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.00086589 AFDM g_cm2 NA whole_organism NA 379.0462 NA ugC_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 43.68714 NA ugN_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 6.036627 NA ugP_cm2 ICP_OMS https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1/4e8f0e27-251f-40b1-b5ad-07fd1ca3ad9e 10.11827 161.9288 16.00361 TRUE -28.92 NA 4.36 NA TRUE NA NA FALSE {"parentSampleID":["POSE.20170718.EPILITHON.1"]} NA Chad Petersen 2025-07-18 20163NEON-as_Stoich_template2025-07-18-with_Ids.csv 2025-09-09