eprscope

Overview

The key objective of this open source package is to bring handy functions corresponding to “everyday” data processing/analysis in the EPR (Electron Paramagnetic Resonance) spectroscopy mainly in chemistry. Similar tools like cwepr and the related projetcs have been developed, so far. The eprscope, as the first complex package 📦 for EPR, doesn’t want to replace the latter nor the excellent and standard EPR simulation/processing EasySpin Toolbox for MATLAB and its additional frameworks like SpecProFi or CW EPR Scripts by Emilien Etienne. Rather, it may be considered like a complementary 📦 or toolbox with practical functions which have to be otherwise performed by several proprietary tools. For instance, like acquisition/processing software, supplied by the EPR spectrometer manufacturers (see e.g. Xenon/WinEPR) as well as several other software platforms like the MS Office and/or Orgin/SigmaPlot/Igor which are often applied in the EPR processing/analysis workflow. Therefore, the eprscope tries to reduce such many steps/programs if the above-mentioned software combination would be adopted. In order to achieve the goal it uses superior power of the open source ecosystem that combines data processing, analysis and great scientific visualizations together with the extensive publishing capabilities by Rmarkdown and Quarto. Everything at one place (see the RStudio IDE) without the need to switch between or employ any other additional software.

Installation

Before the installation, please make sure that you have already followed instructions for the {nloptr} package installation depending on your operating system (OS). This package is required for the proper running of the eprscope optimization/fitting functions. Additionally, the function draw_molecule_by_rcdk() depends on the JDK Development Kit (JAVA), which must be installed on your desired OS as well.

# run code in the R console
#
# after the initial R environment setup (see below) it's always 
# good to install essential collection of packages for data science 
# with all their dependencies:
# install.packages("tidyverse",dependencies = TRUE)
# install.packages(
#   c("DT","vctrs","npreg","patchwork","kableExtra",
#     "htmlwidgets","webshot2","tinytable","gsignal"),
#   dependencies = TRUE
# )
#
# package can be installed using the following command =>
if (!require(devtools)) {install.packages("devtools")}
devtools::install_github("jatanRT/eprscope")
#
# alternatively, install package together with all the vignettes/articles:
# if (!require(devtools)) {install.packages("devtools")}
# devtools::install_github("jatanRT/eprscope",build_vignettes = TRUE)

Completely new users or people who haven’t already installed the R environment, please consult these steps, prior to own eprscope installation ➨

1. the R installation procedure

2. installation of the Rstudio IDE (alternatively, you may try its cloud version without the need for an installation)

3. the latest R tools release ONLY for WINDOWS OS

Additionally, the open-source scientific and technical publishing system Quarto together with the Pandoc, a document converter system, may be required for sharing the results coming from eprscope in desired formats like pdf , html , docx , pptx or tex (details may be found in the create_qmdReport_proj() documentation).

Updates

To update the eprscope 📦, just run the following code in the R console ➨

devtools::install_github("jatanRT/eprscope")
#
# update package together with vignettes/articles:
# devtools::install_github("jatanRT/eprscope",build_vignettes = TRUE)

Usage

In this section, couple of examples are shown in order to briefly demonstrate the package functionality. More detailed description can be found within the articles/vignettes or documentation examples.

Reading Files with Instrumental Parameters

# loading the package/library
library(eprscope)
#
# loading the built-in example file => "TMPD_specelchem_accu_b.par"
tmpd.params.file <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
#
# parameters into interactive table (data frame)
tmpd.params.dt <-
  readEPR_params_tabs(
    path_to_dsc_par = tmpd.params.file,
    origin = "winepr",
    interact = "params"
  )
#
# table preview
tmpd.params.dt

Depict Molecular Structures

# Pphenalenyl (Perinaphthenyl or PNT) radical by `SMILES` code:
# "C1([C.]23)=CC=CC2=CC=CC3=CC=C1"
draw_molecule_by_rcdk(
  molecule = "C1([C.]23)=CC=CC2=CC=CC3=CC=C1",
  mol.label = "Phenalenyl",
  mol.label.color = "black",
  mol.label.xy.posit = c(8.8, 1.2)
)

Simulation of Isotropic EPR Spectra

# simulation of the phenalenyl (perinaphthenyl or PNT) radical,
# see also https://pubs.rsc.org/en/content/articlelanding/2006/CS/b500509b,
# the additional experimental/instrumental parameters are not shown,
# they possess their default values => see corresponding documentation
# of the `eval_sim_EPR_iso()` function.
simulation.iso <-
  eval_sim_EPR_iso(
    g.iso = 2.0027,
    B.unit = "G",
    nuclear.system = list(
      list("1H", 3, 5.09), # 3 x A(1H) = 5.09 MHz
      list("1H", 6, 17.67) # 6 x A(1H) = 17.67 MHz
    ),
    lineGL.DeltaB = list(0.24, NULL) # linewidth in G
  )
#
# simulated spectrum preview, in the region from 3470 G to 3522 G
simulation.iso$plot + 
  ggplot2::coord_cartesian(xlim = c(3470, 3522))

