Read Stable Isotope Data Files • isoreader2

Overview

This package provides easy access to common IRMS (isotope ratio mass spectrometry) file formats, enabling the reading and processing of stable isotope data directly from the data files for platform-independent (Windows, Mac, Linux), efficient, and reproducible data reduction.

isoreader2 succeeds the isoreader package with a completely new architecture built around the isoextract command-line tool. This makes isoreader2 significantly faster, and more versatile with support for the following file formats:

Extension	Measurement type	Produced by
`.dxf`	Continuous flow	Thermo Fisher Isodat
`.cf`	Continuous flow (legacy)	Thermo Fisher Isodat
`.bch`	Continuous flow	SerCon Callisto
`.iarc`	Continuous flow	Elementar IonOS
`.larc`	Continuous flow	Elementar LyticOS
`.imexp`	Continuous flow	Thermo Fisher Qtegra
`.did`	Dual inlet	Thermo Fisher Isodat
`.caf`	Dual inlet (legacy)	Thermo Fisher Isodat
`.scn`	Scan	Thermo Fisher Isodat

Installation

isoreader2 is not yet on the Comprehensive R Archive Network (CRAN) but you can install the latest version from GitHub as shown below. If you are on Windows, make sure to install the equivalent version of Rtools for your version of R (e.g. for the latest R 4.5 and 4.6, use RTools4.5 - you can find out which version you have with getRversion() from an R console).

# checks that you are set up to build R packages from source
if (!requireNamespace("pkgbuild", quietly = TRUE)) {
  install.packages("pkgbuild")
}
pkgbuild::check_build_tools()

# installs the latest isoreader2 package from GitHub
if (!requireNamespace("pak", quietly = TRUE)) {
  install.packages("pak")
}
pak::pak("isoverse/isoreader2")

# check/install isoextract
isoreader2::ir_check_isoextract()

Show me some code

# load library
library(isoreader2)

# copy the bundled example files into a local "examples" folder
data_folder <- ir_copy_examples()

# load data
dataset <-
  data_folder |>
  ir_find_continuous_flow() |>
  ir_read_isofiles() |>
  ir_aggregate_isofiles("mV")

# visualize data for each file
dataset |> ir_plot_continuous_flow(facet = file_name)

Plot of continuous flow examples

# visualize CO2 with ratios and a specific time window
dataset |>
  ir_calculate_ratios(normalize_ratios = median) |>
  ir_plot_continuous_flow(
    species = "CO2",
    time_window.min = c(4.5, 8.5)
  )

Time slice of continuous flow examples with ratios

Show me more details

Read isotope data files

# load library
library(isoreader2)

# specify where the data files are located (relative or absolute path)
data_folder <- "examples"

# search for dual inlet files (all known file types) in that folder
# (or use ir_find_continuous_flow or ir_find_scans instead)
file_paths <- data_folder |> ir_find_dual_inlet()

# read the files
isofiles <- file_paths |> ir_read_isofiles()

✔ [89ms] ir_extract_isofiles() finished extracting 1 file/archive

✔ [209ms] ir_read_isofiles() finished reading 1 isotope data file/archive

# show information about the files
isofiles

─────── 1 isofile with 1 analysis - process with ir_aggregate_isofiles() ───────

1. caf_dual_inlet_example.caf: with 8 sample/standard cycles for CO2clump
(masses 44, 45, 46, 47, 48, and 49); 21 metadata columns

Aggregate the data

# aggregate the data from the read files specifying which units to use
# (mV, V, nA, A, cps, etc.), conversion via resistor values happens automatically
dataset <- isofiles |> ir_aggregate_isofiles("V")

✔ [41ms] ir_aggregate_isofiles() aggregated metadata (1) and cycles (102,
intensity in V) from 1 file using the standard aggregator

# show the available data that was aggregated  metadata is all the available
# sequence information from the different file types
dataset

─ aggregated data from 1 isofiles with 1 analysis - retrieve with ir_get_data( ─

→ metadata (1): uidx, file_path, file_name, analysis, timestamp, type,
h3_factor (all NA), Line, Peak Center, Pressadjust, Background, Reference
Refill, Weight [mg], Sample, Identifier 1, Identifier 2, Analysis, Comment,
Preparation, Pre Script, Post Script, Method

→ cycles (102): uidx, analysis, species, cycle, type, mass, intensity.V; (not
aggregated: channel)

→ problems: has no issues

Visualize the data

# filter the data by a metadata field and mass range and plot it
# (use ir_plot_continuous_flow() and ir_plot_scans(), respectively)
library(ggplot2)
dataset |>
  ir_filter_metadata(file_name == "caf_dual_inlet_example") |>
  ir_calculate_ratios() |>
  ir_plot_dual_inlet(mass = c(44:48)) +
  # use ggplot2 to modify with custom theming (or any other ggplot elements)
  theme(strip.text = element_text(size = 30))

✔ [3ms] ir_calculate_ratios() calculated 85 ratios and added ratio_name and
ratio columns to the cycles

Plot of dual inlet examples

Export the data

# get the data of interest (here, metadata and dual inlet cycles data)
# and export both into one excel file (one sheet per data set)
ir_export_to_excel(
  metadata = dataset |> ir_get_metadata(),
  cycles = dataset |> ir_get_cycles(),
  file = "my_export.xlsx"
)

✔ [2ms] ir_get_data() retrieved 1 records from metadata

✔ [3ms] ir_get_data() retrieved 102 records from the combination of metadata
(1) and cycles (102) via uidx and analysis

✔ [188ms] ir_export_to_excel() exported 1 row of metadata and 102 rows of
cycles to my_export.xlsx

Bonus: explore isofiles interactively

# you can also use the isoexplorer package to explore isofiles
# interactively and generate visualization code from the GUI
# (use ie_explore_continuous_flow/dual_inlet/scans)
if (!requireNamespace("isoexplorer", quietly = TRUE)) {
  pak::pak("isoverse/isoexplorer")
}
example_files <- ir_copy_examples() |> ir_find_isofiles() |> ir_read_isofiles()
example_files |> isoexplorer::ie_explore_continuous_flow()

Isoexplorer screenshot

Package structure

Click on the individual functions to jump straight to their documenation.

Getting help

If you encounter a bug, please file an issue with a minimal reproducible example on GitHub. Example files are very helpful for fixing bugs so please consider including an example data file (you will have to attach it as a zip archive).

isoverse

This package is part of the isoverse suite of data tools for stable isotopes. If you like the functionality that isoverse packages provide, please help us spread the word and include an isoverse or individual package logo on one of your posters or slides. All logos are posted in high resolution in this repository. If you have suggestions for new features or other constructive feedback, please let us know on this short feedback form.

Funding

This project is supported by a grant from the US National Science Foundation (EAR-2411458) to Sebastian Kopf.