knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
Isoreader supports several continuous flow IRMS data formats. This vignette shows some of the functionality for continuous flow files. For additional information on operations more generally (caching, combining read files, data export, etc.), please consult the operations vignette. For details on downstream data processing and visualization, see the isoprocessor package.
# load isoreader package library(isoreader)
Reading continuous flow files is as simple as passing one or multiple file or folder paths to the
iso_read_continuous_flow() function. If folders are provided, any files that have a recognized continuous flow file extensions within those folders will be processed (e.g. all
.iarc). Here we read several files that are bundled with the package as examples (and whose paths can be retrieved using the
iso_get_reader_example() function). Note that some of the files (.cf, .dxf) are individual analysis files whereas others (.iarc) are collections of several files.
# all available examples iso_get_reader_examples() %>% knitr::kable()
# read a few of the continuous flow examples cf_files <- iso_read_continuous_flow( iso_get_reader_example("continuous_flow_example.cf"), iso_get_reader_example("continuous_flow_example.iarc"), iso_get_reader_example("continuous_flow_example.dxf") )
cf_files variable now contains a set of isoreader objects, one for each file. Take a look at what information was retrieved from the files using the
cf_files %>% iso_get_data_summary() %>% knitr::kable()
In case there was any trouble with reading any of the files, the following functions provide an overview summary as well as details of all errors and warnings, respectively. The examples here contain no errors but if you run into any unexpected file read problems, please file a bug report in the isoreader issue tracker.
cf_files %>% iso_get_problems_summary() %>% knitr::kable() cf_files %>% iso_get_problems() %>% knitr::kable()
Detailed file information can be aggregated for all isofiles using the
iso_get_file_info() function which supports the full select syntax of the dplyr package to specify which columns are of interest (by default, all file information is retrieved). Additionally, file information from different file formats can be renamed to the same column name for easy of downstream processing. The following provides a few examples for how this can be used (the names of the interesting info columns may vary between different file formats):
# all file information cf_files %>% iso_get_file_info(select = c(-file_root)) %>% knitr::kable() # select file information cf_files %>% iso_get_file_info( select = c( # rename sample id columns from the different file types to a new ID column ID = `Identifier 1`, ID = `Name`, # select columns without renaming Analysis, `Peak Center`, `H3 Factor`, # select the time stamp and rename it to `Date & Time` `Date & Time` = file_datetime ), # explicitly allow for file specific rename (for the new ID column) file_specific = TRUE ) %>% knitr::kable()
Rather than retrieving specific file info columns using the above example of
iso_get_file_info(select = ...), these information can also be modified across an entire collection of isofiles using the
iso_rename_file_info() functions. For example, the above example could be similarly achieved with the following use of
# select + rename specific file info columns cf_files2 <- cf_files %>% iso_select_file_info( ID = `Identifier 1`, ID = `Name`, Analysis, `Peak Center`, `H3 Factor`, `Date & Time` = file_datetime, # recode to the same name in different files `Sample Weight` = `Identifier 2`, `Sample Weight` = `EA Sample Weight`, file_specific = TRUE ) # fetch all file info cf_files2 %>% iso_get_file_info() %>% knitr::kable()
Any collection of isofiles can also be filtered based on the available file information using the function
iso_filter_files. This function can operate on any column available in the file information and supports full dplyr syntax.
# find files that have 'acetanilide' in the new ID field cf_files2 %>% iso_filter_files(grepl("acetanilide", ID)) %>% iso_get_file_info() %>% knitr::kable() # find files that were run since 2015 cf_files2 %>% iso_filter_files(`Date & Time` > "2015-01-01") %>% iso_get_file_info() %>% knitr::kable()
The file information in any collection of isofiles can also be mutated using the function
iso_mutate_file_info. This function can introduce new columns and operate on any existing columns available in the file information (even if it does not exist in all files) and supports full dplyr syntax. It can also be used in conjunction with
iso_with_unit to generate values with implicit units.
cf_files3 <- cf_files2 %>% iso_mutate_file_info( # update existing column ID = paste("ID:", ID), # introduce new column `Run since 2015?` = `Date & Time` > "2015-01-01", # parse weight as a number and turn into a column with units `Sample Weight` = `Sample Weight` %>% parse_number() %>% iso_with_units("mg") ) cf_files3 %>% iso_get_file_info() %>% iso_make_units_explicit() %>% knitr::kable()
Additionally, a wide range of new file information can be added in the form of a data frame with any number of columns (usually read from a comma-separated-value/csv file or an Excel/xlsx file) using the function
iso_add_file_info and specifying which existing file information should be used to merge in the new information. It is similar to dplyr's left_join but with additional safety checks and the possibility to join the new information sequentially as illustrated below.
# this kind of information data frame is frequently read in from a csv or xlsx file new_info <- dplyr::bind_rows( # new information based on new vs. old samples dplyr::tribble( ~file_id, ~`Run since 2015?`, ~process, ~info, NA, TRUE, "yes", "new runs", NA, FALSE, "yes", "old runs" ), # new information for a single specific file dplyr::tribble( ~file_id, ~process, ~note, "6617_IAEA600", "no", "did not inject properly" ) ) new_info %>% knitr::kable() # adding it to the isofiles cf_files3 %>% iso_add_file_info(new_info, by1 = "Run since 2015?", by2 = "file_id") %>% iso_get_file_info(select = !!names(new_info)) %>% knitr::kable()
Most file information is initially read as text to avoid cumbersome specifications during the read process and compatibility issues between different IRMS file formats. However, many file info columns are not easily processed as text. The isoreader package therefore provides several parsing and data extraction functions to facilitate processing the text-based data (some via functionality implemented by the readr package). See code block below for examples. For a complete overview, see the
# use parsing and extraction in iso_mutate_file_info cf_files2 %>% iso_mutate_file_info( # change type of Peak Center to logical `Peak Center` = parse_logical(`Peak Center`), # retrieve first word of file_id file_id_1st = extract_word(file_id), # retrieve second word of ID column file_id_2nd = extract_word(file_id, 2), # retrieve file extension from the file_id using regular expression name = extract_substring(ID, "(\\w+)-?(.*)?", capture_bracket = 1) ) %>% iso_get_file_info(select = c(matches("file_id"), ID, name, `Peak Center`)) %>% knitr::kable() # use parsing in iso_filter_file_info cf_files2 %>% iso_filter_files(parse_number(`H3 Factor`) > 2) %>% iso_get_file_info() %>% knitr::kable() # use iso_parse_file_info for simplified parsing of column data types cf_files2 %>% iso_parse_file_info( integer = Analysis, number = `H3 Factor`, logical = `Peak Center` ) %>% iso_get_file_info() %>% knitr::kable()
Additionally, some IRMS data files contain resistor information that are useful for downstream calculations (see e.g. section on signal conversion later in this vignette):
cf_files %>% iso_get_resistors() %>% knitr::kable()
As well as isotopic reference values for the different gases:
# reference delta values without ratio values cf_files %>% iso_get_standards(file_id:reference) %>% knitr::kable() # reference values with ratios cf_files %>% iso_get_standards() %>% knitr::kable()
The raw data read from the IRMS files can be retrieved similarly using the
iso_get_raw_data() function. Most data aggregation functions also allow for inclusion of file information using the
include_file_info parameter, which functions identically to the
select parameter of the
iso_get_file_info function discussed earlier.
# get raw data with default selections (all raw data, no additional file info) cf_files %>% iso_get_raw_data() %>% head(n=10) %>% knitr::kable() # get specific raw data and add some file information cf_files %>% iso_get_raw_data( # select just time and the m/z 2 and 3 ions select = c(time.s, v2.mV, v3.mV), # include the Analysis number fron the file info and rename it to 'run' include_file_info = c(run = Analysis) ) %>% # look at first few records only head(n=10) %>% knitr::kable()
The isoreader package is intended to make raw stable isotope data easily accessible. However, as with most analytical data, there is significant downstream processing required to turn these raw intensity chromatograms into peak-specific, properly referenced isotopic measurements. This and similar functionality as well as data visualization is part of the isoprocessor package which takes isotopic data through the various corrections in a transparent, efficient and reproducible manner.
That said, most vendor software also performs some of these calculations and it can be useful to be able to compare new data reduction procedures against those implemented in the vendor software. For this purpose, isoreader retrieves vendor computed data tables whenever possible, as illustrated below.
As with most data retrieval functions, the
iso_get_vendor_data_table() function also allows specific column selection (by default, all columns are selected) and easy addition of file information via the
include_file_info parameter (by default, none is included).
# entire vendor data table cf_files %>% iso_get_vendor_data_table() %>% knitr::kable() # get specific parts and add some file information cf_files %>% iso_get_vendor_data_table( # select peak number, ret. time, overall intensity and all H delta columns select = c(Nr., Rt, area = `rIntensity All`, matches("^d \\d+H")), # include the Analysis number fron the file info and rename it to 'run' include_file_info = c(run = Analysis) ) %>% knitr::kable() # the data table also provides units if included in the original data file # which can be made explicit using the function iso_make_units_explicit() cf_files %>% iso_get_vendor_data_table( # select peak number, ret. time, overall intensity and all H delta columns select = c(Nr., Rt, area = `rIntensity All`, matches("^d \\d+H")), # include the Analysis number fron the file info and rename it to 'run' include_file_info = c(run = Analysis) ) %>% # make column units explicit iso_make_units_explicit() %>% knitr::kable()
For users familiar with the nested data frames from the tidyverse (particularly tidyr's
unnest), there is an easy way to retrieve all data from the iso file objects in a single nested data frame:
all_data <- cf_files %>% iso_get_all_data() # not printed out because this data frame is very big
Saving entire collections of isofiles for retrieval at a later point is easily done using the
iso_save function which stores collections or individual isoreader file objects in the efficient R data storage format
.rds (if not specified, the extension
.cf.rds will be automatically appended). These saved collections can be conveniently read back using the same
iso_read_continuous_flow command used for raw data files.
# export to R data archive cf_files %>% iso_save("cf_files_export.cf.rds") # read back the exported R data archive cf_files <- iso_read_continuous_flow("cf_files_export.cf.rds") cf_files %>% iso_get_data_summary() %>% knitr::kable()
At the moment, isoreader supports export of all data to Excel and the Feather file format (a Python/R cross-over format). Note that both export methods have similar syntax and append the appropriate file extension for each type of export file (
# export to excel cf_files %>% iso_export_to_excel("cf_files_export") # data sheets available in the exported data file: readxl::excel_sheets("cf_files_export.cf.xlsx")
# export to feather cf_files %>% iso_export_to_feather("cf_files_export") # exported feather files list.files(pattern = ".cf.feather")
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.