Radical Kinetic Model Fitted onto the Experimental Data

# decay of a triarylamine radical cation right after 
# its generation by electrochemical potentiostatic oxidation 
# in TBAPF6/CH3CN, double integrals (Areas) vs time were 
# obtained by data pre-processing within the continuous 
# wave (CW) EPR spectrometer acquisition/processing software.
#
# loading the built-in example file with the instrumental parameters
triarylamine_rc_decay_dsc <-
  load_data_example(file = "Triarylamine_radCat_decay_a.DSC")
#
# loading the built-in example file with "Area" vs "time" data frame
triarylamine_rc_decay_txt <-
  load_data_example(file = "Triarylamine_radCat_decay_a.txt")
triarylamine_rc_decay_data <-
  readEPR_Exp_Specs(
    path_to_ASC = triarylamine_rc_decay_txt,
    header = TRUE,
    fill = TRUE,
    select = c(3, 7),
    col.names = c("time_s", "Area"),
    x.unit = "s",
    x.id = 1,
    Intensity.id = 2,
    qValue = 1700,
    data.structure = "others"
  ) %>% na.omit()
#
# fitting the experimental decay by 2R --> B kinetic model
# with "k1" rate constant and the corresponding partial
# rection order "alpha". "qvar0R" refers to the initial
# "quantitative variable" (such as concentration, double integral
# or number of radicals) of the triarylamine radical cation "R".
triarylamine_rc_decay_model <-
  eval_kinR_EPR_modelFit(
    data.qt.expr = triarylamine_rc_decay_data,
    model.react = "(r=2)R --> [k1] B",
    elementary.react = FALSE,
    params.guess = c(
      qvar0R = 0.019,
      k1 = 0.04,
      alpha = 1.9
    ),
    time.correct = TRUE,
    path_to_dsc_par = triarylamine_rc_decay_dsc,
    origin = "xenon"
  )
#
# graph preview
triarylamine_rc_decay_model$plot

#
# data frame/table, showing the obtained kinetic parameters
# by the non-linear fit and numeric solution
# of the Ordinary Differential Equations
triarylamine_rc_decay_model$df.coeffs
#>           Estimate    Std. Error    t value       Pr(>|t|)
#> qvar0R 0.018570037 5.7203136e-05 324.633198 4.3809413e-149
#> k1     0.060438055 5.4514583e-03  11.086585  6.1614969e-19
#> alpha  2.038206072 1.9676205e-02 103.587358 3.9216714e-101

Help, Questions and Contribution

There are several ways how to get help. If the users are already familiar with the R statistical language please, follow either the individual package function documentation or the corresponding articles/vignettes. These might be also considered as a kind of EPR spectroscopy and knowledge resources, particularly for students. In case you are completely new to R, there are couple of great tutorials enabling a quite straightforward diving into . Please, refer to e.g.

• R for Data Science (2e)

• ggplot2: Elegant Graphics for Data Analysis (3e)

• Advanced R

• POSIT Homepage

• R Crash Course

• Statology R Guides

• An Introduction to R

• R CODER

• Why should I use R ? (Series)

• R to Python Data Wrangling

• Official Contributed Documentation of R

• The Big Book of R

• Reproducible Research in R and Guides for the R-Cubed Courses

• Quarto - An Open Source Scientific and Technical Publishing System

• R for Non-Programmers: A Guide for Social Scientists

• YouTube Video Tutorials ➨

  • Introduction to R Programming for Excel Users

  • Bioinformatics and R Programming

  • R Programming 101

  • Equitable Equations

  • R Programming Full Course 2023

  • Plotting Anything with ggplot2

  • Riffomonas Project

  • Introduction to R for Beginners

  • Reproducible Research with R

  • R for Ecology

  • R Quarto

Even though the EPR spectroscopy is a quite complex field there are some introductory on-line materials which may help to start with this special magnetic resonance method ➨

• EasySpin Documentation + EasySpin Academy - YouTube (Video Series)

• EPR LibreTexts in Chemistry

• NMR Spectroscopy of Organic Compounds (Lesson 10)

• Bruker EPR Instruments

• EPR Everywhere - Webpage

• EPR Everywhere - Article

• Basic Concepts of EPR

Any additional questions, comments, remarks or issues can be addressed through several discussion channels like 📧 e-mail jantar40@protonmail.com or github issues on the github source page (see the contributing guide). In the future, there will be also a specialized Discord community channel to discuss the eprscope related topics. If somebody is able and interested in the package development, please refer to contributing guide.

Acknowledgements

I would like to express a deep gratitude to my colleagues from the NMR Spectroscopy Group of the Institute of Organic Chemistry and Biochemistry especially, Dr. Radek Pohl , Dr. Ondřej Socha and Dr. Martin Dračínský . Without the fruitful environment within the NMR Spectroscopy team it wouldn’t be possible to develop such a project like this. Also, I’d like to give a special thanks to my brother Dr. Peter Tarábek for his valuable comments and remarks.