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://www.rstudio.com/) to help manage packages and provide an integrated development environment (IDE).

Installation

There are 2 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 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 2: 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

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 <- stoichUtilities::loadSTOICH(dataPath=file.path(path.expand("~"), "data"))

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

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

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

Example of Mapping STOICH Data

Use the stoichTable from the previous section as the data table for mapping.

# Install the Leaflet package if it isn't installed.
install.packages("leaflet")

# Load the leaflet library.
library(leaflet)

# Split out the GPS data.
gpsGroups <- stoichTable %>% 
  select(c("Latitude", "Longitude")) %>% 
  drop_na(Latitude, Longitude) %>% 
  # Round the GPS coordinates so small differences in location are lumped together.
  mutate(across(everything(), round, 2)) %>% 
  group_by(Latitude, Longitude) %>% 
  # Summarise to get the number of entries for each location in the database.
  summarise(nSamples=n(), .groups="keep") %>%
  # Convert the numbers to characters for use in popups
  mutate(nSamples = paste("Samples: ", nSamples, sep=""), .keep="all")

# Start building the map.
leaflet() %>% 
  # Select the background style.
  addProviderTiles(providers$OpenTopoMap) %>%
  # Add markers for all the sites and group them based on zoom level.
  addMarkers(data = gpsGroups, lng = ~Longitude, lat = ~Latitude, label=~nSamples, clusterOptions = markerClusterOptions())

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 Type SpecConductivity
FilePath Email Citation Longitude SampleYear Origin pHValue
ImportDate DOI State SiteId TrophicMode DO
Url Country SourceId TaxonomicKingdom DOUnits
Title EcosystemType InputFileId TaxonomicOrder DOC
FirstAuthor TrophicStatus Habitat TaxonomicFamily DOCUnits
YearPublished Elevation AirTemp TaxonomicGenus NH4
Journal Notes WaterTemp TaxonomicSpecies NH4Units
Publisher CloudCover SamplePooling SRP
License CanopyCover StatisticalPooling SRPUnits
LitSurveyId Light SampleSize NO3
Organization LightUnits DevelopmentStage NO3Units
Notes 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 Id.InputFile Habitat.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 TrophicStatus.Site Elevation.Site Notes.Site EntryName.InputFile EntryDate.InputFile FilePath.InputFile ImportDate.InputFile Id.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 Id.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
1 Chad Petersen cpetersen4@unl.edu 3 raw_repository NEON (National Ecological Observatory Network). Periphyton, seston, and phytoplankton chemical properties (DP1.20163.001), RELEASE-2023. https://doi.org/10.48443/j0k0-cv96. Dataset accessed from https://data.neonscience.org on March 9, 2023 https://doi.org/10.48443/j0k0-cv96 https://data.neonscience.org/data-products/DP1.20163.001 Periphyton, seston, and phytoplankton chemical properties NEON (National Ecological Observatory Network) 2023 NA NEON (National Ecological Observatory Network) NA NA NEON NA 2689 26 9 2017 220 3 Benthic NA NA NA NA NA NA NA 2017-09-26 McRae Creek NEON 44.25960 -122.16555 Oregon United States of America Stream NA 876.0 NA Chad Petersen 2023-06-08 20163NEON-as_Stoich_template2023-06-08-cleanDates.csv 2023-07-21 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 1974 Periphyton Epilithon other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.0064941812 AFDM g_cm2 NA whole_organism NA 258.3050 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 28.43501 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 0.1354426 NA ug_cm2 ICP_OMS https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1.2/9788982b-217f-4217-9708-6607a679c957 10.593682 4918.16966 464.25498 TRUE -30.57 NA -5.58 NA TRUE NA NA FALSE { "parentSampleID": "MCRA.20170926.EPILITHON.3" } { "Taxonomy": "available in NEON DP1.20166.001 (https://data.neonscience.org/data-products/DP1.20166.001) for parentSampleID=MCRA.20170926.EPILITHON.3" }
1 Chad Petersen cpetersen4@unl.edu 3 raw_repository NEON (National Ecological Observatory Network). Periphyton, seston, and phytoplankton chemical properties (DP1.20163.001), RELEASE-2023. https://doi.org/10.48443/j0k0-cv96. Dataset accessed from https://data.neonscience.org on March 9, 2023 https://doi.org/10.48443/j0k0-cv96 https://data.neonscience.org/data-products/DP1.20163.001 Periphyton, seston, and phytoplankton chemical properties NEON (National Ecological Observatory Network) 2023 NA NEON (National Ecological Observatory Network) NA NA NEON NA 2095 11 7 2017 112 3 Benthic NA NA NA NA NA NA NA 2017-07-11 Lewis Run NEON 39.09564 -77.98322 Virginia United States of America Stream NA 152.0 NA Chad Petersen 2023-06-08 20163NEON-as_Stoich_template2023-06-08-cleanDates.csv 2023-07-21 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 566 Periphyton Epipelon other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.0025962726 AFDM g_cm2 NA whole_organism NA 422.5769 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 251.51234 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 24.5669417 NA ug_cm2 ICP_OMS https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1/4e8f0e27-251f-40b1-b5ad-07fd1ca3ad9e 1.959359 44.35891 22.63950 TRUE -22.59 NA 7.99 NA TRUE NA NA FALSE { "parentSampleID": "LEWI.20170711.EPIPELON.3" } { "Taxonomy": "available in NEON DP1.20166.001 (https://data.neonscience.org/data-products/DP1.20166.001) for parentSampleID=LEWI.20170711.EPIPELON.3" }
1 Chad Petersen cpetersen4@unl.edu 3 raw_repository NEON (National Ecological Observatory Network). Periphyton, seston, and phytoplankton chemical properties (DP1.20163.001), RELEASE-2023. https://doi.org/10.48443/j0k0-cv96. Dataset accessed from https://data.neonscience.org on March 9, 2023 https://doi.org/10.48443/j0k0-cv96 https://data.neonscience.org/data-products/DP1.20163.001 Periphyton, seston, and phytoplankton chemical properties NEON (National Ecological Observatory Network) 2023 NA NEON (National Ecological Observatory Network) NA NA NEON NA 2305 5 7 2017 151 3 Littoral NA NA NA NA NA NA NA 2017-07-05 Crampton Lake NEON 46.20901 -89.47285 Wisconsin United States of America Lake NA 512.7 NA Chad Petersen 2023-06-08 20163NEON-as_Stoich_template2023-06-08-cleanDates.csv 2023-07-21 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 969 Periphyton Epixylon other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.0021471322 AFDM g_cm2 NA whole_organism NA 317.1988 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 33.60630 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 1.7317132 NA ug_cm2 ICP_OMS https://data.neonscience.org/documents/10179/3070551/ICPMetalsLab_P_V1.2/9788982b-217f-4217-9708-6607a679c957 11.007238 472.36938 42.91443 TRUE -28.19 NA -0.36 NA TRUE NA NA FALSE { "parentSampleID": "CRAM.20170705.EPIXYLON.6" } { "Taxonomy": "available in NEON DP1.20166.001 (https://data.neonscience.org/data-products/DP1.20166.001) for parentSampleID=CRAM.20170705.EPIXYLON.6" }
1 Chad Petersen cpetersen4@unl.edu 2 raw_repository NEON (National Ecological Observatory Network). Chemical properties of surface water (DP1.20093.001), RELEASE-2023. https://doi.org/10.48443/wf2d-h925. Dataset accessed from https://data.neonscience.org on March 9, 2023 https://doi.org/10.48443/wf2d-h925 https://data.neonscience.org/data-products/DP1.20093.001 Chemical properties of surface water NEON (National Ecological Observatory Network) 2023 NA NEON (National Ecological Observatory Network) NA NA NEON NA 247 20 11 2019 64 2 NA NA 8.7 NA NA NA NA { "sampler type": "Grab" } 2019-11-20 Lewis Run NEON 39.09422 -77.98143 Virginia United States of America Stream NA 126.8 NA Chad Petersen 2023-06-21 20093NEON-as_Stoich_template2023-06-21-cleanDates.csv 2023-07-21 83 606 8.115 10.53 mg_L 1.205 mg_L 0.04 mg_L 0.0085 mg_L 2.6274 mg_L 2.567 mg_L 2.553 mg_L 5e-04 mg_L 0.115 mg_L TRUE NA NA NA { "NH4": "NH4-N" } 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 3 raw_repository NEON (National Ecological Observatory Network). Periphyton, seston, and phytoplankton chemical properties (DP1.20163.001), RELEASE-2023. https://doi.org/10.48443/j0k0-cv96. Dataset accessed from https://data.neonscience.org on March 9, 2023 https://doi.org/10.48443/j0k0-cv96 https://data.neonscience.org/data-products/DP1.20163.001 Periphyton, seston, and phytoplankton chemical properties NEON (National Ecological Observatory Network) 2023 NA NEON (National Ecological Observatory Network) NA NA NEON NA 2647 7 5 2019 216 3 Benthic NA NA NA NA NA NA NA 2019-05-07 Blacktail Deer Creek NEON 44.95011 -110.58715 Wyoming United States of America Stream NA 2053.0 NA Chad Petersen 2023-06-08 20163NEON-as_Stoich_template2023-06-08-cleanDates.csv 2023-07-21 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 1719 Periphyton Epilithon other NA NA NA NA NA NA_unknown NA_unknown 1 NA NA 0.0009351621 AFDM g_cm2 NA whole_organism NA 660.1542 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 91.72922 NA ug_cm2 CHN_analysis https://data.neonscience.org/documents/10179/2113486/SIRFER_algalPlantChem_isotopes_V1/48b19e2b-7830-4056-817c-da8ea8ee183a 9.8124480 NA ug_cm2 ICP_OMS https://data.neonscience.org/documents/10179/2113486/ICPMetalsLab_P-v2.0/cfcae645-b850-a357-d33e-2c9cb4f651a9 8.392768 173.49789 20.67231 TRUE -28.76 NA 1.77 NA TRUE 3.293017 ug_cm2 FALSE { "parentSampleID": "BLDE.20190507.EPILITHON.2" } {"Chlorophyll": "corrected for pheophytin", "Taxonomy": "available in NEON DP1.20166.001 (https://data.neonscience.org/data-products/DP1.20166.001) for parentSampleID=BLDE.20190507.EPILITHON.2"}