-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.Rmd
106 lines (74 loc) · 8.22 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
version <- as.character(packageVersion("isoreader"))
```
# isoreader <a href='https://isoreader.isoverse.org'><img src='man/figures/isoreader_logo_thumb.png' align="right" height="138.5"/></a>
<!-- badges: start -->
[](https://github.com/isoverse/isoreader/actions?workflow=R-CMD-check)
[](https://isoreader.isoverse.org/)
[](https://doi.org/10.21105/joss.02878)
<!-- badges: end -->
## About
This package is intended as a unified one-stop command line interface to all common IRMS (isotope ratio mass spectrometry) file formats used in stable isotope geochemistry. It is an extension and highly stream-lined re-implementation of the proof-of-concept [isoread](https://github.com/sebkopf/isoread) package and is designed to fit into a larger framework of IRMS data tools that includes the web-based graphical user interface package [isoviewer](https://github.com/isoverse/isoviewer) and the data processing and visualization pipeline [isoprocessor](https://github.com/isoverse/isoprocessor).
[isoreader](https://isoreader.isoverse.org/) enables the reading and processing of stable isotope data directly from the data files and thus provides a tool for platform-independent (Windows, Mac, Linux), efficient and reproducible data reduction. Although implemented in R, it can be used in both RMarkdown as well as Jupyter data processing notebooks and also provides functionality for easy export to Python using the shared R/Python feather file format. At present, it can read most Thermo dual inlet (.did, .caf) and continuous flow (.dxf, .cf) data files as well as Elementar continuous flow data archives (.iarc) with additional extensions for other file formats in the works. Due to the dynamic implementation and design based on the popular [tidyverse](https://www.tidyverse.org/) style of R programming, isoreader is easily extendable, takes care of error catching to avoid pipeline breaks due to problems encountered in source data files (modeled after [readr](https://readr.tidyverse.org/)) and works great with [tidyverse](https://www.tidyverse.org/) packages such as [tidyr](https://tidyr.tidyverse.org/), [dplyr](https://dplyr.tidyverse.org/) and [ggplot](https://ggplot2.tidyverse.org/).
## Installation
```{r cran-installation, eval = FALSE}
# Note: isoreader is temporarily not available on CRAN because of a missing dependency, please install directly from GitHub using the commands below
# install.packages("isoreader")
if(!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
devtools::install_github("isoverse/isoreader")
```
Some isoreader features including Excel and feather export depend on optional packages that are not required for the core functionality of isoreader. To use this functionality, please install the following packages manually if not already installed (isoreader will throw an informative warning if they are needed but missing):
```{r, optional-installation, eval = FALSE}
# optional extensions
install.packages(c("feather", "openxlsx", "xml2", "BiocManager"))
BiocManager::install("rhdf5")
```
To install the current development version of isoreader directly from GitHub, please use the devtools package:
```{r gh-installation, eval = FALSE}
# installs the development tools package if not yet installed
if(!requireNamespace("devtools", quietly = TRUE)) install.packages("devtools")
devtools::install_github("isoverse/isoreader")
```
Troubleshooting note: depending on your workspace and operating system, you may have to re-start your R session or manually install some dependencies. For example, the `digest` package sometimes causes trouble - re-install with `remove.packages("digest"); install.packages("digest")`.
## Show me some code
You can, for example, automatically read the data from **all** supported scan files in a directory (and all its subdirectories) simply by providing the path to the folder. The following code demonstrates this with the example data files bundled with the `isoreader` package. For a more detailed example including continuous flow and dual inlet file reads, check out our [**Quick Start Vignette**](https://isoreader.isoverse.org/articles/quick_start.html).
```{r, message = -c(1:3), echo = -c(2:3)}
library(isoreader)
iso_turn_reader_caching_off() # make sure reading fresh
setwd(tempdir()) # make sure no wd artifacts
data_folder <- iso_get_reader_examples_folder()
iso_files <- iso_read_scan(data_folder)
iso_files
```
## Supported File Types
Currently supported file types:
```{r, echo=FALSE, warning=FALSE, message=FALSE}
library(isoreader)
iso_get_supported_file_types() |>
dplyr::select(-"call") |>
knitr::kable()
```
## Documentation
- for a quick introduction, check out the aforementioned [**Quick Start Vignette**](https://isoreader.isoverse.org/articles/quick_start.html)
- for a full reference of all available functions, see the **[Function Reference](https://isoreader.isoverse.org/reference/)**
- for function help within RStudio, simply start typing `?iso_` in the console and a list of available function will appear (all functions share the `iso_` prefix)
- for a detailed example of how to work with continuous flow data files, see the vignette on **[Continuous Flow](https://isoreader.isoverse.org/articles/continuous_flow.html)**
- for a detailed example of how to work with dual inlet data files, see the vignette on **[Dual Inlet](https://isoreader.isoverse.org/articles/dual_inlet.html)**
- for a detailed example of how to work with scan data files, see the vignette on **[Scans](https://isoreader.isoverse.org/articles/scan.html)**
## Troubleshooting
If you run into a file format that is not currently supported or any issues with supported formats, please file a request/bug report in the [issue tracker](https://github.com/isoverse/isoreader/issues). Likewise if you run into any unexpected behavior or uncaught errors. Most isoreader functionality is continuously tested on Unix and Windows systems using [GitHub Actions](https://github.com/isoverse/isoreader/actions?workflow=R-CMD-check). This makes it possible to ensure proper functionality and catch issues quickly, however, sometimes something slips through or is not yet automatically tested. We try to make sure to fix such errors as soon as possible but ask for patience due to the small development team. If you have the skills and are willing to fix problems yourself, that's great, please take a look at the development section below.
## Development
If you are interested in helping with development, that's fantastic! Please fork the repository and branch off from the [dev branch](https://github.com/isoverse/isoreader/tree/dev) since it contains the most up-to-date development version of [isoreader](https://isoreader.isoverse.org/). Make sure to write [```testthat``` tests](https://r-pkgs.org/tests.html) for your work (stored in the tests/testthat directory). All tests can be run automatically and continuously during development to make it easier to spot any code problems on the go. The easiest way to run them is by running ```make auto_test``` in the [isoreader](https://isoreader.isoverse.org/) directory from command line (it will test everything automatically in a completely separate R session).
## Open Source
[isoreader](https://isoreader.isoverse.org/) is and will always be fully open-source (i.e. free as in **freedom** and free as in **free beer**) and is provided as is. The source code is released under GPL-2.
## isoverse <a href='https://www.isoverse.org'><img src='man/figures/isoverse_logo_thumb.png' align="right" height="138.5"/></a>
This package is part of the isoverse suite of data tools for stable isotopes. If you like the functionality that isoverse packages provide to the geochemical community, 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](https://github.com/isoverse/logos).