v004-element-ratios.Rmd

---
title: "Computation with element contents - unit conversion, element ratios, nominal oxidation state of carbon, oxidative ratio, and degree of unsaturation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{v004-element-ratios}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: "./../inst/REFERENCES.bib"
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
# packages
library(elco)
library(magrittr)
library(dplyr)
library(tibble)
```

# Introduction

This vignette shows how to:

1. Convert the units of element ratios.

2. Compute element ratios for different elements.

3. Compute the nominal oxidation state of carbon (C$_\textrm{ox}$), the oxidative ratio (OR), and the degree of unsaturation.

# Data

Load the example data (simulated CHNO content data and sample masses for five samples):

```{r data}
d <- elco::chno
```

# Unit conversion

Objects of class `elco` may have simple units that represent masses (e.g. g, mg, ...) or molar amounts (e.g. mol, mmol, ...). Moreover, they may have fractional units composed of these simple units, e.g. g/g, mol/g, ... . `elco_el_convert` converts between all these units, automatically taking into account if such a conversion requires multiplication with or division by the molar mass of an element or the mass of the sample. A few examples:

```{r unit-conversion1}
# from g/g to g
elco::elco_elco_convert(d$C, to = "g", sample_mass = d$sample_mass)

# from g/g to mol
elco::elco_elco_convert(d$C, to = "mol", sample_mass = d$sample_mass)

# from g/g to mol/g
elco::elco_elco_convert(d$C, to = "mol/g", sample_mass = NULL)

# from mol to g/g
elco::elco_elco_convert(d$C, to = "mol", sample_mass = d$sample_mass) %>%
  elco::elco_elco_convert(to = "g/g", sample_mass = d$sample_mass)
```

If, for a conversion, the sample mass is requires, as for example from g/g to mol, the sample mass has to be provided as argument `sample_mass`. If this is not the case, the function will throw an error:

```{r unit-conversion2, error=TRUE}
# from g/g to mol/g: sample_mass not needed 
elco::elco_elco_convert(d$C, to = "mol/g", sample_mass = NULL)

# from g/g to g: sample_mass needed 
elco::elco_elco_convert(d$C, to = "g", sample_mass = NULL)

# from g/g to g: sample_mass needed 
elco::elco_elco_convert(d$C, to = "g", sample_mass = d$sample_mass)
```

# Element ratios

Element ratio are easily computed:

```{r element-ratios1}
# compute the C:N ratio (masses)
d <- 
  d %>%
  dplyr::mutate(cn = C/N)
```

During this, the `elco` class attributes are lost since the result is no element content any more. The result keeps the units and errors:

```{r element-ratios2}
class(d$cn)
d$cn
```

If one wishes to compute other element ratios, e.g. molar ratios, one has to convert the respective units beforehand:
```{r element-ratios3}
# compute the C:N ratio (molar)
d <- 
  d %>%
  dplyr::mutate(cn_molar = elco::elco_elco_convert(C, to = "mol/g")/elco::elco_elco_convert(N, to = "mol/g"))

# plot both C:N ratios for comparison
plot(errors::drop_errors(d$cn) ~ errors::drop_errors(d$cn_molar))
```

`elco_elco_convert_df` makes unit conversion and computation of many element ratios much easier. It converts the units of all `elco` columns in a `data.frame` to a specified unit:

```{r element-ratios4}
# convert all elcos to mol
d_mol <-  
  d %>%
  elco::elco_elco_convert_df(to = "mol", sample_mass = d$sample_mass)

# all elcos in mol now:
d_mol

# easier computation of many element ratios
d <- 
  d %>%
  elco::elco_elco_convert_df(to = "mol", sample_mass = d$sample_mass) %>%
  dplyr::mutate(cn_molar = C/N,
                ch_molar = C/H,
                co_molar = C/O)

# plot C:N ~ C:O
plot(errors::drop_errors(d$cn_molar) ~ errors::drop_errors(d$co_molar))

```

# C$_\textrm{ox}$, OR, and degree of unsaturation

Functions `elco_nosc`, `elco_or`, and `elco_du` enable the computation of the C$_\textrm{ox}$, OR, and degree of unsaturation, respectively [@Worrall.2016b].

```{r nosc1}
# compute nosc, or, and du
d <- 
  d %>%
  elco::elco_elco_convert_df(to = "mol", sample_mass = d$sample_mass) %>%
  dplyr::mutate(
    nosc = elco_nosc(C, H, N, O),
    or = elco_or(C, H, N, O),
    du = elco_du(C, H, N)
  )

# show result
head(d %>% dplyr::select(nosc, or, du))
```

As shown, this requires that all element contents are given as molar amounts
```{r nosc2, error = TRUE}
# reconvert to mass
d <- 
  d %>%
  elco::elco_elco_convert_df(to = "g/g", sample_mass = d$sample_mass)

# this throws errors:
with(d, elco_nosc(C, H, N, O))
with(d, elco_or(C, H, N, O))
with(d, elco_du(C, H, N))
```

## License

<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />This Rmarkdown template is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.

Title: Computation with element contents - unit conversion, element ratios, nominal oxidation state of carbon, oxidative ratio, and degree of unsaturation <br>
Author: Henning Teickner <br>
Date: 2020-10-01 <br>

## Session Info
```{r session-info}
sessionInfo()
```

## References