Package 'eprscope' reference manual

Title:	Processing and Analysis of Electron Paramagnetic Resonance Data and Spectra in Chemistry
Description:	Processing, analysis and plottting of Electron Paramagnetic Resonance (EPR) spectra in chemistry. Even though the package is mainly focused on continuous wave (CW) EPR/ENDOR, many functions may be also used for the integrated forms of 1D PULSED EPR spectra. It is able to find the most important spectral characteristics like g-factor, linewidth, maximum of derivative or integral intensities and single/double integrals. This is especially important in spectral (time) series consisting of many EPR spectra like during variable temperature experiments, electrochemical or photochemical radical generation and/or decay. Package also enables processing of data/spectra for the analytical (quantitative) purposes. Namely, how many radicals or paramagnetic centers can be found in the analyte/sample. The goal is to evaluate rate constants, considering different kinetic models, to describe the radical reactions. The key feature of the package resides in processing of the universal ASCII text formats (such as '.txt', '.csv' or '.asc') from scratch. No proprietary formats are used (except the MATLAB EasySpin outputs) and in such respect the package is in accordance with the FAIR data principles. Upon 'reading' (also providing automatic procedures for the most common EPR spectrometers) the spectral data are transformed into the universal R 'data frame' format. Subsequently, the EPR spectra can be visualized and are fully consistent either with the 'ggplot2' package or with the interactive formats based on 'plotly'. Additionally, simulations and fitting of the isotropic EPR spectra are also included in the package. Advanced simulation parameters provided by the MATLAB-EasySpin toolbox and results from the quantum chemical calculations like g-factor and hyperfine splitting/coupling constants (a/A) can be compared and summarized in table-format in order to analyze the EPR spectra by the most effective way.
Authors:	Ján Tarábek [aut, cre]
Maintainer:	Ján Tarábek <[email protected]>
License:	GPL (>= 3) + file LICENSE
Version:	0.1.12
Built:	2025-02-06 06:14:34 UTC
Source:	https://github.com/jatanrt/eprscope

Convert Coupling Constants into Splitting Ones.

Description

Converting hyperfine coupling constants (HFCCs, $A$ values in MHz) into hyperfine splitting ones (HFSCs, $a$ values in mT).

Usage

convert_A_MHz_2a(A.MHz, g.val = 2.0023193)
convert_A_MHz_2a(A.MHz, g.val = 2.0023193)

Arguments

`A.MHz`	Numeric value/vector, corresponding to HFCCs in `MHz`.
`g.val`	Numeric value/vector, corresponding to actual $g$ -factor (`unitless`). Default: `g.val = 2.00231930` (corresponding to free electron).

Details

Conversion done according to following relation:

$a = A\,h / (g\,\mu_{\text{B}})$

where $h$ corresponds to Planck's constant and $\mu_{\text{B}}$ to Bohr's magneton. Both latter are obtained by constans::syms$h and constants::syms$mub, respectively, using the constants package (see syms). Conversion is suitable for the EPR simulations and/or ENDOR.

Value

Numeric value/vector corresponding to HFSCs ( $a$ ) in mT.

Examples

convert_A_MHz_2a(A.MHz = 16)
#
convert_A_MHz_2a(20,2.0059)
#
convert_A_MHz_2a(4,g.val = 2.0036)


convert_A_MHz_2a(A.MHz = 16)
#
convert_A_MHz_2a(20,2.0059)
#
convert_A_MHz_2a(4,g.val = 2.0036)

Convert Splitting Constants into Coupling Ones.

Description

Converting hyperfine splitting constants (HFSCs, $a$ values in mT) into hyperfine coupling ones (HFCCs, $A$ values in MHz).

Usage

convert_a_mT_2A(a.mT, g.val = 2.0023193)
convert_a_mT_2A(a.mT, g.val = 2.0023193)

Arguments

`a.mT`	Numeric value/vector of HFSCs in `mT` ('line distances' from EPR spectrum)
`g.val`	Numeric value/vector, corresponding to actual $g$ -factor (`unitless`). Default: `g.val = 2.00231930` (corresponding to free electron).

Details

Conversion done according to following relation:

$A = (a\,g\,\mu_{\text{B}}) / h$

Value

Numeric value/vector corresponding to HFCCs ( $A$ ) in MHz.

Examples

convert_a_mT_2A(a.mT = 0.5)
#
convert_a_mT_2A(0.6,2.0059)
#
convert_a_mT_2A(0.15,g.val = 2.00036)


convert_a_mT_2A(a.mT = 0.5)
#
convert_a_mT_2A(0.6,2.0059)
#
convert_a_mT_2A(0.15,g.val = 2.00036)

Conversion of Magnetic Flux Density

Description

Conversion of magnetic flux density/field (B) values depending on the input and the required output units.

Usage

convert_B(B.val, B.unit, B.2unit)
convert_B(B.val, B.unit, B.2unit)

Arguments

`B.val`	Numeric value/vector, corresponding to input value(s) of magnetic flux density.
`B.unit`	Character string, referring to input magnetic flux density units. Usually `T`, `mT` or `G` are used.
`B.2unit`	Character string, referring to output magnetic flux density units. Usually `T`, `mT` or `G` are used.

Value

Numeric value or vector as a result of the B conversion. Depending on the output unit (B.2unit) the values are rounded to:

B.2unit = "T": 7 decimal places
B.2unit = "mT": 4 decimal places
B.2unit = "G": 3 decimal places

Examples

## simple conversion:
convert_B(B.val = 3500,B.unit = "G",B.2unit = "T")
#
## conversion of B.seq vector with the Sweep Width = 100 G
## and the central field 3496 G :
B.seq <- seq(3496-100/2,3496+100/2,length.out = 1024)
Bnew <- convert_B(B.seq,B.unit = "G",B.2unit = "mT")
head(as.matrix(Bnew),n = 20)


## simple conversion:
convert_B(B.val = 3500,B.unit = "G",B.2unit = "T")
#
## conversion of B.seq vector with the Sweep Width = 100 G
## and the central field 3496 G :
B.seq <- seq(3496-100/2,3496+100/2,length.out = 1024)
Bnew <- convert_B(B.seq,B.unit = "G",B.2unit = "mT")
head(as.matrix(Bnew),n = 20)

Convert Time $t$ into Variable Linearly Depending on $t$ .

Description

Conversion of time ( $t$ ) into variable ( $var$ ) which is linearly changed on time.

Usage

convert_time2var(
  time.vals,
  time.unit = "s",
  var0,
  var.switch = NULL,
  var.rate,
  var.rate.unit = "s^{-1}"
)
convert_time2var(
  time.vals,
  time.unit = "s",
  var0,
  var.switch = NULL,
  var.rate,
  var.rate.unit = "s^{-1}"
)

Arguments

`time.vals`	Numeric value or vector, corresponding to time (points) where the variable `var` is changed.
`time.unit`	Character string, time unit defined by `s`,`min` or `h`. Default: `time.unit = "s"`.
`var0`	Numeric, the initial value (ALSO WITH NEGATIVE SIGN, if required, e.g. negative electrochemical potential).
`var.switch`	Numeric, the switching point `var` value, in case when a linear CYCLIC CHANGE (or 'triangular ramp') of `var` on time is applied (e.g. in cyclic voltammetry). Default: `var.switch = NULL` (in case there is no such cyclic change).
`var.rate`	Numeric, corresponding to rate of linear `var` change (INCLUDING ALSO NEGATIVE SIGN, if required, e.g. in the case of electrochemical reduction or sample cooling).
`var.rate.unit`	Character string, corresponding to `var.rate` unit defined by following strings `"s^{-1}"` $\equiv \text{s}^{-1}$ , `"min^{-1}"` $\equiv \text{min}^{-1}$ or `"h^{-1}"` $\equiv \text{h}^{-1}$ . Default: `var.rate.unit = "s^{-1}"`.

Details

The linear time change of $var$ can be expressed like

$var = var0 + rate~ t$

This is especially suitable for time conversion of EPR time series experiments (see e.g. readEPR_Exp_Specs_kin) simultaneously performed either during electrochemical/voltammetric or variable temperature experiment. When cyclic series experiment is performed (e.g. cyclic voltammetry), that $var$ value depends on the switching one, like =>

$var = var0 + rate~ t ~~ \text{for} ~~ t \leq t_{\text{switch}}$

$var = var_{\text{switch}} - rate\, (t - t_{\text{switch}}) ~~ \text{for} ~~ t \geq t_{\text{switch}}$

where the $t_{\text{switch}}$ , corresponding to $var_{\text{switch}}$ , are the quantities at the turning point( see also var.switch argument).

Value

Numeric value or vector of the variable such as electrochemical potential or temperature, linearly changing on time.

Examples

## calculate potential after 30 s, starting from 200 mV
## into cathodic direction (reduction) by 5 mV s^{-1}
convert_time2var(30,var0 = 0.2,var.rate = - 0.005)
#
## heating sample after 5 min starting from 293 K
## by the temperature rate of 4 K min^{-1}
convert_time2var(5,
                 time.unit = "min",
                 var0 = 293,
                 var.rate = 4,
                 var.rate.unit = "min^{-1}")
#
## create/evaluate vector containing the applied
## cell potential (in V) from the simultaneously
## performed electrochemical oxidation experiment
## (e.g. cyclic voltammetry from -0.1V to 0.45V and back
## to -0.1V). Time series vector is labeled as "time_s".
time_s <- seq(0,360,by = 18)
E_V <- convert_time2var(time.vals = time_s,
                        var0 = -0.1,
                        var.switch = 0.45,
                        var.rate = 0.003)
## preview
as.matrix(E_V)



## calculate potential after 30 s, starting from 200 mV
## into cathodic direction (reduction) by 5 mV s^{-1}
convert_time2var(30,var0 = 0.2,var.rate = - 0.005)
#
## heating sample after 5 min starting from 293 K
## by the temperature rate of 4 K min^{-1}
convert_time2var(5,
                 time.unit = "min",
                 var0 = 293,
                 var.rate = 4,
                 var.rate.unit = "min^{-1}")
#
## create/evaluate vector containing the applied
## cell potential (in V) from the simultaneously
## performed electrochemical oxidation experiment
## (e.g. cyclic voltammetry from -0.1V to 0.45V and back
## to -0.1V). Time series vector is labeled as "time_s".
time_s <- seq(0,360,by = 18)
E_V <- convert_time2var(time.vals = time_s,
                        var0 = -0.1,
                        var.switch = 0.45,
                        var.rate = 0.003)
## preview
as.matrix(E_V)

Time Correction for the Experimental CW EPR Time Series.

Description

Providing more accurate time for EPR spectral line/spectrum appearance. It assumes that the middle $B$ (or $g$ , $\nu_{\text{MHz}}$ ...etc.) of the EPR spectrum is set as the CF (central field) for the spectrum sweep.

Usage

correct_time_Exp_Specs(time.s, Nscans, sweep.time.s)
correct_time_Exp_Specs(time.s, Nscans, sweep.time.s)

Arguments

`time.s`	Numeric value/vector/column in `data frame`, corresponding to `time` (in `s`) at which the individual EPR spectra were recorded (supplied by the EPR acquisition software).
`Nscans`	Numeric, number of accumulations (number of scans usually denoted as `AVGS`) for each spectrum in EPR time series.
`sweep.time.s`	Numeric, time (in `s`) for recording individual EPR spectrum $\equiv$ one "accumulation".

Details

The actual time at the middle/crossing point is different from that recorder by the EPR acquisition software, see below. This is especially important in determining the kinetics of radical generation or decay. Time is recorded according to the following scheme, where "^v" in the scheme denotes the derivative form of an EPR spectrum:

	EPR Spectr.				EPR Spectr.
`t[1]`	------^v------>	`t[2]`-delay	---->	`t[2]`	------^v-------> ...
	`N_scans`*`swt`		`delay`		`N_scans`*`swt`

The recorded times are: t[1],t[2],t[3],... and the N_scans corresponds to number of scans, swt to sweep time for the individual scan. These parameters can be obtained by the readEPR_params_slct_kin or other functions which can read the instrumental parameter files.

Value

Numeric value/vector, corresponding to time at which the middle ( $x$ -axis) of EPR spectrum/spectra were recorded during the kinetic measurements (e.g. radical formation, stability, electrochemical and/or photochemical measurements).

Examples

## 12 s recorded by spectrometer, 6 accumulations by the sweep time of 6 s
correct_time_Exp_Specs(12,Nscans = 6,6)


## 12 s recorded by spectrometer, 6 accumulations by the sweep time of 6 s
correct_time_Exp_Specs(12,Nscans = 6,6)

Basic Quarto Reproducible Project File/Folder Structure for the EPR Reports

Description

Creating files and folders for the basic Quarto project having the structure shown in Details and corresponding to reproducible report in EPR. The main .qmd ("quarto markdown") file, wd.subdir.name.qmd, is editable (so do the additional files as well) and used for rendering. The latter can be done directly within the RStudio IDE (by activating the Render button and selecting the desired output format like .html,.pdf or .docx). Alternatively, the rendering can be also performed in the terminal or R console. The .pdf format requires one of the $\LaTeX$ distributions: {tinytex} (R package), $\TeX$ Live or $Mik\TeX$ . The complete, above-described, R-environmental setup is also available at Posit Cloud.

Usage

create_qmdReport_proj(
  title = "Project Report",
  path_to_wd = ".",
  wd.subdir.name = "Project_Report",
  citation.style = NULL,
  Rproj.init = TRUE,
  git.init = FALSE
)
create_qmdReport_proj(
  title = "Project Report",
  path_to_wd = ".",
  wd.subdir.name = "Project_Report",
  citation.style = NULL,
  Rproj.init = TRUE,
  git.init = FALSE
)

Arguments

`title`	Character string, corresponding to title of the report like the default one: `title = "Project Report"`. It appears on the title page in all formats: `.pdf`, `.html` and `.docx`.
`path_to_wd`	Character string, setting up the path for working directory, i.e. the parent one, where the project with `wd.subdir.name` will be stored (see also `Details`). Alternatively, the `file.path` can be used to set the path. Default: `path_to_wd = "."`, referring to actual directory.
`wd.subdir.name`	Character string, pointing to `subdirectory` (name, see also `path_to_wd`), under which the entire report project is stored. This actually corresponds to main project directory. Default: `wd.subdir.name = "Project_Report"`.
`citation.style`	Character string, referring to citation style used for `References` and citations in the main `.qmd` document, which inherits the name from `wd.subdir.name`. This file is automatically created under the `subdirectory`. The argument must be added in the form of `https` url, like `citation.style = "https://www.zotero.org/styles/american-chemical-society"`. All available citation styles can be found at Zotero Citation Style Language Repository. Default: `citation.style = NULL`, actually corresponding to Chicago Manual of Style (Author-Date).
`Rproj.init`	Logical, whether to initiate the newly created repository/directory as R-project when working in RStudio. Therefore, default: `Rproj.init = TRUE`, which triggers the creation of `.Rproj` file, with the name inherited from `wd.subdir.name`. If the RStudio is not the preferred IDE of your choice, set `Rproj.init = FALSE`.
`git.init`	Logical, if `git.init = TRUE`, the whole repository/directory becomes (initiated by the `use_git`) version-controlled, using the git system. PLEASE, FOLLOW THE R CONSOLE PROMPT and select whether to commit your changes immediately or later. Default: `git.init = FALSE`. This is meant to be an option either for novice users or for those who do not want track changes within the repository by the `git`. Instead, they prefer cloud storage services like nexcloud/owncloud/ Open Science Framework...etc., supporting version (history of changes) control.

Details

In order to support reproducible research workflow (see References) in EPR from scratch, a central data hub (repository/directory) with a well-defined structure must be available. The one, presented below, is created using the essential dir.create and file.create file-folder R-management functions. For several files (like wd.subdir.name.qmd, header.tex, title.tex, styles.scss and _quarto.yml) customized templates (stored under /extdata/_extensions) are used. Remaining wd.subdir.name.bib and README.Rmd files are generated "ab initio". The wd.subdir.name is everywhere replaced by the actual character string defined by the argument of the same name. Therefore, if we take the default string like "Project_Report", file/directory names turn into Project_Report/Project_Report.ext (.ext $\equiv$ .qmd, .bib,...etc). Prior to rendering, you may provide information about the author like name:, email:, orcid: and affiliations name: and url:, directly within the main .qmd file. The .bib file is already pre-populated by one example, actually corresponding to {eprscope} package citation. The .bib reference/citation database/file can be extended and organized by the online service called CiteDrive, which can be also used as a web clipper for your references/citations, please refer to the available browser extensions.

path_to_wd
|
|
|—– wd.subdir.name
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– wd.subdir.name.qmd..."dynamic" document, main file for the entire
⁠ ⁠|⁠ ⁠ data processing and analysis workflow
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– header.tex...file to set up the .qmd (.tex)
⁠ ⁠|⁠ ⁠ ==> .pdf conversion, usually containing additional $LaTeX$
⁠ ⁠|⁠ ⁠ packages and visual setup for the .pdf output
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– title.tex...file for setting up the title and authors
⁠ ⁠|⁠ ⁠ in the .pdf output
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– styles.scss...style sheet to set up visual style
⁠ ⁠|⁠ ⁠ of the .html output format
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– wd.subdir.name.bib...bibliographic file database of all
⁠ ⁠|⁠ ⁠ reference-list entries related to the project report
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– README.Rmd...general documentation for the entire project/repository
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– _quarto.yml...setup for the main wd.subdir.name.qmd file,
⁠ ⁠|⁠ ⁠ providing different format outputs (.html,.pdf,.docx)
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– Input_Data
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|—– EPR_RAW
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|—–...folder dedicated for all raw files from EPR spectrometer,
⁠ ⁠|⁠ ⁠|⁠ ⁠⁠ ⁠like .dsc/.DSC/.par, .DTA, .YGF
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|—– EPR_ASCII
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|—–...folder dedicated to all additional text files from EPR spectrometer,
⁠ ⁠|⁠ ⁠|⁠ ⁠⁠ ⁠like .txt, .csv, .asc
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|—– EasySpin_Simulations
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|
⁠ ⁠|⁠ ⁠|⁠ ⁠|—–...folder dedicated for output files from the EasySpin(-MATLAB),
⁠ ⁠|⁠ ⁠|⁠ ⁠⁠ ⁠like .mat or .txt corresponding to EPR simulated spectral data
⁠ ⁠|
⁠ ⁠|
⁠ ⁠|—– _output
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|—– Figures
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|—– Tables
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|
⁠ ⁠ ⁠ ⁠|—–...+ .html,.pdf,.docx formats and supporting files
⁠ ⁠ ⁠ ⁠ ⁠ ⁠ of the report, these are created by rendering the main
⁠ ⁠ ⁠ ⁠ ⁠ ⁠ wd.subdir.name.qmd file (they are not present after
⁠ ⁠ ⁠ ⁠ ⁠ ⁠ the project is created)

Rendering of the wd.subdir.name.qmd into different formats (.html,.pdf, .docx) is provided by the open-source scientific and technical publishing system (based on pandoc), called Quarto (Allaire JJ et al. (2024) in the References). The main .qmd file represents a "dynamic" document, combining text, code (besides R, also other programming languages like Python, Julia or Observable can be used as well) and outputs (usually, figures and/or tables). Upon rendering, they are nicely combined into shareable above-listed report formats stored under the _output. Among them, the .html output possesses a distinctive position, because it preserves the structure of interactive EPR spectra or tables (see e.g. plot_EPR_Specs3D_interact or readEPR_params_tabs). File-Folder structure, presented above, is flexible and customizable to meet the user's needs, right after its creation by the actual function. For such purpose, please consult the Quarto documentation as well.

Value

File-folder structure ("tree") for the basic Quarto reproducible report in R, which may be used for data processing and analysis in Electron Paramagnetic Resonance (EPR).

References

Alston JM, Rick JA (2021). “A Beginner's Guide to Conducting Reproducible Research”, Bull. Ecol. Soc. Am., 102(2), e01801–14, https://doi.org/10.1002/bes2.1801.

Gandrud C (2020). Reproducible Research with R and RStudio, 3rd edition, Chapman and Hall/CRC. ISBN 978-0-429-03185-4, https://doi.org/10.1201/9780429031854.

National Academies of Sciences, Engineering, and Medicine, Policy and Global Affairs, Committee on Science, Engineering, Medicine, and Public Policy, Board on Research Data and Information, Division on Engineering and Physical Sciences, Committee on Applied and Theoretical Statistics, Board on Mathematical Sciences and Analytics, Division on Earth and Life Studies, Nuclear and Radiation Studies Board, Division of Behavioral and Social Sciences and Education, Committee on National Statistics, Board on Behavioral, Cognitive, and Sensory Sciences, Committee on Reproducibility and Replicability in Science (2019). “Reproducibility and Replicability in Science: Understanding Reproducibility and Replicability”, https://www.ncbi.nlm.nih.gov/books/NBK547546/, National Academies Press (US).

Allaire JJ, Teague C, Scheidegger C, Xie Y, Dervieux C (2024). Quarto. https://doi.org/10.5281/zenodo.5960048, v1.5, https://github.com/quarto-dev/quarto-cli.

Examples

## Not run: 
## creating reproducible report structure
## with the default parameters
create_qmdReport_proj()
#
## creating report with the specified citation style (ACS)
## and with versioning controlled by the `git` within
## the RStudio (Rproj.init = TRUE)
create_qmdReport_proj(
  citation.style =
    "https://www.zotero.org/styles/american-chemical-society",
  git.init = TRUE
)

## End(Not run)


## Not run: 
## creating reproducible report structure
## with the default parameters
create_qmdReport_proj()
#
## creating report with the specified citation style (ACS)
## and with versioning controlled by the `git` within
## the RStudio (Rproj.init = TRUE)
create_qmdReport_proj(
  citation.style =
    "https://www.zotero.org/styles/american-chemical-society",
  git.init = TRUE
)

## End(Not run)

Draw Molecule by `{rcdk}` Defined by SMILES or SDF

Description

Drawing a molecular structure based on rcdk package and using SMILES or SDF input data. This function is inspired by the Edgardo Rivera-Delgado article.

Usage

draw_molecule_by_rcdk(
  molecule,
  type = "smiles",
  mol.label = NULL,
  mol.label.color = "black",
  mol.label.xy.posit = c(8.2, 1.2),
  sma = NULL,
  annotate = "off",
  style = "cow",
  abbr = "off",
  suppressh = TRUE,
  ...
)
draw_molecule_by_rcdk(
  molecule,
  type = "smiles",
  mol.label = NULL,
  mol.label.color = "black",
  mol.label.xy.posit = c(8.2, 1.2),
  sma = NULL,
  annotate = "off",
  style = "cow",
  abbr = "off",
  suppressh = TRUE,
  ...
)

Arguments

molecule

Character input string => either SMILES strings (in case of type = "smiles"/type = "SMILES") or file path strings pointing to ".sdf" file.

type

Character string referred to the original molecular type input => either type = "smiles"/type = "SMILES" or type = "sdf"/type = "SDF". Default: type = "smiles".

mol.label

Character string, pointing to name of the molecule/compound, e.g. mol.label = c("acetone") or mol.label = c("PBN"). If mol.label = NULL (default) a character string "mol. structure viewer" with the gray color is shown.

mol.label.color

Character string, pointing to displayed font color of the chemical structure label. Default: mol.label.color = "black".

mol.label.xy.posit

Numeric vector of two values, matching the $x,y$ -position of the mol.label within the image having the total size of (1,1,10,10) => see rasterImage. Default: mol.label.xy.posit = c(8.2,1,2) => the label is positioned at the bottom right corner.

sma

Character string, allowing to highlight sub-structures using SMARTS (SMILES ARbitrary Target Specification) to highlight the common substructures in a set of molecules, such as sma = "C=O".

annotate

Character string, whether to display (annotate = "number") or do not display (annotate = "off") the atomic numbers/indexes. Default: annotate = "off".

style

Character string, denoting the plotting style like =>

Plotting Style	Style Text String
"color on black"	`style = "cob"`
"color on white"	`style = "cow"`
"black on white"	`style = "bow"`
"white on black"	`style = "wob"`
"neon on black"	`style = "nob"`

Default: style = "cow".

abbr

Character string, which controls how the structure is displayed. Following options can be set => abbr = "off" (default), pointing to present structure as is; abbr = "groups", creating an abbreviation for groups; abbr = "reagents", creating an abbreviation for reagents or abbr = "on" to abbreviate both. The abbr = "groups" WORKS ONLY IF annotate = "off"!

suppressh

Logical, denoting whether to suppress displaying of the hydrogen atoms. The SMILES or SDF STRUCTURE MUST CONTAIN H ATOMS! Default: supressh = TRUE.

...

additional options/arguments for the get.depictor.

Value

Graphics/Figure object with molecular structure.

Examples

## draw N,N,N',N'-tetramethyl-p-phenylenediamine based
## on the `smiles` code character with highlighting
## the "C(aromatic)--N" bond
draw_molecule_by_rcdk("CN(C)C1=C([H])C([H])=C(N(C)C)C([H])=C1[H]",
                      type = "smiles",
                      sma = "cN")
#
## draw N,N,N',N'-tetramethyl-p-phenylenediamine (TMPD) radical
## cation based on the `smiles` code character, with hydrogen atoms
## and molecule name label = "TMPD^(+.)"
draw_molecule_by_rcdk("CN(C)[C+]1C([H])=C([H])[C.]([N](C)C)C([H])=C1[H]",
                      type = "smiles",
                      mol.label = expression(TMPD^+.),
                      mol.label.color = "blue",
                      suppressh = FALSE)
#
## draw N,N,N',N'-tetramethyl-p-phenylenediamine based
## on the `sdf` file path ("TMPD.sdf") with "color on black"
## style + atom numbering
draw_molecule_by_rcdk(molecule = load_data_example("TMPD.sdf"),
                      type = "sdf",
                      annotate = "number",
                      style = "cob")


## draw N,N,N',N'-tetramethyl-p-phenylenediamine based
## on the `smiles` code character with highlighting
## the "C(aromatic)--N" bond
draw_molecule_by_rcdk("CN(C)C1=C([H])C([H])=C(N(C)C)C([H])=C1[H]",
                      type = "smiles",
                      sma = "cN")
#
## draw N,N,N',N'-tetramethyl-p-phenylenediamine (TMPD) radical
## cation based on the `smiles` code character, with hydrogen atoms
## and molecule name label = "TMPD^(+.)"
draw_molecule_by_rcdk("CN(C)[C+]1C([H])=C([H])[C.]([N](C)C)C([H])=C1[H]",
                      type = "smiles",
                      mol.label = expression(TMPD^+.),
                      mol.label.color = "blue",
                      suppressh = FALSE)
#
## draw N,N,N',N'-tetramethyl-p-phenylenediamine based
## on the `sdf` file path ("TMPD.sdf") with "color on black"
## style + atom numbering
draw_molecule_by_rcdk(molecule = load_data_example("TMPD.sdf"),
                      type = "sdf",
                      annotate = "number",
                      style = "cob")

Calculation of EPR/ENDOR Spectrum Linewidth ( e.g. $\Delta B_{pp}$ )

Description

Calculating the peak-to-peak (distance between the x-axis projection of "min" and "max" derivative intensities) linewidth of an EPR/ENDOR spectrum.

Usage

eval_DeltaXpp_Spec(
  data.spectr,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  xlim = NULL
)
eval_DeltaXpp_Spec(
  data.spectr,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  xlim = NULL
)

Arguments

`data.spectr`	EPR/ENDOR spectrum data frame object with magnetic flux density B (in `mT` or `G`) or g-Value or RF (in `MHz`) column/variable as well as including the derivative `dIepr_over_dB` `Intensity`. Also `index` column may be present.
`x`	Character string, pointing to name of the `x`-axis/column/variable (in the original `data.spectr`) like magnetic flux density $B$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`Intensity`	Character string, pointing to name of the `intensity column/variable`, in the original `data.spectr`, if other than `dIepr_over_dB` name/label is used (e.g. for simulated spectra). Default: `Intesity = "dIepr_over_dB"`.
`xlim`	Numeric vector, corresponding to lower and upper limit of the selected x-region, such as `xlim = c(3495.4,3595.4)` (B in `G`) or `xlim = c(12.5,21.2)` (RF in `MHz`) or `xlim = c(2.004,2.001)` (g dimensionless). Default: `xlim = NULL` (corresponding to the entire `x`-range).

Value

Numeric value difference of the x-axis quantity like B,g,RF (the absolute value), corresponding to minimum and maximum of the derivative intensity (dIepr_over_dB) in EPR/ENDOR spectrum.

Examples

## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## evaluation of the central linewidth (∆Bpp in `mT`):
eval_DeltaXpp_Spec(aminoxyl.data,
                   xlim = c(348.345,350.450))
#
## plot interactive spectrum
plot_EPR_Specs2D_interact(aminoxyl.data)
#
## the linewidth ∆Bpp (in `mT`) may be directly
## checked from the interactive spectrum above
## as a difference between the minimum and maximum
## of the `dIepr_over_dB` central line intensity:
349.648-349.107
#
## loading the perinaphthenyl (PNT) CW ENDOR spectrum:
pnt.endor.data.path <-
  load_data_example(file = "PNT_ENDOR_a.txt")
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.endor.data.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                   x.unit = "MHz")
#
## evaluation of the fourth linewidth (∆freq.(pp)
## in `MHz`) in the ENDOR spectrum:
eval_DeltaXpp_Spec(pnt.endor.data,
                  x = "RF_MHz",
                  xlim = c(22.38,24.54)
                  )
#
## plot interactive ENDOR spectrum:
plot_EPR_Specs2D_interact(pnt.endor.data,
                          x = "RF_MHz",
                          x.unit = "MHz")
#
## the linewidth (∆freq.(pp) in `MHz`) may be
## directly checked from the previous interactive
## CW ENDOR spectrum as a difference between
## the minimum and maximum of the `dIepr_over_dB`
## of the 4th line intensity:
23.42-23.30


## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## evaluation of the central linewidth (∆Bpp in `mT`):
eval_DeltaXpp_Spec(aminoxyl.data,
                   xlim = c(348.345,350.450))
#
## plot interactive spectrum
plot_EPR_Specs2D_interact(aminoxyl.data)
#
## the linewidth ∆Bpp (in `mT`) may be directly
## checked from the interactive spectrum above
## as a difference between the minimum and maximum
## of the `dIepr_over_dB` central line intensity:
349.648-349.107
#
## loading the perinaphthenyl (PNT) CW ENDOR spectrum:
pnt.endor.data.path <-
  load_data_example(file = "PNT_ENDOR_a.txt")
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.endor.data.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                   x.unit = "MHz")
#
## evaluation of the fourth linewidth (∆freq.(pp)
## in `MHz`) in the ENDOR spectrum:
eval_DeltaXpp_Spec(pnt.endor.data,
                  x = "RF_MHz",
                  xlim = c(22.38,24.54)
                  )
#
## plot interactive ENDOR spectrum:
plot_EPR_Specs2D_interact(pnt.endor.data,
                          x = "RF_MHz",
                          x.unit = "MHz")
#
## the linewidth (∆freq.(pp) in `MHz`) may be
## directly checked from the previous interactive
## CW ENDOR spectrum as a difference between
## the minimum and maximum of the `dIepr_over_dB`
## of the 4th line intensity:
23.42-23.30

Transferred Charge and Number of Electrons from Chronoamperogram

Description

Evaluation of the transferred charge and the corresponding number of electrons from chronoamperogram related to electrochemical experiment, performed simultaneously with the EPR time series measurement or independently of the latter. To acquire charge, the input $I$ vs $time$ relation (coming from the data.at) is integrated by the pracma::cumtrapz function. Prior to integration a capacitive current correction must be done, especially if it is relatively high in comparison to faradaic one. Afterwards, the number of electrons is calculated by Faraday's law (see details). The output plot can be visualized either as $Q(N_{\text{e}})$ vs $t$ (time) or as $Q(N_{\text{e}})$ vs $E$ (potential, if available in the input data.at).

Usage

eval_ECh_QNe_chronoamp(
  data.at,
  time = "time_s",
  time.unit = "s",
  tlim = NULL,
  Current = "I_A",
  Current.unit = "A",
  E = NULL,
  E.unit = NULL,
  ref.electrode = NULL,
  Ne.output = TRUE,
  separate.plots = FALSE
)
eval_ECh_QNe_chronoamp(
  data.at,
  time = "time_s",
  time.unit = "s",
  tlim = NULL,
  Current = "I_A",
  Current.unit = "A",
  E = NULL,
  E.unit = NULL,
  ref.electrode = NULL,
  Ne.output = TRUE,
  separate.plots = FALSE
)

Arguments

`data.at`	Data frame (table) object, including required columns like `Time` ( $t$ ), `Current` ( $I$ ). Even though an arbitrary column label can be used, the best option is to use labels such as `time_s`, `I_uA` or `I_mA`. Optionally, column related to potential ( $E$ ) may be present as well for the transferred charge ( $Q$ ) or number of electrons ( $N_{\text{e}}$ ) vs $E$ visualization (see also the arguments `E`, `E.unit` and `ref.electrode`).
`time`	Character string, pointing to `time`-axis/column header in the original `data.at`. Default: `time = "time_s"` (time in seconds).
`time.unit`	Character string, pointing to `time`-quantity unit. There are following units available: `time.unit = "s"` (default), `time.unit = "ms"`, `time.unit = "us"` (microseconds), `time.unit = "ns"` or `time.unit = "min"`.
`tlim`	Numeric vector of the `time`-quantity lower and upper limit, e.g. `xlim = c(5,400)` (time in seconds. Default: `tlim = NULL` actually setting the entire `time` interval from the original dataset.
`Current`	Character string, indicating the `Current`( $I$ )-axis/column quantity name in the original `data.at` object. Default: `Current = "I_A"` (current in $\text{A}$ ).
`Current.unit`	Character string, pointing to `Current` quantity unit like `Current.unit = "uA"` (microamps) `Current.unit = "A"` (default), `Current.unit = "mA"` and `Current.unit = "nA"`.
`E`	Character string, referring to $E$ (potential) column name within the input `data.at` dataset. Default: `E = NULL`, corresponding to situation, when one doesn't want to visualize transferred charge (or number of electrons) vs $E$ .
`E.unit`	Character string, setting the potential unit (see `E` argument), usually `E.unit = "mV"` or `E.unit = "V"`. Default: `E.unit = NULL`, corresponding to situation, when one doesn't want to visualize transferred charge (or number of electrons) vs $E$ .
`ref.electrode`	Character string, corresponding to reference electrode notiation/label, e.g. `ref.electrode = "Ag-quasiref"` or `ref.electrode = "Fc/Fc+"`. Default: `ref.electrode = NULL` (displayed potential is not related to any `ref.electrode`).
`Ne.output`	Logical. Should be the number of transferred electrons (`Ne`) presented within the plot ? Default: `Ne.output = TRUE`.
`separate.plots`	Logical. By default, both relations: $Q(N_{\text{e}})$ vs $t,E$ (time or potential) are shown in one plot (`separate.plots = FALSE`). One can separate $N_{\text{e}}$ vs $t,E$ and $Q$ vs $t,E$ into individual plots setting up the `separate.plots = TRUE`.

Details

When quantitative EPR is carried out along with electrochemistry simultaneously, one can easily compare the number of radicals with the number of transferred electrons. Number of radicals ( $N_{\text{R}}$ ) are evaluated from quantitative measurements (see also quantify_EPR_Abs), whereas number of transferred electrons ( $N_{\text{e}}$ ) is related to charge ( $Q$ ), according to:

$N_{\text{e}} = (Q\,N_{\text{A}})/F$

where $N_{\text{A}}$ stands for the Avogadro's number and $F$ for the Faraday's constants. Both are obtained by the constans::syms$na and the constants::syms$f, respectively, using the constants package (see syms). If both numbers match ( $N_{\text{R}} = N_{\text{e}}$ ), it reveals the presence of one-electron oxidation/reduction, while different numbers may point to a more complex mechanism (such as comproportionation, follow-up reactions, multiple electron transfer).

Value

List containing the following elements, depending on separate.plots:

If separate.plots = FALSE

df

Original data.at data frame object with the following additional columns/variables: Q_C (charge in coulombs), Q_mC (charge in millicoulombs, if the maximum charge $\leq 0.099\,\text{C}$ ) and Ne (number of transferred electrons, if Ne.output = TRUE).

plot

Side-by-side plot object (list) of $N_{\text{e}}$ vs $t,E$ as well as $Q$ vs $t,E$ .
If separate.plots = TRUE

df

Original data.at data frame object with the following additional columns/variables: Q_C (charge in coulombs), Q_mC (charge in millicoulombs, if the maximum charge $\leq 0.099\,\text{C}$ ) and Ne (number of transferred electrons, if Ne.output = TRUE).

plot.Ne

Plot object (list) of $N_{\text{e}}$ vs $t,E$ .

plot.Q

Plot object (list) of $Q$ vs $t,E$ .

References

Bard AJ, Faulkner LR, White HS (2022). Electrochemical methods: Fundamentals and Applications, 3rd edition, John Wiley and Sons, Inc., ISBN 978-1-119-33405-7, https://www.wiley.com/en-us/9781119334064.

Pingarrón JM, Labuda J, Barek J, Brett CMA, Camões MF, Fojta M, Hibbert DB (2020). “Terminology of Electrochemical Methods of Analysis (IUPAC Recommendations 2019).” Pure Appl. Chem., 92(4), 641–694, https://doi.org/10.1515/pac-2018-0109.

Neudeck A, Petr A, Dunsch L (1999). “The redox mechanism of Polyaniline Studied by Simultaneous ESR–UV–vis Spectroelectrochemistry.” Synth. Met., 107(3), 143–158, https://doi.org/10.1016/S0379-6779(99)00135-6.

Hans W. Borchers (2023). pracma: Practical Numerical Math Functions. R package version 2.4.4, https://cran.r-project.org/web/packages/pracma/index.html.

Examples

## loading package built-in example file =>
## `.txt` file generated by the IVIUM potentiostat software
triarylamine.path.cv <-
load_data_example(file = "Triarylamine_ECh_CV_ivium.txt")
## the data frame contains following variables:
## time, desired potential, current and the actual/applied
## potential
triarylamine.data.cv <-
  data.table::fread(file = triarylamine.path.cv,
    skip = 2,
    col.names = c("time_s",
                  "E_V_des", # desired potential
                  "I_A",
                  "E_V_app") # applied potential
  )
#
## simple chronoamperogram plot
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "time_s",
  x.unit = "s",
  Current = "I_A",
  Current.unit = "A",
  ticks = "in"
 )
#
## transferred charge and the number of electrons
## with default parameters
triarylamine.data.QNe <-
  eval_ECh_QNe_chronoamp(data.at = triarylamine.data.cv)
#
## data frame preview
triarylamine.data.QNe$df
#
## graphical representation
triarylamine.data.QNe$plot



## loading package built-in example file =>
## `.txt` file generated by the IVIUM potentiostat software
triarylamine.path.cv <-
load_data_example(file = "Triarylamine_ECh_CV_ivium.txt")
## the data frame contains following variables:
## time, desired potential, current and the actual/applied
## potential
triarylamine.data.cv <-
  data.table::fread(file = triarylamine.path.cv,
    skip = 2,
    col.names = c("time_s",
                  "E_V_des", # desired potential
                  "I_A",
                  "E_V_app") # applied potential
  )
#
## simple chronoamperogram plot
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "time_s",
  x.unit = "s",
  Current = "I_A",
  Current.unit = "A",
  ticks = "in"
 )
#
## transferred charge and the number of electrons
## with default parameters
triarylamine.data.QNe <-
  eval_ECh_QNe_chronoamp(data.at = triarylamine.data.cv)
#
## data frame preview
triarylamine.data.QNe$df
#
## graphical representation
triarylamine.data.QNe$plot

Find Intensity Extremes within the EPR/ENDOR Spectrum

Description

Finding the x positions like B (in mT or G)), g (unitless) or RF (in MHz) of the intensity minimum or maximum within the selected region of an EPR/ENDOR spectrum. In terms of extremes, If one wants to perform peak picking of an EPR/ENDOR spectrum, the eval_peakPick_Spec function can be applied.

Usage

eval_extremeX_Spec(
  data.spectr,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  xlim = NULL,
  extreme = "max"
)
eval_extremeX_Spec(
  data.spectr,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  xlim = NULL,
  extreme = "max"
)

Arguments

`data.spectr`	EPR/ENDOR spectrum data frame object with magnetic flux density B (in `mT` or `G`) or g-Value or RF (in `MHz`) column/variable as well as including the derivative `dIepr_over_dB` `Intensity`. Also `index` column may be present.
`x`	Character string, pointing to name of the `x`-axis/column/variable (in the original `data.spectr`) like magnetic flux density $B$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`Intensity`	Character string, pointing to name of the `intensity column/variable`, in the original `data.spectr`, if other than `dIepr_over_dB` name/label is used (e.g. for simulated spectra). Default: `Intesity = "dIepr_over_dB"`.
`xlim`	Numeric vector, corresponding to lower and upper limit of the selected x-region, such as `xlim = c(3495.4,3595.4)` (B in `G`) or `xlim = c(12.5,21.2)` (RF in `MHz`) or `xlim = c(2.004,2.001)` (g dimensionless). Default: `xlim = NULL` (corresponding to the entire `x`-range).
`extreme`	Character string with only two values allowed: `"min"` or `"max"` (default).

Value

Numeric value of x-axis variable like B,g,RF, corresponding to Intensity minimum or its maximum, within the EPR/ENDOR spectrum or its integrated form.

Examples

## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
## finding maximum and minimum `B` within the entire
## spectral (`B`) range:
eval_extremeX_Spec(data.spectr = tmpd.data.file)
#
eval_extremeX_Spec(data.spectr = tmpd.data.file,
                   extreme = "min")
#
## both values can be checked by the interactive
## spectrum:
plot_EPR_Specs2D_interact(tmpd.data.file)


## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
## finding maximum and minimum `B` within the entire
## spectral (`B`) range:
eval_extremeX_Spec(data.spectr = tmpd.data.file)
#
eval_extremeX_Spec(data.spectr = tmpd.data.file,
                   extreme = "min")
#
## both values can be checked by the interactive
## spectrum:
plot_EPR_Specs2D_interact(tmpd.data.file)

Evaluating Full Width at Half-Maximum (FWHM) from Integrated EPR Spectrum

Description

Finding the full width at half-maximum (FWHM) height of the EPR integrated spectrum/intensity. For such purpose, the EPR spectrum must be available in single integrated form (common absorption-like spectrum). If this is not the case, the derivative EPR spectrum (with the intensity dIepr_over_dB) can be integrated by the eval_integ_EPR_Spec. The FWHM is evaluated as a difference between the points ( $x > x_{\text{max}}$ and $x < x_{\text{max}}$ ) having the intensity closest to the intensity maximum/2 corresponding to one individual EPR line/peak defined by the xlim argument.

Usage

eval_FWHMx_Spec(
  data.spectr.integ,
  x = "B_G",
  Intensity = "single_Integ",
  xlim = NULL
)
eval_FWHMx_Spec(
  data.spectr.integ,
  x = "B_G",
  Intensity = "single_Integ",
  xlim = NULL
)

Arguments

`data.spectr.integ`	Data frame object, containing `x`-column/variable like magnetic flux density, B (in in `mT` or `G`) or g-factor/value (unitless) and integrated intensity (common absorption-like spectrum) column/variable.
`x`	Character string, pointing to name of the `x`-axis/column/variable (in the original `data.spectr.integ`) like magnetic flux density B (in `mT` or `G`) or g-Value (unitless), default: `x = "B_G"`.
`Intensity`	Character string, pointing to name of the `intensity column/variable` (in the original `data.spectr.integ`) if other than `single_Integ` (default) name/label is used (such as "Integral_Intensity" or "integral").
`xlim`	Numeric vector, corresponding to lower and upper limit of the selected x-region, e.g. `xlim = c(3495.4,3595.4)` (B in `G`) or `xlim = c(2.004,2.001)` (g dimensionless). Default: `xlim = NULL` (corresponding to the entire x-range).

Value

Numeric value of the FWHM, directly from EPR spectrum, depending on the x variable => either in mT/G or unitless in case if g-factor is presented on abscissa.

Examples

## simulation of the phenalenyl/perinaphthenyl (PNT) radical
## in integrated form:
pnt.sim.integ.iso <-
  eval_sim_EPR_iso(g = 2.0027,
    instrum.params = c(Bcf = 3500, # central field
                       Bsw = 100, # sweep width
                       Npoints = 4096,
                       mwGHz = 9.8), # MW Freq. in GHz
    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
     ),
    lineSpecs.form = "integrated",
    lineGL.DeltaB = list(0.54,NULL), # Gauss. FWHM in G
    Intensity.sim = "single_Integ"
  )
#
## FWHM of one of the central
## lines/peaks (`xlim = c(3494,3496.5)`)
## from the simulated spectral data:
eval_FWHMx_Spec(pnt.sim.integ.iso$df,
                x = "Bsim_G",
                Intensity = "single_Integ",
                xlim = c(3494,3496.5)
                )
#
## interactive plot of the above-simulated
## EPR spectrum in order to check the values:
plot_EPR_Specs2D_interact(pnt.sim.integ.iso$df,
  x = "Bsim_G",
  x.unit = "G",
  Intensity = "single_Integ",
  lineSpecs.form = "integrated"
 )


## simulation of the phenalenyl/perinaphthenyl (PNT) radical
## in integrated form:
pnt.sim.integ.iso <-
  eval_sim_EPR_iso(g = 2.0027,
    instrum.params = c(Bcf = 3500, # central field
                       Bsw = 100, # sweep width
                       Npoints = 4096,
                       mwGHz = 9.8), # MW Freq. in GHz
    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
     ),
    lineSpecs.form = "integrated",
    lineGL.DeltaB = list(0.54,NULL), # Gauss. FWHM in G
    Intensity.sim = "single_Integ"
  )
#
## FWHM of one of the central
## lines/peaks (`xlim = c(3494,3496.5)`)
## from the simulated spectral data:
eval_FWHMx_Spec(pnt.sim.integ.iso$df,
                x = "Bsim_G",
                Intensity = "single_Integ",
                xlim = c(3494,3496.5)
                )
#
## interactive plot of the above-simulated
## EPR spectrum in order to check the values:
plot_EPR_Specs2D_interact(pnt.sim.integ.iso$df,
  x = "Bsim_G",
  x.unit = "G",
  Intensity = "single_Integ",
  lineSpecs.form = "integrated"
 )

Basic Calculation of $g$ -factor

Description

Calculation of $g$ -factor according to fundamental formula (see Value). The magnetic flux density (B.val) and microwave frequency (nu.val, $\nu$ ) can be defined, having the common units like G (Gauss) mT (millitesla) or T (tesla) as well as GHz or Hz.

Usage

eval_gFactor(nu.val, nu.unit = "GHz", B.val, B.unit = "mT")
eval_gFactor(nu.val, nu.unit = "GHz", B.val, B.unit = "mT")

Arguments

`nu.val`	Numeric, microwave Frequency value.
`nu.unit`	Character string, frequency unit defined by `GHz` or `Hz`, default: `nu.unit = "GHz"`.
`B.val`	Numeric, magnetic flux density value.
`B.unit`	Character string, magnetic flux density unit in `G` or `mT` or `T`, default: `B.unit = "mT"`.

Value

$g$ -Value from $(\nu h)/(\mu_{\text{B}} B)$ . Physical constants ( $\mu_{\text{B}}$ and $h$ ) are taken from constants package by the syms.

Examples

eval_gFactor(9.8020458,
             nu.unit = "GHz",
             350.214,
             B.unit = "mT")
#
eval_gFactor(nu.val = 9.8020458e+9,
             nu.unit = "Hz",
             B.val = 3502.14,
             B.unit = "G")
#
eval_gFactor(9.5421,"GHz",0.333251,"T")


eval_gFactor(9.8020458,
             nu.unit = "GHz",
             350.214,
             B.unit = "mT")
#
eval_gFactor(nu.val = 9.8020458e+9,
             nu.unit = "Hz",
             B.val = 3502.14,
             B.unit = "G")
#
eval_gFactor(9.5421,"GHz",0.333251,"T")

Calculation of $g$ -factor from Quantum Chemical Computational Output

Description

In the Gaussian and ORCA outputs, the $g$ -value (its 3 principal components) is presented in the form of differences from the $g_e$ ( $g$ of the free electron). Therefore, the function takes these values to calculate the entire $g$ -factor components or parses the corresponding $g$ -mean value from the outputs.

Usage

eval_gFactor_QCHcomp(path_to_QCHoutput, mean = TRUE, origin = "gaussian")
eval_gFactor_QCHcomp(path_to_QCHoutput, mean = TRUE, origin = "gaussian")

Arguments

`path_to_QCHoutput`	Character string, corresponding to path of "Gaussian" or "ORCA" output text files including all $g$ -factors. Alternatively, the `file.path` can be applied to get the full/relative path of that file.
`mean`	Logical, whether to calculate the `mean value/iso` from the principal components, default: `mean = TRUE`, or return the entire vector with the all 3 components.
`origin`	Character string, pointing to origin of the EPR calculation parameters <=> which software package was used. Only two values are available => `"Gaussian"` (default) or `"ORCA"`.

Value

Numeric mean $g$ -factor value from the principal difference (from $g_e$ ) components calculated by the QCH method (e.g. by DFT) or numeric vector with the principal $g$ -components if mean = FALSE.

Examples

## built-in package file example and path:
gauss.file.path <-
  load_data_example(file = "TMPDAradCatEPRa.inp.log.zip")
gauss.file <- unzip(gauss.file.path)
## g_iso-value calculation from Gaussian output file:
eval_gFactor_QCHcomp(gauss.file)


## built-in package file example and path:
gauss.file.path <-
  load_data_example(file = "TMPDAradCatEPRa.inp.log.zip")
gauss.file <- unzip(gauss.file.path)
## g_iso-value calculation from Gaussian output file:
eval_gFactor_QCHcomp(gauss.file)

Calculation of $g$ -factor ("Position") from EPR Spectrum/Data

Description

Calculation of g-value according to fundamental formula, see eval_gFactor. $g$ -related magnetic flux density (like $B_{\text{iso}}$ or $B_{\text{center}}$ ) is directly taken from the EPR spectrum. If positive and negative derivative intensities of the spectral line are similar and their distance from the middle point of the spectrum equals, the $B_{\text{iso}}$ should be considered. Otherwise, the $B_{\text{center}}$ must be taken into account. In case of integrated EPR spectrum/data, the $B_{\text{max}}$ is used for the $g$ -value calculation.

Usage

eval_gFactor_Spec(
  data.spectr,
  nu.GHz,
  B.unit = "G",
  B = "B_G",
  Intensity = "dIepr_over_dB",
  lineSpecs.form = "derivative",
  Blim = NULL,
  iso = TRUE
)
eval_gFactor_Spec(
  data.spectr,
  nu.GHz,
  B.unit = "G",
  B = "B_G",
  Intensity = "dIepr_over_dB",
  lineSpecs.form = "derivative",
  Blim = NULL,
  iso = TRUE
)

Arguments

`data.spectr`	Spectrum data frame object where the magnetic flux density (in `mT` or `G` or `T`) column can be labeled as `Field` or `B_G` and that of the derivative intensity as `dIepr_over_dB` or single integrated intensity like `Integrated_Intensity` (`index` column might be included as well).
`nu.GHz`	Numeric value, microwave frequency in `GHz`.
`B.unit`	Character string, denoting the magnetic flux density unit e.g. `B.unit = "G"` (gauss, default) or `B.unit = "mT"`/`"T"` (millitesla/tesla).
`B`	Character string, pointing to magnetic flux density `column` of the EPR spectrum data frame `data.spectr` either in "millitesla"/"tesla" or in "gauss", that is `B = "B_mT"` (default) or `B = "B_G"`/`B = "T"` or `B = "Bsim_G"` to include simulated EPR spectra as well.
`Intensity`	Character string, pointing to `intensity column` if other than `dIepr_over_dB` name/label is used (e.g. for simulated spectra), default: `Intesity = "dIepr_over_dB"`
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (i.e. `"absorption"` which can be used as well) line form of the analyzed EPR spectrum/data.
`Blim`	Numeric vector, magnetic flux density in `mT`/`G`/`T` corresponding to lower and upper limit of the selected $B$ -region, such as `Blim = c(3495.4,3595.4)`. Default: `Blim = NULL` (corresponding to the entire $B$ -range of the EPR spectrum).
`iso`	Logical, whether to calculate the $g$ -factor from the $B$ -value corresponding to that between the `min.` and `max.` derivative intensities (`dIepr_over_dB`, that is $g_{\text{iso}}$ (this is the default one: `iso = TRUE`), or by finding the $B$ -value corresponding to `dIepr_over_dB = 0` (close to zero, which is `iso = FALSE`). For the `lineSpecs.form = "integrated"` (or `absorptiion`), the `iso` is related to magnetic flux density with `max.` intensity.

Value

Numeric $g_{\text{iso}}$ -value ('iso' = 'isotropic') or $g_{\text{center}}$ , from the EPR spectrum, according to $(h\,\nu)/(\mu_{\text{B}}\,B)$ .

Examples

## load package built-in EPR spectral data example:
data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
data.epr <-
  readEPR_Exp_Specs(path_to_ASC = data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    origin = "winepr")
#
## g_iso calculation from EPR spectrum/data:
eval_gFactor_Spec(data.spectr = data.epr,
                  nu.GHz = 9.814155,
                  B.unit = "mT",
                  B = "B_mT",
                  Blim = c(349.677, 350.457))


## load package built-in EPR spectral data example:
data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
data.epr <-
  readEPR_Exp_Specs(path_to_ASC = data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    origin = "winepr")
#
## g_iso calculation from EPR spectrum/data:
eval_gFactor_Spec(data.spectr = data.epr,
                  nu.GHz = 9.814155,
                  B.unit = "mT",
                  B = "B_mT",
                  Blim = c(349.677, 350.457))

Integration of EPR Spectrum/Data for Quantitative Analysis

Description

Evaluates integrals of EPR spectra (based on the pracma::cumtrapz function) depending on input data => either corresponding to derivative or single integrated EPR signal form, with the option to correct the single integral baseline by the polynomial fit of the poly.degree level. For EPR time/temperature/...etc spectral series, (data frame must be available in tidy/long table format), there is an option to integrate all EPR spectra literally in one step (see also Examples), similarly to function available in acquisition/processing software at EPR spectrometers.

Usage

eval_integ_EPR_Spec(
  data.spectr,
  B = "B_G",
  B.unit = "G",
  Intensity = "dIepr_over_dB",
  lineSpecs.form = "derivative",
  Blim = NULL,
  correct.integ = FALSE,
  BpeaKlim = NULL,
  poly.degree = NULL,
  sigmoid.integ = FALSE,
  output.vecs = FALSE
)
eval_integ_EPR_Spec(
  data.spectr,
  B = "B_G",
  B.unit = "G",
  Intensity = "dIepr_over_dB",
  lineSpecs.form = "derivative",
  Blim = NULL,
  correct.integ = FALSE,
  BpeaKlim = NULL,
  poly.degree = NULL,
  sigmoid.integ = FALSE,
  output.vecs = FALSE
)

Arguments

`data.spectr`	Spectrum data frame/table object with magnetic flux density (in `mT` or `G` or `T`) and that of the derivative or already single integrated intensity. `index` column may be already present as well.
`B`	Character string, pointing to magnetic flux density column header (in the original `data.spectr`) either in `millitesla`/`tesla` or in `Gauss`, such as `B = "B_mT"` or `B = "B_G"` (default) or `B = "Field"`...etc.
`B.unit`	Character string pointing to unit of magnetic flux density, which is to be presented on $x(B)$ -axis of the EPR spectrum, like `"G"` ("Gauss"), `"mT"` ("millitesla") or `"T"` ("Tesla"). Default: `B.unit = "G"`.
`Intensity`	Character string, pointing to column name of either derivative (e.g. `Intensity = "dIepr_over_dB"`, default) or single integrated EPR spectrum (e.g. `Intensity = "single_Integrated"`) within the actual `data.spectr`.
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (i.e. `"absorption"`, which can be used as well) line form of the analyzed EPR spectrum/data.
`Blim`	Numeric vector, magnetic flux density in `mT`/`G`/`T` corresponding to lower and upper limit of the selected $B$ -region, e.g. `Blim = c(3495.4,3595.4)`. Default: `Blim = NULL` (corresponding to the entire spectral $B$ -range).
`correct.integ`	Logical, whether to correct the integral by baseline polynomial model fit. Default: `correct.integ = FALSE`.
`BpeaKlim`	Numeric vector, magnetic flux density in `mT`/`G`/`T` corresponding to lower and upper limit of the SELECTED $B$ -PEAK REGION, e.g. `BpeaKlim = c(3535.4,3555.4)`. This is the region (without the peak), which is actually not considered for the baseline fit.
`poly.degree`	Numeric, degree of the polynomial function used to fit baseline under the single integrated curve of the original EPR spectrum (see also `BpeaKlim`).
`sigmoid.integ`	Logical, whether to involve (column in data frame) double integral or single integral (if the `data.spectr` and `Intesity` are already in single integrated form), in sigmoid shape, which is required for the quantitative analysis, default: `sigmoid.integ = FALSE`.
`output.vecs`	Logical, whether the "integral" columns are presented within the original `data.spectr` data frame (`output.vecs = FALSE`, default) or called as a vectors or list for additional processing of spectral data series by dplyr (see `Value` and `Examples`).

Details

The relative error of the cumulative trapezoidal (cumtrapz) function is minimal, usually falling into the range of $\langle 1,5\rangle\,\%$ or even lower, depending on the spectral data resolution (see Epperson JF (2013) and Seeburger P (2023) in the References). Therefore, the better the resolution, the more accurate the integral. If the initial EPR spectrum displays low signal-to-noise ratio, the integral often looses its sigmoid-shape and thus, the EPR spectrum has to be either simulated (see also vignette("functionality")) or smoothed by the smooth_EPR_Spec_by_npreg, prior to integration. Afterwards, integrals are evaluated from the simulated or smoothed EPR spectra. For the purpose of quantitative analysis, the integrals are evaluated using the B.units = "G" (see Arguments). Hence, depending on $B$ -unit (G or mT or T) each resulting integral column have to be optionally (in case of mT or T) multiplied by the factor of 10 or 10000, respectively, because $1\,\text{mT}\equiv 10\,\text{G}$ and $1\,\text{T}\equiv 10^4\,\text{G}$ . Such corrections are already included in the function/script. Instead of "double integral/integ." the term "sigmoid integral/integ." is used. "Double integral" in the case of originally single integrated EPR spectrum (see data.spectr and Intensity) is confusing. In such case, the EPR spectrum is integrated just once.

Value

The integration results may be divided into following types, depending on the above-described arguments. Generally, they are either data frames, including the original data and the integrals (output.vecs = FALSE) or vectors/vectors list, corresponding to individual baseline corrected/uncorrected integrals (output.vecs = TRUE). This is especially useful for spectral (time) series EPR data, which can be handily processed by the group_by using the pipe operators (%>%).

Data frame/table, including EPR spectral data (general Intensity (integrated or derivative) vs $B$ ) as well as its corresponding single (column single_Integ) integral. This is the case if only a single uncorrected integral is required.
Data frame/table with single integral/intensity already corrected by a certain degree of polynomial baseline (fitted to experimental baseline without peak). Single integrals are related either to derivative or already integrated EPR spectra where corrected integral column header is denoted as single_Integ_correct. This is the case if correct.integ = TRUE and sigmoid.integ = FALSE + output.vecs = FALSE.
Data frame with single and double/sigmoid integral column/variable (sigmoid_Integ), essential for the quantitative analysis. For such case it applies: output.vecs = FALSE and correct.integ = FALSE.
Data frame in case of correct.integ = TRUE, sigmoid.integ = TRUE and output.vecs = FALSE. It contains the original data frame columns + corrected single integral (single_Integ_correct) and double/sigmoid integral (sigmoid_Integ) which is evaluated from the baseline corrected single one. Therefore, such double/sigmoid integral is suitable for the accurate determination of radical (paramagnetic centers) amount.
Numeric vector, corresponding to baseline uncorrected/corrected single integral in case of sigmoid.integ = FALSE + output.vecs = TRUE.
List of numeric vectors corresponding to:

single

Corrected or uncorrected single integral (in case of derivative form), depending on the correct.integ argument.

sigmoid

Double integral (in case of derivative form) or single integral (in case of integrated spectral form) for quantitative analysis.

References

Weber RT (2011). Xenon User's Guide. Bruker BioSpin Manual Version 1.3, Software Version 1.1b50.

Hans W. Borchers (2023). pracma: Practical Numerical Math Functions. R package version 2.4.4, https://cran.r-project.org/web/packages/pracma/index.html.

Seeburger P (2023). “Numerical Integration - Midpoint, Trapezoid, Simpson's rule”, http://tinyurl.com/trapz-integral.

Svirin A (2023). “Calculus, Integration of Functions-Trapezoidal Rule”, https://math24.net/trapezoidal-rule.html.

Epperson JF (2013). An Introduction to Numerical Methods and Analysis. Wiley and Sons, ISBN 978-1-118-36759-9, https://books.google.cz/books?id=310lAgAAQBAJ.

Examples

## loading the built-in package example
## time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
    dir_ASC = tempdir(),
    dir_dsc_par =
      system.file("extdata",
                  package = "eprscope")
   )
#
## select the first spectrum
triarylamine.decay.series.data1st <-
   triarylamine.decay.series.data$df %>%
     dplyr::filter(time_s ==
       triarylamine.decay.series.data$time[1])
#
## integrate the first spectrum with default arguments
triarylamine.decay.data1st.integ01 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st)
#
## data frame preview
head(triarylamine.decay.data1st.integ01)
#
## integration (including baseline correction)
## of the 1st spectrum from the series
triarylamine.decay.data1st.integ02 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st,
    ## limits obtained from interactive spectrum:
    BpeaKlim = c(3471.5,3512.5),
    Blim = c(3425,3550),
    correct.integ = TRUE,
    poly.degree = 3,
    sigmoid.integ = TRUE
    )
#
## data frame preview
head(triarylamine.decay.data1st.integ02)
#
## plot the single integrated EPR spectrum,
## including baseline correction
plot_EPR_Specs(triarylamine.decay.data1st.integ02,
               x = "B_G",
               x.unit = "G",
               Intensity = "single_Integ_correct",
               lineSpecs.form = "integrated"
             )
#
## plot, corresponding to double/sigmoid integral,
## which is related to corrected single integral
plot_EPR_Specs(triarylamine.decay.data1st.integ02,
               x = "B_G",
               x.unit = "G",
               Intensity = "sigmoid_Integ",
               lineSpecs.form = "integrated"
             )
#
## vectorized output of the uncorrected `sigmoid_integral`
triarylamine.decay.data1st.integ03 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st,
                      sigmoid.integ = TRUE,
                      output.vecs = TRUE)[["sigmoid"]]
#
## preview of the first 6 values
triarylamine.decay.data1st.integ03[1:6]
#
## incorporation of vectorized integration into
## data "pipe" ("%>%") `dplyr` processing of EPR spectral
## time series, creating column with `sigmoid` integral
## where its corresponding single integral (intensity)
## has undergone a baseline correction, finally the max. value
## of all sigmoid integrals along with the time is
## summarized in data frame for quantitative kinetic analysis
triarylamine.decay.data.integs <-
  triarylamine.decay.series.data$df %>%
  dplyr::group_by(time_s) %>%
  dplyr::filter(dplyr::between(B_G,3425,3550)) %>%
  dplyr::mutate(sigmoid_Integ =
    eval_integ_EPR_Spec(dplyr::pick(B_G,dIepr_over_dB),
                        correct.integ = TRUE,
                        BpeaKlim = c(3471.5,3512.5),
                        poly.degree = 3,
                        sigmoid.integ = TRUE,
                        output.vecs = TRUE)$sigmoid
                       ) %>%
  dplyr::summarize(Area = max(sigmoid_Integ))
## in such case `Blim` range is not defined by `eval_integ_EPR_Spec`,
## the `Blim = NULL` and `dplyr::between()` must be set !!!
#
## preview of the final data frame
head(triarylamine.decay.data.integs)
#
## preview of the simple plot
ggplot2::ggplot(triarylamine.decay.data.integs) +
  ggplot2::geom_point(ggplot2::aes(x = time_s,y = Area))
#
## this does not correspond to example
## in `eval_kinR_EPR_modelFit`, `eval_kin_EPR_ODE_model`
## or in `plot_theme_NoY_ticks` based on the same input data,
## as those `Area` vs `time` relations were evaluated using
## the simulated EPR spectra (see also `vignette("datasets")`)
#
## Not run: 
## Similar to previous data processing, creating both: corrected
## single integral + sigmoid integral for each time within the spectral
## series. Sigmoid integral was evalutated from the single one by
## `cumtrapz()` function from `pracma` package and finally re-scaled.
triarylamine.decay.data.integs <-
  triarylamine.decay.series.data$df %>%
  dplyr::group_by(time_s) %>%
  eval_integ_EPR_Spec(correct.integ = TRUE,
                      Blim = c(3425,3550),
                      BpeaKlim = c(3472.417,3505.5),
                      poly.degree = 3) %>%
 dplyr::group_by(time_s) %>%
 dplyr::mutate(sigmoid_Integ =
   pracma::cumtrapz(B_G,single_Integ_correct)[,1]) %>%
 dplyr::mutate(sigmoid_Integ_correct =
   abs(min(sigmoid_Integ) - sigmoid_Integ))

## End(Not run)


## loading the built-in package example
## time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
    dir_ASC = tempdir(),
    dir_dsc_par =
      system.file("extdata",
                  package = "eprscope")
   )
#
## select the first spectrum
triarylamine.decay.series.data1st <-
   triarylamine.decay.series.data$df %>%
     dplyr::filter(time_s ==
       triarylamine.decay.series.data$time[1])
#
## integrate the first spectrum with default arguments
triarylamine.decay.data1st.integ01 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st)
#
## data frame preview
head(triarylamine.decay.data1st.integ01)
#
## integration (including baseline correction)
## of the 1st spectrum from the series
triarylamine.decay.data1st.integ02 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st,
    ## limits obtained from interactive spectrum:
    BpeaKlim = c(3471.5,3512.5),
    Blim = c(3425,3550),
    correct.integ = TRUE,
    poly.degree = 3,
    sigmoid.integ = TRUE
    )
#
## data frame preview
head(triarylamine.decay.data1st.integ02)
#
## plot the single integrated EPR spectrum,
## including baseline correction
plot_EPR_Specs(triarylamine.decay.data1st.integ02,
               x = "B_G",
               x.unit = "G",
               Intensity = "single_Integ_correct",
               lineSpecs.form = "integrated"
             )
#
## plot, corresponding to double/sigmoid integral,
## which is related to corrected single integral
plot_EPR_Specs(triarylamine.decay.data1st.integ02,
               x = "B_G",
               x.unit = "G",
               Intensity = "sigmoid_Integ",
               lineSpecs.form = "integrated"
             )
#
## vectorized output of the uncorrected `sigmoid_integral`
triarylamine.decay.data1st.integ03 <-
  eval_integ_EPR_Spec(triarylamine.decay.series.data1st,
                      sigmoid.integ = TRUE,
                      output.vecs = TRUE)[["sigmoid"]]
#
## preview of the first 6 values
triarylamine.decay.data1st.integ03[1:6]
#
## incorporation of vectorized integration into
## data "pipe" ("%>%") `dplyr` processing of EPR spectral
## time series, creating column with `sigmoid` integral
## where its corresponding single integral (intensity)
## has undergone a baseline correction, finally the max. value
## of all sigmoid integrals along with the time is
## summarized in data frame for quantitative kinetic analysis
triarylamine.decay.data.integs <-
  triarylamine.decay.series.data$df %>%
  dplyr::group_by(time_s) %>%
  dplyr::filter(dplyr::between(B_G,3425,3550)) %>%
  dplyr::mutate(sigmoid_Integ =
    eval_integ_EPR_Spec(dplyr::pick(B_G,dIepr_over_dB),
                        correct.integ = TRUE,
                        BpeaKlim = c(3471.5,3512.5),
                        poly.degree = 3,
                        sigmoid.integ = TRUE,
                        output.vecs = TRUE)$sigmoid
                       ) %>%
  dplyr::summarize(Area = max(sigmoid_Integ))
## in such case `Blim` range is not defined by `eval_integ_EPR_Spec`,
## the `Blim = NULL` and `dplyr::between()` must be set !!!
#
## preview of the final data frame
head(triarylamine.decay.data.integs)
#
## preview of the simple plot
ggplot2::ggplot(triarylamine.decay.data.integs) +
  ggplot2::geom_point(ggplot2::aes(x = time_s,y = Area))
#
## this does not correspond to example
## in `eval_kinR_EPR_modelFit`, `eval_kin_EPR_ODE_model`
## or in `plot_theme_NoY_ticks` based on the same input data,
## as those `Area` vs `time` relations were evaluated using
## the simulated EPR spectra (see also `vignette("datasets")`)
#
## Not run: 
## Similar to previous data processing, creating both: corrected
## single integral + sigmoid integral for each time within the spectral
## series. Sigmoid integral was evalutated from the single one by
## `cumtrapz()` function from `pracma` package and finally re-scaled.
triarylamine.decay.data.integs <-
  triarylamine.decay.series.data$df %>%
  dplyr::group_by(time_s) %>%
  eval_integ_EPR_Spec(correct.integ = TRUE,
                      Blim = c(3425,3550),
                      BpeaKlim = c(3472.417,3505.5),
                      poly.degree = 3) %>%
 dplyr::group_by(time_s) %>%
 dplyr::mutate(sigmoid_Integ =
   pracma::cumtrapz(B_G,single_Integ_correct)[,1]) %>%
 dplyr::mutate(sigmoid_Integ_correct =
   abs(min(sigmoid_Integ) - sigmoid_Integ))

## End(Not run)

Confidence Interval of a Vector or Data Frame Column

Description

Calculation of the mean value and its confidence limits (according to Student's t-distribution), corresponding to data frame column or vector, characterizing dispersion of the individual values such as double integrals in quantitative EPR analysis, g-values or linewidths.

Usage

eval_interval_cnfd_tVec(data.vec.col, level.cnfd = 0.95, separate = TRUE)
eval_interval_cnfd_tVec(data.vec.col, level.cnfd = 0.95, separate = TRUE)

Arguments

`data.vec.col`	Numeric vector (pointing to column) of interest (within a data frame) to calculate the confidence interval or uncertainty (margin of error).
`level.cnfd`	Numeric (floating) value, corresponding to confidence level (default: `level.cnfd = 0.95`). This value is related to significance level $alpha$ defined by $1 - confidence\,\,level$ .
`separate`	Logical, whether to separate the mean value and the uncertainty (margin of error), corresponding to non-negative right/left confidence limit of the mean. If `separate = TRUE` (default), the result is shown as a named vector with the (mean) `value` and the `uncertaity`. Otherwise, the result is returned in the format of $value\pm\,\,uncertainty$ .

Details

The confidence interval evaluation suggests that values/observations obey two-tailed Student's t-distribution, which for number of observations $N > 30$ approaches the normal $z$ -distribution. Evaluation of the confidence interval and/or its limits can be well documented on $g$ -factor series example:

$g = \overline{g}\pm (t_{(1-\alpha/2),df}\,s/\sqrt{N})$

where $\overline{g}$ is the mean value and the $t_{(1-\alpha/2),df}$ corresponds to the quantile of the t-distribution having the significance level of $\alpha$ ( $1-\alpha = condfidence\,\,level$ , see the level.cnfd argument) and the degrees of freedom $df = N -1$ . Finally, the $s$ represents the sample standard deviation, defined by the following relation (regarding the $g$ -value series example):

$s = \sqrt{(1/(N-1))\,\sum_{i=1}^N (g_i - \overline{g})^2}$

which is computed by the sd function. The above-mentioned $t$ -quantile is actually calculated by the stats::qt. Alternatively, one could also evaluate confidence interval by the one sample t.test for a certain level of confidence, giving a descriptive output with statistical characteristics.

Value

Named vector of (mean) value and uncertaity or $value\pm\,\,uncertainty$ format depending on the separate argument, where the uncertainty actually represents non-negative limit for the mean (one side of the confidence interval not including the mean value).

References

Miller JN, Miller JC, Miller RD (2018). Statistics and Chemometrics for Analytical Chemistry, 7th edition, Pearson Education. ISBN 978-1-292-18674-0, https://elibrary.pearson.de/book/99.150005/9781292186726.

Hayes A, Moller-Trane R, Jordan D, Northrop P, Lang MN, Zeileis A (2022). distributions3: Probability Distributions as S3 Objects. https://github.com/alexpghayes/distributions3, https://alexpghayes.github.io/distributions3/, see also Vignette: t-confidence interval for a mean, https://alexpghayes.github.io/distributions3/articles/one-sample-t-confidence-interval.html.

National Institute of Standards and Technology (NIST) (2012). “Confidence Limits for the Mean”, https://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm.

Kaleta J, Tarábek J, Akdag A, Pohl R, Michl J (2012). “The 16 CB11(CH3)n(CD3)12–N• Radicals with 5-Fold Substitution Symmetry: Spin Density Distribution in CB11Me12•”, Inorg. Chem., 51(20), 10819–10824, https://doi.org/10.1021/ic301236s.

Curley JP, Milewski TM (2020). “PSY317L Guidebook - Confidence Intervals”, https://bookdown.org/curleyjp0/psy317l_guides5/confidence-intervals.html.

Goodson DZ (2011). Mathematical Methods for Physical and Analytical Chemistry, 1st edition, John Wiley and Sons, Inc. ISBN 978-0-470-47354-2, https://onlinelibrary.wiley.com/doi/book/10.1002/9781118135204.

Examples

## double integral/intensity values
## coming from several experiments:
di.vec <- c(0.025,0.020,0.031,0.022,0.035)
#
## evaluation of the confidence interval
## in different formats:
eval_interval_cnfd_tVec(di.vec)
#
eval_interval_cnfd_tVec(di.vec,
                        level.cnfd = 0.95,
                        separate = FALSE)


## double integral/intensity values
## coming from several experiments:
di.vec <- c(0.025,0.020,0.031,0.022,0.035)
#
## evaluation of the confidence interval
## in different formats:
eval_interval_cnfd_tVec(di.vec)
#
eval_interval_cnfd_tVec(di.vec,
                        level.cnfd = 0.95,
                        separate = FALSE)

Radical Kinetic Models Fitted onto Experimental Data

Description

Fitting of the integrals/areas/concentration/...etc. vs time relation (either from experiment or from integration of the EPR spectral time series) in order to find the kinetic parameters (like rate constant, $k$ as well as (partial) reaction order(s)) of proposed radical reaction. Reaction model is taken from the eval_kinR_ODE_model, while the optimization/fitting is provided by the differential Levenberg-Marquardt optimization method, nls.lm. Because the radical concentration is directly proportional to the EPR spectrum (double) integral (see the quantify_EPR_Abs), for a quick evaluation and/or comparison of different kinetic data, it is possible to obtain the rate constants ( $k$ ) by the integrals/areas vs time fit. Therefore, the unit of $k$ is expressed in terms of $\text{s}^{-1}$ as well as in units of integrals/areas, e.g. procedure defined unit (see p.d.u.), depending on the order of reaction (see the params.guess argument).

Usage

eval_kinR_EPR_modelFit(
  data.qt.expr,
  time.unit = "s",
  time = "time_s",
  qvarR = "Area",
  model.react = "(r=1)R --> [k1] B",
  elementary.react = TRUE,
  params.guess = c(qvar0R = 0.001, k1 = 0.001),
  params.guess.lower = NULL,
  params.guess.upper = NULL,
  fit.kin.method = "diff-levenmarq",
  solve.ode.method = "lsoda",
  time.frame.model = 2,
  time.correct = FALSE,
  path_to_dsc_par = NULL,
  origin = NULL,
  ...
)
eval_kinR_EPR_modelFit(
  data.qt.expr,
  time.unit = "s",
  time = "time_s",
  qvarR = "Area",
  model.react = "(r=1)R --> [k1] B",
  elementary.react = TRUE,
  params.guess = c(qvar0R = 0.001, k1 = 0.001),
  params.guess.lower = NULL,
  params.guess.upper = NULL,
  fit.kin.method = "diff-levenmarq",
  solve.ode.method = "lsoda",
  time.frame.model = 2,
  time.correct = FALSE,
  path_to_dsc_par = NULL,
  origin = NULL,
  ...
)

Arguments

data.qt.expr

A data frame object, containing the concentrations/integral intensities/areas under the EPR spectra calculated using the experimental data as well as time column. These two essential columns are described by character strings like those below (see arguments time and qvarR).

time.unit

Character string, corresponding to time unit like "s" (default), "min" or "h".

time

Character string, pointing to time column/variable name in the original data.qt.expr data frame. Default: time = "time_s".

qvarR

Character string, pointing to qvarR (quantitative variable related to radical) column/variable name in the original data.qt.expr. Default: qvarR = "Area".

model.react

Character string, denoting a specific radical ("R") reaction related to changes in integral intensities (or any other quantitative variable) in EPR spectral time series. Arrow shows direction of the reaction ("-->", forward or "<==>", forward + reverse). Rate constants are indicated by square brackets after the arrows. Following examples of the reaction schemes are predefined and commonly used to describe the integral intensity and/or radical concentration/amount changes during the EPR time series experiment (the r,a,b stoichiometric coefficients may vary, see below).

Reaction Scheme	model.react
$(r=1)\text{R} \xrightarrow{k_1} \text{B}$	`"(r=1)R --> [k1] B"`
$(a=2)\text{A} \xrightarrow{k_1} (r=2)\text{R}$	`"(a=2)A --> [k1] (r=2)R"`
$(a=2)\text{A} \xrightleftharpoons[k_4]{k_1} (r=2)\text{R} \xrightleftharpoons[k_3]{k_2} (b=1)\text{B}$	`"(a=2)A <==> [k1] [k4] (r=2)R <==> [k2] [k3] (b=1)B"`
$(r=1)\text{R} \xrightleftharpoons[k_2]{k_1} (b=1)\text{B}$	`"(r=1)R <==> [k1] [k2] (b=1)B"`
$(a=2)\text{A} \xrightleftharpoons[k_2]{k_1} (r=2)\text{R}$	`"(a=2)A <==> [k1] [k2] (r=2)R"`
$(a=1)\text{A} + (b=1)\text{B} \xrightarrow{k_1} (r=1)\text{R}$	`"(a=1)A + (b=1)B --> [k1] (r=1)R"`
$(a=1)\text{A} + (r=1)\text{R} \xrightarrow{k_1} \text{B}$	`"(a=1)A + (r=1)R --> [k1] B"`

Couple of examples are also given in Details. The function is relatively flexible and enables later addition of any other reaction schemes describing the EPR time series experiments (YOU MAY ASK DEVELOPER(S) via forum/help-channels). The stoichiometric coefficient (such as (r=1) or (a=1)) can be varied within the model.react character string. Defined/Allowed values are integers, e.g. 1,2,3...etc. The space character within the model.react string is not fixed and can be skipped for the sake of simplicity. If elementary.react = FALSE (the model reaction is not considered as an elementary one), a possible non-integer partial coefficients (e.g. alpha,beta or gamma) must be included in kin.params (see also kin.params description). For the consecutive model reaction presented above, it applies only to one part/step of the mechanism.

elementary.react

Logical, if the model reaction should be considered as the elementary one, i.e. the stoichiometric coefficients equal to the partial reaction orders. Such reaction proceeds without identifiable intermediate species forming. Default: elementary.react = TRUE. If elementary.react = FALSE, i.e. the model.react cannot be considered like an elementary one, one must include the parameterized reaction orders $\alpha$ , $\beta$ or $\gamma$ in the kin.params, e.g kin.params = c(k1 = 0.01, qvar0A = 0.05, alpha = 1.5). For the consecutive model reaction presented above, it applies only to one part/step of the mechanism.

params.guess

Named vector, initial values of kin.params (see eval_kinR_ODE_model) ready for optimization/fitting. The k1-unit is eventually expressed in terms of $s^{-1}$ as well as in units of the applied qvar (e.g. c, concentration) and depends on the partial reaction order(s), which power(s) the qvar(s). For example, the k1-unit of elementary radical recombination, evaluated by double integrals, like model.react = "(r=2)R --> [k1] B", reads: $\text{s}^{-1}\,(\text{p.d.u.})^{-1}$ .

params.guess.lower

Numeric vector of lower bounds on each parameter in params.guess. If not given, the default (params.guess.lower = NULL) lower bound corresponds to -Inf of each params.guess component.

params.guess.upper

Numeric vector of upper bounds on each parameter in params.guess. If not given, the default (params.guess.upper = NULL) upper bound corresponds to +Inf of each params.guess component.

fit.kin.method

Character string, pointing to optimization/fitting method. So far, the default one (fit.kin.method = "diff-levenmarq") is exclusively used (additional methods are planned). It corresponds to differential Levenberg-Marquardt (see also nls.lm) because it is based on the numeric solution of the ordinary differential equations and not on the common integration of rate equations.

solve.ode.method

Character string, setting up the integrator (the method argument in ode), applied to find the numeric solution of ODE. Default: solve.ode.method = "lsoda" (lsoda, additional methods, see the ode link above).

time.frame.model

Numeric value, corresponding to interval time resolution, i.e. the smallest time difference between two consecutive points. The number of points is thus defined by the time.interval.model argument:

$((Interval[2] - Interval[1])\,/\,Frame) + 1$

This argument is required to numerically solve the kinetic differential equations by the ode. For the default interval mentioned above, the default value reads time.frame.model = 2 (in seconds).

time.correct

Logical, if time of recorded series of the EPR spectra needs to be corrected. Default: time.correc = FALSE, which actually assumes that time correction was done (either by correct_time_Exp_Specs or by readEPR_Exp_Specs_kin with a subsequent integration), prior to fitting procedure. If time.correct = TRUE, the path to file with EPR instrumental parameters (like .DSC/.dsc or par) must be defined (see the path_to_dsc_par).

path_to_dsc_par

Character string, path (also provided by the file.path) to .DSC/.dsc or .par (depending on origin parameter) text files including instrumental parameters and provided by the EPR machine. Default: path_to_dsc_par = NULL.

origin

Character string, corresponding to software which was used to acquire the EPR spectra, essential to load the parameters by the path_to_dsc_par (see also the readEPR_params_slct_kin). Two origins are available: origin = "winepr" or origin = "xenon".

...

additional arguments for nls.lm, e.g. defined by the control = minpack.lm::nls.lm.control().

Value

List with the following components is available:

df: Data frame object with the variables/columns such as time, experimental quantitative variable like sigmoid_Integ (sigmoid integral) or Area, concentration c_M or number of radicals of the relevant EPR spectrum; the corresponding quantitative variable fitted vector values as well as residual vector (experiment - kinetic model) related to the qvarR argument.
plot: Plot object Quantitative variable vs Time with the experimental data and the corresponding fit.
plot.ra: GGplot2 object (related to simple residual analysis), including two main plots: Q-Q plot and residuals vs predicted qvarR from the kinetic model.
df.coeffs: Data frame object containing the optimized (best fit) parameter values (Estimates), their corresponding standard errors, t- as well as p-values.
N.evals: Total number of evaluations/iterations before the best fit is found.
min.rss: Minimum sum of residual squares after N.evals.
N.converg: Vector, corresponding to residual sum of squares at each iteration/evaluation.

References

Mullen KM, Elzhov TV, Spiess A, Bolker B (2023). “minpack.lm.” https://github.com/cran/minpack.lm.

Gavin HP (2024). “The Levenberg-Marquardt algorithm for nonlinear least squares curve-fitting problems.” Department of civil and environmental engineering, Duke University, https://people.duke.edu/~hpgavin/ce281/lm.pdf.

Examples

## loading example data (incl. `Area` and `time` variables)
## from Xenon: decay of a triarylamine radical cation
## after its generation by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated
## EPR spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
## data preview
head(triaryl_radCat_data)
#
## loading the `.DSC` file
triaryl_radCat_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.DSC")
#
## fit previous data by second order kinetics,
## where the `model.react` is considered as an elementary
## step (`time.correct` of the CW-sweeps is included (`TRUE`))
triaryl_model_kin_fit_01 <-
  eval_kinR_EPR_modelFit(data.qt.expr = triaryl_radCat_data,
                         model.react = "(r=2)R --> [k1] B",
                         elementary.react = TRUE,
                         params.guess = c(qvar0R = 0.019,
                                          k1 = 0.04
                                         ),
                         time.correct = TRUE,
                         path_to_dsc_par = triaryl_radCat_dsc_path,
                         origin = "xenon")
## data frame preview
head(triaryl_model_kin_fit_01$df)
#
## plot preview
triaryl_model_kin_fit_01$plot
#
## coefficients/parameters table preview
triaryl_model_kin_fit_01$df.coeffs
#
## convergence preview
triaryl_model_kin_fit_01$N.converg
#
## simple residual analysis plots
## showing the random pattern, which indicates that
## kinetic model provides a decent fit to the data +
## normal quantile (Q-Q) plot, indicating that residuals
## are normally distributed
triaryl_model_kin_fit_01$plot.ra
#
## take the same experimental data and perform fit
## by first order kinetics where the `model.react`
## is considered as an elementary step
## (`time.correct` of the CW-sweeps is included (`TRUE`))
triaryl_model_kin_fit_02 <-
  eval_kinR_EPR_modelFit(data.qt.expr = triaryl_radCat_data,
    model.react = "(r=1)R --> [k1] B",
    elementary.react = TRUE,
    params.guess = c(qvar0R = 0.019,
                     k1 = 0.0002
                     ),
    time.correct = TRUE,
    path_to_dsc_par = triaryl_radCat_dsc_path,
    origin = "xenon")
## plot preview
triaryl_model_kin_fit_02$plot
#
## coefficients/parameters table preview
triaryl_model_kin_fit_02$df.coeffs


## loading example data (incl. `Area` and `time` variables)
## from Xenon: decay of a triarylamine radical cation
## after its generation by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated
## EPR spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
## data preview
head(triaryl_radCat_data)
#
## loading the `.DSC` file
triaryl_radCat_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.DSC")
#
## fit previous data by second order kinetics,
## where the `model.react` is considered as an elementary
## step (`time.correct` of the CW-sweeps is included (`TRUE`))
triaryl_model_kin_fit_01 <-
  eval_kinR_EPR_modelFit(data.qt.expr = triaryl_radCat_data,
                         model.react = "(r=2)R --> [k1] B",
                         elementary.react = TRUE,
                         params.guess = c(qvar0R = 0.019,
                                          k1 = 0.04
                                         ),
                         time.correct = TRUE,
                         path_to_dsc_par = triaryl_radCat_dsc_path,
                         origin = "xenon")
## data frame preview
head(triaryl_model_kin_fit_01$df)
#
## plot preview
triaryl_model_kin_fit_01$plot
#
## coefficients/parameters table preview
triaryl_model_kin_fit_01$df.coeffs
#
## convergence preview
triaryl_model_kin_fit_01$N.converg
#
## simple residual analysis plots
## showing the random pattern, which indicates that
## kinetic model provides a decent fit to the data +
## normal quantile (Q-Q) plot, indicating that residuals
## are normally distributed
triaryl_model_kin_fit_01$plot.ra
#
## take the same experimental data and perform fit
## by first order kinetics where the `model.react`
## is considered as an elementary step
## (`time.correct` of the CW-sweeps is included (`TRUE`))
triaryl_model_kin_fit_02 <-
  eval_kinR_EPR_modelFit(data.qt.expr = triaryl_radCat_data,
    model.react = "(r=1)R --> [k1] B",
    elementary.react = TRUE,
    params.guess = c(qvar0R = 0.019,
                     k1 = 0.0002
                     ),
    time.correct = TRUE,
    path_to_dsc_par = triaryl_radCat_dsc_path,
    origin = "xenon")
## plot preview
triaryl_model_kin_fit_02$plot
#
## coefficients/parameters table preview
triaryl_model_kin_fit_02$df.coeffs

Reaction Activation Parameters Obtained by Essential Transition State Theory

Description

Finding the temperature-dependence of a rate constant ( $k$ ) related to the elementary radical reaction, using the essential transition state theory (TST). The activation parameters, such as $\Delta^{\ddagger} S^o$ and $\Delta^{\ddagger} H^o$ are obtained by the non-linear fit (see the general nls R function) of the Eyring expression (its non-linear form, see Details) on the original $k$ vs $T$ relation (please, refer to the data.kvT argument). The latter can be acquired by the eval_kinR_EPR_modelFit from sigmoid-integrals of the EPR spectra recorded at different temperatures. Finally, the activation Gibbs energy ( $\Delta^{\ddagger} G^o$ ) is calculated, using the optimized $\Delta^{\ddagger} S^o$ and $\Delta^{\ddagger} H^o$ , for each temperature in the series.

Usage

eval_kinR_Eyring_GHS(
  data.kvT,
  rate.const,
  rate.const.unit = "s^{-1}",
  Temp,
  Temp.unit = "K",
  transmiss.coeff = 1,
  fit.method = "default"
)
eval_kinR_Eyring_GHS(
  data.kvT,
  rate.const,
  rate.const.unit = "s^{-1}",
  Temp,
  Temp.unit = "K",
  transmiss.coeff = 1,
  fit.method = "default"
)

Arguments

`data.kvT`	Data frame object, which must include two essential columns: rate constant ( $k$ of an elementary radical reaction) and the corresponding temperatures at which the $k$ was acquired.
`rate.const`	Character string, pointing to rate constant column header in the actual `data.kvT` data frame.
`rate.const.unit`	Character string, referring to rate constant unit. This has to be specified using the `plotmath` notation, like `rate.const.unit = "M^{-1}~s^{-1}"` or `rate.const.unit = "s^{-1}"` (default), because it is automatically applied as $y$ -axis unit in the graphical output by the `{ggplot2}`.
`Temp`	Character string, pointing to temperature column header within the original `data.kvT` data frame.
`Temp.unit`	Character string, corresponding to temperature unit related to `Temp`. Temperature can be defined in the following units: `Temp.unit = "K"` (kelvin, default), `Temp.unit = "oC"` (degree Celsius) or `Temp.unit = "oF"` (degree Fahrenheit). If other than default specified, temperature values (column characterized by the `Temp` argument) are automatically converted into `"K"` (kelvins).
`transmiss.coeff`	Numeric value, corresponding to probability that the activated complex is transformed into products. Default: `transmiss.coeff = 1` ( $100\,\%$ ).
`fit.method`	Character string, corresponding to method applied to fit the theoretical Eyring relation (by optimizing the activation parameters, see `Details`) to the experimental $k$ vs $T$ dependence. For this purpose, the `nls` function is used. Therefore, all the methods, defined under its `algorithm` argument, are available: `"default"` (corresponding to Gauss-Newton algorithm), `"plinear"`, which is Golub-Pereyra algorithm or `"port"` (Fortran PORT, "portable" library for numerical computation).

Details

The basic assumption of the Transition State Theory (TST) is the existence of activated state/complex, formed by the collision of reactant molecules, which does not actually lead to reaction products directly. The activated state (AS) is formed as highly energized, and therefore as an unstable intermediate, decomposing into products of the reaction. Accordingly, the reaction rate is given by the rate of its decomposition. Additional important assumption for TST is the presence of pre-equilibrium (characterized by the $K^{\ddagger}$ constant) of the reactants with the activated complex (AC). Because the latter is not stable, it dissociates with motion along the corresponding bond-stretching coordinate. For this reason, the rate constant ( $k$ ) must be related to the associated vibration frequency ( $\nu$ ). Thus, every time, if the AC is formed, the $k$ of AC-dissociation actually equals to $\nu$ . Nevertheless, it is possible that the AC will revert back to reactants and therefore, only a fraction of ACs will lead to product(s). Such situation is reflected by the transmission coefficient $\kappa$ (see also the argument transmiss.coeff), where $k = \kappa\,\nu$ .

According to statistical thermodynamics, the equilibrium constant can be expressed by the partition function ( $q$ ) of the reactants and that of the AC. By definition, each $q$ corresponds to ratio of total number of particles to the number of particles in the ground state. In essence, it is the measure of degree to which the particles are spread out (partitioned among) over the energy levels. Therefore, taking into account the energies of a harmonic quantum oscillator vibrating along the reaction coordinate as well as partition functions of the AC and those of the reactants, the rate constant can be expressed as follows (see e.g. Ptáček P, Šoukal F, Opravil T (2018) in the References):

$k = \kappa\,(k_{\text{B}}\,T\,/\,h)\,K^{\ddagger}$

where the $k_{\text{B}}$ and $h$ are the Boltzmann and Planck constants, respectively, $T$ corresponds to temperature and finally, the $K^{\ddagger}$ represents the equilibrium constant including the partition functions of reactants and that of the AC. In order to evaluate the AC partition function, its structure must be known. However, often, due to the lack of structural information, it is difficult (if not impossible) to evaluate the corresponding $q^{\ddagger}(\text{AC})$ . Therefore, considering the equilibrium between the reactants and the AC, one may express the $K^{\ddagger}$ in terms of Gibbs activation energy ( $\Delta^{\ddagger} G^o$ ), because $\Delta^{\ddagger} G^o = - R\,T\,ln K^{\ddagger}$ and thus the Eyring equation reads:

$k = \kappa\,(k_{\text{B}}\,T\,/\,h)\,exp[- (\Delta^{\ddagger} G^o)/(R\,T)] = \kappa\,(k_{\text{B}}\,T\,/\,h)\,exp[- (\Delta^{\ddagger} H^o)/(R\,T)]\,exp[\Delta^{\ddagger} S^o / R]$

where $R\approx 8.31446\,\text{J}\,\text{mol}^{-1}\,\text{K}^{-1}$ is the universal gas constant and the upper index $^o$ denotes the standard molar state (see IUPAC (2019) in the References). Previous formula is applied as a model to fit the experimental $k\,\,vs\,\,T$ (see the argument data.kvT) relation, where both the $\Delta^{\ddagger} S^o$ and the $\Delta^{\ddagger} H^o$ (in the graphical output, are also denoted as $\Delta^{active} S^o$ and $\Delta^{active} H^o$ , respectively) are optimized using the fit.method (by the nls function). In the first approach, both latter are considered as temperature independent within the selected temperature range. Often, the Eyring equation is not applied in the original form, however in the linearized one. Nevertheless, the latter is not recommended as a model for fitting the experimental $k(T)$ (see also Lente G, Fábián I, Poë AJ (2005) in the References). The reason inherits in the misinterpretation of the extrapolation to $T\rightarrow \infty$ (or $1/T\rightarrow 0$ ) by which the $\Delta^{\ddagger} S^o$ is obtained and thus it is unreliable. Accordingly, the original exponential Eyring form is recommended as a model to fit the experimental $k(T)$ . The $k$ -unit depends on the molecularity of the reaction, please also refer to the rate.const.unit argument. Therefore, the left hand site of the Eyring equation above must be multiplied by the standard molar concentration $c^o = 1\,\text{mol}\,\text{dm}^{-3}$ :

$k\,(c^o)^{- \sum_i \nu_i^{\ddagger}}$

where the $\sum_i \nu_i^{\ddagger}$ goes through stoichiometric coefficients (including the negative sign for reactants) of the AC formation reaction (therefore the index $^{\ddagger}$ is used), i.e. for the bi-molecular reaction, the sum results in -1, however for the mono-molecular one, the sum results in 0.

While the transition state theory (TST) is a helpful tool to get information about the mechanism of an elementary reaction, it has some limitations, particularly for radical reactions. Couple of them are listed below.

One should be very careful if applied to elementary steps in a multistep reaction kinetics (like consecutive reactions, example shown in eval_kinR_ODE_model). If the intermediate (e.g. in the consecutive reaction mechanism) possesses a short life-time, the TST probably fails.
For very fast reactions the assumed equilibrium between the reactants and the AC won't be reached. Therefore, the spin trapping reactions, which $k$ s may actually fall into the order of $10^9\,\text{dm}^3\,\text{mol}^{-1}\,\text{s}^{-1}$ (or oven higher, see Kemp TJ (1999) in the References) should be taken with extreme caution in terms of TST.
Formation of AC in TST is based on classical mechanics, that is molecules/atoms will only collide, having enough energy (to form the AC), otherwise reaction does not occur. Whereas, taking into account the quantum mechanical principle, molecules/atoms with any finite energy may (with a certain probability) tunnel across the energy barrier. Such effect will be less probable for high energy barriers, however e.g. for radical-radical recombination, where the barriers are typically very low, the tunneling probability is high and TST may fail. In addition, such reactions proceed relatively fast and therefore the TST (Eyring fit) can also strongly bias the activation parameters. This type of reactions may also exhibit negative $k$ vs $T$ dependence (see Wardlaw DM and Marcus RA (1986) in the References).

Value

As a result of the Eyring-relation fit, list with the following components is available:

df

Data frame, including the original data.kvT + the column of $\Delta^{\ddagger} G^o$ , with the name of DeltaG_active_kJ_per_mol, as well as fitted/predicted values of the rate constant and finally, the corresponding residuals.

df.fit

Data frame including temperature (in the same region like in the original data.kvT, however with the resolution of 1024 points) and the corresponding .fitted $k$ , according to Eyring model.

plot

Static ggplot2-based object/list, showing graphical representation of the non-linear fit, together with the Eyring equation.

plot.ra

GGplot2 object (related to simple residual analysis), including two main plots: Q-Q plot and residuals vs predicted/fitted $k$ vs $T$ from the Eyring fit.

df.coeffs.HS

Data frame object, containing the optimized (best fit) parameter values (Estimates), their corresponding standard errors, t- as well as p-values for both $\Delta^{\ddagger} H^o$ and $\Delta^{\ddagger} S^o$ .

converg

List, containing fitting/optimization characteristics like number of evaluations/iterations (N.evals); character denoting the (un)successful convergence (message) and finally, standard deviation of the residuals (residual.sd), which is defined as:

$\sqrt{\sum_i (y_i - y_{i,\text{fit/model}})^2\,/\,(N - k_{\text{pars}} - 1)}$

where $N$ is the number of observations and $k_{\text{pars}}$ is the number of optimized parameters. Therefore, the smaller the residual.sd, the better the Eyring-relation fit.

References

Engel T, Reid P (2013). Physical Chemistry, 3rd Edition, Pearson Education, ISBN 978-0-321-81200-1, https://elibrary.pearson.de/book/99.150005/9781292035444.

Ptáček P, Šoukal F, Opravil T (2018). "Introduction to the Transition State Theory", InTech., https://doi.org/10.5772/intechopen.78705.

International Union of Pure and Applied Chemistry (IUPAC) (2019). “Transition State Theory”, https://goldbook.iupac.org/terms/view/T06470.

Anslyn EV, Dougherty DA (2006). Modern Physical Organic Chemistry, University Science Books, ISBN 978-1-891-38931-3, https://uscibooks.aip.org/books/modern-physical-organic-chemistry/.

Lente G, Fábián I, Poë AJ (2005). "A common Misconception about the Eyring Equation", New J. Chem., 29(6), 759–760, https://doi.org/10.1039/B501687H.

Kemp TJ (1999), "Kinetic Aspects of Spin Trapping", Progress in Reaction Kinetics, 24(4), 287-358, https://doi.org/10.3184/007967499103165102.

Wardlaw DM and Marcus RA (1986), "Unimolecular reaction rate theory for transition states of any looseness. 3. Application to methyl radical recombination", J. Phys. Chem., 90(21), 5383-5393, https://doi.org/10.1021/j100412a098.

Examples

## demonstration on raw data, presented
## in https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf
## considering reaction H+ + (S2O6)2- <==> SO2 + (HSO4)-
kinet.test.data <-
  data.frame(k_per_M_per_s =
               c(9.54e-7,1.91e-6,3.76e-6,
                 7.33e-6,1.38e-5,2.56e-5,
                 4.71e-5,8.43e-5,1.47e-4),
             T_oC = c(50,55,60,65,70,
                      75,80,85,90)
)
activ.kinet.test.data <-
  eval_kinR_Eyring_GHS(
    data.kvT = kinet.test.data,
    rate.const = "k_per_M_per_s",
    rate.const.unit = "M^{-1}~s^{-1}",
    Temp = "T_oC",
    Temp.unit = "oC"
  )
#
## preview of the original data
## + ∆G (activated) + fitted + residuals
activ.kinet.test.data$df
#
## preview of the non-linear fit plot
activ.kinet.test.data$plot
#
## preview of the optimized (activated)
## ∆S and ∆H parameters
activ.kinet.test.data$df.coeffs.HS
#
## compare values with those presented in
## https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf
## ∆S = (7.2 +- 1.1) kJ/mol*K & ∆H = (118.80 +- 0.41) kJ/mol
#
## preview of the new `.fitted` data frame
activ.kinet.test.data$df.fit
#
## preview of the convergence measures
activ.kinet.test.data$converg


## demonstration on raw data, presented
## in https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf
## considering reaction H+ + (S2O6)2- <==> SO2 + (HSO4)-
kinet.test.data <-
  data.frame(k_per_M_per_s =
               c(9.54e-7,1.91e-6,3.76e-6,
                 7.33e-6,1.38e-5,2.56e-5,
                 4.71e-5,8.43e-5,1.47e-4),
             T_oC = c(50,55,60,65,70,
                      75,80,85,90)
)
activ.kinet.test.data <-
  eval_kinR_Eyring_GHS(
    data.kvT = kinet.test.data,
    rate.const = "k_per_M_per_s",
    rate.const.unit = "M^{-1}~s^{-1}",
    Temp = "T_oC",
    Temp.unit = "oC"
  )
#
## preview of the original data
## + ∆G (activated) + fitted + residuals
activ.kinet.test.data$df
#
## preview of the non-linear fit plot
activ.kinet.test.data$plot
#
## preview of the optimized (activated)
## ∆S and ∆H parameters
activ.kinet.test.data$df.coeffs.HS
#
## compare values with those presented in
## https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf
## ∆S = (7.2 +- 1.1) kJ/mol*K & ∆H = (118.80 +- 0.41) kJ/mol
#
## preview of the new `.fitted` data frame
activ.kinet.test.data$df.fit
#
## preview of the convergence measures
activ.kinet.test.data$converg

Quantitative EPR Kinetic Model Profiles by Numeric Solution of the ODE.

Description

Theoretical quantitative kinetic profiles (such as concentration/amount/integral intensity) as well as comparison with the experimental data for various predefined model reactions involving radical(s) (labeled as "R"). Profiles are evaluated by the numeric solution of rate equations by the Ordinary Differential Equations (ODE from desolve R package). This function is inspired by the R-bloggers article.

Usage

eval_kinR_ODE_model(
  model.react = "(r=1)R --> [k1] B",
  model.expr.diff = FALSE,
  elementary.react = TRUE,
  kin.params = c(k1 = 0.001, qvar0R = 0.02),
  time.unit = "s",
  time.interval.model = c(0, 1800),
  time.frame.model = 2,
  solve.ode.method = "lsoda",
  data.qt.expr = NULL,
  time.expr = NULL,
  qvar.expr = NULL,
  ...
)
eval_kinR_ODE_model(
  model.react = "(r=1)R --> [k1] B",
  model.expr.diff = FALSE,
  elementary.react = TRUE,
  kin.params = c(k1 = 0.001, qvar0R = 0.02),
  time.unit = "s",
  time.interval.model = c(0, 1800),
  time.frame.model = 2,
  solve.ode.method = "lsoda",
  data.qt.expr = NULL,
  time.expr = NULL,
  qvar.expr = NULL,
  ...
)

Arguments

model.react

Reaction Scheme	model.react
$(r=1)\text{R} \xrightarrow{k_1} \text{B}$	`"(r=1)R --> [k1] B"`
$(a=2)\text{A} \xrightarrow{k_1} (r=2)\text{R}$	`"(a=2)A --> [k1] (r=2)R"`
$(a=2)\text{A} \xrightleftharpoons[k_4]{k_1} (r=2)\text{R} \xrightleftharpoons[k_3]{k_2} (b=1)\text{B}$	`"(a=2)A <==> [k1] [k4] (r=2)R <==> [k2] [k3] (b=1)B"`
$(r=1)\text{R} \xrightleftharpoons[k_2]{k_1} (b=1)\text{B}$	`"(r=1)R <==> [k1] [k2] (b=1)B"`
$(a=2)\text{A} \xrightleftharpoons[k_2]{k_1} (r=2)\text{R}$	`"(a=2)A <==> [k1] [k2] (r=2)R"`
$(a=1)\text{A} + (b=1)\text{B} \xrightarrow{k_1} (r=1)\text{R}$	`"(a=1)A + (b=1)B --> [k1] (r=1)R"`
$(a=1)\text{A} + (r=1)\text{R} \xrightarrow{k_1} \text{B}$	`"(a=1)A + (r=1)R --> [k1] B"`

model.expr.diff

Logical, difference between the integral intensities/areas under the EPR spectra calculated using the experimental data and those generated by the model. By default the argument is FALSE and it is ONLY ACTIVATED (model.expr.diff = TRUE) IN THE CASE WHEN THE KINETIC MODEL FITTING PROCEDURE (see also eval_kinR_EPR_modelFit or examples below) IS PERFORMED.

elementary.react

kin.params

Named numeric vector, containing rate constants as well as initial radical or other reactant/product concentration/integral intensities/areas...etc. Therefore, a general qvar (quantitative variable) is defined which may actually reflect all above-mentioned quantities. Default: kin.params = c(k1 = 0.001,qvar0R = 0.02). The initial values are denoted as qvar0X (e.g. qvar0R for radical or qvar0A for the reactant A). The components of kin.params depend on model.react as well as on the elementary.react. If elementary.react = FALSE additional parameters like partial reaction orders (alpha and/or beta and/or gamma) must be defined within the kin.params, like summarized in the following table:

model.react	Essential kin.params components
`"(r=1)R --> [k1] B"`	`k1`, `qvar0R`, (`alpha`)
`"(a=1)A --> [k1] (r=1)R"`	`k1`, `qvar0A`, `qvar0R`, (`alpha`)
`"(a=1)A <==> [k1] [k4] (r=1)R <==> [k2] [k3] (b=1)B"`	`k1`, `k2`, `k3`, `k4`, `qvar0A`, `qvar0R`, `qvar0B`, (`alpha`, `beta`, `gamma`)
`"(r=1)R <==> [k1] [k2] (b=1)B"`	`k1`, `k2`, `qvar0R`, `qvar0B`, (`alpha`, `beta`)
`"(a=1)A <==> [k1] [k2] (r=1)R"`	`k1`, `k2`, `qvar0A`, `qvar0R`, (`alpha`, `beta`)
`"(a=1)A + (b=1)B --> [k1] (r=1)R"`	`k1`, `qvar0A`, `qvar0B`, `qvar0R`, (`alpha`,`beta`)
`"(a=1)A + (r=1)R --> [k1] B"`	`k1`, `qvar0A`, `qvar0R`, (`alpha`,`beta`)

The k1-unit is eventually expressed in terms of $s^{-1}$ as well as in units of the applied qvar (e.g. c, concentration) and depends on the partial reaction order(s) (PRO, see above), which power(s) the qvar(s). For example, the k1-unit of elementary radical recombination, evaluated by double integrals, like model.react = "(r=2)R --> [k1] B", reads: $\text{s}^{-1}\,(\text{p.d.u.})^{-1}$ , where p.d.u. stands for the procedure defined units.

time.unit

Character string, corresponding to time unit like "s" (default), "min" or "h".

time.interval.model

Numeric vector, including two values: starting and final time/termination of the model reaction (e.g. c(0,1800) in seconds, default).

time.frame.model

Numeric value, corresponding to interval time resolution, i.e. the smallest time difference between two consecutive points. The number of points is thus defined by the time.interval.model argument:

$((Interval[2] - Interval[1])\,/\,Frame) + 1$

solve.ode.method

data.qt.expr

A data frame object, containing the concentrations/integral intensities/areas under the EPR spectra calculated using the experimental data as well as time column. These two essential column headers are described by the character strings like those below time.expr and qvar.expr. The data.qt.expr MUST BE USED ONLY IN SUCH CASE WHEN THE EXPERIMENTAL TIME HAS TO BE INCLUDED IN THE KINETIC MODEL (e.g. also for THE FITTING of EXPERIMENTAL DATA BY THE KINETIC MODEL). Default: data.qt.expr = NULL.

time.expr

Character string, pointing to time column/variable name in the original data.qt.expr data frame. Default: time.expr = NULL (when the experimental data aren't taken into account). If the time has to be corrected (e.g. in the case of double integrals), please use correct_time_Exp_Specs function prior to kinetic evaluation.

qvar.expr

Character string, pointing to qvar column/variable name in the original data.qt.expr data frame. Default: qvar.expr = NULL (when the experimental data aren't taken into account).

...

additional arguments passed to the ODE (see also ode).

Details

According to IUPAC (2019), see als the References, the rate of a chemical reaction with the radicals ( $\text{R}$ ) involved (refer to the example in model.react argument)

$a\text{A} + r\text{R} \xrightarrow\, b\text{B}$

is expressed via the time change of extent of the reaction ( $\text{d}\xi/\text{d}t$ ):

$-(1/r)\,(\text{d}n_{\text{R}}/\text{d}t) = -(1/a)\,(\text{d}n_{\text{A}}/\text{d}t) = (1/b)\,(\text{d}n_{\text{B}}/\text{d}t)$

where $a,r,b$ are the stoichiometric coefficients. At constant volume ( $V$ ) conditions (or if volume changes are negligible) the amount ( $n$ in mole) of reactant/product can be replaced by its corresponding concentration ( $c = n/V$ ). Such reaction rate (expressed in moles per unit volume and per second) is function of temperature ( $T$ ), pressure ( $p$ ) as well as that of concentration of reactants/products. For the reaction example shown above it applies (for radical $\text{R}$ ):

$\text{d}c_{\text{R}}/\text{d}t = - r\,k(T,p)\,c_{\text{A}}^{\alpha}\,c_{\text{R}}^{\beta}$

This is called rate law, where $k$ is the rate constant and its pressure dependence is usually small and therefore can be ignored, in the first approach. Coefficients $\alpha$ and $\beta$ , in general, correspond to fitting parameters, coming from experimental relation of the reaction rate and the concentration of reactants/products. These coefficients are called partial reaction orders or PROs and their sum represents total order of the reaction. If the kinetic equation, for the reaction, corresponds to its stoichiometry, the reaction is described as the elementary one. In EPR Spectroscopy the number of radicals is directly proportional to (double) integral of the radical EPR spectrum (see also quantify_EPR_Abs). Therefore, for a quick evaluation or and/or comparison of different kinetic data, one can also obtain the rate constant from the area/integral vs time fit onto the experimental EPR spectral time series outputs (see also the eval_kinR_EPR_modelFit). Accordingly, the "R" concentration (or number of radicals/V) can be replaced by the corresponding integral. For such a purpose a more general quantitative variable ( $qvar$ ) is defined. However, in such case the unit of $k$ must be expressed accordingly (see the kin.params argument). Quantitative kinetic profiles (such as that $\text{d}c_{\text{R}}/\text{d}t$ or $\text{d}(qvar)_{\text{R}}/\text{d}t$ described above) are not evaluated by common integration of the kinetic equations/rate laws, however by numeric solution of the Ordinary Differential Equations, ODE in {desolve} R package. Therefore, higher number of models might be available than for integrated differential equations, because for complex mechanisms it's quite often highly demanding to obtain the analytical solution by common integration. Several kinetic models for radical reactions in EPR spectroscopy are predefined and summarized below (see also the model.react function argument).

model.react	Short Description
`"(r=1)R --> [k1] B"`	Basic forward reaction, e.g. irrev. dimerization (if `(r=2)`).
`"(a=1)A --> [k1] (r=1)R"`	Basic forward radical formation
`"(a=1)A <==> [k1] [k4] (r=1)R <==> [k2] [k3] (b=1)B"`	Consecutive reactions, e.g. considering comproportionation (for `(a=2)` and `(r=2)`) + follow-up reversible dimerization (`(b=1)`).
`"(r=1)R <==> [k1] [k2] (b=1)B"`	Basic reversible radical quenching, e.g. rev. $\pi-\pi$ dimerization for `(r=2)` and `(b=1)`.
`"(a=1)A <==> [k1] [k2] (r=1)R"`	Basic reversible radical formation, e.g. from rev. comproportionation of conjugated thiophene oligomers ( $\text{A}^{++} + \text{A}^0 \xrightleftharpoons ~ 2\text{R}^{.+}$ , for `(a=2)` and `(r=2)`).
`"(a=1)A + (b=1)B --> [k1] (r=1)R"`	Radical formation by chemical reaction like oxidation, reduction or spin trapping (if `A` refers to transient radical, which is not visible within the common EPR time scale).
`"(a=1)A + (r=1)R --> [k1] B"`	General radical quenching by chemical reaction.

Value

If the function is not used for fitting of the experimental and processed data, the result is list consisting of:

df: Data frame, containing time column and qvar, quantitative variable, columns corresponding to quantities of different relevant species denoted as "R", "A", "B" + if data.qt.expr is NOT NULL additional experimental quantitative variable is present.
plot: Plot object, containing time as $x$ -axis and qvar (see df above) as $y$ -axis + if data.qt.expr is NOT NULL the experimental quantitative variable is presented as well.

Applying function for the fitting procedure requires model.expr.diff = TRUE and therefore the result is represented by the difference between the integral intensities/areas, calculated using the experimental data and those generated by the model.

References

International Union of Pure and Applied Chemistry (IUPAC) (2019). “Rate of Reaction”, https://goldbook.iupac.org/terms/view/R05156.

Quisenberry KT, Tellinghuisen J (2006). “Textbook Deficiencies: Ambiguities in Chemical Kinetics Rates and Rate Constants.” J. Chem. Educ., 83(3), 510, https://doi.org/10.1021/ed083p510.

Levine IN (2009). Physical Chemistry, 6th edition. McGraw-Hill, ISBN 978-0-072-53862-5, https://books.google.cz/books/about/Physical_Chemistry.html?id=L5juAAAAMAAJ&redir_esc=y.

rdabbler (2013). “Learning R: Parameter Fitting for Models Involving Differential Equations”, https://www.r-bloggers.com/2013/06/learning-r-parameter-fitting-for-models-involving-differential-equations/.

Examples

## irreversible dimerization quantitative kinetic profile,
## table (df) with first 10 observations/rows and application
## of the "euler" integrator (to solve ODE) method
##
kin.test.01 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      kin.params = c(k1 = 0.012,
                                     qvar0R = 0.08),
                      solve.ode.method = "euler")
## preview
head(kin.test.01$df,n = 10)
#
## consecutive reactions and the corresponding plot
## (`model.react` character string without spaces)
kin.test.02 <-
 eval_kinR_ODE_model(
   model.react = "(a=2)A<==>[k1][k4](r=2)R<==>[k2][k3](b=1)B",
   kin.params = c(k1 = 0.1,
                  k2 = 0.1,
                  k3 = 2e-4,
                  k4 = 2e-5,
                  qvar0A = 0.02,
                  qvar0R = 0.002,
                  qvar0B = 0)
 )
## plot preview
kin.test.02$plot
#
## data frame/table preview
head(kin.test.02$df)
#
## loading example data (incl. `Area` and `time` variables)
## from Xenon software: decay of a triarylamine radical cation
## after its generation by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated
## EPR spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
## data preview
head(triaryl_radCat_data)
#
## comparison of the kinetic model with the experimental
## data `triaryl_radCat_data`, kinetic parameters were estimated
## to be as close as possible to the latter.
compar_model_expr_data_01 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      kin.params = c(qvar0R = 0.019,
                                     k1 = 0.04),
                      time.interval.model = c(0,1500),
                      data.qt.expr = triaryl_radCat_data,
                      qvar.expr = "Area",
                      time.expr = "time_s")
## plot preview
compar_model_expr_data_01$plot
#
## previous kinetic model with partial reaction
## order ("alpha") corresponding to "R" (radical species).
## In such case REACTION is NOT CONSIDERED
## as an ELEMENTARY one !
compar_model_expr_data_02 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      elementary.react = FALSE,
                      kin.params = c(qvar0R = 0.019,
                                     k1 = 0.04,
                                     alpha = 1.9
                                    ),
                      time.interval.model = c(0,1500),
                      data.qt.expr = triaryl_radCat_data,
                      qvar.expr = "Area",
                      time.expr = "time_s")
## plot preview
compar_model_expr_data_02$plot


## irreversible dimerization quantitative kinetic profile,
## table (df) with first 10 observations/rows and application
## of the "euler" integrator (to solve ODE) method
##
kin.test.01 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      kin.params = c(k1 = 0.012,
                                     qvar0R = 0.08),
                      solve.ode.method = "euler")
## preview
head(kin.test.01$df,n = 10)
#
## consecutive reactions and the corresponding plot
## (`model.react` character string without spaces)
kin.test.02 <-
 eval_kinR_ODE_model(
   model.react = "(a=2)A<==>[k1][k4](r=2)R<==>[k2][k3](b=1)B",
   kin.params = c(k1 = 0.1,
                  k2 = 0.1,
                  k3 = 2e-4,
                  k4 = 2e-5,
                  qvar0A = 0.02,
                  qvar0R = 0.002,
                  qvar0B = 0)
 )
## plot preview
kin.test.02$plot
#
## data frame/table preview
head(kin.test.02$df)
#
## loading example data (incl. `Area` and `time` variables)
## from Xenon software: decay of a triarylamine radical cation
## after its generation by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated
## EPR spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
## data preview
head(triaryl_radCat_data)
#
## comparison of the kinetic model with the experimental
## data `triaryl_radCat_data`, kinetic parameters were estimated
## to be as close as possible to the latter.
compar_model_expr_data_01 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      kin.params = c(qvar0R = 0.019,
                                     k1 = 0.04),
                      time.interval.model = c(0,1500),
                      data.qt.expr = triaryl_radCat_data,
                      qvar.expr = "Area",
                      time.expr = "time_s")
## plot preview
compar_model_expr_data_01$plot
#
## previous kinetic model with partial reaction
## order ("alpha") corresponding to "R" (radical species).
## In such case REACTION is NOT CONSIDERED
## as an ELEMENTARY one !
compar_model_expr_data_02 <-
  eval_kinR_ODE_model(model.react = "(r=2)R --> [k1] B",
                      elementary.react = FALSE,
                      kin.params = c(qvar0R = 0.019,
                                     k1 = 0.04,
                                     alpha = 1.9
                                    ),
                      time.interval.model = c(0,1500),
                      data.qt.expr = triaryl_radCat_data,
                      qvar.expr = "Area",
                      time.expr = "time_s")
## plot preview
compar_model_expr_data_02$plot

ENDOR/Larmor Frequency of Specific Nucleus

Description

Larmor/ENDOR frequency calculations for the analysis in EPR/Electron-Nuclear Double Resonance (ENDOR). Function is inspired by the similar Larmor Frequency Calculator, available online.

Usage

eval_nu_ENDOR(nucle_us_i, B.unit = "G", B.val)
eval_nu_ENDOR(nucle_us_i, B.unit = "G", B.val)

Arguments

`nucle_us_i`	(Vector) character string in the form like `"14N"` or `c("1H","13C")`, pointing to specific nucleus/nuclei, for which the frequency should by calculated. The nuclear g-factors for those nuclei are taken from the `isotopes_ds`.
`B.unit`	Character string, denoting the magnetic flux density B unit. Default: `B.unit = "G"`.
`B.val`	Numeric, magnetic flux density $B$ -`value`. This actually corresponds to $B$ at which the EPR signal saturates to record the ENDOR spectrum/spectra.

Details

The frequency in MHz is calculated according to relation

$\nu_{\text{ENDOR}}^{} = - (1/h)\,\mu_{\text{N}}^{}\,g_{\text{n}}^{}\,B\,10^{-6}$

where $h$ is the Planck's constant, $\mu_{\text{N}}^{}$ is the nuclear magneton available from constants package (constants::syms$mun), $g_{\text{n}}^{}$ is the nuclear $g$ -factor of the specific nucleus (reported in the package isotopes_ds data frame as g_Nuclear) and finally, the $B$ denotes the magnetic flux density at which the ENDOR spectra are recorded (see also B.val in arguments). The $10^{-6}$ coefficient is referred to the resulting frequency in MHz. The negative sign " $-$ " mirrors the convention to describe the direction of magnetic spin moments precession either counter-clockwise ( $+$ , if $\gamma_{\text{n}}^{} < 0$ ) or clockwise ( $-$ , if $\gamma_{\text{n}}^{} > 0$ , Levitt MH (2013)).

Value

Numeric value or vector of nuclear Larmor/ENDOR frequencies in MHz for selected nuclei at $B$ = B.val.

References

Levitt MH (2013). Spin Dynamics: Basics of Nuclear Magnetic Resonance. Wiley, ISBN 978-1-118-68184-8, https://books.google.cz/books?id=bysFAa4MPQcC.

Examples

## Larmor/ENDOR frequency for one selected nucleus
## only, e.g. "14N" at 3486 G
eval_nu_ENDOR(nucle_us_i = "14N",
              B.val = 3486)
#
## Larmor/ENDOR frequency for selected nuclei
## e.g. "1H" and "31P" at saturation
## field of B = 349.9 mT
eval_nu_ENDOR(nucle_us_i = c("1H","31P"),
              B.unit = "mT",
              B.val = 349.9)


## Larmor/ENDOR frequency for one selected nucleus
## only, e.g. "14N" at 3486 G
eval_nu_ENDOR(nucle_us_i = "14N",
              B.val = 3486)
#
## Larmor/ENDOR frequency for selected nuclei
## e.g. "1H" and "31P" at saturation
## field of B = 349.9 mT
eval_nu_ENDOR(nucle_us_i = c("1H","31P"),
              B.unit = "mT",
              B.val = 349.9)

Peak Picking of EPR/ENDOR Spectra

Description

The peak picking expands the functionality of the basic eval_extremeX_Spec to quickly find extremes within several regions of the entire EPR/ENDOR Spectrum (without a need for an interactive plotting). The function is based on the findpeaks to find the local intensity maxima and/or minima by fitting the experimental EPR spectral parts/points using the shortened vertex form of a parabola. The parabola vertices actually represent the maxima or minima. Visualization of the peak picking is provided by the plot_EPR_Specs together with the geom_text function (see geom_label).

Usage

eval_peakPick_Spec(
  data.spectr,
  x = "B_mT",
  x.unit = "mT",
  xlim = NULL,
  Intensity = "dIepr_over_dB",
  Ilim = NULL,
  lineSpecs.form = "derivative",
  only.peak.pn = NULL,
  min.peak.height = NULL,
  min.peak.dist = NULL,
  min.peak.width = 1,
  max.peak.width = Inf,
  double.sided = TRUE,
  line.color = "darkviolet",
  peak.color = "steelblue",
  peak.text.angle = 90,
  peak.text.size = 3,
  peak.point.size = 2,
  peak.point.shape = 16,
  peak.text.overlap = FALSE,
  ...
)
eval_peakPick_Spec(
  data.spectr,
  x = "B_mT",
  x.unit = "mT",
  xlim = NULL,
  Intensity = "dIepr_over_dB",
  Ilim = NULL,
  lineSpecs.form = "derivative",
  only.peak.pn = NULL,
  min.peak.height = NULL,
  min.peak.dist = NULL,
  min.peak.width = 1,
  max.peak.width = Inf,
  double.sided = TRUE,
  line.color = "darkviolet",
  peak.color = "steelblue",
  peak.text.angle = 90,
  peak.text.size = 3,
  peak.point.size = 2,
  peak.point.shape = 16,
  peak.text.overlap = FALSE,
  ...
)

Arguments

`data.spectr`	Data frame object/table, containing `x`-values and the `Intensity` (see the arguments below), from which the peaks are to be found (picked).
`x`	Character string, pointing to $x$ -axis/column quantity header in the original `data.spectr` like magnetic flux density $B$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`x.unit`	Character string, pointing to unit of `x`-quantity coming from the original `data.spectra`. Units like `"G"` (Gauss), `"mT"` (millitesla), `"T"` (tesla), `"MHz"` (megahertz in case of ENDOR spectra) or `"Unitless"` / `"unitless"` (in case of $g$ -values) can be used. Default: `x.unit = "mT"`.
`xlim`	Numeric vector, referring to lower and upper limit of the selected $x$ -region, e.g. `xlim = c(3495.4,3595.4)` ( $B$ in `G`) or `xlim = c(12.5,21.2)` ( $RF$ in `MHz`) or `xlim = c(2.004,2.001)` (dimensionless $g$ ). Default: `xlim = NULL` (actually corresponding to the entire $x$ -range).
`Intensity`	Character string, pointing to `intensity column` name in the original `data.spectr` if other than `dIepr_over_dB` name/label is used (e.g. for simulated or integrated spectra), default: `Intesity = "dIepr_over_dB"`.
`Ilim`	Numeric vector, corresponding to limits of the selected `y` / `Intensity` region, e.g. `Ilim = c(-2e-3,2e-3)`. Default: `Ilim = NULL` (actually corresponding to the entire Intensity range).
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (in such case also `"absorption"` can be used) line form of the analyzed EPR spectrum/data.
`only.peak.pn`	Character string, setting up the selection of positive (`Intenstity` > 0) and/or negative (`Intensity` < 0) peaks (in the case of `lineSpecs.form = "derivative"`) or only positive ones (in the case of `lineSpecs.form = "integrated"` or `lineSpeccs.form = "absorption"`). Default: `only.peak.pn = NULL`, corresponding to automatic selection of positive/negative peaks depending on `lineSpecs.form`. In addition to `only.peak.pn = "positive"` and `only.peak.pn = "negative"` strings, the short code like `only.peak.pn = "p"` (or `"P"`) and `only.peak.pn = "n"` (or `"N"`) can be applied as well.
`min.peak.height`	Numeric, setting the `Intensity` threshold (its absolute value) in order to filter/select only those intensity values, which are taken to find to maxima and/or minima. Default: `min.peak.height = NULL`, corresponding to $20\,\%$ of the maximum Intensity value.
`min.peak.dist`	Numeric (integer > 0), pointing to minimum distance (in points) between the expected peaks, which are constructed by parabola fits over the points. For such purpose, the shortened (vertex) parabola (the 2nd polynomial) expression like $a\,(x - h)^2 + k$ is applied, where $a$ and $h,k$ denote the concavity and the vertex, respectively. These vertices actually correspond to peak maxima ( $a < 0$ ) or minima ( $a > 0$ ). Peaks separated by less than this distance are considered as a single peak. Please, also refer to documentation of the `findpeaks` function. The default distance (`min.peak.dist = NULL`) actually equals to one-half divided by the distance between the adjacent points, rounded to the integer: e.g. $round(0.5\,/\,(x_2 - x_1))$ where such formula corresponds to `round(0.5/(data.spectr[[x]][2] - data.spectr[[x]][1]))`. This is especially useful for rather noisy EPR spectra or spectra with high resolution. If according to `{ggplot2}` graphical representation the peak picking fails, i.e. not all peaks are properly detected, try lower values than the default one (such as 1 or 4 or ...etc.).
`min.peak.width`	Numeric (integer > 0), setting the minimum peak-width (points) to fit the vertex parabola expression (see also the `min.peak.dist` argument and the `findpeaks` documentation) to find the peaks. Default: `min.peak.width = 1`.
`max.peak.width`	Numeric (integer > 0), pointing to maximum peak-width (points) to find the peaks. Default: `max.peak.width = Inf` (infinity).
`double.sided`	Logical. Should be the peaks found for both intensity sites (`data.spectr[[Intensity]]` > 0 as well as `data.spectr[[Intensity]]` < 0)? If `lineSpecs.form = "derivative"` then `double.sided = TRUE`, default, otherwise, for the single integrated EPR spectra, it applies `double.sided = FALSE`.
`line.color`	Character string, line color to plot the EPR/ENDOR spectrum. All `{ggplot2}` colors are available (see also `aes_colour_fill_alpha`). Default: `line.color = "darkviolet"`.
`peak.color`	Character string, "point" color to visualize/emphasize the peaks. Similarly, as for the `line.color` argument, all `{ggplot2}` color definitions are available. Default: `peak.color = "steelblue"`.
`peak.text.angle`	Numeric, setting the angle (in deg) of the peak value (projection onto the $x$ -axis) annotation text, presented near the local maximum or minimum, and measured relatively to the $x$ -axis (see also `geom_text`). Default: `peak.text.angle = 90`.
`peak.text.size`	Numeric, pointing to peak annotation text size (in mm, see the `aes_linetype_size_shape`). Default: `peak.text.size = 3`.
`peak.point.size`	Numeric, size (in mm) of the peak "point" in graphical representation of the peak picking. Please consult the `aes_linetype_size_shape` `{ggplot2}` aesthetic arguments. Default: `peak.point.size = 2`.
`peak.point.shape`	Numeric (integer between 0 and 24), controlling the "point" symbol like square, triangle, circle, asterisk...etc, refer to e.g. `{ggplot2}` aesthetic specifications. Default: `peak.point.shape = 16` (filled circle).
`peak.text.overlap`	Logical, if `TRUE`, the overlapping peak text annotation to a previous one, will be not displayed, for clarity (see also `geom_label`). If `peak.text.overlap = FALSE` (default), all found peaks are presented with their corresponding values (text annotations).
`...`	additional arguments specified, please refer to the `plot_EPR_Specs` function, in order to customize the graphical output.

Value

List, consisting of following components, will be returned:

df: Data frame, corresponding to the original data.spectr, with all peaks (Intensity vs x) found by findpeaks algorithm and the arguments defined above.
plot: Graphical representation of found peaks in the EPR/ENDOR spectrum.

Examples

## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
## peak picking of only positive (Intensitity > 0)
## peaks in the derivative EPR spectrum of TMPD:
tmpd.peak.pick.01 <-
  eval_peakPick_Spec(data.spectr = tmpd.data.file,
                     only.peak.pn = "p",
                     min.peak.dist = 1)
#
## peak picking visualization:
tmpd.peak.pick.01$plot
#
## found peaks data frame preview
tmpd.peak.pick.01$df
#
## peak picking in 'G' (not in default 'mT')
## of both positive as well as negative intensities
## with the intensity threshold 15% of the maximum,
## peaks annotation text angle 60 deg:
tmpd.peak.pick.02 <-
  eval_peakPick_Spec(
    data.spectr = tmpd.data.file,
    x = "B_G",
    x.unit = "G",
    min.peak.height =
      0.15 * max(tmpd.data.file$dIepr_over_dB),
    peak.text.angle = 60
  )
#
## graph/EPR spectrum peaks preview:
tmpd.peak.pick.02$plot


## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G",
                                  "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
## peak picking of only positive (Intensitity > 0)
## peaks in the derivative EPR spectrum of TMPD:
tmpd.peak.pick.01 <-
  eval_peakPick_Spec(data.spectr = tmpd.data.file,
                     only.peak.pn = "p",
                     min.peak.dist = 1)
#
## peak picking visualization:
tmpd.peak.pick.01$plot
#
## found peaks data frame preview
tmpd.peak.pick.01$df
#
## peak picking in 'G' (not in default 'mT')
## of both positive as well as negative intensities
## with the intensity threshold 15% of the maximum,
## peaks annotation text angle 60 deg:
tmpd.peak.pick.02 <-
  eval_peakPick_Spec(
    data.spectr = tmpd.data.file,
    x = "B_G",
    x.unit = "G",
    min.peak.height =
      0.15 * max(tmpd.data.file$dIepr_over_dB),
    peak.text.angle = 60
  )
#
## graph/EPR spectrum peaks preview:
tmpd.peak.pick.02$plot

Simulation of Isotropic EPR Spectra

Description

EPR spectra often display hyperfine structure, where the spectral lines split into several other ones, as a consequence of the electron-nuclear interaction with nuclei close to the paramagnetic center. Sometimes, such splitting can be complicated and requires simulations, i.e. computational "synthesis" of spectral structure based on quantum chemistry as well as on mathematical description of spectral lineshapes (see also References). The actual function helps to analyze the hyperfine structure (HFS) of the isotropic EPR spectra by simulations. For such purpose, properties like nuclear $g$ -value, spin quantum number as well as natural abundance of the isotopes, related to interacting nuclei, must be known and are collected in the isotopes_ds. EPR spectra can be simulated for the derivative as well as for the integrated line forms (see the argument lineSpec.form).

Usage

eval_sim_EPR_iso(
  g.iso = 2.00232,
  instrum.params = c(Bcf = 3500, Bsw = 200, Npoints = 2048, mwGHz = 9.8),
  path_to_dsc_par = NULL,
  origin = NULL,
  B.unit = "G",
  nuclear.system = NULL,
  natur.abund = TRUE,
  lineSpecs.form = "derivative",
  lineGL.DeltaB = list(1, NULL),
  lineG.content = 1,
  Intensity.sim = "dIeprSim_over_dB",
  plot.sim.interact = FALSE
)
eval_sim_EPR_iso(
  g.iso = 2.00232,
  instrum.params = c(Bcf = 3500, Bsw = 200, Npoints = 2048, mwGHz = 9.8),
  path_to_dsc_par = NULL,
  origin = NULL,
  B.unit = "G",
  nuclear.system = NULL,
  natur.abund = TRUE,
  lineSpecs.form = "derivative",
  lineGL.DeltaB = list(1, NULL),
  lineG.content = 1,
  Intensity.sim = "dIeprSim_over_dB",
  plot.sim.interact = FALSE
)

Arguments

g.iso

Numeric value, guess of the isotropic $g$ -factor. It may also possess a NULL value if the $g$ corresponding to "central field" is equal to g.iso. Default: g.iso = 2.00232 (the approximate $g$ of the free electron).

instrum.params

Named numeric vector, containing instrumental parameters required for the simulation =>

`Bcf`	"central field" (magnetic flux density, $B_{\text{CF}}$ )
`Bsw`	"sweep width" (magnetic flux density recording region, $B_{\text{SW}}$ )
`Npoints`	number of spectral points (corresponding to resolution) within the "sweep width"
`mwGHz`	applied microwave frequency in `GHz` to record the continuous wave (CW) EPR spectrum

Default values are chosen to cover the EPR spectra of common organic radicals. If instrum.params = NULL then parameters must be provided by the path_to_dsc_par as well as by origin arguments.

path_to_dsc_par

Character string, path (can be also acquired by the file.path) to .DSC/.dsc or .par (depending on the OS, see origin argument) text files including all instrumental parameters from the EPR machine. Default: path_to_dsc_par = NULL in case if the instrum.params is already defined. IF the instrum.params = NULL then BOTH the path_to_dsc_par AS WELL AS the origin MUST BE DEFINED !

origin

Character string, corresponding to software which was used to obtain the EPR spectra on spectrometers, because the files are slightly different, whether they were recorded by the "WinEpr" (origin = "winepr") or by the "Xenon". Default: origin = NULL in case no file is used to extract the parameters (i.e. exactly if path_to_dsc_par = NULL).

B.unit

Character string, pointing to unit of magnetic flux density which is to be presented on $B$ -axis of the EPR spectrum, like "G" (Gauss) or "mT" (millitesla), default: B.unit = "G". THE UNIT MUST BE SHARED ACROSS ALL RELEVANT B-ARGUMENTS like cf and sw within the instrum.params AS WELL AS within THOSE IN lineGL.DeltaB !

nuclear.system

List, containing the information about groups of equivalent nuclei interacting with the unpaired electron like nuclear.system = list("14N",1,45). This corresponds to one group of "14N" interacting nuclei where the second number denotes the number of nuclei within the group and the third number is the guess of the hyperfine coupling constant in MHz. Therefore, in summary it refers to $A(1\times ^{14}\text{N}) = 45~\text{MHz}$ . If more complex interaction is considered, e.g. $A(3\times ^{1}\text{H}) = 5.06~\text{MHz} + A(6\times ^{1}\text{H}) = 17.64~\text{MHz}$ , such system must be defined by nested lists like nuclear.system = list(list("1H",3,5.06),list("1H",6,17.64)). The number of lists is not limited and therefore, any number of equivalent nuclei groups can be used to simulate the EPR spectra. Default: nuclear.system = NULL in case if no interaction with the unpaired electron surrounding nuclei is considered and only single line EPR spectrum is expected.

natur.abund

Logical, whether the natural abundance of the interacting nuclei is taken into the calculation of intensity pattern of the simulated EPR spectrum. Default: natur.abund = TRUE. For a single-line EPR spectrum without hyperfine splitting(HFS) it is automatically switched to natur.abund = FALSE.

lineSpecs.form

Character string, describing either "derivative" (default) or "integrated" (i.e. "absorption" which can be used as well) line form of the analyzed EPR spectrum/data.

lineGL.DeltaB

List of two values referred to as Gaussian (G) and Lorentzian (L) spectral line-forms, respectively. For the "pure" Gaussian only the first value is numeric and the second one is NULL => e.g. lineGL.DeltaB = list(1,NULL) (default). For the "pure" Lorentzian the opposite expression must be used => e.g. lineGL.DeltaB = list(NULL,0.5). If the linear combination of both line forms is taken into account (see lineG.content), that is so called pseudo-Voigt, then both values are numeric (e.g. lineGL.DeltaB = list(0.5,0.5)) and are related to Gaussian and Lorentzian forms, respectively. The DeltaB corresponds either to $\Delta B_{\text{pp}}$ (if lineSpecs.form = "derivative") or to $FWHM$ (if lineSpecs.form = "integrated" or if lineSpecs.form = "absorption"). The unit of values must coincide with those used in instrum.params as well as with B.unit.

lineG.content

Numeric value between 0 and 1 referring to content of Gaussian line form. If lineG.content = 1 (default) it corresponds to "pure" Gaussian line form and if lineG.content = 0 it corresponds to Lorentzian one. The value from (0,1) (e.g. lineG.content = 0.5) represents the linear combination (for the example above with the coefficients 0.5 and 0.5) of both line forms => so called pseudo-Voigt.

Intensity.sim

Character string, pointing to column of simulated EPR intensity within the related output data frame. Default: Intensity.sim = "dIeprSim_over_dB".

plot.sim.interact

Logical, whether to display the simulated spectrum by interactive plotly graph (see also plot_EPR_Specs2D_interact). If plot.sim.interact = FALSE (dafault), then the output contains the data frame as well as ggplot2 based plot of the simulated EPR spectrum within a list.

Details

Theoretical predictions or computations of a spectrum (and its comparison with the experiment) represent an important step in the analysis of EPR spectra. However, such step requires an iterative process with modelling the above-described electron-nuclear system followed by a numerical simulations of EPR spectra to match the experimental ones (see also eval_sim_EPR_isoFit). Commonly, quantum chemical calculations (usually DFT, see also vignette("functionality") are involved in this process. EPR simulations in the isotropic regime assume that the molecules tumble/move extremely fast causing a total averaging of any anisotropic properties out. An EPR spectrum corresponding to the latter consists of a series of symmetric lines with equal widths. In such case the spectrum is characterized by the isotropic HF coupling/splitting constants $A_{\text{iso}}/a_{\text{iso}}$ (see also the nuclear.system argument) as well as by the above-mentioned linewidth. Many organic radicals exhibit such EPR spectra at room temperature and in solutions of low viscosities (Gerson F, Huber W (2003), see References).

In the first step the $B$ -region (magnetic flux density) and the resolution must be defined by the instrum.params argument or can be directly acquired from the parameter file using the path_to_dsc_par argument. Position of the spectrum (within the desired $B$ -region) as well as those of HFS-lines are evaluated by the resonance condition (see also the eval_gFactor) and by the Breit-Rabi analytical expression for energy levels of the interacting nuclei. The related $B$ s are computed by the fixed-point iterations, because the corresponding $g$ -value for each of the HFS-lines is not known (Weil JA (1971) and Stoll A, Schweiger A (2006)). The shape of spectral lines are calculated by the analytical formula of linear combination of the Gaussian and the Lorentzian line-shapes (also referred to as pseudo-Voigt, Weil JA, Bolton JR (2007) and Stoll S (2024)). The linear coefficients are defined by the lineG.content argument, actually, corresponding to Gaussian line content (the Lorentzian one is computed as 1-lineG.content, accordingly). The linewidth, from that linear combination, is defined individually for the Gaussian and the Lorentzian (please, refer to the lineGL.DeltaB argument). The multiplicities (relative intensity ratios) are computed by the binomial/multinomial coefficients taking into account the spin quantum numbers of the interacting nuclei, in each of the equivalent groups, as well as their natural abundance (if natur.abund = TRUE).

Value

If plot.sim.interact = TRUE, function returns an interactive plot object with the simulated EPR spectrum. Otherwise (if plot.sim.interact = FALSE), the output is represented by the list with the following elements:

plot: ggplot2 static object showing the simulated EPR spectrum.
df: Data frame/table object related to the simulated spectrum.

References

Weil JA, Bolton JR (2007). Electron paramagnetic resonance: elementary theory and practical applications, 2nd edition. John Wiley and Sons. ISBN 978-0-471-75496-1, https://onlinelibrary.wiley.com/doi/book/10.1002/0470084987.

Weil JA (1971). “The Analysis of Large Hyperfine Splitting in Paramagnetic Resonance Spectroscopy.” J. Magn. Reson. (1969), 4(3), 394–399, https://doi.org/10.1016/0022-2364(71)90049-7.

Stoll S, Schweiger A (2006). “EasySpin, A Comprehensive Software Package for Spectral Simulation and Analysis in EPR.” J. Magn. Reson., 178(1), 42–55, https://doi.org/10.1016/j.jmr.2005.08.013.

Stoll S (2024). “EasySpin Documentation - Line Shapes.”, https://easyspin.org/easyspin/documentation/lineshapes.html.

Gerson F, Huber W (2003). Electron Spin Resonance Spectroscopy of Organic Radicals, Biotechnology Series, Wiley-VCH, ISBN 978-3-527-30275-8, https://books.google.cz/books?id=SEPeNjG3IvYC.

Examples

## simulation of simple EPR spectrum (without hyperfine
## structure) with g(iso) = 1.9804 and the linewidth
## ∆Bpp = 3.2 G, only Gaussian lineform is considered:
sim.simple.a <-
  eval_sim_EPR_iso(g.iso = 1.9804,
    instrum.params = c(Bcf = 3490,
                       Bsw = 200,
                       Npoints = 1600,
                       mwGHz = 9.8943),
    lineGL.DeltaB = list(3.2,NULL)
  )
## simulation preview:
sim.simple.a$plot
#
## simulation of luteolin radical anion with
## the following four hyperfine coupling constants
## A(1 x 1H) = 3.1 MHz, A(1 x 1H) = 2.8 MHz,
## A(1 x 1H) = 8.0 MHz and A(1 x 1H) = 4.1 MHz,
## one may check out the simulation
## at https://doi.org/10.1016/j.electacta.2013.06.136
## (see Fig. 6 in that article):
sim.luteol <-
  eval_sim_EPR_iso(g.iso = 2.00495,
    instrum.params = c(Bcf = 339.367,
                       Bsw = 5.9,
                       Npoints = 2048,
                       mwGHz = 9.5294),
    nuclear.system = list(list("1H",1,3.1),
                          list("1H",1,2.8),
                          list("1H",1,8.0),
                          list("1H",1,4.1)),
    lineGL.DeltaB = list(0.034,0.034),
    lineG.content = 0.6,
    B.unit = "mT"
 )
#
## simulated spectrum preview within
## the B = (338-341) mT region:
sim.luteol$plot +
  ggplot2::coord_cartesian(xlim = c(338,341))
#
## ...and the corresponding data frame:
head(sim.luteol$df)
#
## simulation of phenalenyl/perinaphthenyl
## (PNT) radical in the integrated form:
eval_sim_EPR_iso(g = 2.0027,
  instrum.params = c(Bcf = 3500, # central field
                     Bsw = 100, # sweep width
                     Npoints = 4096,
                     mwGHz = 9.8), # MW Freq. in GHz
  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
   ),
  lineSpecs.form = "integrated",
  lineGL.DeltaB = list(0.54,NULL), # Gauss. FWHM in G
  Intensity.sim = "single_Integ",
  plot.sim.interact = TRUE
 )



## simulation of simple EPR spectrum (without hyperfine
## structure) with g(iso) = 1.9804 and the linewidth
## ∆Bpp = 3.2 G, only Gaussian lineform is considered:
sim.simple.a <-
  eval_sim_EPR_iso(g.iso = 1.9804,
    instrum.params = c(Bcf = 3490,
                       Bsw = 200,
                       Npoints = 1600,
                       mwGHz = 9.8943),
    lineGL.DeltaB = list(3.2,NULL)
  )
## simulation preview:
sim.simple.a$plot
#
## simulation of luteolin radical anion with
## the following four hyperfine coupling constants
## A(1 x 1H) = 3.1 MHz, A(1 x 1H) = 2.8 MHz,
## A(1 x 1H) = 8.0 MHz and A(1 x 1H) = 4.1 MHz,
## one may check out the simulation
## at https://doi.org/10.1016/j.electacta.2013.06.136
## (see Fig. 6 in that article):
sim.luteol <-
  eval_sim_EPR_iso(g.iso = 2.00495,
    instrum.params = c(Bcf = 339.367,
                       Bsw = 5.9,
                       Npoints = 2048,
                       mwGHz = 9.5294),
    nuclear.system = list(list("1H",1,3.1),
                          list("1H",1,2.8),
                          list("1H",1,8.0),
                          list("1H",1,4.1)),
    lineGL.DeltaB = list(0.034,0.034),
    lineG.content = 0.6,
    B.unit = "mT"
 )
#
## simulated spectrum preview within
## the B = (338-341) mT region:
sim.luteol$plot +
  ggplot2::coord_cartesian(xlim = c(338,341))
#
## ...and the corresponding data frame:
head(sim.luteol$df)
#
## simulation of phenalenyl/perinaphthenyl
## (PNT) radical in the integrated form:
eval_sim_EPR_iso(g = 2.0027,
  instrum.params = c(Bcf = 3500, # central field
                     Bsw = 100, # sweep width
                     Npoints = 4096,
                     mwGHz = 9.8), # MW Freq. in GHz
  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
   ),
  lineSpecs.form = "integrated",
  lineGL.DeltaB = list(0.54,NULL), # Gauss. FWHM in G
  Intensity.sim = "single_Integ",
  plot.sim.interact = TRUE
 )

Simulation of Isotropic EPR Spectra Consisting of Several Components

Description

This is an extension of the "basic" EPR simulation provided by the eval_sim_EPR_iso function, where one can combine several simulated EPR spectra (components), even with (partial) overlay, into one spectrum corresponding to sum of all components. Such processing might be useful for the simulation of EPR spectra with satellites, especially of those consisted of naturally occurring isotopes, like the one presented in Examples.

Usage

eval_sim_EPR_iso_combo(
  g.iso.vec,
  instrum.params = c(Bcf = 3500, Bsw = 200, Npoints = 2048, mwGHz = 9.8),
  B.unit = "G",
  path_to_dsc_par = NULL,
  origin = NULL,
  nuclear.system,
  natur.abund.vec,
  lineSpecs.form = "derivative",
  lineGL.DeltaB,
  lineG.content.vec,
  Intensity.sim = "dIeprSim_over_dB",
  Intensity.sim.coeffs.vec,
  plot.sim.interact = NULL
)
eval_sim_EPR_iso_combo(
  g.iso.vec,
  instrum.params = c(Bcf = 3500, Bsw = 200, Npoints = 2048, mwGHz = 9.8),
  B.unit = "G",
  path_to_dsc_par = NULL,
  origin = NULL,
  nuclear.system,
  natur.abund.vec,
  lineSpecs.form = "derivative",
  lineGL.DeltaB,
  lineG.content.vec,
  Intensity.sim = "dIeprSim_over_dB",
  Intensity.sim.coeffs.vec,
  plot.sim.interact = NULL
)

Arguments

g.iso.vec

Numeric vector with all $g_{\text{iso}}$ values fro each component.

instrum.params

Named numeric vector, containing instrumental parameters required for the simulation =>

`Bcf`	"central field" (magnetic flux density, $B_{\text{CF}}$ )
`Bsw`	"sweep width" (magnetic flux density recording region, $B_{\text{SW}}$ )
`Npoints`	number of spectral points (corresponding to resolution) within the "sweep width"
`mwGHz`	applied microwave frequency in `GHz` to record the continuous wave (CW) EPR spectrum

B.unit

path_to_dsc_par

origin

nuclear.system

Nested list with the elements corresponding to considered interacting nuclei for each EPR spectral component. For example, the list(list("1H",2,24),NULL,list(list("14N",1,45),list("1H",4,15))) refers to the following components: 1. $2\times A(\text{1H}) = 24\,\text{MHz}$ , 2. single line spectrum without HF structure, 3. $1\times A(\text{14N}) = 45\,\text{MHz} + 4\times A(\text{1H}) = 15\,\text{MHz}$ .

natur.abund.vec

Logical vector, whether to consider natural abundance of the interacting nuclei within the components (see also Examples) like c(TRUE,FALSE,TRUE).

lineSpecs.form

Character string, describing either "derivative" (default) or "integrated" (i.e. "absorption" which can be used as well) line form of the analyzed EPR spectrum/data.

lineGL.DeltaB

Nested list of the Gaussian and Lorentzian linewidths for all individual components like list(list(1,NULL),list(3,NULL),list(1,NULL)).

lineG.content.vec

Numeric vector, corresponding to Gaussian line content for all individual components of the EPR spectrum like 1,1,1 (all spectral components are described by the pure Gaussian line).

Intensity.sim

Character string, pointing to column of simulated EPR intensity within the related output data frame. Default: Intensity.sim = "dIeprSim_over_dB".

Intensity.sim.coeffs.vec

Numeric vector of multiplication coefficients related to EPR component intensities like c(2,10,0.2).

plot.sim.interact

Character string, indicating the interactive plot outputs, to visualize either individual "components" or "sum" of all components. As default, the interactive plot is switched off (plot.sim.interact = NULL).

Value

List of the following data frames and plots in case of plot.sim.interact = NULL =>

df: Long-format data frame with the simulated EPR spectral components A, B, C, ... (e.g. representing the individual radicals) as a categorical variable + magnetic flux density, intensity as well as their sigmoid integral column/variable.
df.areas: Data frame with simulation components A, B, C ...and their corresponding double/single integrals (or areas) and their relative ratios to overall integral sum (weighted_areas).
df.sum: Data frame with the overall intensity (+ magnetic flux density) as well as integral sum from all simulation components.
plot.comps: Overlay plot object with all simulated components with their corresponding intensities defined by Intensity.sim.coeffs.vec.
plot.sum: Plot object displaying the sum of all simulation components.

If plot.sim.interact is activated (i.e. possesses either "components" or "sum" values) interactive plots (based on plotly) are presented either with all individual components or with the overall simulated EPR spectrum sum, respectively.

Examples

## Simulation of EPR spectrum of TEMPO (aminoxyl)
## radical with 13C satellites and hyperfine coupling
## constants A(1 x 14N) = 48 MHz, A(1 x 13C) = 18.2 MHz,
## the latter 13C may appear on 4 different
## positions (methyl carbons) => therefore the overall
## probability to find it at any position is
## approx. 4,4% (1.1% per one 13C), the additional
## two quaternary α-Carbons are not considered
## see e.g. https://doi.org/10.1016/j.mencom.2014.09.018
sim.tempo.13c <-
eval_sim_EPR_iso_combo(g.iso.vec = c(2.0059,2.0059),
                       nuclear.system = list(list("14N",1,48),
                                             list(list("14N",1,48),
                                                  list("13C",1,18.5)
                                               )
                                            ),
                       natur.abund.vec = c(FALSE,FALSE),
                       lineGL.DeltaB = list(list(1.3,NULL),
                                            list(1.3,NULL)
                                            ),
                       lineG.content.vec = c(1,1),
                       Intensity.sim.coeffs.vec = c(0.956/3,0.044/6))
#
## simulated spectrum/plot:
sim.tempo.13c$plot.sum +
ggplot2::coord_cartesian(xlim = c(3425,3550))
#
## ...and the corresponding data frame:
options(pillar.sigfig = 5) ## prevent rounding
#
tempo.df.sum <- sim.tempo.13c$df.sum
tempo.df.sum[1000:1005, ]
#
## data frame with all components:
sim.tempo.13c$df[1000:1005,]
#
## areas/integrals
sim.tempo.13c$df.areas


## Simulation of EPR spectrum of TEMPO (aminoxyl)
## radical with 13C satellites and hyperfine coupling
## constants A(1 x 14N) = 48 MHz, A(1 x 13C) = 18.2 MHz,
## the latter 13C may appear on 4 different
## positions (methyl carbons) => therefore the overall
## probability to find it at any position is
## approx. 4,4% (1.1% per one 13C), the additional
## two quaternary α-Carbons are not considered
## see e.g. https://doi.org/10.1016/j.mencom.2014.09.018
sim.tempo.13c <-
eval_sim_EPR_iso_combo(g.iso.vec = c(2.0059,2.0059),
                       nuclear.system = list(list("14N",1,48),
                                             list(list("14N",1,48),
                                                  list("13C",1,18.5)
                                               )
                                            ),
                       natur.abund.vec = c(FALSE,FALSE),
                       lineGL.DeltaB = list(list(1.3,NULL),
                                            list(1.3,NULL)
                                            ),
                       lineG.content.vec = c(1,1),
                       Intensity.sim.coeffs.vec = c(0.956/3,0.044/6))
#
## simulated spectrum/plot:
sim.tempo.13c$plot.sum +
ggplot2::coord_cartesian(xlim = c(3425,3550))
#
## ...and the corresponding data frame:
options(pillar.sigfig = 5) ## prevent rounding
#
tempo.df.sum <- sim.tempo.13c$df.sum
tempo.df.sum[1000:1005, ]
#
## data frame with all components:
sim.tempo.13c$df[1000:1005,]
#
## areas/integrals
sim.tempo.13c$df.areas

Least-Squares Fitting of Isotropic EPR spectra by Simulations

Description

Fitting of the simulated spectrum onto the experimental one represents an important step in the analysis of EPR spectra. Parameters of the simulated spectrum like $g_{\text{iso}}$ ; coupling constants (in MHz) $A_{\text{iso}}$ for each group of equivalent nuclei; linewidth (either $\Delta B_{\text{pp}}$ or $FWHM$ depending on the lineSpecs.form argument); spectral baseline (see the baseline.correct) and finally the intensity (multiplication coefficient) are optimized by the methods listed in optim_for_EPR_fitness. The lineG.content corresponding parameter is the only one, which needs to be varied "manually". In order to control the optimization/fitting process, by similar interactive way like in EasySpin, a Shiny app and/or gganimate visualization is under development.

Usage

eval_sim_EPR_isoFit(
  data.spectr.expr,
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  nu.GHz,
  B.unit = "G",
  nuclear.system.noA = NULL,
  baseline.correct = "constant",
  lineG.content = 0.5,
  lineSpecs.form = "derivative",
  optim.method = "neldermead",
  optim.params.init,
  optim.params.lower = NULL,
  optim.params.upper = NULL,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  check.fit.plot = TRUE,
  output.list.final = FALSE,
  ...
)
eval_sim_EPR_isoFit(
  data.spectr.expr,
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  nu.GHz,
  B.unit = "G",
  nuclear.system.noA = NULL,
  baseline.correct = "constant",
  lineG.content = 0.5,
  lineSpecs.form = "derivative",
  optim.method = "neldermead",
  optim.params.init,
  optim.params.lower = NULL,
  optim.params.upper = NULL,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  check.fit.plot = TRUE,
  output.list.final = FALSE,
  ...
)

Arguments

`data.spectr.expr`	Data frame object/table, containing the experimental spectral data the with magnetic flux density (`"B_mT"` or `"B_G"`) and the intensity (see the `Intensity.expr` argument) columns.
`Intensity.expr`	Character string, pointing to column name of the experimental EPR intensity within the original `data.spectr.expr`. Default: `dIepr_over_dB`.
`Intensity.sim`	Character string, pointing to column name of the simulated EPR intensity within the related output data frame. Default: `Intensity.sim = "dIeprSim_over_dB"`.
`nu.GHz`	Numeric value, microwave frequency in `GHz`.
`B.unit`	Character string, denoting the magnetic flux density unit e.g. `B.unit = "G"` (gauss, default) or `B.unit = "mT"`/`"T"` (millitesla/tesla).
`nuclear.system.noA`	List or nested list without estimated hyperfine coupling constant values, such as `list("14N",1)` or `list(list("14N", 2),list("1H", 4),list("1H", 12))`. The $A$ -values are already defined as elements of the `optim.params.init` argument/vector. If the EPR spectrum does not display any hyperfine splitting, the argument definition reads `nuclear.system.noA = NULL` (default).
`baseline.correct`	Character string, referring to baseline correction of the simulated/fitted spectrum. Corrections like `"constant"` (default), `"linear"` or `"quadratic"` can be applied.
`lineG.content`	Numeric value between `0` and `1`, referring to content of the Gaussian line form. If `lineG.content = 1` (default) it corresponds to "pure" Gaussian line form and if `lineG.content = 0` it corresponds to Lorentzian one. The value from (0,1) (e.g. `lineG.content = 0.5`) represents the linear combination (for the example above, with the coefficients 0.5 and 0.5) of both line forms => so called pseudo-Voigt.
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (i.e. `"absorption"` which can be used as well) line form of the analyzed EPR spectrum/data.
`optim.method`	Character string (vector), setting the optimization method(s) gathered within the `optim_for_EPR_fitness`. Default: `optim.method = "neldermead"`. Additionally, several consecutive methods can be defined like `optim.method = c("levenmarq","neldermead")`, where the best fit parameters from the previous method are used as input for the next one. In such case, the output is `list` with the elements/vectors from each method, in order to see the progress of the optimization.
`optim.params.init`	Numeric vector with the initial parameter guess (elements) where the first five elements are immutable g-value (g-factor) Gaussian linewidth Lorentzian linewidth baseline constant (intercept) intensity multiplication constant baseline slope (only if `baseline.correct = "linear"` or `baseline.correct = "quadratic"`), if `baseline.correct = "constant"` it corresponds to the first HFCC ( $A_1$ ) baseline quadratic coefficient (only if `baseline.correct = "quadratic"`), if `baseline.correct = "constant"` it corresponds to the second HFCC ( $A_2$ ), if `baseline.correct = "linear"` it corresponds to the first HFCC ( $A_1$ ) additional HFCC ( $A_3$ ) if `baseline.correct = "constant"` or if `baseline.correct = "linear"` ( $A_2$ ), if `baseline.correct = "quadratic"` it corresponds to the first HFCC ( $A_1$ ) ...additional HFCCs ( $A_k...$ , each vector element is reserved only for one $A$ ) DO NOT PUT ANY OF THESE PARAMETERS to `NULL`. If the lineshape is expected to be pure Lorentzian or pure Gaussian then put the corresponding vector element to `0`.
`optim.params.lower`	Numeric vector (with the same element order like `optim.params.init`) with the lower bound constraints. Default: `optim.params.lower = NULL` which actually equals to $g_{\text{init}} - 0.001$ , $0.8\,\Delta B_{\text{G,init}}$ , $0.8\,\Delta B_{\text{L,init}}$ , baseline intercept initial constant $- 0.001$ , intensity multiplication initial constant $= 0.8\,\text{init}$ , baseline initial slope $- 5$ (in case the `baseline.correct` is set either to `"linear"` or `"quadratic"`) and finally, the baseline initial quadratic coefficient $- 5$ (in case the `baseline.correct` is set to `"quadratic"`). Lower limits of all hyperfine coupling constant (HFCCs) are set to $0.875\,A_{\text{init}}$ .
`optim.params.upper`	Numeric vector (with the same element order like `optim.params.init`) with the upper bound constraints. Default: `optim.params.upper = NULL` which actually equals to $g_{\text{init}} + 0.001$ , $1.2\,\Delta B_{\text{G,init}}$ , $1.2\,\Delta B_{\text{L,init}}$ , baseline intercept initial constant $+ 0.001$ , intensity multiplication initial constant $= 1.2\,\text{init}$ , baseline initial slope $+ 5$ (in case the `baseline.correct` is set either to `"linear"` or `"quadratic"`) and finally, the baseline initial quadratic coefficient $+ 5$ (in case the `baseline.correct` is set to `"quadratic"`). Upper limits of all HFCCs are set to $1.125\,A_{\text{init}}$ .
`Nmax.evals`	Numeric value, maximum number of function evaluations and/or iterations. The only one method, limited by this argument, is `nls.lm`, where `Nmax.evals = 1024`. Higher `Nmax.evals` may extremely extend the optimization time, therefore the default value reads `Nmax.evals = 512`. However, the `"pswarm"` method requires at least the default or even higher values.
`tol.step`	Numeric value, describing the smallest optimization step (tolerance) to stop the optimization. Default: `tol.step = 5e-7`.
`pswarm.size`	Numeric value, which equals to particle swarm size (i.e. number of particles), if `method = "pswarm"`. The default value (`pswarm.size = NULL`) actually corresponds to `floor(10+2*sqrt(length(x.0)))` (for `SPSO2007`, see the `pswarm.type` argument), e.g. to optimize 8 parameters, number of particles = 15. For the `SPSO2011` the default number of particles equals to `40`.
`pswarm.diameter`	Numeric value, corresponding to diameter of the particle swarm search space (in case `method = "pswarm"`). The default value (`pswarm.diameter = NULL`) refers to the Euclidean distance, defined as: $\sqrt{\sum_k\,(\text{optim.params.upper}[k] - \text{optim.params.lower}[k])^2}$
`pswarm.type`	Character string, setting the type/version of particle swarm algorithm if `method = "pswarm"`. There are two types available: `pswarm.type = "SPSO2007"` and `pswarm.type = "SPSO2011"`. The latter introduced an adaptive random topology, which allows the swarm to dynamically adjust its communication structure. This helps in maintaining diversity in the swarm and improves the algorithm's ability to escape local optima. This type generally offers better performance on larger multidimensional spaces than the `pswarm.type = "SPSO2007"`, which uses a more static topology. Details may be found in the `References` of the `optim_for_EPR_fitness`. Default: `pswarm.type = NULL` (actually corresponding to `"SPSO2007"`, that performs slightly better on smaller scales such as simulations of EPR spectra).
`check.fit.plot`	Logical, whether to return overlay plot with the initial simulation + the best simulation fit + experimental spectrum (including residuals in the lower part of the plot, `check.fit.plot = TRUE`, default) or with the following three spectra (`check.fit.plot = FALSE`): 1. experimental, 2. the best simulated one with the baseline fit and 3. the best simulated spectrum with the baseline fit subtracted. The latter two are offset for clarity, within the plot.
`output.list.final`	Logical. If `TRUE`, `list` with the following components will be exclusively returned: 1. optimized parameters from the best fit (together with the minimum sum of residual squares) and 2. data frame of the final best simulated spectrum with and without the baseline fit (see `Value`). Such output will be applied for the more complex optimization/fitting (which is currently under development), as stated in the `Description`, therefore, the default value reads `output.list.final = FALSE`.
`...`	additional arguments specified (see also `optim_for_EPR_fitness`).

Value

Optimization/Fitting procedure results in vector or data frame or list depending on the check.fit.plot and output... arguments.

If check.fit.plot = TRUE or check.fit.plot = FALSE, the result corresponds to list with the following components:

plot

Visualization of the experimental as well as the best fitted EPR simulated spectra. If check.fit.plot = TRUE, the overlay plot consists of the initial simulation + the best simulation fit + experimental spectrum, including residuals in the plot lower part. Whereas, if check.fit.plot = FALSE, following three spectra are available: 1. experimental, 2. the best simulated one with the baseline fit and 3. the best simulated spectrum with the baseline fit subtracted. The latter two are offset for clarity.

best.fit.params

Vector of the best (final) fitting (optimized) parameters, for each corresponding optim.method, to simulate the experimental EPR spectrum, see also description of the optim.params.init.

df

Tidy data frame (table) with the magnetic flux density and intensities of the experimental, the best simulated/fitted, as well as the initially simulated EPR spectrum and residuals (if check.fit.plot = TRUE), or wide data frame with the following variables / columns (for check.fit.plot = FALSE): magnetic flux density, intensity of the experimental spectrum, intensity of the best simulated one (including the baseline fit), residual intensity and finally, the best simulated spectrum intensity without the baseline fit.

min.rss

Minimum sum of residual squares (vector) after the least-square procedure.

N.evals

Number of iterations/function evaluations completed before termination. If the pswarm optimization algorithm is included in optim.method, the N.evals equals to vector with the following elements: number of function evaluations, number of iterations (per one particle) and the number of restarts.

N.converg

Vector or simple integer code indicating the successful completion of the optimization/fit. In the case of "levenmarq" method, the vector elements coincide with the sum of residual squares at each iteration. If the optim.method = "pswarm" is applied, one of the following codes can be returned: 0: algorithm terminated by reaching the absolute tolerance, 1: maximum number of function evaluations reached, 2: maximum number of iterations reached, 3: maximum number of restarts reached, 4: maximum number of iterations without improvement reached. For all the other remaining methods (coming from {nloptr} package), the integers have to be positive to indicate the successful convergence.
If output.list.final = TRUE, the function exclusively returns list with the two components, which will be applied for the more complex optimization/fitting (which is currently under development).

params

Vector, corresponding to the best fitting (optimized) parameters (related to the optim.params.init argument, see also list above) + minimum sum of residual squares, after the (final) optim.method procedure.

df

Data frame including the final best simulated spectrum with and without the baseline fit.

Note

In order to guess the intensity multiplication constant (please, refer to the optim.params.init argument), one might compare the intensities of the experimental (expr) and simulated (sim) EPR spectrum by one of the interactive or static plot functions (e.g. plot_EPR_Specs or plot_EPR_Specs2D_interact) as well as by the eval_sim_EPR_iso. Accordingly, the initial intensity multiplication constant can be estimated as the ratio max(expr intensity)/max(sim intensity).

Examples

## loading built-in example dataset which is simple
## EPR spectrum of the aminoxyl radical:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## EPR spectrum simulation fit with "Nelder-Mead"
## optimization method with `check.fit.plot = FALSE`:
tempo.test.sim.fit.a <-
  eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data,
    nu.GHz = 9.806769,
    lineG.content = 0.5,
    optim.method = "neldermead",
    nuclear.system.noA = list("14N",1),
    baseline.correct = "linear",
    optim.params.init =
      c(2.006, # g-value
        4.8, # G Delta Bpp
        4.8, # L Delta Bpp
        0, # intercept (constant) lin. baseline
        0.018, # Sim. intensity multiply
        1e-6, # slope lin. baseline
        49), # A in MHz
    check.fit.plot = FALSE
  )
## OUTPUTS:
## best fit parameters:
tempo.test.sim.fit.a$best.fit.params
#
## spectrum plot with experimental spectrum,
## simulated one with the linear baseline fit
## and simulated one with the linear baseline
## fit subtracted:
tempo.test.sim.fit.a$plot
#
## minimum sum of residual squares:
tempo.test.sim.fit.a$min.rss
#
## number of evaluations / iterations:
tempo.test.sim.fit.a$N.evals
#
## convergence, in this case it is represented
## by the integer code indicating the successful
## completion (it must be > 0):
tempo.test.sim.fit.a$N.converg
#
## preview of data frame including all EPR spectra:
head(tempo.test.sim.fit.a$df)
#
## similar EPR spectrum simulation fit with "particle swarm"
## optimization algorithm and `check.fit.plot = TRUE` option
## as well as user defined bound constraints:
tempo.test.sim.fit.b <-
  eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data,
    nu.GHz = 9.806769,
    lineG.content = 0.4,
    optim.method = "pswarm",
    nuclear.system.noA = list("14N",1),
    baseline.correct = "constant",
    optim.params.init = c(2.006,4.8,4.8,0,1.4e-2,49),
    optim.params.lower = c(2.0048,4.4,4.4,-1e-4,1.1e-2,45),
    optim.params.upper = c(2.0072,5.2,5.2,1e-4,1.7e-2,53),
    check.fit.plot = TRUE
  )
## OUTPUTS:
## best fit parameters:
tempo.test.sim.fit.b$best.fit.params
#
## quick simulation check by plotting the both
## simulated and the experimental EPR spectra
## together with the initial simulation
## and the residuals (differences between the
## experiment and the best fit)
tempo.test.sim.fit.b$plot
#
## fitting of the aminoxyl EPR spectrum
## by the combination of the 1. "Levenberg-Marquardt"
## and 2. "Nelder-Mead" algorithms
tempo.test.sim.fit.c <-
  eval_sim_EPR_isoFit(aminoxyl.data,
                      nu.GHz = 9.86769,
                      lineG.content = 0.5,
                      optim.method = c("levenmarq",
                                       "neldermead"),
                      nuclear.system.noA = list("14N",1),
                      baseline.correct = "constant",
                      optim.params.init = c(2.0060,
                                            4.8,
                                            4.8,
                                            0,
                                            7e-3,
                                            49),
                      check.fit.plot = FALSE
                    )
## OUTPUTS:
## best fit parameters for both procedures within a list:
tempo.test.sim.fit.c$best.fit.params
#
## compare the results with the example in the `readMAT_params_file`,
## corresponding to the best fit from `Easyspin`
#
## `N.converg` also consists of two components
## each corresponding to result of the individual
## optimization method where the "levenmarq" returns
## the sum of squares at each iteration, therefore the 1st
## component is vector and the 2nd one is integer code
## as already stated above:
tempo.test.sim.fit.c$N.converg


## loading built-in example dataset which is simple
## EPR spectrum of the aminoxyl radical:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## EPR spectrum simulation fit with "Nelder-Mead"
## optimization method with `check.fit.plot = FALSE`:
tempo.test.sim.fit.a <-
  eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data,
    nu.GHz = 9.806769,
    lineG.content = 0.5,
    optim.method = "neldermead",
    nuclear.system.noA = list("14N",1),
    baseline.correct = "linear",
    optim.params.init =
      c(2.006, # g-value
        4.8, # G Delta Bpp
        4.8, # L Delta Bpp
        0, # intercept (constant) lin. baseline
        0.018, # Sim. intensity multiply
        1e-6, # slope lin. baseline
        49), # A in MHz
    check.fit.plot = FALSE
  )
## OUTPUTS:
## best fit parameters:
tempo.test.sim.fit.a$best.fit.params
#
## spectrum plot with experimental spectrum,
## simulated one with the linear baseline fit
## and simulated one with the linear baseline
## fit subtracted:
tempo.test.sim.fit.a$plot
#
## minimum sum of residual squares:
tempo.test.sim.fit.a$min.rss
#
## number of evaluations / iterations:
tempo.test.sim.fit.a$N.evals
#
## convergence, in this case it is represented
## by the integer code indicating the successful
## completion (it must be > 0):
tempo.test.sim.fit.a$N.converg
#
## preview of data frame including all EPR spectra:
head(tempo.test.sim.fit.a$df)
#
## similar EPR spectrum simulation fit with "particle swarm"
## optimization algorithm and `check.fit.plot = TRUE` option
## as well as user defined bound constraints:
tempo.test.sim.fit.b <-
  eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data,
    nu.GHz = 9.806769,
    lineG.content = 0.4,
    optim.method = "pswarm",
    nuclear.system.noA = list("14N",1),
    baseline.correct = "constant",
    optim.params.init = c(2.006,4.8,4.8,0,1.4e-2,49),
    optim.params.lower = c(2.0048,4.4,4.4,-1e-4,1.1e-2,45),
    optim.params.upper = c(2.0072,5.2,5.2,1e-4,1.7e-2,53),
    check.fit.plot = TRUE
  )
## OUTPUTS:
## best fit parameters:
tempo.test.sim.fit.b$best.fit.params
#
## quick simulation check by plotting the both
## simulated and the experimental EPR spectra
## together with the initial simulation
## and the residuals (differences between the
## experiment and the best fit)
tempo.test.sim.fit.b$plot
#
## fitting of the aminoxyl EPR spectrum
## by the combination of the 1. "Levenberg-Marquardt"
## and 2. "Nelder-Mead" algorithms
tempo.test.sim.fit.c <-
  eval_sim_EPR_isoFit(aminoxyl.data,
                      nu.GHz = 9.86769,
                      lineG.content = 0.5,
                      optim.method = c("levenmarq",
                                       "neldermead"),
                      nuclear.system.noA = list("14N",1),
                      baseline.correct = "constant",
                      optim.params.init = c(2.0060,
                                            4.8,
                                            4.8,
                                            0,
                                            7e-3,
                                            49),
                      check.fit.plot = FALSE
                    )
## OUTPUTS:
## best fit parameters for both procedures within a list:
tempo.test.sim.fit.c$best.fit.params
#
## compare the results with the example in the `readMAT_params_file`,
## corresponding to the best fit from `Easyspin`
#
## `N.converg` also consists of two components
## each corresponding to result of the individual
## optimization method where the "levenmarq" returns
## the sum of squares at each iteration, therefore the 1st
## component is vector and the 2nd one is integer code
## as already stated above:
tempo.test.sim.fit.c$N.converg

Nuclear Isotope Data Frame (Dataset) with ENDOR Frequencies

Description

Data frame/Dataset summarizing the essential characteristics of nuclei in EPR spectroscopy.

Usage

isotopes_ds
isotopes_ds

Format

A data frame with 351 rows and 9 variables/columns:

No_Proton: Numeric, proton number.
Isotope: Character, ponting to isotope in format like "14N".
Stability: Character, pointing either to stable, "STB", or to radio-active, "RA", isotope.
Name: Character, corresponding to isotope name.
Spin: Numeric, denoting the spin quantum number.
g_Nuclear: Numeric, corresponding to nuclear $g$ -factor ( $g_{\text{n}}^{}$ ).
Abund_Natur_Percent: Numeric, pointing to natural abundance of an isotope in $\%$ .
Q_Barn: Numeric, corresponding to nuclear quadrupolar moment in $10^{-28}\,\text{m}^2$ .
nu_ENDOR_MHz_035T: Numeric, specific Larmor/ENDOR frequency ( $\nu_{\text{ENDOR}}^{}$ ) at $0.35\,\text{T}$ .

Details

This dataset was taken form 'EasySpin' toolbox and only it's format was slightly modified. Therefore, IT CONTAINS THE ENTIRE INFORMATION LIKE THE ORIGINAL DATASET (see the Source). For better orientation in ENDOR spectra, column with the Larmor/ENDOR frequencies (in MHz) at 0.35 T was added according to =>

$\nu_{\text{ENDOR}}^{} = - (1/h)\,\mu_{\text{N}}^{}\,g_{\text{n}}^{}\,B\,10^{-6}$

where $h$ is the Planck's constant, $\mu_{\text{N}}^{}$ is the nuclear magneton available from constants package (constants::syms$mun,syms), $g_{\text{n}}^{}$ is the nuclear $g$ -factor of the specific nucleus (reported in the data frame as g_Nuclear) and finally, the $B = 0.35\,\text{T}$ denotes the magnetic flux density. The negative sign " $-$ " mirrors convention to describe the direction of magnetic spin moments precession (see also eval_nu_ENDOR) either counter-clockwise ( $+$ , if $\gamma_{\text{n}}^{} < 0$ ) or clockwise ( $-$ , if $\gamma_{\text{n}}^{} > 0$ ) Please, consult the vignette("datasets") as well.

Source

https://easyspin.org/easyspin/documentation/isotopetable.html

Loading Built-In Data Files for Package Examples

Description

Loads built-in package data files which are required either to demonstrate the package functionality by examples within the documentation, or to run functions involving essential characteristics of nuclei important for EPR spectroscopy (e.g. eval_nu_ENDOR or eval_sim_EPR_iso, see also isotopes_ds). Details of all data are summarized in vignette("datasets").

Usage

load_data_example(file = NULL)
load_data_example(file = NULL)

Arguments

file

Character string, corresponding to file name + extension.

Examples

## list of all files within the "extdata" directory =>
load_data_example()
#
## additionally, you may refer to several function examples


## list of all files within the "extdata" directory =>
load_data_example()
#
## additionally, you may refer to several function examples

General Function for Non-Linear Optimization/Fitting of EPR Parameters/Data

Description

General-purpose optimization of the objective fn function (also called "fitness") which is to be minimized in order to fit theoretical models (EPR simulations) onto the experimental data. Several methods/algorithms are implemented (see also Details): from the nloptr package: slsqp, neldermead, crs2lm, sbplx, cobyla, lbfgs; from the minpack.lm package: nls.lm and finally from the pso package: psoptim.

Usage

optim_for_EPR_fitness(
  method = "neldermead",
  x.0,
  fn,
  lower,
  upper,
  data,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  ...
)
optim_for_EPR_fitness(
  method = "neldermead",
  x.0,
  fn,
  lower,
  upper,
  data,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  ...
)

Arguments

`method`	Character string, pointing to applied optimization method/algorithm. One may choose one from those listed in `Details`, default: `method = "neldermead"`, setting up the "Nelder-Mead" simplex method.
`x.0`	Numeric vector with the initial values to be optimized in order to fit onto the experimental data.
`fn`	Objective function that is to be minimized. Usually it is the function calculating the sum of residual squares, in which a more general parameterized one can be implemented (see `Details` and `Examples`).
`lower`, `upper`	lower and upper bound constraints.
`data`	Data frame object, containing columns/variables (e.g. intensity of an EPR spectrum), required to undergo a fitting/optimization process.
`Nmax.evals`	Numeric value, maximum number of function evaluations and/or iterations. The only one method, limited by this argument, is `nls.lm`, where `Nmax.evals = 1024`. Higher `Nmax.evals` may extremely extend the optimization time, therefore the default value reads `Nmax.evals = 512`. However, the `"pswarm"` method requires at least the default or even higher values.
`tol.step`	Numeric, the smallest optimization step (relative change) between 2 iterations to stop the optimization procedure. For the `method = "pswarm"` (particle swarm optimization procedure) it actually corresponds to tolerance for restarting. Once the maximum distance between the "best" particle and all the others is less than `tol.step` * `pswarm.diameter`) the algorithm restarts. See also `psoptim`. Default: `tol.step = 5e-7`.
`pswarm.size`	Numeric value, which equals to particle swarm size (i.e. number of particles), if `method = "pswarm"`. The default value (`pswarm.size = NULL`) actually corresponds to `floor(10+2*sqrt(length(x.0)))` (for `SPSO2007`, see the `pswarm.type` argument), e.g. to optimize 8 parameters, number of particles = 15. For the `SPSO2011` the default number of particles equals to `40`.
`pswarm.diameter`	Numeric value, corresponding to diameter of the particle swarm search space (in case `method = "pswarm"`). The default value (`pswarm.diameter = NULL`) refers to the Euclidean distance, defined as: $\sqrt{\sum_k\,(\text{upper}[k] - \text{lower}[k])^2}$
`pswarm.type`	Character string, setting the type/version of particle swarm algorithm if `method = "pswarm"`. There are two types available: `pswarm.type = "SPSO2007"` and `pswarm.type = "SPSO2011"`. The latter introduced an adaptive random topology, which allows the swarm to dynamically adjust its communication structure. This helps in maintaining diversity in the swarm and improves the algorithm's ability to escape local optima. This type generally offers better performance on larger multidimensional spaces than the `pswarm.type = "SPSO2007"`, which uses a more static topology. Details may be found in the `References`. Default: `pswarm.type = NULL` (actually corresponding to `"SPSO2007"`, that performs slightly better on smaller scales such as simulations of EPR spectra).
`...`	additional arguments passed to the function.

Details

All algorithms are based on the least-square minimization however, the fn definition in case of nls.lm must be provided as a difference/residual vector (see also eval_kinR_EPR_modelFit) and not as sum of differences/residual squares. The applied optimization/fitting methods are summarized in the following table (please, consult the details in References or in the individual function documentation - links in the Description) =>

Method/Algorithm	Package	Short Description
`slsqp`	`{nloptr}`	Sequential quadratic programming method for non-linearly constrained, gradient-based optimization.
`cobyla`	`{nloptr}`	Constrained optimization by linear approximations, algorithm for derivative-free optimization with nonlinear inequality and equality constraints.
`lbfgs`	`{nloptr}`	Low-storage version of the Broyden-Fletcher-Goldfarb-Shanno (BFGS) method. This is a quasi-Newton method well suited for the optimization problems with a large number of variables.
`neldermead`	`{nloptr}`	Nelder-Mead ("N-M") simplex algorithm.
`crs2lm`	`{nloptr}`	Controlled Random Search (CRS) algorithm (and in particular, the CRS2 variant) with the `local mutation' modification.
`sbplx`	`{nloptr}`	Subplex algorithm, which is a variant of the "N-M" method on a sequence of sub-spaces.
`nls.lm` (`levenmarq`)	`{minpack.lm}`	Modified Levenberg-Marquardt algorithm. It is a combination of gradient descent and Gauss-Newton method.
`psoptim` (`pswarm`)	`{pso}`	Particle swarm optimization, which is a population-based stochastic optimization algorithm motivated by the intelligent collective behavior of some animals such as flocks of birds or schools of fish.

Not all {nloptr}-methods are implemented into the optim_for_EPR_fitness. Those summarized above were tested by the EPR simulation fit (see eval_sim_EPR_isoFit) on the experimental spectra of TEMPOL and Wuster's blue radicals. They provide the best results (without extensive "playing" with nl.opts, i.e. with options to control the optimization procedure) and proceed relatively fast.

Value

For all listed algorithms the function returns list with the elements like (please, refer to e.g. Value in eval_sim_EPR_isoFit)

The best parameters found (par vector, depending on the initial x.0 set of parameters).
The value of fn (minimum value) corresponding to the best par.
Number of evaluations and/or iterations (in case of the method = "pswarm", see also Value in the psoptim) before the termination.
(Un)successful termination information (convergence or rsstrace), usually corresponding either to integer value showing the (un)successful termination like 2: Maximum number of iterations reached (or integer code > 0 indicating successful completion) or in the case of nls.lm, it returns a vector with the values equal to sum of the residual squares at each iteration.
A descriptive message/character string giving additional information about the optimization procedure/termination. By default, this is however "turned off", for the sake of simplicity, because most of the information can be found in the previous convergence list element.

References

Johnson SG (2023). “The NLopt nonlinear-optimization package.” https://github.com/stevengj/nlopt.

Stamm A (2023). “nloptr.” https://github.com/astamm/nloptr/.

Mullen KM, Elzhov TV, Spiess A, Bolker B (2023). “minpack.lm.” https://github.com/cran/minpack.lm.

Gavin HP (2019). “The Levenberg-Marquardt algorithm for nonlinear least squares curve-fitting problems.” Department of civil and environmental engineering, Duke University, https://people.duke.edu/~hpgavin/lm.pdf.

Adyatama A (2019). “Particle Swarm Optimization.” https://rpubs.com/argaadya/intro-pso.

Tam A (2021). “A Gentle Introduction to Particle Swarm Optimization.” https://machinelearningmastery.com/a-gentle-introduction-to-particle-swarm-optimization/.

Ugolotti R, Cagnoni S (2016). "A Fair Comparison Between Standard PSO Versions." In: Rossi F, Mavelli F, Stano P, Caivano D (eds), Advances in Artificial Life, Evolutionary Computation and Systems Chemistry, WIVACE 2015, Communications in Computer and Information Science, Springer, https://doi.org/10.1007/978-3-319-32695-5_1.

Zambrano-Bigiarini M, Clerc M, Rojas-Mujica R (2013). "Standard Particle Swarm Optimisation 2011 at CEC-2013: A baseline for future PSO improvements." 2013 IEEE Congress on Evolutionary Computation, https://ieeexplore.ieee.org/document/6557848.

Examples

## Not run: 
## following code snippets were taken from
## the `quantify_EPR_Sim_series` function
#
## if an EPR spectrum consists of several
## components or several radical spectra partly overlay,
## following simple function, taking the linear
## combination of EPR simulated intensities (max. 6),
## can be applied in order to fit the sum of the individual
## simulations onto the experimental EPR spectrum
## envelope, the input parameters therefore correspond
## to zero-point/intercept(par[1]) and coefficients
## of the linear combinations(par[2]...par[7]),
## equal to individual intensity multiplications:
fit_params_specs_par <- function(data,
                                 col.name.pattern,
                                 par){
  #
  # data contains variables/columns of simulated
  # intensities with the headers characterized
  # by the `col.name.patter`
  #
  data <- data[,grep(col.name.pattern,
                     colnames(data),
                     value = TRUE)]
  #
  ## create a sum for all columns/simulated spectra
  if (ncol(data) == 1){
    summa <- par[1] + (par[2] * data[[1]])
  }
  if (ncol(data) == 2){
      summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]])
  }
  if (ncol(data) == 3){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]])
  }
  if (ncol(data) == 4){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]])
  }
  if (ncol(data) == 5){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]]) +
      (par[6] * data[[5]])
  }
  if (ncol(data) == 6){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]]) +
      (par[6] * data[[5]]) +
      (par[7] * data[[6]])
  }
  #
 return(summa)
 }
 #
 ## following function is applied to vary only
 ## `method`, `function` and `data`
optim_fn <- function(fun,method,data){
  optim.list <-
    optim_for_EPR_fitness(x.0 = optim.params.init,
                          method = method,
                          fn = fun,
                          lower = optim.params.lower,
                          upper = optim.params.upper,
                          Nmax.evals = Nmax.evals,
                          tol.step = tol.step,
                          pswarm.size = pswarm.size,
                          pswarm.diameter = pswarm.diameter,
                          data = data,
                          col.name.pattern =
                          "Sim.*_[[:upper:]]$"
    )
  #
  return(optim.list)
 }
#
## finally, the following function is to be minimized:
min_residuals_ps <- function(data,col.name.pattern,par){
  with(data,sum((data[[Intensity.expr]] -
    fit_params_specs_par(data,col.name.pattern,par))^2)
    )
  }
#
## therefore, the final `optimization` list may look like
optimization.list <-
  lapply(seq(data.list),
         function(o) {
         optim_fn(method = optim.method,
         data = data.list[[o]],
         fun = min_residuals_ps)
       }
    )
## where `data.list` represents the list of data frames
## including all individual simulated spectra
## (one data frame for each spectrum + original
## experimental spectrum intensity column)
#

## End(Not run)


## Not run: 
## following code snippets were taken from
## the `quantify_EPR_Sim_series` function
#
## if an EPR spectrum consists of several
## components or several radical spectra partly overlay,
## following simple function, taking the linear
## combination of EPR simulated intensities (max. 6),
## can be applied in order to fit the sum of the individual
## simulations onto the experimental EPR spectrum
## envelope, the input parameters therefore correspond
## to zero-point/intercept(par[1]) and coefficients
## of the linear combinations(par[2]...par[7]),
## equal to individual intensity multiplications:
fit_params_specs_par <- function(data,
                                 col.name.pattern,
                                 par){
  #
  # data contains variables/columns of simulated
  # intensities with the headers characterized
  # by the `col.name.patter`
  #
  data <- data[,grep(col.name.pattern,
                     colnames(data),
                     value = TRUE)]
  #
  ## create a sum for all columns/simulated spectra
  if (ncol(data) == 1){
    summa <- par[1] + (par[2] * data[[1]])
  }
  if (ncol(data) == 2){
      summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]])
  }
  if (ncol(data) == 3){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]])
  }
  if (ncol(data) == 4){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]])
  }
  if (ncol(data) == 5){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]]) +
      (par[6] * data[[5]])
  }
  if (ncol(data) == 6){
    summa <- par[1] + (par[2] * data[[1]]) +
      (par[3] * data[[2]]) +
      (par[4] * data[[3]]) +
      (par[5] * data[[4]]) +
      (par[6] * data[[5]]) +
      (par[7] * data[[6]])
  }
  #
 return(summa)
 }
 #
 ## following function is applied to vary only
 ## `method`, `function` and `data`
optim_fn <- function(fun,method,data){
  optim.list <-
    optim_for_EPR_fitness(x.0 = optim.params.init,
                          method = method,
                          fn = fun,
                          lower = optim.params.lower,
                          upper = optim.params.upper,
                          Nmax.evals = Nmax.evals,
                          tol.step = tol.step,
                          pswarm.size = pswarm.size,
                          pswarm.diameter = pswarm.diameter,
                          data = data,
                          col.name.pattern =
                          "Sim.*_[[:upper:]]$"
    )
  #
  return(optim.list)
 }
#
## finally, the following function is to be minimized:
min_residuals_ps <- function(data,col.name.pattern,par){
  with(data,sum((data[[Intensity.expr]] -
    fit_params_specs_par(data,col.name.pattern,par))^2)
    )
  }
#
## therefore, the final `optimization` list may look like
optimization.list <-
  lapply(seq(data.list),
         function(o) {
         optim_fn(method = optim.method,
         data = data.list[[o]],
         fun = min_residuals_ps)
       }
    )
## where `data.list` represents the list of data frames
## including all individual simulated spectra
## (one data frame for each spectrum + original
## experimental spectrum intensity column)
#

## End(Not run)

Plot Voltammogram or Chronoamperogram from the (Spectro)Electrochemical Experiment

Description

Visualization of electrochemical responses like voltammogram or chronoamperogram either by ggplot2 (static plot) or by plotly interactive package. The corresponding data frame for the plot can be created from the ASCII text file, generated by the potentiostat electrochemical instrument, using the fread function (see also section Examples).

Usage

plot_ECh_VoC_amperogram(
  data.vat,
  x = "E_V",
  x.unit = "V",
  Current = "I_uA",
  Current.unit = "uA",
  xlim = NULL,
  Ilim = NULL,
  line.color = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  theme.basic = "theme_gray",
  axis.title.size = 15,
  axis.text.size = 14,
  border.line.color = "black",
  border.line.width = 0.5,
  border.line.type = 1,
  ref.electrode = NULL,
  plot.interact = FALSE,
  ticks = "out",
  grid = TRUE
)
plot_ECh_VoC_amperogram(
  data.vat,
  x = "E_V",
  x.unit = "V",
  Current = "I_uA",
  Current.unit = "uA",
  xlim = NULL,
  Ilim = NULL,
  line.color = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  theme.basic = "theme_gray",
  axis.title.size = 15,
  axis.text.size = 14,
  border.line.color = "black",
  border.line.width = 0.5,
  border.line.type = 1,
  ref.electrode = NULL,
  plot.interact = FALSE,
  ticks = "out",
  grid = TRUE
)

Arguments

`data.vat`	Data frame (table) object, including required columns like `Potential` ( $E$ ) and/or `Time` ( $t$ ) as well as `Current` ( $I$ ). Even though an arbitrary column label can be used, the best option is to use labels e.g. `E_V`, `E_mV`, `time_s`, `I_uA` or `I_mA`.
`x`	Character string, pointing to `x`-axis/column quantity, in the original `data.vat`, like potential (e.g. `x = "E_V"`, `x = "E_mV"`) or time (e.g. `x = "time_s"`, `x = "time_min"` or `x = "time_ms"`). Default: `x = "E_V"` (potential in volts).
`x.unit`	Character string, pointing to `x`-quantity unit. There are following units available: `x.unit = "V"`, `x.unit = "mV"` (in case of voltammetry, `x` corresponds to potential) as well as `x.unit = "s"`, `x.unit = "ms"` or `x.unit = "min"` (in case of chronoamperometry, `x` corresponds to time). Default: `x.unit = "V"`.
`Current`	Character string, indicating the `Current`( $I$ )-axis/column quantity in the original `data.vat` object. Default: `Current = "I_ua"` (current in $\text{µA}$ ).
`Current.unit`	Character string, pointing to `Current` quantity unit like `Current.unit = "uA"` (microamps, default), `Current.unit = "A"`, `Current.unit = "mA"` and `Current.unit = "nA"`.
`xlim`	Numeric vector of the `x`-quantity lower and upper limit, e.g. `xlim = c(-100,400)` (potential in "mV", in case of voltammetry) or `xlim = c(0,1000)` (time in seconds, in case of chronoamperometry). Default: `xlim = NULL` actually setting the entire `x`-range from the original dataset.
`Ilim`	Numeric vector, characterizing the lower and upper limit of the current, e.g. `Ilim = c(-0.05,0.2)`, corresponding to current in milliamps. Default: `Ilim = NULL` related to the entire current ( $I$ ) range from the original dataset.
`line.color`	Character string, pointing to line color of the voltammogram / chronoamperogram. All `{ggplot2}` compatible colors are allowed, e.g. `line.color = "blue"`. Default: `line.color = "darkviolet"`.
`line.width`	Numeric, linewidth of the plot line in `mm`, default: `line.width = 0.75`.
`line.type`	Character string or integer, corresponding to width of the voltammogram/chronoamperogram line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`theme.basic`	Character string, calling a `ggplot` theme base. Following themes are defined: `"theme_gray"` (default one) => gray background with the white grid lines `"theme_bw"` => white background with thin gray grid lines, the theme is suggested for publications `"theme_light"` => similar to `theme_bw()` but without the pronounced axis black lines `"theme_classic"` => without grid, pronounced axis lines, however without opposite ones `"theme_linedraw"` => pronounced axis lines (both for the origin and the opposite) as well as the grid ones, theme is suggested for publications if the `grid` is set to `FALSE`
`axis.title.size`	Numeric, axis text title size in `pt`. Default: `axis.title.size = 15`.
`axis.text.size`	Numeric, text size in `pt` for the axes unit values/descriptions, default: `axis.text.size = 14`.
`border.line.color`	Character string, referring to color of the plot graph/panel border line. Default: `border.line.color = "black"`.
`border.line.width`	Numeric, width (in `mm`) of the plot graph/panel border line, default: `border.line.width = 0.5`.
`border.line.type`	Character string or integer, corresponding to width of the plot graph/panel border line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`ref.electrode`	Character string, corresponding to reference electrode notiation/label, e.g. `ref.electrode = "Ag-quasiref"` or `ref.electrode = "Fc/Fc+"`. Default: `ref.electrode = NULL` (displayed potential is not related to any `ref.electrode`).
`plot.interact`	Logical, whether the voltammogram or chronoamperogram is visualized as an interactive plot by `{plotly}` (`plot.interact = TRUE`). Default: `plot.interact = FALSE` (static plot by `{ggplot2}` is displayed).
`ticks`	Character string, corresponding to pointing direction of the axis ticks, either pointing into the panel graph or outwards (default). If `ticks = "in"` also the opposite axis ticks are displayed.
`grid`	Logical, whether to display the `grid` within the panel/graph, default: `grid = TRUE`.

Value

Graphical representation (list object) of voltammogram or chronoamperogram either in static form by {ggplot2} (plot.interact = FALSE) or in interactive form by {plotly} (plot.interact = TRUE).

References

Bard AJ, Faulkner LR, White HS (2022). Electrochemical methods: Fundamentals and Applications, 3rd edition. John Wiley and Sons, Inc., ISBN 978-1-119-33405-7, https://www.wiley.com/en-us/9781119334064.

Pingarrón JM, Labuda J, Barek J, Brett CMA, Camões MF, Fojta M, Hibbert DB (2020). “Terminology of Electrochemical Methods of Analysis (IUPAC Recommendations 2019).” Pure and Appl. Chem., 92(4), 641–694. https://doi.org/10.1515/pac-2018-0109.

Elgrishi N, Rountree KJ, McCarthy BD, Rountree ES, Eisenhart TT, Dempsey JL (2018). “A Practical Beginner’s Guide to Cyclic Voltammetry.” J. Chem. Educ., 95(2), 197–206, https://doi.org/10.1021/acs.jchemed.7b00361.

Examples

## loading package built-in example file =>
## `.txt` file generated by the IVIUM potentiostat software
triarylamine.path.cv <-
load_data_example(file = "Triarylamine_ECh_CV_ivium.txt")
## the data frame contains following variables:
## time, desired potential, current and the actual/applied
## potential
triarylamine.data.cv <-
  data.table::fread(file = triarylamine.path.cv,
    skip = 2,
    col.names = c("time_s",
                  "E_V_des", # desired potential
                  "I_A",
                  "E_V_app") # applied potential
  )
## data frame preview
head(triarylamine.data.cv)
#
## simple voltammogram plot with ref. electrode string:
plot_ECh_VoC_amperogram(data.vat =
                          triarylamine.data.cv,
  x = "E_V_app",
  Current = "I_A",
  Current.unit = "A",
  ref.electrode = "Ag-quasiref."
 )
#
## simple chronoamperogram plot with "theme_bw" theme
## and `ticks` pointing into the graph panel (ticks = "in")
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "time_s",
  x.unit = "s",
  Current = "I_A",
  line.color = "darkred",
  line.type = 3,
  Current.unit = "A",
  theme.basic = "theme_bw",
  ticks = "in"
 )
#
## simple interactive "darkgreen" voltammogram
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "E_V_app",
  Current = "I_A",
  Current.unit = "A",
  line.color = "darkgreen",
  plot.interact = TRUE
 )


## loading package built-in example file =>
## `.txt` file generated by the IVIUM potentiostat software
triarylamine.path.cv <-
load_data_example(file = "Triarylamine_ECh_CV_ivium.txt")
## the data frame contains following variables:
## time, desired potential, current and the actual/applied
## potential
triarylamine.data.cv <-
  data.table::fread(file = triarylamine.path.cv,
    skip = 2,
    col.names = c("time_s",
                  "E_V_des", # desired potential
                  "I_A",
                  "E_V_app") # applied potential
  )
## data frame preview
head(triarylamine.data.cv)
#
## simple voltammogram plot with ref. electrode string:
plot_ECh_VoC_amperogram(data.vat =
                          triarylamine.data.cv,
  x = "E_V_app",
  Current = "I_A",
  Current.unit = "A",
  ref.electrode = "Ag-quasiref."
 )
#
## simple chronoamperogram plot with "theme_bw" theme
## and `ticks` pointing into the graph panel (ticks = "in")
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "time_s",
  x.unit = "s",
  Current = "I_A",
  line.color = "darkred",
  line.type = 3,
  Current.unit = "A",
  theme.basic = "theme_bw",
  ticks = "in"
 )
#
## simple interactive "darkgreen" voltammogram
plot_ECh_VoC_amperogram(data.vat = triarylamine.data.cv,
  x = "E_V_app",
  Current = "I_A",
  Current.unit = "A",
  line.color = "darkgreen",
  plot.interact = TRUE
 )

Present/Save Interactive Plot for Publication in `.html`,`.pdf` or `.docx`

Description

Add the interactive plots (see plot_EPR_Specs2D_interact or plot_EPR_Specs3D_interact) to various document formats like .html, .pdf or .docx. Function is based on the saveWidget as well as on the webshot with the help of knitr package functions. Depending on the output format, plot is saved in working/actual directory either as .html or as .png. The file name inherits the name of the object/variable (see argument p and example). Afterwards, during the R markdown or Quarto processing, the image is automatically attached to the document in the above-described format. Therefore, this function is quite handy in interactive notebooks (such as .Rmd or .qmd, please also consult the create_qmdReport_proj function).

Usage

plot_EPR_present_interact(p, size.width = 7, size.height = 5, res.ppi = 200)
plot_EPR_present_interact(p, size.width = 7, size.height = 5, res.ppi = 200)

Arguments

`p`	Plot object/variable name.
`size.width`	Numeric, `width` of the image/object window in `in`, default: `size.width = 7`.
`size.height`	Numeric, `height` of the image/object window in `in`, default: `size.height = 5`.
`res.ppi`	Numeric, `resolution` in `ppi`, default: `res.ppi = 200`.

Value

Interactive plot format corresponding to that of the output document. If the desired document format $\equiv$ .html, interactive plotly graph is saved in working/actual directory in the same format. Otherwise, for .pdf and .docx it is saved as .png bitmap with the resolution of size.with $\cdot$ res.ppi x size.height $\cdot$ res.ppi.

Examples

## Not run: 
## plotting EPR spectrum of verdazyl radical (`verdazyl.rad.data`),
## where the actual plot is stored under
## the `verdazyl.epr.plot.interact` variable name
verdazyl.epr.plot.interact <-
  plot_EPR_Specs2D_interact(data.spectra = verdazyl.rad.data)
#
## afterwards, it is automatically transformed and attached
## to document with the desired format by `knitr`
plot_EPR_present_interact(verdazyl.epr.plot.interact)
#
## remaining image files are stored in the working directory

## End(Not run)


## Not run: 
## plotting EPR spectrum of verdazyl radical (`verdazyl.rad.data`),
## where the actual plot is stored under
## the `verdazyl.epr.plot.interact` variable name
verdazyl.epr.plot.interact <-
  plot_EPR_Specs2D_interact(data.spectra = verdazyl.rad.data)
#
## afterwards, it is automatically transformed and attached
## to document with the desired format by `knitr`
plot_EPR_present_interact(verdazyl.epr.plot.interact)
#
## remaining image files are stored in the working directory

## End(Not run)

Essential Plotting of EPR/ENDOR Spectrum/Spectra

Description

Plot of EPR/ENDOR spectrum/spectra (overlay plot) based on the ggplot2-functionality. Spectral data input must be available as a data frame object (see also argument data.spectra). Theme of the visual spectrum representation as well as additional plot elements can be varied like using the {ggplot2} package. Within a theme, the y ticks can be either displayed or skipped (which is common for visualization of EPR spectra) and the intensity (e.g. dIepr_over_dB) is presented in "procedure defined unit" (see p.d.u.).

Usage

plot_EPR_Specs(
  data.spectra,
  x = "B_mT",
  x.unit = "mT",
  xlim = NULL,
  var2nd.series = NULL,
  var2nd.series.slct.by = NULL,
  Intensity = "dIepr_over_dB",
  Ilim = NULL,
  lineSpecs.form = "derivative",
  line.colors = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  border.line.width = 0.5,
  border.line.color = "black",
  border.line.type = 1,
  theme.basic = "theme_gray",
  axis.title.size = 15,
  axis.text.size = 14,
  legend.title = NULL,
  legend.title.size = NULL,
  legend.text.size = NULL,
  grid = TRUE,
  yTicks = TRUE
)
plot_EPR_Specs(
  data.spectra,
  x = "B_mT",
  x.unit = "mT",
  xlim = NULL,
  var2nd.series = NULL,
  var2nd.series.slct.by = NULL,
  Intensity = "dIepr_over_dB",
  Ilim = NULL,
  lineSpecs.form = "derivative",
  line.colors = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  border.line.width = 0.5,
  border.line.color = "black",
  border.line.type = 1,
  theme.basic = "theme_gray",
  axis.title.size = 15,
  axis.text.size = 14,
  legend.title = NULL,
  legend.title.size = NULL,
  legend.text.size = NULL,
  grid = TRUE,
  yTicks = TRUE
)

Arguments

`data.spectra`	Data frame/table object, containing magnetic flux density, $g$ -value or radio-frequency columns as `x` variable. They can be labeled as `Field`, `B_mT`, `B_G` or `RF_MHz` see also `x` argument. The `y / Intensity` variable can be labeled as `dIepr_over_dB`, in case of derivative intensity, or if integrated or simulated spectra intensities are present, they can be labeled accordingly. See also `Intensity` parameter/argument. For the spectral series, the second independent variable `var2nd.series` column (e.g. `var2nd.series = "time_s"` or `var2nd.series = "T_K"`) must be available. In such case the entire `data.spectra` must inherit the form of tidy/long table format (see also argument `var2nd.series`).
`x`	Character string, pointing to $x$ -axis/column quantity header in the original `data.spectra` like magnetic flux density $B$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`x.unit`	Character string, pointing to unit of `x`-quantity coming from the original `data.spectra`. Units like `"G"` (Gauss), `"mT"` (millitesla), `"T"` (tesla), `"MHz"` (megahertz in case of ENDOR spectra) or `"Unitless"` / `"unitless"` (in case of $g$ -values) can be used. Default: `x.unit = "mT"`.
`xlim`	Numeric vector, referring to lower and upper limit of the selected $x$ -region, e.g. `xlim = c(3495.4,3595.4)` ( $B$ in `G`) or `xlim = c(12.5,21.2)` ( $RF$ in `MHz`) or `xlim = c(2.004,2.001)` (dimensionless $g$ ). Default: `xlim = NULL` (actually corresponding to the entire $x$ -range).
`var2nd.series`	Character string, referred to name of the second independent variable/quantity column in the original `data.spectra` (such as time, Temperature, Electrochemical Potential, Microwave Power...etc) altered upon individual experiments. Data must be available in long table / tidy format (see also `readEPR_Exp_Specs_multif` or `plot_EPR_Specs2D_interact`). Default: `var2nd.series = NULL`. Otherwise, usually `var2nd.series = "time_s"`.
`var2nd.series.slct.by`	Numeric, corresponding to each $n-th$ presented spectrum in the overlay plot, e.g. display each second (`var2nd.series.slct.by = 2`) or third (`var2nd.series.slct.by = 3`), ...etc. spectrum. The argument is only used if `var2nd.series` is NOT NULL (e.g. `var2nd.series = "time_s"`) and one wants to present DISCRETE LABELS / LEVELS for the overlay spectra (see also `line.colors` argument). THE `var2nd.series.slct.by = 1` MAY DISPLAY ALL DISCRETE SPECTRA WITHIN THE SERIES. However, the RECOMENDED MAX. NUMBER of spectra/lines IS `12`.
`Intensity`	Character string, pointing to `intensity column` name in the original `data.spectra` if other than `dIepr_over_dB` name/label is used (e.g. for simulated or integrated spectra), default: `Intesity = "dIepr_over_dB"`.
`Ilim`	Numeric vector, corresponding to limits of the selected `y` / `Intensity` region, e.g. `Ilim = c(-2e-3,2e-3)`. Default: `Ilim = NULL` (actually corresponding to the entire Intensity range).
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (in such case also `"absorption"` can be used) line form of the analyzed EPR spectrum/data.
`line.colors`	Character string, line color(s) to plot EPR spectrum/spectra. All `{ggplot2}` compatible colors are allowed to plot the individual spectrum, default: `line.colors = "steelblue"`. For the series of EPR spectra two color scales are used: Continuous. This is the case when `var2nd.series` IS NOT `NULL` and `var2nd.series.slct.by = NULL`. The `line.colors` argument is identical with the continuous `colorscales`, i.e. with the one from `scale_colour_gradientn`. Following color definitions are allowed => any color vector like `c("blue","green","red")` with the length of $\geq 2$ any color definition from grDevices like `hcl.colors(n,pallete)`, `rainbow(n)`, `heat.colors(n)`, `terrain.colors(n)`, `topo.colors(n)`, `cm.colors(n)` where the number of colors $n \geq 2$ should be specified. See also grDevices Palettes and HCL Color Palettes Discrete. This is the case when both `var2nd.series` as well as `var2nd.series.slct.by` are DISTINCT FROM `NULL`. Following color definitions are allowed => any color vector like `c("blue","green","red")` with the length of $\geq 2$ any color definition from `scale_color_viridis_d` `"option"`. These involve `line.colors = "magma"` (or ...`"A"`), `line.colors = "inferno"` (or ...`"B"`), `line.colors = "plasma"` (or ...`"C"`), `line.colors = "viridis"` (or ...`"D"`), `line.colors = "cividis"` (or ...`"E"`), `line.colors = "rocket"` (or ...`"F"`), `line.colors = "mako"` (or ...`"G"`) and `line.colors = "turbo"` (or ...`"H"`)
`line.width`	Numeric, linewidth of the plot line in `mm`, default: `line.width = 0.75`.
`line.type`	Character string or integer, corresponding to width of the (spectral) line(s). Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`border.line.width`	Numeric, width (in `mm`) of the plot graph/panel border line, default: `border.line.width = 0.5`.
`border.line.color`	Character string, referring to color of the plot graph/panel border line. Default: `border.line.color = "black"`.
`border.line.type`	Character string or integer, corresponding to width of the plot graph/panel border line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`theme.basic`	Character string, calling a `ggplot` theme base. Following themes are defined: `"theme_gray"` (default one) => gray background with the white grid lines `"theme_bw"` => white background with thin gray grid lines, the theme is suggested for publications `"theme_light"` => similar to `theme_bw()` but without the pronounced axis black lines `"theme_classic"` => without grid, pronounced axis lines, however without opposite ones `"theme_linedraw"` => pronounced axis lines (both for the origin and the opposite) as well as the grid ones, theme is suggested for publications if the `grid` is set to `FALSE`
`axis.title.size`	Numeric, axis text title size in `pt`. Default: `axis.title.size = 15`.
`axis.text.size`	Numeric, text size in `pt` for the axes unit values/descriptions, default: `axis.text.size = 14`.
`legend.title`	Character string identical to legend title, e.g. `legend.title = "Time (s)"`, `legend.title = "Electrochem. Potential (V)"` or `legend.title = "Sample"`. Default: `legend.title = NULL` in case of `var2nd.series = NULL`.
`legend.title.size`	Numeric, legend text title size in `pt`,default: `legend.title.size = NULL`, actually corresponding to 13/13pt.
`legend.text.size`	Numeric, legend text size in `pt`, default: `legend.text.size = NULL`, actually corresponding to 11/11pt.
`grid`	Logical, whether to display the `grid` within the panel/graph, default: `grid = TRUE`.
`yTicks`	Logical, whether to display the `y` (`Intensity`) ticks and the corresponding text (not the axis title!), which is often skipped in the EPR community, default: `yTicks = TRUE` (the axis ticks as well as the text are present).

Details

Output from the plot_EPR_Specs can be additionally combined by the + sign with other ggplot2 or internal plotting functions (e.g. with plot_theme_In_ticks). For details of ggplot2 theme elements, please refer to Modify Components of a Theme (see also theme) or to ggplot2 Elements Demonstration by Henry Wang. The actual function does not assume a deep knowledge of ggplot2 package (as well as the grammar of graphics philosophy, see vignette("functionality")) and literally, one can easily start to plot from scratch (see also building plot in example of plot_theme_NoY_ticks). However, there is a great interactive Rstudio addin/package called esquisse which nicely helps to dive into the ggplot2 even for complete beginners.

Value

EPR spectrum/spectra ('overlay') plot object (corresponding to list of plot components) using the ggplot2 functionality, with the key parameter variations like line color, theme, grid...etc.

Examples

## load the following built-in spectral data:
aminoxyl.file.path <-
load_data_example("Aminoxyl_radical_a.txt")
## read the aminoxyl radical spectrum without intensity
## normalization
aminoxyl.data <- readEPR_Exp_Specs(aminoxyl.file.path)
#
## simple plot of an EPR spectrum with B in `mT`
## and dIepr_over_dB_Sim in `p.d.u.` (derivative intensity)
plot_EPR_Specs(aminoxyl.data)
#
## the same spectrum with B in `G` and `theme_bw`
## ggplot2 graph theme
plot_EPR_Specs(data.spectra = aminoxyl.data,
               x = "B_G",
               x.unit = "G",
               theme.basic = "theme_bw")
#
## single integration (without baseline correction)
## of the previous spectrum by the `eval_integ_EPR_Spec`
## function
aminoxyl.data.sinteg <-
  eval_integ_EPR_Spec(aminoxyl.data)
## plot the single integrated spectrum
plot_EPR_Specs(aminoxyl.data.sinteg,
               x = "B_G",
               x.unit = "G",
               Intensity = "single_Integ",
               line.colors = "darkorange",
               line.type = "dashed",
               lineSpecs.form = "integrated")
#
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting the previous ENDOR data spectrum
## in derivative form with `darkred` linecolor
## and 1.2 mm linewidth:
plot_EPR_Specs(pnt.endor.data,
               x = "RF_MHz",
               x.unit = "MHz",
               line.colors = "darkred",
               line.width = 1.2)
#
## loading the built-in package example to demonstrate
## visualizatioin of time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
  dir_ASC = tempdir(),
  dir_dsc_par =
    system.file("extdata",
                package = "eprscope")
)
#
## plot with the CONTINUOUS COLORSCALE (see argument
## `line.colors` and color definitions `1.`):
plot_EPR_Specs(triarylamine.decay.series.data$df,
               var2nd.series = "time_s",
               line.colors =
               grDevices::hcl.colors(8,palette = "Roma"),
               legend.title = "Time (s)",
               yTicks = FALSE)
#
## plot with the DISCRETE COLORSCALE (see argument
## `line.colors` and color definitions `2.`),
## each 10-th spectrum from the original plot is presented:
plot_EPR_Specs(triarylamine.decay.series.data$df,
               var2nd.series = "time_s",
               var2nd.series.slct.by = 10,
               line.colors = c("darkblue",
                               "darkorange",
                               "darkviolet"),
               legend.title = "Time (s)")
#
## Not run: 
## display the variable temperature experiment selecting
## the DISCRETE COLORSCALE where all EPR spectra from
## the series are presented:
plot_EPR_Specs(data.spectra,
  Ilim = c(-4e-3,4e-3),
  var2nd.series = "T_K", # temperature in Kelvins
  var2nd.series.slct.by = 1,
  line.colors = c("darkblue",
                  "darkorange",
                  "magenta",
                  "steelblue"),
  legend.title = "Temperature (K)")

## End(Not run)


## load the following built-in spectral data:
aminoxyl.file.path <-
load_data_example("Aminoxyl_radical_a.txt")
## read the aminoxyl radical spectrum without intensity
## normalization
aminoxyl.data <- readEPR_Exp_Specs(aminoxyl.file.path)
#
## simple plot of an EPR spectrum with B in `mT`
## and dIepr_over_dB_Sim in `p.d.u.` (derivative intensity)
plot_EPR_Specs(aminoxyl.data)
#
## the same spectrum with B in `G` and `theme_bw`
## ggplot2 graph theme
plot_EPR_Specs(data.spectra = aminoxyl.data,
               x = "B_G",
               x.unit = "G",
               theme.basic = "theme_bw")
#
## single integration (without baseline correction)
## of the previous spectrum by the `eval_integ_EPR_Spec`
## function
aminoxyl.data.sinteg <-
  eval_integ_EPR_Spec(aminoxyl.data)
## plot the single integrated spectrum
plot_EPR_Specs(aminoxyl.data.sinteg,
               x = "B_G",
               x.unit = "G",
               Intensity = "single_Integ",
               line.colors = "darkorange",
               line.type = "dashed",
               lineSpecs.form = "integrated")
#
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting the previous ENDOR data spectrum
## in derivative form with `darkred` linecolor
## and 1.2 mm linewidth:
plot_EPR_Specs(pnt.endor.data,
               x = "RF_MHz",
               x.unit = "MHz",
               line.colors = "darkred",
               line.width = 1.2)
#
## loading the built-in package example to demonstrate
## visualizatioin of time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
  dir_ASC = tempdir(),
  dir_dsc_par =
    system.file("extdata",
                package = "eprscope")
)
#
## plot with the CONTINUOUS COLORSCALE (see argument
## `line.colors` and color definitions `1.`):
plot_EPR_Specs(triarylamine.decay.series.data$df,
               var2nd.series = "time_s",
               line.colors =
               grDevices::hcl.colors(8,palette = "Roma"),
               legend.title = "Time (s)",
               yTicks = FALSE)
#
## plot with the DISCRETE COLORSCALE (see argument
## `line.colors` and color definitions `2.`),
## each 10-th spectrum from the original plot is presented:
plot_EPR_Specs(triarylamine.decay.series.data$df,
               var2nd.series = "time_s",
               var2nd.series.slct.by = 10,
               line.colors = c("darkblue",
                               "darkorange",
                               "darkviolet"),
               legend.title = "Time (s)")
#
## Not run: 
## display the variable temperature experiment selecting
## the DISCRETE COLORSCALE where all EPR spectra from
## the series are presented:
plot_EPR_Specs(data.spectra,
  Ilim = c(-4e-3,4e-3),
  var2nd.series = "T_K", # temperature in Kelvins
  var2nd.series.slct.by = 1,
  line.colors = c("darkblue",
                  "darkorange",
                  "magenta",
                  "steelblue"),
  legend.title = "Temperature (K)")

## End(Not run)

Plotting Integrated Forms of EPR Spectra Acquired by `eval_integ_EPR_Spec`

Description

Visualization (static plots based on ggplot2) of integrated EPR spectra coming as data frame outputs from eval_integ_EPR_Spec.

Usage

plot_EPR_Specs_integ(
  data.spectra.integ,
  B = "B_G",
  B.unit = "G",
  Blim = NULL,
  ylim = NULL,
  slct.integs = c("single_Integ", "baseline_Integ_fit", "single_Integ_correct"),
  line.width = 0.75,
  line.type = 1,
  axis.title.size = 15,
  axis.text.size = 14,
  legend.title.size = 13,
  legend.text.size = 11,
  separate.integs = FALSE,
  separate.integ.scales = NULL,
  output.df = FALSE
)
plot_EPR_Specs_integ(
  data.spectra.integ,
  B = "B_G",
  B.unit = "G",
  Blim = NULL,
  ylim = NULL,
  slct.integs = c("single_Integ", "baseline_Integ_fit", "single_Integ_correct"),
  line.width = 0.75,
  line.type = 1,
  axis.title.size = 15,
  axis.text.size = 14,
  legend.title.size = 13,
  legend.text.size = 11,
  separate.integs = FALSE,
  separate.integ.scales = NULL,
  output.df = FALSE
)

Arguments

`data.spectra.integ`	Data frame object, inherited output from the `eval_integ_EPR_Spec`, if `output.vecs = FALSE` (argument from the latter), corresponding to data frame including the original EPR spectral data and the integral(s).
`B`	Character string, pointing to magnetic flux density `column` of the original (`data.spectra.integ`) data frame, either in "millitesla" or in "gauss", that is `B = "B_G"` (default) or `B = "B_mT"` or `B = "Bsim_G"` to include simulated EPR spectra as well.
`B.unit`	Character string, denoting the magnetic flux density unit e.g. `B.unit = "G"` (gauss, default), `B.unit = "mT"` (millitesla) or `B.unit = T` (tesla).
`Blim`	Numeric vector, magnetic flux density in `mT`/`G` corresponding to lower and upper limit of the selected $B$ -region, such as `Blim = c(3495.4,3595.4)`. Default: `Blim = NULL` (corresponding to the entire $B$ -range of the integrated EPR spectrum).
`ylim`	Numeric vector, corresponding to lower and upper limit of the $y$ -axis scale (e.g. `ylim = c(-1e-4,1e-3)`). This doesn't apply for separated integrals (if `separate.integs = TRUE`) and works only in overlay mode (in one graph/panel). Default: `ylim = NULL` corresponding to the entire $y$ -range of presented integrals.
`slct.integs`	Character string vector, pointing to selected integrals/columns/variables (of the original `data.spectra.integ` data frame) to be presented in the actual plot. Default: `slct.integs = c("single_Integ","baseline_Integ_fit","single_Integ_correct")`.
`line.width`	Numeric, linewidth of the plot line in `mm`, default: `line.width = 0.75`.
`line.type`	Character string or integer, corresponding to width of the (spectral) line(s). Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`axis.title.size`	Numeric, axis text title size in `pt`. Default: `axis.title.size = 15`.
`axis.text.size`	Numeric, text size in `pt` for the axes unit values/descriptions, default: `axis.text.size = 14`.
`legend.title.size`	Numeric, legend text title size in `pt`,default: `legend.title.size = NULL`, actually corresponding to 13/13pt.
`legend.text.size`	Numeric, legend text size in `pt`, default: `legend.text.size = NULL`, actually corresponding to 11/11pt.
`separate.integs`	Logical, should be the integrals presented in overlay mode (in one graph/panel) or on separated panels (by `facet_wrap`, see also the next argument) ? Default: `separate.integs = FALSE` (integrals are presented in overlay mode).
`separate.integ.scales`	Character string related to $y$ -axes scales, unless the `separate.integs = FALSE`, inherited from `facet_wrap`. Following expressions are available => `"fixed"`, `"free"` or in one dimension `"free_x"` or `"free_y"`. Default: `separate.integ.scales = NULL` in case of `separate.integs = FALSE`.
`output.df`	Logical, whether a transformed `data.spectra.integ` data frame into tidy/long table format is required for additional processing or plotting. Default: `output.df = TRUE`.

Value

Depending on output.df argument, function returns plot object including all selected integrated EPR spectra (output.df = FALSE,default) or list (output.df = TRUE) consisting of

df: Data frame object with intensities of all selected integrals and magnetic flux density $B$ variables/columns in tidy/long table format.
plot: Plot object showing all integrated EPR spectra corresponding to df.

Examples

## loading the package built-in example
TMPD.data.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
TMPD.data <-
  readEPR_Exp_Specs(TMPD.data.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = c(20,0.001),
                    origin = "winepr")
## integration of the `TMPD` EPR spectrum
TMPD.data.integs <-
  eval_integ_EPR_Spec(TMPD.data,sigmoid.integ = TRUE)
#
## plotting integrals in overlay mode
plot_EPR_Specs_integ(TMPD.data.integs,
  slct.integs = c("single_Integ",
                  "sigmoid_Integ"),
  B = "B_mT",
  B.unit = "mT"
  )
#
## separate integrals within the plot
plot_EPR_Specs_integ(TMPD.data.integs,
  slct.integs = c("single_Integ",
                  "sigmoid_Integ"),
  B = "B_mT",
  B.unit = "mT",
  separate.integs = TRUE,
  separate.integ.scales = "free_y"
  )



## loading the package built-in example
TMPD.data.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
TMPD.data <-
  readEPR_Exp_Specs(TMPD.data.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = c(20,0.001),
                    origin = "winepr")
## integration of the `TMPD` EPR spectrum
TMPD.data.integs <-
  eval_integ_EPR_Spec(TMPD.data,sigmoid.integ = TRUE)
#
## plotting integrals in overlay mode
plot_EPR_Specs_integ(TMPD.data.integs,
  slct.integs = c("single_Integ",
                  "sigmoid_Integ"),
  B = "B_mT",
  B.unit = "mT"
  )
#
## separate integrals within the plot
plot_EPR_Specs_integ(TMPD.data.integs,
  slct.integs = c("single_Integ",
                  "sigmoid_Integ"),
  B = "B_mT",
  B.unit = "mT",
  separate.integs = TRUE,
  separate.integ.scales = "free_y"
  )

Interactive Plot (incl. Zooming, Data Reading...etc) of EPR Spectra

Description

Interactive visualization of EPR spectra or their integrals based on plotly package. In the first step function takes the essential plot parts as ggplot2, which is subsequently transferred by ggplotly into the final interactive format. Such plots mostly contain buttons in order to zoom, move and select (parts of) the EPR spectra/integrals as well as to display the point values directly within graph/panel. Additionally, plots can be exported into .png image or .html formats (see also plot_EPR_present_interact) and can optionally also contain tools to draw lines, circles or rectangles directly into the plot panel for annotations.

Usage

plot_EPR_Specs2D_interact(
  data.spectra,
  x = "B_mT",
  x.unit = "mT",
  Intensity = "dIepr_over_dB",
  var2nd.series = NULL,
  lineSpecs.form = "derivative",
  line.colors = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  bg.color = "#e5ecf6",
  grid.color = "white",
  border.line.width = 1.2,
  border.line.color = "black",
  legend.title = NULL,
  legend.title.size = NULL,
  axis.title.size = 15,
  axis.text.size = 14
)
plot_EPR_Specs2D_interact(
  data.spectra,
  x = "B_mT",
  x.unit = "mT",
  Intensity = "dIepr_over_dB",
  var2nd.series = NULL,
  lineSpecs.form = "derivative",
  line.colors = "darkviolet",
  line.width = 0.75,
  line.type = 1,
  bg.color = "#e5ecf6",
  grid.color = "white",
  border.line.width = 1.2,
  border.line.color = "black",
  legend.title = NULL,
  legend.title.size = NULL,
  axis.title.size = 15,
  axis.text.size = 14
)

Arguments

`data.spectra`	Spectrum data frame/table object, containing magnetic flux density, $g$ -value or radio-frequency columns as `x` variable. They can be labeled as `Field`, `B_mT` in mT (or `B_G` in gauss), see also `x` parameter/argument. The `y/Intensity` variable can be labeled as `dIepr_over_dB`, in case of derivative intensity, or if integrated or simulated spectra intensities are present, they can be labeled accordingly. See also `Intensity` parameter/argument. For spectral series the second independent variable `var2nd.series` column (e.g. `var2nd.series = "time_s"`) must be available. In such case, the entire `data.spectra` must be present in the form of tidy/long table format (see also parameter/argument `var2nd.series`).
`x`	Character string, pointing to $x$ -axis/column quantity in the original `data.spectrum` like magnetic flux density $B$ , $Field$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`x.unit`	Character string pointing to $x$ -unit of quantity (coming from the original ASCII data, see also `column.names` parameter) which is to be presented on $x$ -axis of the EPR spectrum, like `"G"` ("Gauss"), `"mT"` ("millitesla"), `"MHz"` ("megahertz", in the case of ENDOR spectra) or `"Unitless"` in case of $g$ -values, default: `x.unit = "mT"`.
`Intensity`	Character string, corresponding to the intensity column header in the original `data.spectrum` if other than `dIepr_over_dB` name/label is used (e.g. for integrated or simulated spectra), default: `Intesity = "dIepr_over_dB"`.
`var2nd.series`	Character string, referred to name of the second independent variable/quantity column in the original `data.spectra` (such as time, Temperature, Electrochemical Potential, Microwave Power...etc) altered upon individual experiments. Data must be available in long table (or tidy) format (see also `data.spectra` argument). Default: `var2nd.series = NULL`. Otherwise, usually, `var2nd.series = "time_s"`.
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (i.e. `"absorption"` which can be used as well) line form of the analyzed EPR spectrum/integral.
`line.colors`	Character string (vector). In case of of SIMPLE SPECTRUM (NOT FOR `var2nd.series`) ONLY ONE COLOR CHARACTER STRING IS REQUIRED => therefore, default: `line.color = "darkviolet"`. For the SERIES OF SPECTRA CHARACTER COLOR VECTOR WITH THE LENGTH $\geq 2$ must be DEFINED (e.g. `line.colors = c("darkorange","darkblue")`).
`line.width`	Numeric, linewidth of the plot line in `mm`, default: `line.width = 0.75`.
`line.type`	Character string or integer, corresponding to width of the (spectral) line(s). Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`.
`bg.color`	Character string, corresponding to background color of the panel/graph. Available colors are listed on the CSS Color Module Homepage. Default: `bg.color = "#e5ecf6"` (corresponding to light blue-gray).
`grid.color`	Character string, corresponding to grid lines color of the panel/graph. Available colors are listed on the CSS Color Module Homepage. Default: `grid.color = "white"`.
`border.line.width`	Numeric, width (in `px`) of the graph/plot panel border line, default: `border.line.width = 1.2`.
`border.line.color`	Character string, referring to color of the plot graph/panel border line. Available colors are listed on CSS Color Module Homepage. Default: `border.line.color = "black"`.
`legend.title`	Character string $\equiv$ title of the legend (if the `var2nd.series` in NOT `NULL`). It can be defined either by simple text like `legend.title = "Time (s)"` or if additional formatting is required, the `html` markup language, such as `legend.title = "<i>Time</i> (s)"` or `legend.title = "<i>Potential<i> <br> <i>vs</i> Fc/Fc<sup>+</sup> (V)"` is used. If a $\LaTeX$ typesetting is required for the title, please refer to e.g. LaTeX Plotly Tepesetting. Default: `legend.title = NULL` (in all cases if `var2nd.series = NULL`).
`legend.title.size`	Numeric, text size (in `px`) for the legend title, default: `legend.title.size = NULL`, which actually corresponds to `13` if not otherwise defined.
`axis.title.size`	Numeric, text size (in `px`) for the axis title, default: `axis.title.size = 15`.
`axis.text.size`	Numeric, text size (in `px`) for the axis unit values/descriptions, default: `axis.text.size = 14`.

Value

Interactive plot object of EPR spectrum/spectra based on plotly package.

Examples

## load built-in EPR spectral data
data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## spectrum recorded as accumulation of 20 scans
data.epr <-
  readEPR_Exp_Specs(path_to_ASC = data.file.path,
                    col.names = c("B_G", "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
## interactive plot or screenshot
plot_EPR_Specs2D_interact(data.spectra = data.epr)
#
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting ENDOR spectrum
plot_EPR_Specs2D_interact(data.spectra = pnt.endor.data,
                          x = "RF_MHz",
                          x.unit = "MHz",
                          line.colors = "darkgreen",
                          bg.color = "cornsilk",
                          grid.color = "darkgrey")
#
## Not run: 
## plot time series EPR spectra = verdazyl radical
## oxidation kinetics (`verdazylRad.kinet.spectr`)
plot_EPR_Specs2D_interact(verdazylRad.kinet.spectr,
  x = "B_G",
  x.unit = "G",
  var2nd.series = "time_s",
  legend.title = "<i>Time</i> (s)",
  line.colors = c("darkorange","darkblue")
  )

## End(Not run)


## load built-in EPR spectral data
data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## spectrum recorded as accumulation of 20 scans
data.epr <-
  readEPR_Exp_Specs(path_to_ASC = data.file.path,
                    col.names = c("B_G", "dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
## interactive plot or screenshot
plot_EPR_Specs2D_interact(data.spectra = data.epr)
#
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting ENDOR spectrum
plot_EPR_Specs2D_interact(data.spectra = pnt.endor.data,
                          x = "RF_MHz",
                          x.unit = "MHz",
                          line.colors = "darkgreen",
                          bg.color = "cornsilk",
                          grid.color = "darkgrey")
#
## Not run: 
## plot time series EPR spectra = verdazyl radical
## oxidation kinetics (`verdazylRad.kinet.spectr`)
plot_EPR_Specs2D_interact(verdazylRad.kinet.spectr,
  x = "B_G",
  x.unit = "G",
  var2nd.series = "time_s",
  legend.title = "<i>Time</i> (s)",
  line.colors = c("darkorange","darkblue")
  )

## End(Not run)

Interactive 3D Surface and 2D Contour Plots for the Series of EPR Spectra

Description

Interactive plotting of EPR spectra or their integrals based on plotly package. The aim of this function is to nicely visualize the series of EPR spectra (or their corresponding integrals), while checking out the EPR intensities upon e.g. kinetic (time series), variable temperature or simultaneous spectroelectrochemical experiments (potential series). For such purpose, the data frame input (see the data.spectra.series argument) is transformed into the matrix (with columns/variables corresponding to intensities at defined times, potentials, temperatures...etc.). In the next step the plot_ly function generates either 3D surface or 2D contour plot objects which are finally customized by the layout as well as by the colorbar. Similarly, as for the plot_EPR_Specs2D_interact final plots can be stored or attached to a certain document format, using the plot_EPR_present_interact function (or directly within Rstudio), as .png or .html.

Usage

plot_EPR_Specs3D_interact(
  data.spectra.series,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  var2nd.series = "time_s",
  plot.type = "surface",
  scheme.color = "Viridis",
  contour.labels = FALSE,
  xlim = NULL,
  xlab = "<i>B</i> (mT)",
  ylab = "<i>Time</i> (s)",
  zlab = "d <i>I</i><sub>EPR</sub> / d <i>B</i> (p.d.u.)",
  axis.title.size = 12,
  axis.text.size = 11,
  bg.x.color = "rgb(220, 220,220)",
  grid.x.color = "rgb(255, 255, 255)",
  bg.y.color = "rgb(220, 220,220)",
  grid.y.color = "rgb(255, 255, 255)",
  bg.z.color = "rgb(220, 220,220)",
  grid.z.color = "rgb(255, 255, 255)",
  output.matrix.df = FALSE
)
plot_EPR_Specs3D_interact(
  data.spectra.series,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  var2nd.series = "time_s",
  plot.type = "surface",
  scheme.color = "Viridis",
  contour.labels = FALSE,
  xlim = NULL,
  xlab = "<i>B</i> (mT)",
  ylab = "<i>Time</i> (s)",
  zlab = "d <i>I</i><sub>EPR</sub> / d <i>B</i> (p.d.u.)",
  axis.title.size = 12,
  axis.text.size = 11,
  bg.x.color = "rgb(220, 220,220)",
  grid.x.color = "rgb(255, 255, 255)",
  bg.y.color = "rgb(220, 220,220)",
  grid.y.color = "rgb(255, 255, 255)",
  bg.z.color = "rgb(220, 220,220)",
  grid.z.color = "rgb(255, 255, 255)",
  output.matrix.df = FALSE
)

Arguments

`data.spectra.series`	Spectrum data frame/table, object containing magnetic flux density, $g$ -value or radio-frequency columns as `x` variable. They can be labeled as `Field`, `B_mT` in mT (or `B_G` in gauss), see also `x` parameter/argument. The `y/Intensity` variable can be labeled as `dIepr_over_dB`, in case of derivative intensity, or if integrated or simulated spectral intensities are present, they can be labeled accordingly. See also `Intensity` parameter/argument. A second independent variable `var2nd.series` column (e.g. `var2nd.series = "time_s"`) must be available. In such case, the entire `data.spectra` must be present in the form of tidy/long table format (see also parameter/argument `var2nd.series`).
`x`	Character string, pointing to $x$ -axis/column quantity in the original `data.spectrum` like magnetic flux density $B$ , $Field$ , $g$ -Value or $RF$ (radio frequency), default: `x = "B_mT"`.
`Intensity`	Character string, corresponding to the intensity column header in the original `data.spectrum` if other than `dIepr_over_dB` name/label is used (e.g. for integrated or simulated spectra), default: `Intesity = "dIepr_over_dB"`.
`var2nd.series`	Character string, referred to name of the second independent variable/quantity column in the original `data.spectra.series` (such as time, Temperature, Electrochemical Potential, Microwave Power...etc) altered upon individual experiments. Data must be available in long table (or tidy) format (see also `data.spectra.series` argument). Default: `var2nd.series = NULL`. Otherwise, usually, `var2nd.series = "time_s"`.
`plot.type`	Character string, inherited from `plot_ly`, specifying the trace. Only two character strings are available: `plot.type = "surface"` (default, for 3D surface plots) or `plot.type = "contour"` (for 2D contour plots).
`scheme.color`	Character string, corresponding to `color scale`. See also surface-colorscale. Color scale must be an array containing arrays mapping a normalized value to an RGB, RGBa, HEX, HSL, HSV, or named color string. At minimum, a mapping for the lowest (0) and the highest (1) values are required. For example, `[[0, 'rgb(0,0,255)'], [1, 'rgb(255,0,0)']]` or as a list: `list(c(0, 1), c("tan", "blue"))` or `list(c(0, "tan"), c(1, "blue"))`. To control the bounds of the color scale in the corresponding space, use `cmin` and `cmax`. Alternatively, `color scale` may be a palette name string of the following list: `"Blackbody"`,`"Bluered"`,`"Blues"`, `"Cividis"`,`"Earth"`,`"Electric"`,`"Greens"`,`"Greys"`,`"Hot"`, `"Jet"`,`"Picnic"`,`"Portland"`,`"Rainbow"`,`"RdBu"`,`"Reds"`, `"Viridis"`,`"YlGnBu"`,`"YlOrRd"`. Default: `scheme.color = "Viridis"`.
`contour.labels`	Logical, whether contours of intensity "hills" and "valleys" are projected onto the $x,y$ -plane. Default: `contour.labels = FALSE`.
`xlim`	Numeric vector, pointing to lower and upper limit of the $x$ -axis range. Assignment of `xlim = NULL` (default) actually corresponds to the entire original range (see also the `data.spectra.series` argument).
`xlab`	Character string $\equiv$ title of the $x$ -axis. Either simple, like `xlab = "B (mT)"` can be applied or if additional formatting is required, the `html` markup language is used, such as `xlab = "<i>B</i> (mT)"` (default). If a $\LaTeX$ typesetting is required for the title, please refer to e.g. LaTeX Plotly Tepesetting.
`ylab`	Character string $\equiv$ title of the $y$ -axis (see also `xlab`), default: `ylab = "<i>Time</i> (s)"`.
`zlab`	Character string $\equiv$ title of the $z$ -axis (see also `xlab`), default: `zlab = "d <i>I</i><sub>EPR</sub> / d <i>B</i> (p.d.u.)"`.
`axis.title.size`	Numeric, text size (in `px`) for the axis title, default: `axis.title.size = 15`.
`axis.text.size`	Numeric, text size (in `px`) for the axis unit values/descriptions, default: `axis.text.size = 14`.
`bg.x.color`	Character string, setting the background color of the $x$ -axis wall. Default: `bg.x.color = "rgb(220, 220,220)"` (light gray). For additional color definitions, consult CSS Color Module Homepage.
`grid.x.color`	Character string, pointing to color of $x$ -axis grid lines, default: `grid.x.color = "rgb(255, 255, 255)"` (white). For additional color definitions, consult CSS Color Module Homepage.
`bg.y.color`	Character string, setting the background color of the $y$ -axis wall (see also `bg.x.color`), default: `bg.y.color = "rgb(220, 220,220)"` (light gray).
`grid.y.color`	Character string, pointing to color of $y$ -axis grid lines, default: `grid.y.color = "rgb(255, 255, 255)"` (white).
`bg.z.color`	Character string, setting the background color of the $z$ -axis wall (see also `bg.x.color`), default: `bg.z.color = "rgb(220, 220,220)"` (light gray).
`grid.z.color`	Character string, pointing to color of $z$ -axis grid lines, default: `grid.z.color = "rgb(255, 255, 255)"` (white).
`output.matrix.df`	Logical, if `output.matrix.df = TRUE` a wide data frame format, with all spectral/integral intensities and within the (time, Temperature,...etc.) series, represented by individual columns/variables, is returned. Default: `output.matrix.df = FALSE`.

Value

Depending on output.matrix.df, function returns either interactive plot object (output.matrix.df = FALSE) or if otput.matrix.df = TRUE, it results in the list consisting of

plot: Interactive object plot (see below).
df: Associated data fame object in wide table format for subsequent processing by other graphing software programs. It can be also quite easily transformed into the long/tidy format by the pivot_longer.

In both cases the interactive plot can be visualized either in 3D surface mode (plot.type = "surface") or in 2D contour mode with the intensity scale mapped onto the color bar (plot.type = "contour").

Examples

## loading the built-in package example to demonstrate
## visualizatioin of time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
                          "Triarylamine_radCat_decay_series",
                        dir_ASC = tempdir(),
                        dir_dsc_par =
                          system.file("extdata",
                                      package = "eprscope")
                        )
#
## plot basics `surface` plot (with default arguments)
## and the `Jet` color scheme including
## Intensity contour labels
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  contour.labels = TRUE,
  scheme.color = "Jet")
#
## plot basic `contour` plot (with default arguments)
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  plot.type = "contour")
#
## Not run: 
## 3D surface plotting EPR spectra series (in the region
## of <334,345> mT) from variable temperature
## (VT) experiments
plot_EPR_Specs3D_interact(data.spectra.series,
  var2nd.series = "Temperature_K",
  xlim = c(334,345),
  contour.labels = T,
  ylab = "<i>Temperature</i> (K)")

## End(Not run)


## loading the built-in package example to demonstrate
## visualizatioin of time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
                          "Triarylamine_radCat_decay_series",
                        dir_ASC = tempdir(),
                        dir_dsc_par =
                          system.file("extdata",
                                      package = "eprscope")
                        )
#
## plot basics `surface` plot (with default arguments)
## and the `Jet` color scheme including
## Intensity contour labels
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  contour.labels = TRUE,
  scheme.color = "Jet")
#
## plot basic `contour` plot (with default arguments)
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  plot.type = "contour")
#
## Not run: 
## 3D surface plotting EPR spectra series (in the region
## of <334,345> mT) from variable temperature
## (VT) experiments
plot_EPR_Specs3D_interact(data.spectra.series,
  var2nd.series = "Temperature_K",
  xlim = c(334,345),
  contour.labels = T,
  ylab = "<i>Temperature</i> (K)")

## End(Not run)

Interactive Application to Plot and Evaluate CW Isotropic EPR Spectra

Description

Launch this app in order to quickly check recorded EPR spectra with their instrumental parameters. Additionally, you may try to interactively simulate the isotropic continuous wave (CW) EPR spectra using the simple user interface based on the R Shiny and several functions from the package (see Details).

Usage

plot_eval_ExpSim_app()
plot_eval_ExpSim_app()

Details

Based on the acquisition EPR spectrum origin, in user interface, one can load a spectrum and its instrumental/experimental parameters by the readEPR_Exp_Specs as well as by the readEPR_params_tabs functions. An EPR is immediately depicted in the interactive {plotly} format by plot_EPR_Specs2D_interact. The magnetic flux density $B$ of such EPR spectrum can be changed from mT to G and to g-values. Moreover, if the compound/radical structure is already known one can easily show its structure by entering its corresponding SMILES code, using the draw_molecule_by_rcdk. Uploaded ASCII data (spectrum + parameters) are applied to interactively simulate the corresponding experimental spectrum by the eval_sim_EPR_iso and to visualize it by the present_EPR_Sim_Spec. Additionally, one can also print and download the corresponding data frame/table in several formats (.csv,.pdf or .xls(x)) and thus use the data not only in R environment but also in other programs.

Examples

## Not run: 
## run the app just by the following
## command in R console:
plot_eval_ExpSim_app()
#
## this is an examples of the raw
## shiny R code to run the app,
## code example from the `SERVER` part:
server <- function(input, output,session) {
## redefinition of `norm.vec.add`
norm_vec <- reactiveValues(val = NULL)
observe({
 if (isTRUE(input$normVec)){
   norm_vec$val <- as.numeric(unlist(strsplit(input$vecNorm,",")))
 } else {
   norm_vec$val <- NULL
 }
})
#
## Load experimental spectrum data frame
expr_data <- reactive({
#
req(input$ASCIIfile)
#
 spectr.data <-
   readEPR_Exp_Specs(
     path_to_ASC = input$ASCIIfile$datapath,
     col.names = switch(
       3-origin.cond(orig = input$origin),
       c("index","B_G", "dIepr_over_dB"),
       c("B_G", "dIepr_over_dB"),
       c("B_mT","dIepr_over_dB")
     ),
     x.unit = switch(
       3-origin.cond(orig = input$origin),
       "G",
       "G",
       "mT"
     ),
     qValue = input$qValue,
     origin = input$origin,
     norm.vec.add = norm_vec$val
   )
 spectr.data
})
#
# -------------------- INTERACTIVE SPECTRUM ---------------------
#
output$plot <- plotly::renderPlotly({
 #
 ## add g-Value condition:
 if (isTRUE(input$gval)) {
   expr_data_g <- expr_data() %>%
     dplyr::mutate(g_Value =
                     eval_gFactor(
                       nu.val = input$MWnuGHz,
                       B.val = .data$B_mT
                     ))
 }
...})
 }

## End(Not run)


## Not run: 
## run the app just by the following
## command in R console:
plot_eval_ExpSim_app()
#
## this is an examples of the raw
## shiny R code to run the app,
## code example from the `SERVER` part:
server <- function(input, output,session) {
## redefinition of `norm.vec.add`
norm_vec <- reactiveValues(val = NULL)
observe({
 if (isTRUE(input$normVec)){
   norm_vec$val <- as.numeric(unlist(strsplit(input$vecNorm,",")))
 } else {
   norm_vec$val <- NULL
 }
})
#
## Load experimental spectrum data frame
expr_data <- reactive({
#
req(input$ASCIIfile)
#
 spectr.data <-
   readEPR_Exp_Specs(
     path_to_ASC = input$ASCIIfile$datapath,
     col.names = switch(
       3-origin.cond(orig = input$origin),
       c("index","B_G", "dIepr_over_dB"),
       c("B_G", "dIepr_over_dB"),
       c("B_mT","dIepr_over_dB")
     ),
     x.unit = switch(
       3-origin.cond(orig = input$origin),
       "G",
       "G",
       "mT"
     ),
     qValue = input$qValue,
     origin = input$origin,
     norm.vec.add = norm_vec$val
   )
 spectr.data
})
#
# -------------------- INTERACTIVE SPECTRUM ---------------------
#
output$plot <- plotly::renderPlotly({
 #
 ## add g-Value condition:
 if (isTRUE(input$gval)) {
   expr_data_g <- expr_data() %>%
     dplyr::mutate(g_Value =
                     eval_gFactor(
                       nu.val = input$MWnuGHz,
                       B.val = .data$B_mT
                     ))
 }
...})
 }

## End(Not run)

Labels for Various Plots (Spectroscopy, EPR, Voltammetry,...etc)

Description

Using physico-chemical notation of quantities or formulas (labels and titles with greek symbols, subscript and superscript...etc) in static plots. The function is inspired by the R-Bloggers:Math Notation and R-Bloggers:Plotmath, in order to simplify the writing. See also plotmath documentation or in console write ?plotmath.

Usage

plot_labels_xyz(quantity, unit, user.defined = FALSE)
plot_labels_xyz(quantity, unit, user.defined = FALSE)

Arguments

`quantity`	Variable string without quotation (some parts of the expression can be however quoted, see examples below), corresponding to physical quantity, which should be displayed as the (axis) title like $B$ , d $I_{EPR}$ /d $B$ , $time$ , $\Delta B_{pp}$ , Double Integral...etc.
`unit`	Variable String without quotation (some parts of the expression can be however quoted, see examples below) referring to displayed physical quantity unit, like `mT`, `s`, `p.d.u.`, ...etc.
`user.defined`	Logical, in order to bring more flexibility to customize quantities and units to meet the users needs. Default: `user.defined = FALSE`.

Value

Axis labels/expressions for different plots.

Examples

## Not run: 
## magnetic flux density
plot_labels_xyz(B,mT)
#
## derivative intensity
plot_labels_xyz(d*italic(I)[EPR]~"/"~d*italic(B),
                "("~p.d.u.~")",
                user.defined = TRUE)
#
## derivative intesity
plot_labels_xyz(d*italic(I)[EPR]~"/"~d*italic(B),p.d.u.)

#
## ∆Bpp
plot_labels_xyz(quantity = Delta*B[pp],
                unit = "("~mT~")",
                user.defined = TRUE)
#
## time
plot_labels_xyz(t,s)
#
## temperature
plot_labels_xyz(T,K)
#
## electrochemical potential
plot_labels_xyz(E,
                "("~V~")"~~~italic(vs)~~~italic(Ref.~Electrode),
                user.defined = TRUE)
#
## concentration
plot_labels_xyz(c,mmol~dm^-3)
#
## double integral
plot_labels_xyz(Double~~Integral,
                p.d.u.,
                user.defined = FALSE)
#
## ENDOR frequency
plot_labels_xyz(italic(nu)[RF],"("~MHz~")",
                user.defined = TRUE)

## End(Not run)
#
## loading example data (incl. `Area` and `time`
## variables) from Xenon: decay of a triarylamine
## radical cation after its generation
## by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file =
                     "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated EPR
## spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
#
## simple plot of previous data using
## `plot_labels_xyz()`
ggplot2::ggplot(data = triaryl_radCat_data) +
  ggplot2::geom_point(
    ggplot2::aes(x = time_s,y = Area)
    ) +
  ggplot2::labs(title = "Radical Kinetics",
                x = plot_labels_xyz(Time,s),
                y = plot_labels_xyz(Double~~Integral,p.d.u.)) +
  plot_theme_NoY_ticks()


## Not run: 
## magnetic flux density
plot_labels_xyz(B,mT)
#
## derivative intensity
plot_labels_xyz(d*italic(I)[EPR]~"/"~d*italic(B),
                "("~p.d.u.~")",
                user.defined = TRUE)
#
## derivative intesity
plot_labels_xyz(d*italic(I)[EPR]~"/"~d*italic(B),p.d.u.)

#
## ∆Bpp
plot_labels_xyz(quantity = Delta*B[pp],
                unit = "("~mT~")",
                user.defined = TRUE)
#
## time
plot_labels_xyz(t,s)
#
## temperature
plot_labels_xyz(T,K)
#
## electrochemical potential
plot_labels_xyz(E,
                "("~V~")"~~~italic(vs)~~~italic(Ref.~Electrode),
                user.defined = TRUE)
#
## concentration
plot_labels_xyz(c,mmol~dm^-3)
#
## double integral
plot_labels_xyz(Double~~Integral,
                p.d.u.,
                user.defined = FALSE)
#
## ENDOR frequency
plot_labels_xyz(italic(nu)[RF],"("~MHz~")",
                user.defined = TRUE)

## End(Not run)
#
## loading example data (incl. `Area` and `time`
## variables) from Xenon: decay of a triarylamine
## radical cation after its generation
## by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file =
                     "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated EPR
## spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
#
## simple plot of previous data using
## `plot_labels_xyz()`
ggplot2::ggplot(data = triaryl_radCat_data) +
  ggplot2::geom_point(
    ggplot2::aes(x = time_s,y = Area)
    ) +
  ggplot2::labs(title = "Radical Kinetics",
                x = plot_labels_xyz(Time,s),
                y = plot_labels_xyz(Double~~Integral,p.d.u.)) +
  plot_theme_NoY_ticks()

Additional Layout for Interactive 2D Plots

Description

Additional customization of interactive 2D plots (see also plot_EPR_Specs2D_interact). The main goal is to simplify setting up process of the layout via several nested lists. Mostly, it nicely works (using the %>%) either with the general plot_ly or the above-mentioned plot_EPR_Specs2D_interact (see also Examples).

Usage

plot_layout2D_interact(
  p,
  data = NULL,
  xlab = "<i>B</i> (mT)",
  ylab = "d <i>I</i> <sub>EPR</sub> / d <i>B</i>  (p.d.u.)",
  axis.title.x.family = "Arial",
  axis.title.x.color = "black",
  axis.title.x.size = 15,
  axis.text.x.family = "Arial",
  axis.text.x.color = "black",
  axis.text.x.size = 14,
  axis.title.y.family = "Arial",
  axis.title.y.color = "black",
  axis.title.y.size = 15,
  axis.text.y.family = "Arial",
  axis.text.y.color = "black",
  axis.text.y.size = 14,
  legend.title = NULL,
  legend.title.family = "Arial",
  legend.title.color = "black",
  legend.title.size = 13,
  bg.color = "#e5ecf6",
  grid.x = TRUE,
  grid.y = TRUE,
  grid.color = "white",
  grid.line.width = 1,
  grid.line.type = "solid",
  border.line.width = 1.4,
  border.line.color = "black"
)
plot_layout2D_interact(
  p,
  data = NULL,
  xlab = "<i>B</i> (mT)",
  ylab = "d <i>I</i> <sub>EPR</sub> / d <i>B</i>  (p.d.u.)",
  axis.title.x.family = "Arial",
  axis.title.x.color = "black",
  axis.title.x.size = 15,
  axis.text.x.family = "Arial",
  axis.text.x.color = "black",
  axis.text.x.size = 14,
  axis.title.y.family = "Arial",
  axis.title.y.color = "black",
  axis.title.y.size = 15,
  axis.text.y.family = "Arial",
  axis.text.y.color = "black",
  axis.text.y.size = 14,
  legend.title = NULL,
  legend.title.family = "Arial",
  legend.title.color = "black",
  legend.title.size = 13,
  bg.color = "#e5ecf6",
  grid.x = TRUE,
  grid.y = TRUE,
  grid.color = "white",
  grid.line.width = 1,
  grid.line.type = "solid",
  border.line.width = 1.4,
  border.line.color = "black"
)

Arguments

`p`	`Plotly` object, corresponding to previous/actual graph/plot.
`data`	Data frame object in order to associate with the layout (optional). If not provided, arguments are evaluated using the data frame in `plot_ly` function of the previous/actual plot. Therefore, default: `data = NULL`.
`xlab`	Character string $\equiv$ title of the $x$ -axis. Either simple, like `xlab = "B (mT)"` can be applied or if additional formatting is required, the `html` markup language is used, such as `xlab = "<i>B</i> (mT)"` (default). If a $\LaTeX$ typesetting is required for the title, please refer to e.g. LaTeX Plotly Tepesetting.
`ylab`	Character string $\equiv$ title of the $y$ -axis (see also `xlab`), default: `ylab = "d <i>I</i> <sub>EPR</sub> / d <i>B</i> (p.d.u.)"`.
`axis.title.x.family`	Character string, setting the font of the $x$ -axis title. Following `html` fonts are available: "Arial" (default), "Balto", "Courier New", "Droid Sans", "Droid Serif", "Droid Sans Mono", "Gravitas One", "Old Standard TT", "Open Sans", "Overpass", "PT Sans Narrow", "Raleway" and "Times New Roman".
`axis.title.x.color`	Character string, pointing to color of the $x$ -axis title font, default: `axis.title.x.color = "black"`. Additional available colors are listed at the CSS Color Module Homepage.
`axis.title.x.size`	Numeric, setting up the size of the $x$ -axis title font in `px`, default: `axis.title.x.size = 15`.
`axis.text.x.family`	Character string, setting the font of the $x$ -axis text. Following `html` fonts are available: "Arial" (default), "Balto", "Courier New", "Droid Sans", "Droid Serif", "Droid Sans Mono", "Gravitas One", "Old Standard TT", "Open Sans", "Overpass", "PT Sans Narrow", "Raleway" and "Times New Roman".
`axis.text.x.color`	Character string, pointing to color of the $x$ -axis text font, default: `axis.title.x.color = "black"`. Additional available colors are listed at the CSS Color Module Homepage.
`axis.text.x.size`	Numeric, setting up the size of the $x$ -axis text font in `px`, default: `axis.title.x.size = 14`.
`axis.title.y.family`	Character string, setting the font of the $y$ -axis title (see also `axis.title.x.family`). Default: `axis.title.y.family = "Arial"`.
`axis.title.y.color`	Character string, pointing to color of the $y$ -axis title font (see also `axis.title.x.color`). Default: `axis.title.y.color = "black"`.
`axis.title.y.size`	Numeric, setting up the size of the $y$ -axis title font in `px`, default: `axis.title.x.size = 15`.
`axis.text.y.family`	Character string, setting the font of the $y$ -axis text (see also `axis.text.x.family`). Default: `axis.text.y.family = "Arial"`.
`axis.text.y.color`	Character string, pointing to color of the $y$ -axis text font (see also `axis.text.x.color`). Default: `axis.text.y.color = "black"`.
`axis.text.y.size`	Numeric, setting up the size of the $y$ -axis text font in `px`, default: `axis.text.x.size = 14`.
`legend.title`	Character string $\equiv$ title of the legend (if the `var2nd.series` in NOT `NULL`). It can be defined either by simple text like `legend.title = "Time (s)"` or if additional formatting is required, the `html` markup language, such as `legend.title = "<i>Time</i> (s)"` or `legend.title = "<i>Potential<i> <br> <i>vs</i> Fc/Fc<sup>+</sup> (V)"` is used. If a $\LaTeX$ typesetting is required for the title, please refer to e.g. LaTeX Plotly Tepesetting. Default: `legend.title = NULL` (in all cases if `var2nd.series = NULL`).
`legend.title.family`	Character string, setting the font of the legend title. Following `html` fonts are available: "Arial" (default), "Balto", "Courier New", "Droid Sans", "Droid Serif", "Droid Sans Mono", "Gravitas One", "Old Standard TT", "Open Sans", "Overpass", "PT Sans Narrow", "Raleway" and "Times New Roman".
`legend.title.color`	Character string pointing to color of the legend title font, default: `legend.title.x.color = "black"`. Additional available colors are listed at the CSS Color Module Homepage.
`legend.title.size`	Numeric, text size (in `px`) for the legend title, default: `legend.title.size = NULL`, which actually corresponds to `13` if not otherwise defined.
`bg.color`	Character string, corresponding to background color of the panel/graph. Available colors are listed on the CSS Color Module Homepage. Default: `bg.color = "#e5ecf6"` (corresponding to light blue-gray).
`grid.x`	Logical, whether to show (`grid.x = TRUE`, default) or hide the grid $x$ -axis lines.
`grid.y`	Logical, whether to show (`grid.y = TRUE`, default) or hide the grid $y$ -axis lines.
`grid.color`	Character string, corresponding to grid lines color of the panel/graph. Available colors are listed on the CSS Color Module Homepage. Default: `grid.color = "white"`.
`grid.line.width`	Numeric, width (in `px`) of the graph/plot panel grid lines, default: `grid.line.width = 1.4`.
`grid.line.type`	Character string, corresponding to type of the grid line. In addition to `grid.line.type = "solid"` (default), "dot", "dash", "longdash", "dashdot", "longdashdot" can be used, as well.
`border.line.width`	Numeric, width (in `px`) of the graph/plot panel border line, default: `border.line.width = 1.2`.
`border.line.color`	Character string, referring to color of the plot graph/panel border line. Available colors are listed on CSS Color Module Homepage. Default: `border.line.color = "black"`.

Value

List of the interactive plot object properties/parts, which can be used in connection with plot_EPR_Specs2D_interact or plot_ly.

Examples

## example from `plot_EPR_Specs2D_interact()`
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting ENDOR spectrum
plot_EPR_Specs2D_interact(data.spectra = pnt.endor.data,
  x = "RF_MHz",
  x.unit = "MHz",
  line.colors = "darkgreen",
  bg.color = "cornsilk",
  grid.color = "darkgrey") %>%
    plot_layout2D_interact(xlab =
                     "<i>&#957;</i><sub>RF</sub> (MHz)",
      axis.title.x.family = "Times New Roman",
      axis.title.y.family = "Times New Roman",
      border.line.color = "blue",
      grid.y = FALSE
      )


## example from `plot_EPR_Specs2D_interact()`
## loading the built-in CW ENDOR spectrum
## of perinaphthenyl (PNT)
pnt.file.path <- load_data_example("PNT_ENDOR_a.txt")
## read the PNT CW ENDOR data without intensity
## normalization
pnt.endor.data <-
  readEPR_Exp_Specs(pnt.file.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz")
## plotting ENDOR spectrum
plot_EPR_Specs2D_interact(data.spectra = pnt.endor.data,
  x = "RF_MHz",
  x.unit = "MHz",
  line.colors = "darkgreen",
  bg.color = "cornsilk",
  grid.color = "darkgrey") %>%
    plot_layout2D_interact(xlab =
                     "<i>&#957;</i><sub>RF</sub> (MHz)",
      axis.title.x.family = "Times New Roman",
      axis.title.y.family = "Times New Roman",
      border.line.color = "blue",
      grid.y = FALSE
      )

Custom `ggplot2` Theme with Axis Ticks Oriented Inside the Panel

Description

Change the ggplot2-based theme in order to meet the needs of graph (such as EPR spectrum, kinetic profiles...etc) visuals/non-data components of the actual plot. Theme can be mainly applied for the basic ggplot2 components like ggplot() + geom_...() + ... and consists of highlighted panel borders, grid and axis ticks pointing inside the graph/plot panel. For details of ggplot2 theme elements please, refer to Modify Components of a Theme (see also the theme) or to ggplot2 Elements Demonstration by Henry Wang.

Usage

plot_theme_In_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)
plot_theme_In_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)

Arguments

`axis.text.size`	Numeric, text size (in `pt`) for the axes units/descriptions, default: `axis.text.size = 14`.
`axis.title.size`	Numeric, text size (in `pt`) for the axes title, default: `axis.title.size = 15`.
`grid`	Logical, whether to display the `grid` within the plot/graph panel, default: `grid = TRUE`.
`border.line.color`	Character string, setting up the color of the plot panel border line, default: `border.line.color = "black"`.
`border.line.type`	Character string or integer, corresponding to width of the graph/plot panel border line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`..
`border.line.width`	Numeric, width (in `mm`) of the plot panel border line, default: `border.line.width = 0.5`.
`bg.transparent`	Logical, whether the entire plot background (excluding the panel) should be transparent, default: `bg.transparent = FALSE`, i.e. no transparent background.
`...`	additional arguments specified by the `theme` (such as `panel.backgroud`, `axis.line`,...etc), which are not specified otherwise.

Value

Custom ggplot2 theme (list) with x,y-axis ticks pointing inside the graph/plot panel.

Examples

## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## simple `ggplot2` without any theme customization
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
  ggplot2::aes(x = B_mT,y = dIepr_over_dB)
  )
#
## simple `ggplot2` with `in-ticks` theme and tile
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    ) +
  plot_theme_In_ticks() +
  ggplot2::ggtitle(
  label = "EPR Spectrum of Aminoxyl Radical"
  )
#
## basic EPR spectrum plot by the `plot_EPR_Specs()`
plot_EPR_Specs(data.spectra = aminoxyl.data)
#
## previous spectrum combined with `in-ticks` theme
## without the panel background
plot_EPR_Specs(data.spectra = aminoxyl.data) +
  plot_theme_In_ticks(
    panel.background = ggplot2::element_blank()
    )


## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## simple `ggplot2` without any theme customization
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
  ggplot2::aes(x = B_mT,y = dIepr_over_dB)
  )
#
## simple `ggplot2` with `in-ticks` theme and tile
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    ) +
  plot_theme_In_ticks() +
  ggplot2::ggtitle(
  label = "EPR Spectrum of Aminoxyl Radical"
  )
#
## basic EPR spectrum plot by the `plot_EPR_Specs()`
plot_EPR_Specs(data.spectra = aminoxyl.data)
#
## previous spectrum combined with `in-ticks` theme
## without the panel background
plot_EPR_Specs(data.spectra = aminoxyl.data) +
  plot_theme_In_ticks(
    panel.background = ggplot2::element_blank()
    )

Custom `ggplot2` Theme without `Y` Axis Ticks

Description

Change the ggplot2-based theme in order to meet the needs of graph (such as EPR spectrum, kinetic profiles...etc) visuals/non-data components of the actual graph/plot. The theme can be mainly applied for the basic ggplot2 components like ggplot() + geom_...() + ... and consists of highlighted panel borders, grid and x-axis ticks pointing inside the plot panel. The y-axis ticks are skipped (see also plot_EPR_Specs). For details of ggplot2 theme elements please, refer to Modify Components of a Theme (see also theme) or to ggplot2 Elements Demonstration by Henry Wang.

Usage

plot_theme_NoY_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)
plot_theme_NoY_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)

Arguments

`axis.text.size`	Numeric, text size (in `pt`) for the axes units/descriptions, default: `axis.text.size = 14`.
`axis.title.size`	Numeric, text size (in `pt`) for the axes title, default: `axis.title.size = 15`.
`grid`	Logical, whether to display the `grid` within the plot/graph panel, default: `grid = TRUE`.
`border.line.color`	Character string, setting up the color of the plot panel border line, default: `border.line.color = "black"`.
`border.line.type`	Character string or integer, corresponding to width of the graph/plot panel border line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`..
`border.line.width`	Numeric, width (in `mm`) of the plot panel border line, default: `border.line.width = 0.5`.
`bg.transparent`	Logical, whether the entire plot background (excluding the panel) should be transparent, default: `bg.transparent = FALSE`, i.e. no transparent background.
`...`	additional arguments specified by the `theme` (such as `panel.backgroud`, `axis.line`,...etc), which are not specified otherwise.

Value

Custom ggplot2 theme (list) with x-axis ticks pointing inside the graph/plot panel, and with y-ticks being not displayed.

Examples

#' ## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## simple `ggplot2` without any theme customization
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    )
#
## simple `ggplot2` with `noY-ticks` theme and tile
## (+subtitle)
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    ) +
  plot_theme_NoY_ticks() +
  ggplot2::ggtitle(label = "Aminoxyl Radical",
                   subtitle = "EPR Spectrum")
#
## comparison of EPR spectra generated
## by `plot_EPR_Specs()` and by the simple
## `ggplot2` with `noY-ticks` theme
plot_EPR_Specs(data.spectra = aminoxyl.data,
               yTicks = FALSE) +
  ggplot2::ggtitle(label = "Aminoxyl Radical",
                   subtitle = "EPR Spectrum")
#
## loading example data (incl. `Area` and `time`
## variables) from Xenon: decay of a triarylamine
## radical cation after its generation
## by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file =
                     "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated EPR
## spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
#
## simple plot of previous data using
## the `noY-ticks` theme
ggplot2::ggplot(data = triaryl_radCat_data) +
  ggplot2::geom_point(
    ggplot2::aes(x = time_s,y = Area)
    ) +
  ggplot2::labs(title = "Radical Kinetics",
                x = plot_labels_xyz(Time,s),
                y = plot_labels_xyz(Double~~Integral,p.d.u.)) +
  plot_theme_NoY_ticks()


#' ## loading the aminoxyl radical CW EPR spectrum:
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
#
## simple `ggplot2` without any theme customization
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    )
#
## simple `ggplot2` with `noY-ticks` theme and tile
## (+subtitle)
ggplot2::ggplot(data = aminoxyl.data) +
  ggplot2::geom_line(
    ggplot2::aes(x = B_mT,y = dIepr_over_dB)
    ) +
  plot_theme_NoY_ticks() +
  ggplot2::ggtitle(label = "Aminoxyl Radical",
                   subtitle = "EPR Spectrum")
#
## comparison of EPR spectra generated
## by `plot_EPR_Specs()` and by the simple
## `ggplot2` with `noY-ticks` theme
plot_EPR_Specs(data.spectra = aminoxyl.data,
               yTicks = FALSE) +
  ggplot2::ggtitle(label = "Aminoxyl Radical",
                   subtitle = "EPR Spectrum")
#
## loading example data (incl. `Area` and `time`
## variables) from Xenon: decay of a triarylamine
## radical cation after its generation
## by electrochemical oxidation
triaryl_radCat_path <-
  load_data_example(file =
                     "Triarylamine_radCat_decay_a.txt")
## corresponding data (double integrated EPR
## spectrum = `Area` vs `time`)
triaryl_radCat_data <-
  readEPR_Exp_Specs(triaryl_radCat_path,
                    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()
#
## simple plot of previous data using
## the `noY-ticks` theme
ggplot2::ggplot(data = triaryl_radCat_data) +
  ggplot2::geom_point(
    ggplot2::aes(x = time_s,y = Area)
    ) +
  ggplot2::labs(title = "Radical Kinetics",
                x = plot_labels_xyz(Time,s),
                y = plot_labels_xyz(Double~~Integral,p.d.u.)) +
  plot_theme_NoY_ticks()

Custom `ggplot2` Theme with Axis Ticks Oriented Outside the Panel

Description

Change the ggplot2-based theme in order to meet the needs of graph (such as EPR spectrum, kinetic profiles...etc) visuals/non-data components of the actual graph/plot. The theme can be mainly applied for the basic ggplot2 components like ggplot() + geom_...() + ... and consists of highlighted panel borders, grid and axis ticks pointing outside of the plot panel. For details of ggplot2 theme elements please, refer to Modify Components of a Theme (see also theme) or to ggplot2 Elements Demonstration by Henry Wang.

Usage

plot_theme_Out_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)
plot_theme_Out_ticks(
  axis.text.size = 14,
  axis.title.size = 15,
  grid = TRUE,
  border.line.color = "black",
  border.line.type = 1,
  border.line.width = 0.5,
  bg.transparent = FALSE,
  ...
)

Arguments

`axis.text.size`	Numeric, text size (in `pt`) for the axes units/descriptions, default: `axis.text.size = 14`.
`axis.title.size`	Numeric, text size (in `pt`) for the axes title, default: `axis.title.size = 15`.
`grid`	Logical, whether to display the `grid` within the plot/graph panel, default: `grid = TRUE`.
`border.line.color`	Character string, setting up the color of the plot panel border line, default: `border.line.color = "black"`.
`border.line.type`	Character string or integer, corresponding to width of the graph/plot panel border line. Following types can be specified: `0 = "blank"`, `1 = "solid"` (default), `2 = "dashed"`, `3 = "dotted"`, `4 = "dotdash"`, `5 = "longdash"` and `6 = "twodash"`..
`border.line.width`	Numeric, width (in `mm`) of the plot panel border line, default: `border.line.width = 0.5`.
`bg.transparent`	Logical, whether the entire plot background (excluding the panel) should be transparent, default: `bg.transparent = FALSE`, i.e. no transparent background.
`...`	additional arguments specified by the `theme` (such as `panel.backgroud`, `axis.line`,...etc), which are not specified otherwise.

Value

Custom ggplot2 theme (list) with x,y-axis ticks pointing outside of the graph/plot panel.

Examples

## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
ggplot2::ggplot(data = tmpd.data.file,
       ggplot2::aes(x = B_G,y = dIepr_over_dB)
       ) +
  ggplot2::geom_line(linewidth = 0.75,color = "darkgreen") +
  ggplot2::xlab("B (G)") +
  ggplot2::ylab("dIepr / dB  (p.d.u.)") +
  plot_theme_Out_ticks()


## loading TMPD built-in example file:
tmpd.data.file.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
## reading data:
tmpd.data.file <-
  readEPR_Exp_Specs(path_to_ASC = tmpd.data.file.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = 20,
                    origin = "winepr")
#
ggplot2::ggplot(data = tmpd.data.file,
       ggplot2::aes(x = B_G,y = dIepr_over_dB)
       ) +
  ggplot2::geom_line(linewidth = 0.75,color = "darkgreen") +
  ggplot2::xlab("B (G)") +
  ggplot2::ylab("dIepr / dB  (p.d.u.)") +
  plot_theme_Out_ticks()

A Comparison of EPR Spectra Between Experimental and Simulated Form

Description

Presenting experimental as well as simulated/fitted EPR spectra together in one ggplot2 object. They are visualized in two possible modes. Despite the fact that quite often two spectra are compared in overlay mode, sometimes it is rather difficult to figure out differences between the experimental and the simulated EPR spectrum by such manner (the details can be "hidden" in overlays). Therefore, there is also an option to offset the EPR simulated spectrum underneath the experimental one, see argument Intensity.shift.ratio. For the sake of presentation, the maximum-minimum intensity difference, of the simulated spectrum, is automatically scaled onto the experimental one.

Usage

present_EPR_Sim_Spec(
  data.spectr.expr,
  data.spectr.sim,
  B.unit = "G",
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  Intensity.shift.ratio = 1.2,
  B.shift = 0,
  lineSpecs.form = "derivative",
  line.color.expr = "red",
  line.color.sim = "blue",
  line.width = 0.75,
  output.df = FALSE
)
present_EPR_Sim_Spec(
  data.spectr.expr,
  data.spectr.sim,
  B.unit = "G",
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  Intensity.shift.ratio = 1.2,
  B.shift = 0,
  lineSpecs.form = "derivative",
  line.color.expr = "red",
  line.color.sim = "blue",
  line.width = 0.75,
  output.df = FALSE
)

Arguments

`data.spectr.expr`	Data frame object related to experimental spectrum, including the magnetic flux density (in `mT` or `G`) column, which can be labeled as `B_mT` in mT (or `B_G` in gauss), and the intensity column such as `dIepr_over_dB`, where the `index` column can be included as well.
`data.spectr.sim`	Data frame object related to experimental spectrum including the magnetic flux density (in `mT` or `G`) column, which can be labeled as `Bsim_mT` in mT (or `Bsim_G` in gauss), and the intensity column such as `dIeprSim_over_dB`. These column names are acquired automatically if function like the `readEPR_Sim_Spec` or the `eval_sim_EPR_iso` is used to get the simulated spectrum data in ASCII.
`B.unit`	Character string, pointing to unit of magnetic flux density (coming from the original datasets) which is to be presented on $B$ -axis of the EPR spectrum. Strings like `"G"` ('Gauss') (default) or `"mT"` ('millitesla') can be used.
`Intensity.expr`	Character string, referring to intensity column name if other than `dIepr_over_dB` name/label is used (e.g. for integrated spectra), default: `Intesity = "dIepr_over_dB"`.
`Intensity.sim`	Character string, referring to intensity column name of the simulated spectrum if other than `dIeprSim_over_dB` name/label is used (e.g. for integrated spectra), default: `Intesity = "dIeprSim_over_dB"`, which is automatically set if the `readEPR_Sim_Spec` function is used to read the spectrum in ASCII.
`Intensity.shift.ratio`	Numeric (CANNOT BE `0`), showing how 'far' is the simulated EPR spectrum presented underneath the experimental one. The lower the ratio, the 'deeper' the simulated spectrum offset, default: `Intensity.shift.ratio = 1.2`, other common values : `0.6`,`0.8`, `1.2`,`1.1`. If the `Intensity.shift.ratio = NULL`, BOTH SPECTRA ARE PRESENTED IN OVERLAY MODE !
`B.shift`	Numeric, difference between the $B_{center}$ of simulated and experimental spectrum, that can be caused by switching ON the Teslameter. It refers to simulated spectrum, default: `B.shift = 0` (NOTE: It depends on the `B` parameter. If `B.unit = "mT"` => `B.shift` must be in `mT`, or if `B.unit = "G"` then `B.shift` must be in `G`).
`lineSpecs.form`	Character string, describing either `"derivative"` (default) or `"integrated"` (i.e. `"absorption"` or sigmoid-integrated, which can be used as well) line form of the analyzed EPR spectrum/data.
`line.color.expr`	Character string, line color to plot simple EPR spectrum. All `ggplot2` compatible colors are allowed (see also `plot_EPR_Specs`), default: `line.color = "red"`, should be different from `line.color.sim`.
`line.color.sim`	Character string, line color to plot simple EPR spectrum. All `ggplot2` compatible colors are allowed, default: `line.color = "blue"`, should be different from `line.color.expr`.
`line.width`	Numeric, linewidth of the plot line in `mm`, default: `line.width = 0.75`.
`output.df`	Logical, whether the data frame, corresponding to graphic spectra comparison (this actually corresponds to merging of the above-mentioned data frames by `dplyr::bind_cols`) should be returned as well (`output.df = TRUE`). In such case, the output is `list` containing plot (`list$plot`) as well as the data frame (`list$df`). However, the default is `output.df = FALSE`, i.e. only graphical representation is shown.

Value

Plot object (list) of the experimental and the simulated EPR (in derivative or integrated form) spectrum or list consisting of plot and the corresponding data frame df. Any output plot corresponds to simple ggplot2 object and can be combined with a desired theme (e.g. with plot_theme_NoY_ticks, see also Examples).

Examples

## load package built-in EPR spectral
## data example:
data.file.path <-
  load_data_example(file =
    "TMPD_specelchem_accu_b.asc")
data.spectrum.expr <-
  readEPR_Exp_Specs(path_to_ASC =
             data.file.path,
    col.names = c("B_G",
    "dIepr_over_dB"),
    qValue = 3500,
    origin = "winepr"
   )
#
## instrumental parameters for the spectrum,
## by the `WinEPR` spectrometer software
tmpd.params.file <-
  load_data_example(file =
    "TMPD_specelchem_accu_b.par")
#
## simulation of the TMPD radical cation
## EPR spectrum
data.spectrum.sim <-
  eval_sim_EPR_iso(g.iso = 2.00303,
    instrum.params = NULL,
    path_to_dsc_par = tmpd.params.file,
    origin = "winepr",
    nuclear.system = list(
      list("14N", 2, 19.29),
      list("1H", 4, 5.49),
      list("1H", 12, 19.66)
    ),
  lineGL.DeltaB = list(0.48, 0.32),
  lineG.content = 0.5,
)
#
## comparison of both spectra
## by the simulated spectrum offset
present_EPR_Sim_Spec(
  data.spectr.expr = data.spectrum.expr,
  data.spectr.sim = data.spectrum.sim$df
) + plot_theme_NoY_ticks(legend.text =
           ggplot2::element_text(size = 13)
           )
#
## comparison of both spectra
## in overlay mode
present_EPR_Sim_Spec(
  data.spectr.expr = data.spectrum.expr,
  data.spectr.sim = data.spectrum.sim$df,
  Intensity.shift.ratio = NULL,
) + plot_theme_NoY_ticks(legend.text =
           ggplot2::element_text(size = 13)
           )


## load package built-in EPR spectral
## data example:
data.file.path <-
  load_data_example(file =
    "TMPD_specelchem_accu_b.asc")
data.spectrum.expr <-
  readEPR_Exp_Specs(path_to_ASC =
             data.file.path,
    col.names = c("B_G",
    "dIepr_over_dB"),
    qValue = 3500,
    origin = "winepr"
   )
#
## instrumental parameters for the spectrum,
## by the `WinEPR` spectrometer software
tmpd.params.file <-
  load_data_example(file =
    "TMPD_specelchem_accu_b.par")
#
## simulation of the TMPD radical cation
## EPR spectrum
data.spectrum.sim <-
  eval_sim_EPR_iso(g.iso = 2.00303,
    instrum.params = NULL,
    path_to_dsc_par = tmpd.params.file,
    origin = "winepr",
    nuclear.system = list(
      list("14N", 2, 19.29),
      list("1H", 4, 5.49),
      list("1H", 12, 19.66)
    ),
  lineGL.DeltaB = list(0.48, 0.32),
  lineG.content = 0.5,
)
#
## comparison of both spectra
## by the simulated spectrum offset
present_EPR_Sim_Spec(
  data.spectr.expr = data.spectrum.expr,
  data.spectr.sim = data.spectrum.sim$df
) + plot_theme_NoY_ticks(legend.text =
           ggplot2::element_text(size = 13)
           )
#
## comparison of both spectra
## in overlay mode
present_EPR_Sim_Spec(
  data.spectr.expr = data.spectrum.expr,
  data.spectr.sim = data.spectrum.sim$df,
  Intensity.shift.ratio = NULL,
) + plot_theme_NoY_ticks(legend.text =
           ggplot2::element_text(size = 13)
           )

Absolute Quantification of Radicals/Spins

Description

Estimate the number (or concentration) of "spins"/radicals/paramagnetic species using the absolute quantitative method by sigmoid integral as well as by the instrumental parameters without the need for a standard sample with known concentration/amount of radicals/"spins". The calculation assumes that the sample height middle point, within an EPR tube, matches the cavity/resonator center.

Usage

quantify_EPR_Abs(
  integ.sigmoid.max,
  instrum.params = NULL,
  path_to_dsc_par,
  origin = "xenon",
  qValue = NULL,
  tube.sample.id.mm,
  point.sample.factor = 8.51e-09,
  fill.sample.h.mm,
  eff.cavity.h.mm = 23,
  fn.B1.Bm.fit.y = c(1.00179, -0.00307086, -0.0265409, 0.000297603, 0.000223277,
    -4.53833e-06, -4.1451e-07, 1.89417e-08, -1.48241e-09),
  fn.B1.Bm.fit.y.max = 0.28,
  Norm.const = NULL,
  Temp.K = NULL,
  S = 0.5
)
quantify_EPR_Abs(
  integ.sigmoid.max,
  instrum.params = NULL,
  path_to_dsc_par,
  origin = "xenon",
  qValue = NULL,
  tube.sample.id.mm,
  point.sample.factor = 8.51e-09,
  fill.sample.h.mm,
  eff.cavity.h.mm = 23,
  fn.B1.Bm.fit.y = c(1.00179, -0.00307086, -0.0265409, 0.000297603, 0.000223277,
    -4.53833e-06, -4.1451e-07, 1.89417e-08, -1.48241e-09),
  fn.B1.Bm.fit.y.max = 0.28,
  Norm.const = NULL,
  Temp.K = NULL,
  S = 0.5
)

Arguments

integ.sigmoid.max

Numeric value or vector of the entire EPR spectrum sigmoid integral.

instrum.params

Named numeric vector, containing instrumental parameters required for the quantification =>

`PmW`	power of the MW source in mW
`BmmT`	modulation amplitude (magnetic flux density modulation, $B_{\text{m}}$ ) in mT
`TK`	temperature in K
`mwGHz`	applied microwave frequency in `GHz` to record the continuous wave (CW) EPR spectrum

Default: instrum.params = NULL because they are primarily extracted from the path_to_dsc_par based on the origin.

path_to_dsc_par

Character string, path (can be also acquired by the file.path) to .DSC/.dsc or .par (depending on the OS, see the origin argument) text files including all instrumental parameters from the EPR machine. If the instrum.params is already defined, the path_to_dsc_par = NULL. Otherwise, BOTH the path_to_dsc_par AS WELL AS the origin MUST BE SPECIFIED !

origin

Character string, corresponding to software which was used to obtain the EPR spectra on spectrometers, because the files are slightly different, whether they were recorded by the "WinEpr" (origin = "winepr") or by the "Xenon" (default). If origin = NULL as well as path_to_dsc_par = NULL, the instrum.params have to be set.

qValue

Numeric value of the sensitivity Q factor. For the processed EPR spectra by the {eprscope} package the integ.sigmoid.max is usually normalized by the Q value. Therefore, default: qValue = NULL (corresponding to 1).

tube.sample.id.mm

Numeric value, which equals to internal diameter (in mm) of the tube/cell used for the quantitative EPR experiment.

point.sample.factor

Numeric value, corresponding to point sample correction factor, provided by the cavity/probehead manufacturer. Value for the standard Bruker rectangular cavity is set as default.

fill.sample.h.mm

Numeric value, referring to sample height (in mm) within the tube/cell.

eff.cavity.h.mm

Numeric value, which equals to effective cavity/probehead height/length, usually provided by the probehead manufacturer.

fn.B1.Bm.fit.y

Numeric vector (coefficients) of the polynomial degree from 5 to 12. Coefficients for the standard Bruker rectangular cavity are set as default.

fn.B1.Bm.fit.y.max

Numeric value, corresponding to maximum value of the polynomial fit. Value for the standard Bruker rectangular cavity is set as default.

Norm.const

Numeric value, corresponding to normalization constant (see quantify_EPR_Norm_const). Default: Norm.const = NULL in case if the EPR spectrum was normalized by such constant either during the measurement or processing. Otherwise it must be provided by the quantify_EPR_Norm_const.

Temp.K

Numeric value, temperature value in K. Because the instrum.params also contains temperature input one may choose which definition (Temp.K or TK) is taken for the calculation. Either Temp.K or TK CAN BE ALSO NULL but NOT BOTH !! In the latter case, default value 298 K is considered.

S

Numeric value, total spin sample quantum number. For radicals S = 0.5 (default).

Details

There are two approaches how to quantify the number of paramagnetic species/radicals/spins. The relative one needs a standard sample with a known spin number and can be evaluated by the sigmoid integral ratio of the sample under study and that of the standard. While the absolute method do not need the reference sample, it requires a precise cavity signal calibration as well as standardized cell geometry. Both are provided by the EPR instrument and lab-glass manufacturers (see e.g. Hirschmann-Laborgeräte (2023), References). In case of absolute quantitative EPR analysis the sigmoid integral (its maximum value), $I_{\text{sigmoid}}$ ,can be used to calculate the number of "spins"/radicals/paramagnetic species, $N_{\text{Spins}}$ (see also References) =>

$N_{\text{Spins}} = I_{\text{sigmoid}}\,/\,[(c/f(B_1,B_{\text{m}}))\,(G_{\text{R}}\,t_{\text{C}} \,N_{\text{Scans}})\,(\sqrt{P_{\text{MW}}}\,B_{\text{m}}\,Q\,n_{\text{B}}\,S(S+1))]$

where the quantity notations possess the following meaning (parentheses denote whether it is an instrumental or sample dependent parameter):

Quantity Symbol	Meaning/Short Desription
$c$	Point sample calibration factor (instrumental).
$f(B_1,B_\text{m})$	Spatial distribution of the microwave $B_1$ and modulation amplitude within the cavity/probehead/resonator (instrumental).
$G_{\text{R}}$	Receiver gain (commonly in $\text{dB}$ units (instrumental)).
$t_{\text{C}}$	Conversion time (commonly in $\text{ms}$ ) which is an analogy to integration time in other spectroscopies (instrumental).
$N_{\text{Scans}}$	Number of scans/accumulations during the experiment (instrumental).
$P_{\text{MW}}$	Microwave power (instrumental).
$B_{\text{m}}$	Modulation amplitude (instrumental).
$Q$	Q-Value or Q-Factor characterizing the resonator/cavity/probehead sensitivity (unitless and instrumental).
$n_{\text{B}}$	Boltzmann factor for temperature dependence (instrumental-sample).
$S$	Total electronic spin quantum number (sample). Commonly, for radicals $S = 1/2$ .

Almost all summarized quantities are instrument-dependent. Most of them correspond to the essential parameters for the experiment and can be easily acquired from the .DSC/.dsc/.par file(s). The Boltzmann factor describes the population of spin states by $\exp{(\Delta \varepsilon)\,/\,(k_{\text{B}}\,T)}$ , where $\Delta \varepsilon$ denotes the energy difference between the basic spin states, $k_{\text{B}}$ is the Boltzmann constant (available from syms) and the $T$ represents the temperature in $\text{K}$ . For temperatures $\geq 4\,\text{K}$ and continuous wave experiments where the $\Delta \varepsilon = h\,\nu_{\text{MW}}^{}$ is constant, this factor may be very well estimated by the following formula:

$n_{\text{B}} = h\,\nu_{\text{MW}}^{}\,/\,(2\,k_{\text{B}}\,T)$

The term $(G_{\text{R}}\,t_{\text{C}}\,N_{\text{Scans}})$ actually corresponds to normalization constant which is available from quantify_EPR_Norm_const. Besides the above-described parameters which can be easily estimated, there are however characteristics that requires precise calibration and usually are provided by the spectrometer manufacturers. The spatial distribution of the microwave, $B_1$ , and modulation amplitude, $B_\text{m}$ , influences the intensity of the sample predominantly along the $y$ -axis direction (i.e. when moving the sample tube up or down within the cavity). Such intensity distribution, depending on the cavity/probehead for different sample length and positions, can be approximated by a polynomial (see the fn.B1.Bm.fit.y argument) that is supplied by the manufacturer as well (the coefficients of the polynomial can be sometimes found in .DSC/.dsc/.par file(s)). For quantitative purposes, such polynomial is integrated over the length of the sample.

Value

List of the following quantities:

N.cm: Number of spins per effective centimeter. It is defined as the cm around the maximum, $\pm 5\,\text{mm}$ , of the intensity distribution curve/polynomial fit within the cavity $f(B_1,B_{\text{m}})$ from the equation shown in Details.
N.cm3: Number of spins per $\text{cm}^3$ .
c.M: Concentration of spins/radicals in $\text{mol}\,\text{dm}^{-3}$ .

References

Eaton GR, Eaton SS, Barr DP, Weber RT (2010). Quantitative EPR. Springer Science and Business Media. ISBN 978-3-211-92947-6, https://link.springer.com/book/10.1007/978-3-211-92948-3.

Weber RT (2011). Xenon User's Guide. Bruker BioSpin Manual Version 1.3, Software Version 1.1b50.

Hirschmann-Laborgeräte (2023). “Ringcaps.” https://hirschmannlab.de/en/produkt/ringcaps/.

Mazúr M, Valko M, Morris H (2000). “Analysis of the Radial and Longitudinal Effect in a Double TE104 and a Single TE102 Rectangular Cavity.” J. Magn. Reson., 142(1), 37–56. ISSN 1090-7807, https://doi.org/10.1006/jmre.1999.1915.

Portis AM (1953). “Electronic Structure ofF Centers: Saturation of the Electron Spin Resonance.” Phys. Rev., 91(5), 1071–1078, https://doi.org/10.1103/PhysRev.91.1071.

Mailer C, Sarna T, Swartz HM, Hyde JS (1977). “Quantitative Studies of Free Radicals in Biology: Corrections to ESR Saturation Data.” J. Magn. Reson. (1969), 25(1), 205–210, ISSN 0022-2364, https://doi.org/10.1016/0022-2364(77)90133-0.

Examples

## Not run: 
## quantitative analysis (determining the
## radical concentration `c.M`) of a sample measured
## at different temperatures
## all data summarized in `data.tidy.integ`
data.quant <- mapply(function(x,y)
  {quantify_EPR_Abs(x,
    instrum.params = c(PmW = 2.518,
                       BmmT = 5.4e-02,
                       TK = NULL, ## 298 K
                       mwGHz = 9.530265),
    path_to_dsc_par = NULL,
    origin = NULL,
    tube.sample.id.mm = 2.86,
    fill.sample.h.mm = 23,
    Temp.K = y)$c.M
    },
  data.tidy.integ$Area,
  data.tidy.integ$Temperature_K
  )

## End(Not run)


## Not run: 
## quantitative analysis (determining the
## radical concentration `c.M`) of a sample measured
## at different temperatures
## all data summarized in `data.tidy.integ`
data.quant <- mapply(function(x,y)
  {quantify_EPR_Abs(x,
    instrum.params = c(PmW = 2.518,
                       BmmT = 5.4e-02,
                       TK = NULL, ## 298 K
                       mwGHz = 9.530265),
    path_to_dsc_par = NULL,
    origin = NULL,
    tube.sample.id.mm = 2.86,
    fill.sample.h.mm = 23,
    Temp.K = y)$c.M
    },
  data.tidy.integ$Area,
  data.tidy.integ$Temperature_K
  )

## End(Not run)

Normalization Constant Calculation for Quantitative EPR Analysis

Description

Normalization constant used by quantify_EPR_Abs or to normalize the EPR spectrum intensity. Calculation depends on the receiver gain expression.

Usage

quantify_EPR_Norm_const(
  conv.time.ms,
  Nscans,
  Npoints = NULL,
  Bsw = NULL,
  rg,
  rg.unit = "dB"
)
quantify_EPR_Norm_const(
  conv.time.ms,
  Nscans,
  Npoints = NULL,
  Bsw = NULL,
  rg,
  rg.unit = "dB"
)

Arguments

`conv.time.ms`	Numeric, conversion time in milliseconds.
`Nscans`	Numeric, number of scans.
`Npoints`	Numeric, number of points (resolution) corresponding to individual sweep, if `rg.unit = "unitless"` (`rg.unit = "Unitless"`). Default: `Npoints = NULL`.
`Bsw`	Numeric, experimental sweep width (magnetic flux density recording region, $B_{\text{SW}}$ ) in "G" if `rg.unit = "unitless"` (`rg.unit = "Unitless"`). Default: `Bsw = NULL`.
`rg`	Numeric, receiver gain value.
`rg.unit`	Character string corresponding to unit of the receiver gain. Either `rg.unit = "db"` (`rg.unit = "dB"`, default) or `rg.unit = "unitless"` (`rg.unit = "Unitless"`).

Details

For the receiver gain expressed in $\text{dB}$ units the normalization constant is defined by the following relation =>

$N_{\text{norm}} = t_{\text{C}}(\text{ms})\,N_{\text{Scans}}\,(20)\, 10^{(G_{\text{R}}(\text{dB})/20)}$

where $t_{\text{C}}(\text{ms})$ depicts the conversion time in $\text{ms}$ ; $N_{\text{Scans}}$ corresponds to number of scans and $G_{\text{R}}(\text{dB})$ is the receiver gain in $\text{dB}$ . In the case that the receiver gain is unitless, the normalization constant is defined by =>

$N_{\text{norm}} = t_{\text{C}}(\text{ms})\,G_{\text{R}}\, (N_{\text{points}} - 1)\,N_{\text{scans}}\,/\,B_{\text{SW}}(\text{G})$

where $G_{\text{R}}$ and $B_{\text{SW}}(\text{G})$ correspond to unitless receiver gain and sweep width in Gauss, respectively. $N_{\text{points}}$ equals to the number of points (resolution of an individual sweep). One can gather all parameters by the readEPR_param_slct or by the readEPR_params_tabs function from the corresponding .DSC/.dsc or .par file. If during recording of EPR spectra the option Normalize Acquisition (in Spectrometer Configuration/Acquisition Options) is activated, THE INTENSITY is ALREADY NORMALIZED and DOESN'T REQUIRE ANY ADDITIONAL NORMALIZATION !. Please, refer also to the quantify_EPR_Abs function.

Value

Numeric value of the normalization constant for quantitative EPR and intensity normalization.

References

Weber RT (2011). Xenon User's Guide. Bruker BioSpin Manual Version 1.3, Software Version 1.1b50.

Bruker Biospin (2007). WIN-EPR User's Manual.

Examples

quantify_EPR_Norm_const(conv.time.ms = 8.2,
                        Nscans = 10,
                        rg = 32)
#
quantify_EPR_Norm_const(conv.time.ms = 13.1,
                        Bsw = 180,
                        Nscans = 10,
                        Npoints  = 1024,
                        rg = 3.2e+4,
                        rg.unit = "Unitless")


quantify_EPR_Norm_const(conv.time.ms = 8.2,
                        Nscans = 10,
                        rg = 32)
#
quantify_EPR_Norm_const(conv.time.ms = 13.1,
                        Bsw = 180,
                        Nscans = 10,
                        Npoints  = 1024,
                        rg = 3.2e+4,
                        rg.unit = "Unitless")

Quantify (Components) Areas of Series of Simulated EPR Spectra

Description

Evaluating the linear combination of spectral intensities of components (loaded as ASCII text files corresponding to simulated spectra). The related intensity multiplication coefficients (please, refer to the optim.params.init argument) are optimized by methods gathered in the optim_for_EPR_fitness. The goal is to fit the sum of the simulated components onto each experimental spectrum within series. So far, the maximum number of components is set to 6.

Usage

quantify_EPR_Sim_series(
  data.spectra.series,
  dir_ASC_sim,
  name.pattern.sim,
  sim.origin = "easyspin",
  var2nd.series = "time_s",
  B.unit = "G",
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  optim.method = "sbplx",
  optim.params.init,
  optim.params.lower = NULL,
  optim.params.upper = NULL,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  single.integ = "single_IntegSim",
  double.integ = "double_IntegSim",
  output.area.stat = TRUE,
  ...
)
quantify_EPR_Sim_series(
  data.spectra.series,
  dir_ASC_sim,
  name.pattern.sim,
  sim.origin = "easyspin",
  var2nd.series = "time_s",
  B.unit = "G",
  Intensity.expr = "dIepr_over_dB",
  Intensity.sim = "dIeprSim_over_dB",
  optim.method = "sbplx",
  optim.params.init,
  optim.params.lower = NULL,
  optim.params.upper = NULL,
  Nmax.evals = 512,
  tol.step = 5e-07,
  pswarm.size = NULL,
  pswarm.diameter = NULL,
  pswarm.type = NULL,
  single.integ = "single_IntegSim",
  double.integ = "double_IntegSim",
  output.area.stat = TRUE,
  ...
)

Arguments

`data.spectra.series`	Spectrum data frame/table object containing magnetic flux density as `x` variable. They can be labeled as `Field`, `B_mT` in mT (or `B_G` in gauss). The `y/Intensity` variable can be labeled as `dIepr_over_dB`, in case of derivative intensity, or if integrated spectral intensities are present, they can be labeled accordingly. See also `Intensity.expr` parameter/argument. A second independent variable `var2nd.series` column (e.g. `var2nd.series = "time_s"`) must be available. In such case, the entire `data.spectra` must be present in the form of tidy/long table format (see also the parameter/argument `var2nd.series`). Such data frame can be created, e.g. by the `readEPR_Exp_Specs_kin` or the `readEPR_Exp_Specs_multif` function.
`dir_ASC_sim`	Character string, pointing to folder where the simulated EPR spectra (data files) of all components are stored. Path can be alternatively specified by the `file.path` function.
`name.pattern.sim`	Character string pattern from file names related to simulated EPR spectral data like `name.pattern.sim = "DHMB0_1st_04_SimA"` or `name.pattern.sim = "DHMB0_1st_04_Sim[[:upper:]]"` (for the file names `..._SimA`, `..._SimB`,...etc). It assumes, those files must have similar names and this pattern appears at the beginning of the file name. One may also consult how to use regular expressions in R.
`sim.origin`	Character string, referring to "origin" of the simulated ASCII data. There are four possibilities $\Rightarrow$ `sim.orimgin = "easyspin"` (default), `"xenon"`, `"simfonia"` as well as universal `"csv"`.
`var2nd.series`	Character string referred to name of the second independent variable/quantity column in the original `data.spectra.series` (such as time, temperature, electrochemical potential, Microwave Power) altered during individual experiments as a second variable. Data must be available in tidy/long table format. Default: `var2nd.series = "time_s"`.
`B.unit`	Character string, pointing to unit of magnetic flux density like `"G"` (Gauss) or `"mT"` (millitesla), default: `B.unit = "G"`. THE UNIT MUST BE SHARED ACROSS ALL RELEVANT B-ARGUMENTS/DATAFRAMES.
`Intensity.expr`	Character string, pointing to column name of the experimental EPR intensity within the original `data.spectra.series`. Default: `dIepr_over_dB`.
`Intensity.sim`	Character string pointing to column name of the simulated EPR intensity within the related data frames (check the simulated spectral data for all components). Default: `Intensity.sim = "dIeprSim_over_dB"`.
`optim.method`	Character string, pointing to applied optimization method/algorithm. One may choose one from those listed in `optim_for_EPR_fitness`, default: `method = "sbplx"`, setting up the "Subplex" method.
`optim.params.init`	Numeric vector with the elements: baseline constant/intercept followed by simulated intensity multiplication coefficient for each EPR spectral component. Therefore, the length of this vector is equal to number of components + 1.
`optim.params.lower`	Numeric vector with the length of `optim.params.init` and the lower bound constraints. Default: `optim.params.init = NULL`, actually corresponding to vector with all `0` value elements.
`optim.params.upper`	Numeric vector with the length of `optim.params.init`) and the upper bound constraints. Default: `optim.params.init = NULL`, actually corresponding to vector with all `0.9` value elements.
`Nmax.evals`	Numeric value, maximum number of function evaluations and/or iterations. The only one method, limited by this argument, is `nls.lm`, where `Nmax.evals = 1024`. Higher `Nmax.evals` may extremely extend the optimization time, therefore the default value reads `Nmax.evals = 512`. However, the `"pswarm"` method requires at least the default or even higher values.
`tol.step`	Numeric, the smallest optimization step (relative change) between 2 iterations to stop the optimization procedure. For the `optim.method = "pswarm"` (particle swarm optimization procedure) it actually corresponds to tolerance for restarting. Once the maximum distance between the "best" particle and all the others is less than `tol.step` * `pswarm.diameter`) the algorithm restarts. See also `psoptim`. Default: `tol.step = 5e-7`.
`pswarm.size`	Numeric value equal to particle swarm size (i.e. number of particles), if `optim.method = "pswarm"`. The default value (`pswarm.size = NULL`) actually corresponds to `floor(10+2*sqrt(length(optim.params.init)))` (for `SPSO2007`, see the `pswarm.type` argument), e.g. to optimize 3 components, number of particles = 14. For the `SPSO2011` the default number of particles equals to `40`.
`pswarm.diameter`	Numeric value, corresponding to diameter of the particle swarm search space (in case when `optim.method = "pswarm"`). The default value (`pswarm.diameter = NULL`) refers to the Euclidean distance, defined as: $\sqrt{\sum_k\,(\text{optim.params.upper}[k] - \text{optim.params.lower}[k])^2}$
`pswarm.type`	Character string, setting the type/version of particle swarm algorithm if `method = "pswarm"`. There are two types available: `pswarm.type = "SPSO2007"` and `pswarm.type = "SPSO2011"`. The latter introduced an adaptive random topology, which allows the swarm to dynamically adjust its communication structure. This helps in maintaining diversity in the swarm and improves the algorithm's ability to escape local optima. This type generally offers better performance on larger multidimensional spaces than the `pswarm.type = "SPSO2007"`, which uses a more static topology. Details may be found in the `References` of the `optim_for_EPR_fitness`. Default: `pswarm.type = NULL` (actually corresponding to `"SPSO2007"`, that performs slightly better on smaller scales such as simulations of EPR spectra).
`single.integ`	Character string, setting up the column/variable name related to single-integrated spectrum within the output data frame, default: `single.integ = "single_IntegSim"`.
`double.integ`	Character string, setting up the column/variable name related to double-integrated spectrum within the output data frame, default: `double.integ = "double_IntegSim"`. If `double.integ = NULL`, only single integrals are calculated/returned (e.g. in the case of single integrated spectral data).
`output.area.stat`	Logical, whether to summarize all fitted EPR spectral components, in columns, for each time/temperature/...etc. point in row. Additional optimization measures are presented as well (see `Details`).Default: `output.area.stat = TRUE`.
`...`	additional arguments specified (see also `optim_for_EPR_fitness`).

Details

Analyzed EPR spectra may consists of several components (see also the eval_sim_EPR_iso_combo function), like the overlapped EPR spectra of several radicals. In order to follow the concentration/amount variations of each individual radical during the kinetic/temperature/...series, one must figure out, how those individual spectral components are actually changed. In the first approximation, it means to follow the corresponding EPR intensities/integrals, whereas the component positions ( $g$ -values) are assumed to be fixed (or those changes can be neglected). Therefore, the actual function takes the linear combination of the spectral intensities of components (simulated spectra) and optimizes the related multiplication coefficients. Additional analysis, where the positions of spectral components (simulated spectra) are not fixed and can be optimized as well is under development.

Value

Function provides data frame object, depending on the output.area.stat argument, as listed below:

If output.area.stat = TRUE (default), the resulting data frame consists of columns/variables like integrals/areas for each simulated and fitted EPR spectrum, where the components are denoted by the uppercase letters (Area_Sim_A, Area_Sim_B,...etc.); best fitted/optimized coefficients to multiply the intensities (Optim_CoeffInt_Sim_A, Optim_CoeffInt_Sim_B,...etc); best fitted/optimized intercept (or baseline constant, Optim_intercept); minimum sum of residual squares (min_RSS); number of evaluations/iterations (N_evals) and finally convergence information/number (N_converg, like already described in the optim_for_EPR_fitness). These variables are presented for each var2nd.series (e.g. time) point like example for one EPR spectral component:

time_s	Area_Sim_A	Optim_CoeffInt_Sim_A	Optim_intercept	min_RSS	N_evals	N_converg
6	0.020624473	0.052843937	5.508809e-10	2.289953e-07	198	4
21	0.020217930	0.051802287	5.401823e-10	2.438172e-07	177	4
36	0.018836579	0.048263010	5.029705e-10	2.662651e-07	201	4

Tidy/long table format of the original data.spectra.series with additional columns/variables (best fitted simulated intensities) for all spectral components: A, B, C, ...etc.

Examples

## Not run: 
## example with default arguments corresponding
## to one simulated spectral component,
## `optim.params.init` has the length
## of => number of components + 1,
## because of included intercept/baseline constant
quant.data.sim.test.a <-
  quantify_EPR_Sim_series(data.spectra.series,
     dir_ASC_sim = "./",
     optim.method = "pswarm",
     name.pattern.sim = "DHMB0_1st_04_SimA",
     optim.params.init = c(0,0.8),
     output.area.stat = TRUE)
#
## similar example with two components
## (simulated spectra) and tidy data frame
## output (not the summarized one)
quant.data.sim.test.b <-
  quantify_EPR_Sim_series(data.spectra.series,
     dir_ASC_sim = "./",
     optim.method = "sbplx",
     name.pattern.sim = "DHMB0_1st_04_Sim[[:upper:]]",
     optim.params.init = c(0,0.8,0.2),
     output.area.stat = FALSE)
#

## End(Not run)


## Not run: 
## example with default arguments corresponding
## to one simulated spectral component,
## `optim.params.init` has the length
## of => number of components + 1,
## because of included intercept/baseline constant
quant.data.sim.test.a <-
  quantify_EPR_Sim_series(data.spectra.series,
     dir_ASC_sim = "./",
     optim.method = "pswarm",
     name.pattern.sim = "DHMB0_1st_04_SimA",
     optim.params.init = c(0,0.8),
     output.area.stat = TRUE)
#
## similar example with two components
## (simulated spectra) and tidy data frame
## output (not the summarized one)
quant.data.sim.test.b <-
  quantify_EPR_Sim_series(data.spectra.series,
     dir_ASC_sim = "./",
     optim.method = "sbplx",
     name.pattern.sim = "DHMB0_1st_04_Sim[[:upper:]]",
     optim.params.init = c(0,0.8,0.2),
     output.area.stat = FALSE)
#

## End(Not run)

Read the Experimental ASCII or other Text-Based EPR Data.

Description

This function is based on the fread with the purpose to read the experimental EPR/ENDOR spectra or other original (pre-processed) data, from the EPR spectrometers, in tabular ASCII format (such as .txt, .csv or .asc). Default argument values correspond to data reading from Xenon files (see the argument origin).

Usage

readEPR_Exp_Specs(
  path_to_ASC,
  sep = "auto",
  skip = 1,
  header = FALSE,
  col.names = c("index", "B_G", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 3,
  time.series.id = NULL,
  convertB.unit = TRUE,
  qValue = NULL,
  norm.vec.add = NULL,
  origin = "xenon",
  data.structure = "spectra",
  ...
)
readEPR_Exp_Specs(
  path_to_ASC,
  sep = "auto",
  skip = 1,
  header = FALSE,
  col.names = c("index", "B_G", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 3,
  time.series.id = NULL,
  convertB.unit = TRUE,
  qValue = NULL,
  norm.vec.add = NULL,
  origin = "xenon",
  data.structure = "spectra",
  ...
)

Arguments

path_to_ASC

Character string, path to ASCII file/table (e.g. in .txt, .csv or .asc format) with the spectral data ( $Intensity$ vs $B$ , Field) including additional index and/or time variables). The path can be also defined by the file.path function.

sep

The separator between columns. Defaults to the character in the set [,\t |;:] that separates the sample of rows into the most number of lines with the same number of fields. Use NULL or "" to specify no separator; i.e. each line a single character column like base::readLines does.

skip

If 0 (default) start on the first line and from there finds the first row with a consistent number of columns. This automatically avoids irregular header information before the column names row. skip>0 means ignore the first skip rows manually. skip="string" searches for "string" in the file (e.g. a substring of the column names row) and starts on that line (inspired by read.xls in package gdata).

Does the first data line contain column names? Defaults according to whether every non-empty field on the first data line is type character. If so, or TRUE is supplied, any empty column names are given a default name.

col.names

Character string vector, inherited from the fread, corresponding to column/variable names. A safe rule of thumb is to use column names incl. physical quantity notation with its unit, Quantity_Unit like "B_G", "RF_MHz", "Bsim_mT" (e.g. pointing to simulated EPR spectrum $x$ -axis)...etc, default: col.names = c("index","B_G",dIepr_over_dB). For spectral time series col.names must include "T(t)ime" or "S(s)lice" character string in order to identify the corresponding time column/variable in the original ASCII file. The default (for the original fread) is to use the header column if present or detected. If not, the name is denoted as "V" followed by the column number.

x.id

Numeric index related to col.names vector pointing to independent variable, which corresponds to $x$ -axis in the spectra or other plots. Default: x.id = 2 (for Xenon).

x.unit

Character string, corresponding to original x variable/column unit, such as "G", "mT" or "MHz".

Intensity.id

Numeric index related to col.names vector, pointing to general intensity, like derivative intensity (dIepr_over_dB), integral one (e.g. single_Integ), double or sigmoid integral (e.g. Area)...etc. This corresponds to column/vector which should be presented like $y$ -axis in the EPR spectra or other plots. Default: Intensity.id = 3 (for Xenon).

time.series.id

Numeric index related to col.names vector and pointing to time column for time series EPR spectra. If data contains simple relation like $Area$ vs $time$ , use the x and x.unit parameters/arguments instead (see also Examples). This argument is dedicated to kinetic-like experiments. Default: time.series.id = NULL (see also the data.structure argument).

convertB.unit

Logical (default: convertB.unit = TRUE), whether upon reading, an automatic conversion between G and mT should be performed. If default is chosen, a new column/variable $B$ in mT/G is created.

qValue

Numeric, Q value (quality factor, number) displayed at specific dB by the spectrometer, in case of Xenon or new Magnettech software the parameter is included in .DSC/.dsc file, default: qValue = NULL, which actually corresponds to value 1.

norm.vec.add

Numeric vector. Additional normalization constant in the form of vector, including all (in addition to qValue) normalization(s) like concentration, powder sample weight, number of scans, ...etc. (e.g. norm.vec.add = c(2000,0.5,2)). Default: norm.vec.add = NULL, which actually corresponds to value 1. If qValue = NULL, the Q-factor/value might be also included in the norm.vec.add.

origin

Character string, corresponding to origin of the ASCII data, like from the most common spectrometers (from which the data are loaded automatically using the default parameters). Options are summarized in the following table (any other specific origin may be added later) =>

String	Description
"xenon"	default automatically loads data from the "Xenon" software with the default parameters.
"winepr"	automatically loads data from the "WinEpr" software.
"magnettech"	automatically loads data from the new "Magnettech" software (ESR5000 [11-0422]).
"other" (arbitrary string, e.g. "csv")	general, loads any other original data like `csv`, `txt`, `asc` incl. also data from other instrumental/spectrometer software. In such case, all the arguments for `readEPR_Exp_Specs` have to be set up accordingly.

data.structure

Character string, referring to structure of the ASCII data. Common spectral data files with $Intensity$ vs. $x(B,g,RF(\text{MHz}))$ and/or $time$ columns (including the spectral time series) correspond to data.structure = "spectra" (default). For more complex ASCII data structure (such as spectral series processed by the acquisition spectrometer software, see Examples, or any other data) put data.structure = "others". In such case, all the arguments for the readEPR_Exp_Specs have to be set up accordingly. The data.structure argument (assuming time.series.id = NULL) is helping to simplify the reading of "spectra" by the predefined origin argument.

...

additional arguments specified (see also the fread function).

Details

ASCII data are transformed into R data frames, which can be then easily processed by the actual or other R packages, e.g. dplyr), afterwards. Spectral intensities are automatically normalized by the common experimental parameters like Q-factor, concentration, weight...etc. These are defined by the two arguments: qValue and norm.vec.add. The latter actually corresponds to values of the above-mentioned quantities represented by the vector. If qValue = NULL (actually corresponding to 1), the Q-value can be also defined as a component of the norm.vec.add. Finally, the normalized intensity is calculated by the following expression (depending on the qValue and/or norm.vec.add):

$dI_{EPR} / dB = Original~Intensity \, (1/qValue)$

$dI_{EPR} / dB = Original~Intensity \, (1/qValue) \, \prod_{k} 1/(norm.vec.add[k])$

where $k$ is iterating through all components of the norm.vec.add. The structure of ASCII files/tables depends on the origin/software used to acquire the EPR spectra. This is mirrored mainly by the origin and data.structure arguments. Default arguments are set to read the data from Xenon acquisition/processing software. However, additional origins can be set like origin = "winepr" or origin = "magnettech" or even any arbitrary string e.g. origin = "csv" (see also the origin argument). For the latter, all arguments must be set accordingly, as already demonstrated in Examples. Time series (time evolution of EPR spectra/kinetics) is defined by the time.series.id argument. In such case the ASCII data table also contains additional column either with recorded time (see also correct_time_Exp_Specs) or with slice number for each spectrum.

Value

Data frame/table consisting of the magnetic flux density column B_mT in millitesla (as well as B_G in gauss) or RF_MHz (in case of ENDOR spectrum) or unitless g-factor and of the derivative intensity column (dIepr_over_dB) or any other intensities (like integrated spectral form) in procedure defined unit (see p.d.u.), which is normalized by the above-described parameters and finally the index and/or a time (in the case of time series experiment) columns are displayed as well.

Examples

## simple EPR spectrum acquired by "xenon"
## and with `B` conversion "G" <=> "mT"
## Loading the data
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data.01 <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
## preview
head(aminoxyl.data.01)
#
# simple EPR spectrum acquired by "xenon"
## and without `B` conversion "G" <=> "mT"
aminoxyl.data.02 <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    convertB.unit = FALSE,
                    qValue = 2100)
## preview
head(aminoxyl.data.02)
#
## the simple spectrum acquired by "winepr"
## (and 20 scans) on a 1 mM sample concentration:
## Loading the data
TMPD.data.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
TMPD.data <-
  readEPR_Exp_Specs(TMPD.data.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = c(20,0.001),
                    origin = "winepr")
## preview
head(TMPD.data)
#
## the ENDOR spectrum recorded by "xenon"
## and 8 accumulation sweeps
## loading the data
PNT.ENDOR.data.path <-
  load_data_example(file = "PNT_ENDOR_a.txt")
PNT.ENDOR.data <-
  readEPR_Exp_Specs(PNT.ENDOR.data.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz",
                    norm.vec.add = 8)
## preview
head(PNT.ENDOR.data)
#
## reading the (pre-processed) data file
## (data.structure = "mixed") from (by) the "Xenon" software
## corresponding to kinetics with `Area` and `time`
## columns/variables , these two have to be selected
## from several others + normalize `Area`
## against the `qValue` (first of all load the path
## of package example file)
triarylamine.rc.decay.path <-
  load_data_example("Triarylamine_radCat_decay_a.txt")
## data
triarylamine.rc.decay.data <-
  readEPR_Exp_Specs(path_to_ASC = triarylamine.rc.decay.path,
                    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()
## preview
head(triarylamine.rc.decay.data)
#
## reading the "magnettech" file example,
## first of all load the package example file
acridineRad.data.path <-
  load_data_example("AcridineDeriv_Irrad_365nm.csv.zip")
## unzip
acridineRad.data <-
  unzip(acridineRad.data.path,
        files = c("AcridineDeriv_Irrad_365nm.csv"),
        exdir = tempdir())
## reading "magnettech"
acridineRad.data <-
  readEPR_Exp_Specs(acridineRad.data,
                    col.names = c("B_mT","dIepr_over_dB"),
                    x.unit = "mT",
                    origin = "magnettech")
## preview
head(acridineRad.data)
#
## Not run: 
## EPR time series acquired by "Winepr"/"WinEpr"
readEPR_Exp_Specs(path_to_ASC,
                  col.names = c("B_G",
                                "Slice",
                                "dIepr_over_dB"),
                  origin = "Winepr")
#
## example for "xenon" time series experiment
## (evolution of EPR spectra in time, e.g. in case of
## EPR spectroelectrochemistry or photochemistry):
## together with `B` conversion "G" <=> mT
## and intensity normalized against `qValue`
readEPR_Exp_Specs(path_to_ASC,
                  col.names = c("index",
                                "B_G",
                                "time_s",
                                "dIepr_over_dB"),
                  qValue = 2800)
#
## read `.csv` file which is an output from online
## converter:
## https://www.spectra.tools/bin/controller.pl?body=Xepr2gfac
readEPR_Exp_Specs("data.csv",
                  skip = 0,
                  col.names = c("B_G",
                                "g_Value",
                                "dIepr_over_dB"),
                  x.id = 1,
                  Intensity.id = 3,
                  origin = "csv")

## End(Not run)


## simple EPR spectrum acquired by "xenon"
## and with `B` conversion "G" <=> "mT"
## Loading the data
aminoxyl.data.path <-
  load_data_example(file = "Aminoxyl_radical_a.txt")
aminoxyl.data.01 <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    qValue = 2100)
## preview
head(aminoxyl.data.01)
#
# simple EPR spectrum acquired by "xenon"
## and without `B` conversion "G" <=> "mT"
aminoxyl.data.02 <-
  readEPR_Exp_Specs(aminoxyl.data.path,
                    convertB.unit = FALSE,
                    qValue = 2100)
## preview
head(aminoxyl.data.02)
#
## the simple spectrum acquired by "winepr"
## (and 20 scans) on a 1 mM sample concentration:
## Loading the data
TMPD.data.path <-
  load_data_example(file = "TMPD_specelchem_accu_b.asc")
TMPD.data <-
  readEPR_Exp_Specs(TMPD.data.path,
                    col.names = c("B_G","dIepr_over_dB"),
                    qValue = 3500,
                    norm.vec.add = c(20,0.001),
                    origin = "winepr")
## preview
head(TMPD.data)
#
## the ENDOR spectrum recorded by "xenon"
## and 8 accumulation sweeps
## loading the data
PNT.ENDOR.data.path <-
  load_data_example(file = "PNT_ENDOR_a.txt")
PNT.ENDOR.data <-
  readEPR_Exp_Specs(PNT.ENDOR.data.path,
                    col.names = c("index",
                                  "RF_MHz",
                                  "dIepr_over_dB"),
                    x.unit = "MHz",
                    norm.vec.add = 8)
## preview
head(PNT.ENDOR.data)
#
## reading the (pre-processed) data file
## (data.structure = "mixed") from (by) the "Xenon" software
## corresponding to kinetics with `Area` and `time`
## columns/variables , these two have to be selected
## from several others + normalize `Area`
## against the `qValue` (first of all load the path
## of package example file)
triarylamine.rc.decay.path <-
  load_data_example("Triarylamine_radCat_decay_a.txt")
## data
triarylamine.rc.decay.data <-
  readEPR_Exp_Specs(path_to_ASC = triarylamine.rc.decay.path,
                    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()
## preview
head(triarylamine.rc.decay.data)
#
## reading the "magnettech" file example,
## first of all load the package example file
acridineRad.data.path <-
  load_data_example("AcridineDeriv_Irrad_365nm.csv.zip")
## unzip
acridineRad.data <-
  unzip(acridineRad.data.path,
        files = c("AcridineDeriv_Irrad_365nm.csv"),
        exdir = tempdir())
## reading "magnettech"
acridineRad.data <-
  readEPR_Exp_Specs(acridineRad.data,
                    col.names = c("B_mT","dIepr_over_dB"),
                    x.unit = "mT",
                    origin = "magnettech")
## preview
head(acridineRad.data)
#
## Not run: 
## EPR time series acquired by "Winepr"/"WinEpr"
readEPR_Exp_Specs(path_to_ASC,
                  col.names = c("B_G",
                                "Slice",
                                "dIepr_over_dB"),
                  origin = "Winepr")
#
## example for "xenon" time series experiment
## (evolution of EPR spectra in time, e.g. in case of
## EPR spectroelectrochemistry or photochemistry):
## together with `B` conversion "G" <=> mT
## and intensity normalized against `qValue`
readEPR_Exp_Specs(path_to_ASC,
                  col.names = c("index",
                                "B_G",
                                "time_s",
                                "dIepr_over_dB"),
                  qValue = 2800)
#
## read `.csv` file which is an output from online
## converter:
## https://www.spectra.tools/bin/controller.pl?body=Xepr2gfac
readEPR_Exp_Specs("data.csv",
                  skip = 0,
                  col.names = c("B_G",
                                "g_Value",
                                "dIepr_over_dB"),
                  x.id = 1,
                  Intensity.id = 3,
                  origin = "csv")

## End(Not run)

Read and Process Spectral Data of Time Dependent CW EPR Experiments

Description

Reading the continuous wave (CW) EPR time series spectral data (recorded by e.g. 2D_Field_Delay experiment in "Xenon" acquisition/processing software). Function (based on readEPR_Exp_Specs) includes automatic time correction for CW EPR time.series experiments (see also correct_time_Exp_Specs).

Usage

readEPR_Exp_Specs_kin(
  name.root,
  dir_ASC,
  dir_dsc_par,
  time.unit = "s",
  time.delta.slice.s = NULL,
  col.names = c("index", "B_G", "time_s", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 4,
  time.series.id = 3,
  convertB.unit = TRUE,
  qValue = NULL,
  norm.vec.add = NULL,
  origin = "xenon",
  ...
)
readEPR_Exp_Specs_kin(
  name.root,
  dir_ASC,
  dir_dsc_par,
  time.unit = "s",
  time.delta.slice.s = NULL,
  col.names = c("index", "B_G", "time_s", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 4,
  time.series.id = 3,
  convertB.unit = TRUE,
  qValue = NULL,
  norm.vec.add = NULL,
  origin = "xenon",
  ...
)

Arguments

name.root

Character string, corresponding to entire file name without extension.

dir_ASC

Character string, path (can be also defined by the file.path) to directory where the ASCII spectral data is stored.

dir_dsc_par

Character string, path (can be also defined by the file.path) to directory where the .DSC/.dsc or .par parameter file is stored (in order to calculate $g$ -value and/or normalize intensities).

time.unit

Character string, specifying the "s","min", "h" or time.unit = "unitless" (if time.delta.slice.s is different from NULL). Default: time.unit = "s"

time.delta.slice.s

Numeric, time interval in seconds between slices, in the case if origin = "winepr". Default: time.delta.slice = NULL (actually, corresponding to 1 s).

col.names

Character/String vector inherited from fread, corresponding to column/variable names. A safe rule of thumb is to use column names incl. physical quantity notation with its units, Quantity_Unit like "B_G", "RF_MHz", "Bsim_mT" (e.g. pointing to simulated EPR spectrum $x$ -axis)...etc, default: col.names = c("index","B_G","dIepr_over_dB").

x.id

Numeric index related to col.names vector pointing to independent variable, which corresponds to $x$ -axis in the spectra or other plots. Default: x.id = 2 (for Xenon).

x.unit

Character string, corresponding to original x variable/column unit, such as "G", "mT" or "MHz".

Intensity.id

time.series.id

Numeric index related to col.names pointing to time column for time series EPR spectra changing upon time. If data contains simple relationship like $Area$ vs $time$ use x and x.unit parameters/arguments instead. This parameter/argument is dedicated to kinetic-like experiments. Default: time.series.id = 3.

convertB.unit

qValue

Numeric, Q value (quality factor, number) displayed at specific dB by spectrometer. In case of "Xenon" software the parameter is included in .DSC file, therefore default: qValue = NULL (actually corresponding to value 1). If EPR spectra were acquired by the "Winepr" software, the Q value must be defined like qValue = 3400.

norm.vec.add

Numeric vector, additional normalization constant in the form of vector, involving all (in addition to qValue) normalization(s) such as concentration, powder sample weight, number of scans, ...etc (e.g. norm.vec.add = c(2000,0.5,2)). Default: norm.vec.add = NULL (actually corresponding to value 1).

origin

String	Description
"xenon"	default automatically loads data from the "Xenon" software with the default parameters.
"winepr"	automatically loads data from the "WinEpr" software.
"magnettech"	automatically loads data from the new "Magnettech" software (ESR5000 [11-0422]).
"other" (arbitrary string, e.g. "csv")	general, loads any other original data like `csv`, `txt`, `asc` incl. also data from other instrumental/spectrometer software. In such case, all the arguments for `readEPR_Exp_Specs` have to be set up accordingly.

...

additional arguments specified, see also the readEPR_Exp_Specs and fread.

Value

List of EPR spectrum data (including time) in tidy long table format (df) + corrected time vector (time). For the origon = "winepr" "time" slices/indices must be already converted into time domain by time.delta.slice.s (see arguments and examples).

Examples

## loading the built-in package example to demonstrate
## the reading of time series EPR spectra/kinetics:
triarylam.decay.series.dsc.path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.DSC")
triarylam.decay.series.asc.path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.zip")
unzip(triarylam.decay.series.asc.path,exdir = tempdir())
#
## loading the kinetics:
triarylam.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root = "Triarylamine_radCat_decay_series",
                        dir_ASC = tempdir(),
                        dir_dsc_par =
                          system.file("extdata",
                                      package = "eprscope")
                       )
#
## data preview
head(triarylam.decay.series.data$df)
#
## preview of corrected time vector
## (the uncorrected one actually starts from `0`)
triarylam.decay.series.data$time
#
## Not run: 
## reading by the "WinEPR" software
readEPR_Exp_Specs_kin("Sample_spectra_irradiation",
                      file.path(".","ASCII_data_dir"),
                      file.path(".","dsc_data_dir"),
                      time.unit = "s",
                      time.delta.slice.s = 24.1,
                      col.names = c("B_G",
                                    "Slice",
                                    "Intensity"),
                      x.unit = "G",
                      qValue = 2900,
                      origin = "winepr")


## End(Not run)


## loading the built-in package example to demonstrate
## the reading of time series EPR spectra/kinetics:
triarylam.decay.series.dsc.path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.DSC")
triarylam.decay.series.asc.path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.zip")
unzip(triarylam.decay.series.asc.path,exdir = tempdir())
#
## loading the kinetics:
triarylam.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root = "Triarylamine_radCat_decay_series",
                        dir_ASC = tempdir(),
                        dir_dsc_par =
                          system.file("extdata",
                                      package = "eprscope")
                       )
#
## data preview
head(triarylam.decay.series.data$df)
#
## preview of corrected time vector
## (the uncorrected one actually starts from `0`)
triarylam.decay.series.data$time
#
## Not run: 
## reading by the "WinEPR" software
readEPR_Exp_Specs_kin("Sample_spectra_irradiation",
                      file.path(".","ASCII_data_dir"),
                      file.path(".","dsc_data_dir"),
                      time.unit = "s",
                      time.delta.slice.s = 24.1,
                      col.names = c("B_G",
                                    "Slice",
                                    "Intensity"),
                      x.unit = "G",
                      qValue = 2900,
                      origin = "winepr")


## End(Not run)

Load Several/Multiple EPR Data/Spectra Files Simultaneously

Description

Loads the EPR spectra from several/multiple text files (including the instrumental parameters in .DSC/.dsc or .par format) at once. Finally, the data are transformed either into a list of data frames or into a tidy/long table format. According to experimental quantity (e.g. temperature, microwave power, recording time...etc), names and var2nd.series (in the case of tidy = TRUE) arguments have to be specified.

Usage

readEPR_Exp_Specs_multif(
  name.pattern,
  dir_ASC,
  dir_dsc_par,
  col.names = c("index", "B_G", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 3,
  convertB.unit = TRUE,
  qValues = NULL,
  norm.list.add = NULL,
  names,
  tidy = FALSE,
  var2nd.series = NULL,
  var2nd.series.factor = FALSE,
  origin = "xenon",
  ...
)
readEPR_Exp_Specs_multif(
  name.pattern,
  dir_ASC,
  dir_dsc_par,
  col.names = c("index", "B_G", "dIepr_over_dB"),
  x.id = 2,
  x.unit = "G",
  Intensity.id = 3,
  convertB.unit = TRUE,
  qValues = NULL,
  norm.list.add = NULL,
  names,
  tidy = FALSE,
  var2nd.series = NULL,
  var2nd.series.factor = FALSE,
  origin = "xenon",
  ...
)

Arguments

name.pattern

Character string ('specimen'), inherited from list.files. A pattern from file name which might not necessarily appear at the beginning of the file name. One might also consult how to use regular expressions in R. THE SAME NAME AND name.pattern MUST BE USED FOR ALL FILE NAMES WITHIN THE SERIES.

dir_ASC

Path (defined by file.path or by character string) to directory where the ASCII files are stored.

dir_dsc_par

Path (defined by file.path or by character string) to directory where the .DSC/.dsc or .par files,including instrumental parameters, are stored.

col.names

Character string vector, inherited from fread, corresponding to column/variable names for individual file (see also readEPR_Exp_Specs). A safe rule of thumb is to use column names including the physical quantity notation with its units, Quantity_Unit like "B_G", "RF_MHz", "Bsim_mT" (e.g. pointing to simulated EPR spectrum $x$ -axis)...etc, default: col.names = c("index","B_G",dIepr_over_dB) referring to column names coming from Xenon software.

x.id

Numeric index related to col.names vector pointing to independent variable, which corresponds to $x$ -axis in the spectra or other plots. Default: x.id = 2 (for Xenon).

x.unit

Character string pointing to unit of quantity (coming from the original ASCII data, see also col.names argument) which is to be presented on $x$ -axis of the EPR spectrum. Units like "G" ("Gauss"), "mT" ("millitesla"), "MHz" ("megahertz" in case of ENDOR spectra) or "Unitless" in case of $g$ -values can be used. Default: x.unit = "G".

Intensity.id

convertB.unit

qValues

Numeric vector of Q-values (sensitivity factors to normalize EPR intensities) either loaded from instrumental parameters (.DSC or .par), therefore qValues = NULL (default), or in case of the origin = "winepr", they have to be provided by the spectrometer operator.

norm.list.add

Numeric list of vectors. Additional normalization constants in the form of vectors involving all (i.e. in addition to qValue) normalization(s) like e.g. concentration, powder sample weight, number of scans, ...etc (e.g. norm.list.add = list(c(2000,0.5,2),c(1500,1,3))). Default: norm.list.add = NULL.

names

Character string vector, corresponding either to values of additional quantity (e.g. temperature,microwave power...etc, c("240","250","260","270")) or to general sample coding by alpha character (e.g. c("a","b","c","d")) being varied by the individual experiments.

tidy

Logical, whether to transform the list of data frames into the long table (tidy) format, default: tidy = FALSE.

var2nd.series

Character string, if tidy = TRUE (see also the tidy argument) it is referred to name of the variable/quantity (such as "time","Temperature","Electrochemical Potential", "Microwave Power"...etc) altered during individual experiments as a second variable series (var2nd.series) and related to the spectral data.

var2nd.series.factor

Logical, whether to factorize var2nd.series column vector which is useful for plotting the spectra in overlay form. Default: var2nd.series.factor = FALSE, which is the case to visualize EPR spectra by plot-functions.

origin

String	Description
"xenon"	default automatically loads data from the "Xenon" software with the default parameters.
"winepr"	automatically loads data from the "WinEpr" software.
"magnettech"	automatically loads data from the new "Magnettech" software (ESR5000 [11-0422]).
"other" (arbitrary string, e.g. "csv")	general, loads any other original data like `csv`, `txt`, `asc` incl. also data from other instrumental/spectrometer software. In such case, all the arguments for `readEPR_Exp_Specs` have to be set up accordingly.

...

additional arguments specified, see alsoreadEPR_Exp_Specs and fread.

Value

List of Data Frames (or long table tidy format) corresponding to multiple spectral data files/data sets. g-Value column (if x.unit = "mT" or "G") is automatically calculated during the processing and it is included in the data frame list/database as well.

Examples

## Not run: 
## multiple ENDOR spectra at different temperatures recorded by `Xenon` software
## read and transformed into `longtable`, ready to plot the overlay
## EPR spectra => `var2nd.series.factor = FALSE` (default).
readEPR_Exp_Specs_multif(name.pattern = "^.*_sample_VT_",
                         file.path(".","ASCII_data_dir"),
                         file.path(".","DSC_data_dir"),
                         col.names = c("index",
                                       "RF_MHz",
                                       "Intensity"),
                         x.id = 2,
                         x.unit = "MHz",
                         Intensity.id = 3,
                         names = c("210","220","230","240"),
                         tidy = TRUE,
                         var2nd.series = "Temperature_K")
#
## multiple EPR spectra recorded at different temperatures
## by `WinEPR` software, experiments performed with a powder
## sample (m = 10 mg) and each spectrum acquired
## as 7 accumulations, the resulting database
## corresponds to list of data frames
readEPR_Exp_Specs_multif("^Sample_VT_",
                         file.path(".","ASCII_data_dir"),
                         file.path(".","DSC_data_dir"),
                         col.names = c("B_G","dIepr_over_dB"),
                         x.id = 1,
                         x.unit = "G",
                         Intensity.id = 2,
                         names = c("210","220","230","240"),
                         qValues = c(3400,3501,3600,2800),
                         norm.list.add = rep(list(c(10,7)),times = 4),
                         origin = "winepr")
#
## multiple `Xenon` EPR spectra related to one powder sample (m = 8 mg)
## where several instrumental parameters are changed
## at once, the file names (files are stored in the actual directory)
## start with the "R5228_AV_powder_", function returns all spectral data
## in `tidy` (long) table format
readEPR_Exp_Specs_multif(name.pattern = "R5228_AV_powder_",
                         dir_ASC = ".",
                         dir_dsc_par = ".",
                         names = c("a","b","c","d"),
                         tidy = TRUE,
                         var2nd.series = "sample",
                         norm.list.add = rep(list(8),4))

## End(Not run)


## Not run: 
## multiple ENDOR spectra at different temperatures recorded by `Xenon` software
## read and transformed into `longtable`, ready to plot the overlay
## EPR spectra => `var2nd.series.factor = FALSE` (default).
readEPR_Exp_Specs_multif(name.pattern = "^.*_sample_VT_",
                         file.path(".","ASCII_data_dir"),
                         file.path(".","DSC_data_dir"),
                         col.names = c("index",
                                       "RF_MHz",
                                       "Intensity"),
                         x.id = 2,
                         x.unit = "MHz",
                         Intensity.id = 3,
                         names = c("210","220","230","240"),
                         tidy = TRUE,
                         var2nd.series = "Temperature_K")
#
## multiple EPR spectra recorded at different temperatures
## by `WinEPR` software, experiments performed with a powder
## sample (m = 10 mg) and each spectrum acquired
## as 7 accumulations, the resulting database
## corresponds to list of data frames
readEPR_Exp_Specs_multif("^Sample_VT_",
                         file.path(".","ASCII_data_dir"),
                         file.path(".","DSC_data_dir"),
                         col.names = c("B_G","dIepr_over_dB"),
                         x.id = 1,
                         x.unit = "G",
                         Intensity.id = 2,
                         names = c("210","220","230","240"),
                         qValues = c(3400,3501,3600,2800),
                         norm.list.add = rep(list(c(10,7)),times = 4),
                         origin = "winepr")
#
## multiple `Xenon` EPR spectra related to one powder sample (m = 8 mg)
## where several instrumental parameters are changed
## at once, the file names (files are stored in the actual directory)
## start with the "R5228_AV_powder_", function returns all spectral data
## in `tidy` (long) table format
readEPR_Exp_Specs_multif(name.pattern = "R5228_AV_powder_",
                         dir_ASC = ".",
                         dir_dsc_par = ".",
                         names = c("a","b","c","d"),
                         tidy = TRUE,
                         var2nd.series = "sample",
                         norm.list.add = rep(list(8),4))

## End(Not run)

Read Selected EPR Instrumental Parameters and Information

Description

Taking selected instrumental parameters or information from the .DSC/.dsc or .par file of an EPR spectrum (written by the Xenon/Magnettech or WinEpr software, respectively).

Usage

readEPR_param_slct(path_to_dsc_par, string, origin = "xenon")
readEPR_param_slct(path_to_dsc_par, string, origin = "xenon")

Arguments

path_to_dsc_par

Character string, path to .DSC/.dsc or .par file including the instrumental parameters provided by the EPR machine. File path can be also defined by the file.path function.

string

Character (vector) string (appeared at the line beginning) within the .DSC/.dsc or .par file corresponding to instrumental parameter or information. Following strings are defined for all three main acquisition softwares described-above (in parenthesis for the "winepr" origin):

String	Instrumental Parameter
"OPER" ("JON")	operator (of the EPR instrument)
"CMNT" ("JCO")	comment (in order to describe the measurement)
"DATE" ("JDA")	date (when the EPR spectrum was recorded)
"TIME" ("JTM")	time (when the EPR spectrum was recorded)
"SAMP"	name/decsript. of the sample, not available in "magnettech" `.dsc`
"B0MF"	modulation frequency in `Hz`
"MWFQ" ("MF")	microwave frequency in `Hz` (`GHz`)
"QValue"	recorded quality-Factor (required for intensity normalization) `unitless`
"A1CT" ("HCF")	central field (B) in `T` (`G`)
"A1SW" ("HSW")	sweep width in `T` (`G`)
"STMP" ("TE")	temperature in `K`
"B0MA" ("RMA")	modulation amplitude in `T` (`G`)
"AVGS" ("JSD")	number of accumulations for each spectrum
"A1RS" ("RES")	number of points/resolution
"MWPW" ("MP")	microwave power in `W` (`mW`)
"SPTP" ("RCT")	conversion time in `s` (`ms`)
"RCTC" ("RTC")	time constant in `s` (ms), not available in "magnettech" `.dsc`
"RCAG" ("RRG")	signal receiver gain in `dB` (unitless), not available in "magnettech" `.dsc`
"ConvFact"	conversion factor/instr. calibration constant for quantitative analysis `unitless`, not available in "magnettech" `.dsc`

origin

Character string, corresponding to software used to acquire EPR spectra. The files are slightly different depending on whether they were recorded by the "WinEpr",origin = "winepr", "Xenon" (default: origin = "xenon") or by the "Magnettech" (ESR5000 [11-0422], origin = "magnettech").

Value

Numeric or character string (e.g. date or comment), corresponding to selected instrumental parameter(s) applied to record the EPR spectra. In case of string character vector, named list, containing either character and/or numeric values, is returned with the names corresponding to string.

Examples

## loading `.DSC` (`Xenon`) parameter file example
triaryl_radCat_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.DSC")
#
## reading modulation amplitude (in T) from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,string = "B0MA")
#
## reading Q-Value from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,string = "QValue")
#
## reading `CMNT` (comment) and `MWFQ` (microwave frequency in Hz)
## from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,
                   string = c("CMNT","MWFQ"))
#
## loading `.par` (`WinEPR`) parameter file example
TMPD_radCat_par_path <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
#
## reading `JDA` (date) from `WinEPR` spectrometer file
readEPR_param_slct(TMPD_radCat_par_path,
                   string = "JDA",
                   origin = "winepr")
#
## reading `RMA` (modulation amplitude in G) and `TE`
## (temperature in K) as well as `JCO` (comment)
## from `WinEPR` spectrometer file
readEPR_param_slct(TMPD_radCat_par_path,
                   string = c("RMA","TE","JCO"),
                   origin = "WinEPR")
#
## loading and reading the `.DSC` file from `Xenon`
## corresponding to phenalenyl (PNT) CW ENDOR spectrum,
## read expr. date (`TIME`), microwave frequency (`MWFQ`)
## in Hz and the corresponding field for saturation (`B0VL`)
## in Tesla:
pnt_endor_dsc_path <-
  load_data_example(file = "PNT_ENDOR_a.DSC")
readEPR_param_slct(pnt_endor_dsc_path,
                string = c("TIME","MWFQ","B0VL")
               )



## loading `.DSC` (`Xenon`) parameter file example
triaryl_radCat_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_a.DSC")
#
## reading modulation amplitude (in T) from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,string = "B0MA")
#
## reading Q-Value from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,string = "QValue")
#
## reading `CMNT` (comment) and `MWFQ` (microwave frequency in Hz)
## from the `Xenon` spectrometer file
readEPR_param_slct(triaryl_radCat_dsc_path,
                   string = c("CMNT","MWFQ"))
#
## loading `.par` (`WinEPR`) parameter file example
TMPD_radCat_par_path <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
#
## reading `JDA` (date) from `WinEPR` spectrometer file
readEPR_param_slct(TMPD_radCat_par_path,
                   string = "JDA",
                   origin = "winepr")
#
## reading `RMA` (modulation amplitude in G) and `TE`
## (temperature in K) as well as `JCO` (comment)
## from `WinEPR` spectrometer file
readEPR_param_slct(TMPD_radCat_par_path,
                   string = c("RMA","TE","JCO"),
                   origin = "WinEPR")
#
## loading and reading the `.DSC` file from `Xenon`
## corresponding to phenalenyl (PNT) CW ENDOR spectrum,
## read expr. date (`TIME`), microwave frequency (`MWFQ`)
## in Hz and the corresponding field for saturation (`B0VL`)
## in Tesla:
pnt_endor_dsc_path <-
  load_data_example(file = "PNT_ENDOR_a.DSC")
readEPR_param_slct(pnt_endor_dsc_path,
                string = c("TIME","MWFQ","B0VL")
               )

Read the Selected Instrumental Parameters of EPR Time Series Experiment

Description

Function takes selected instrumental parameters relevant to time series ("kinetic") experiment from the .DSC/.dsc or .par file of an EPR Spectrum, obtained from the "Xenon", "WinEpr" or "Magnettech" software. These parameters are required for time correction of the CW (continuous wave) EPR spectra, see the correct_time_Exp_Specs.

Usage

readEPR_params_slct_kin(path_to_dsc_par, origin = "xenon")
readEPR_params_slct_kin(path_to_dsc_par, origin = "xenon")

Arguments

`path_to_dsc_par`	String, path to `.DSC/.dsc` or `.par` file including all instrumental parameters provided by the EPR machine.
`origin`	Character string, corresponding to software used to acquire EPR spectra. The files are slightly different depending on whether they were recorded by the "WinEpr",`origin = "winepr"`, "Xenon" (default: `origin = "xenon"`) or by the "Magnettech" (ESR5000 [11-0422], `origin = "magnettech"`).

Value

List containing:

Nscans: Number of scans.
swTime: Sweep time in s required for time correction during the 2D_Field_Delay (time series EPR experiment).
Npoints: Number of points (spectral resolution).

Examples

## loading `.DSC` (`Xenon`) parameter file example
aminoxyl_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.DSC")
#
readEPR_params_slct_kin(aminoxyl_dsc_path)


## loading `.DSC` (`Xenon`) parameter file example
aminoxyl_dsc_path <-
  load_data_example(file = "Triarylamine_radCat_decay_series.DSC")
#
readEPR_params_slct_kin(aminoxyl_dsc_path)

Read the Selected Instrumental Parameters Relevant to EPR Quantitative Analysis

Description

Reading the .DSC/.dsc or .par file to extract the important parameters like "modulation amplitude", "temperature", "microwave power" as well as "microwave frequency" which are are required for the absolute EPR quantitative analysis ( $\equiv$ radical or paramagnetic species number determination, see the quantify_EPR_Abs function).

Usage

readEPR_params_slct_quant(path_to_dsc_par, origin = "xenon")
readEPR_params_slct_quant(path_to_dsc_par, origin = "xenon")

Arguments

`path_to_dsc_par`	Character string, path (also provided by `file.path`) to `.DSC/.dsc` or `.par` (depending on OS, see the `origin` argument) `text` files including all instrumental parameters and provided by the EPR machine.
`origin`	Character string, corresponding to software used to acquire EPR spectra. The files are slightly different depending on whether they were recorded by the "WinEpr",`origin = "winepr"`, "Xenon" (default: `origin = "xenon"`) or by the "Magnettech" (ESR5000 [11-0422], `origin = "magnettech"`).

Value

List consisting of:

BmmT: Modulation amplitude value in mT.
PmW: Microwave source power in mW.
TK: Experimental temperature in K.
mwGHz: Microwave frequency value in GHz.

Examples

## loading `.DSC` (`Xenon`) parameter file example
aminoxyl_dsc_path <-
  load_data_example(file = "Aminoxyl_radical_a.DSC")
#
readEPR_params_slct_quant(aminoxyl_dsc_path)


## loading `.DSC` (`Xenon`) parameter file example
aminoxyl_dsc_path <-
  load_data_example(file = "Aminoxyl_radical_a.DSC")
#
readEPR_params_slct_quant(aminoxyl_dsc_path)

Read the Selected Instrumental Parameters Required for EPR Simulations

Description

Reading the .DSC/.dsc or .par file to extract the important parameters like "sweep width", "central field", "number of points" as well as "microwave frequency" which are are required for the simulations of EPR spectra (see also the eval_sim_EPR_iso function).

Usage

readEPR_params_slct_sim(path_to_dsc_par, origin = "xenon", B.unit = "G")
readEPR_params_slct_sim(path_to_dsc_par, origin = "xenon", B.unit = "G")

Arguments

`path_to_dsc_par`	Character string, path (also provided by `file.path`) to `.DSC/.dsc` or `.par` (depending on OS, see the `origin` argument) `text` files including all instrumental parameters and provided by the EPR machine.
`origin`	Character string, corresponding to software used to acquire EPR spectra. The files are slightly different depending on whether they were recorded by the "WinEpr",`origin = "winepr"`, "Xenon" (default: `origin = "xenon"`) or by the "Magnettech" (ESR5000 [11-0422], `origin = "magnettech"`).
`B.unit`	Character string, pointing to unit of magnetic flux density which is the output "unit", `"G"` ("Gauss") or `"mT"` ("millitesla"), for `"sweep width"` and `"central field"` (see also the `eval_sim_EPR_iso`). Default: `B.unit = "G"`.

Value

List consisting of:

Bcf: Central field (magnetic flux density, B) value in B.unit.
Bsw: Sweep width (magnetic flux density, B, experimental range) value in B.unit.
Npoints: Number of points (spectral resolution).
mwGHz: Microwave frequency value in GHz.

Examples

## loading `.par` (`WinEPR`) parameter file example
TMPD_radCat_par_path <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
#
## `B` parameters in `mT`
readEPR_params_slct_sim(TMPD_radCat_par_path,
                        origin = "winepr",
                        B.unit = "mT")
#
## loading `.dsc` (`Magnettech`) parameter
## file example
AcridineRad.params.path <-
  load_data_example("AcridineDeriv_Irrad_365nm.dsc")
readEPR_params_slct_sim(AcridineRad.params.path,
                        origin = "magnettech")


## loading `.par` (`WinEPR`) parameter file example
TMPD_radCat_par_path <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
#
## `B` parameters in `mT`
readEPR_params_slct_sim(TMPD_radCat_par_path,
                        origin = "winepr",
                        B.unit = "mT")
#
## loading `.dsc` (`Magnettech`) parameter
## file example
AcridineRad.params.path <-
  load_data_example("AcridineDeriv_Irrad_365nm.dsc")
readEPR_params_slct_sim(AcridineRad.params.path,
                        origin = "magnettech")

Read EPR Instrumental Parameters and Information and Write them into Tables

Description

Taking the instrumental parameters from the .DSC/.dsc or .par files, applied to record the EPR Spectra, and transferring them into list of Tables/Data Frames. They include either parameter values and their units or character/string information about the measurement, see also the readEPR_param_slct.

Usage

readEPR_params_tabs(path_to_dsc_par, origin = "xenon", interact = NULL)
readEPR_params_tabs(path_to_dsc_par, origin = "xenon", interact = NULL)

Arguments

`path_to_dsc_par`	Character string, path (also provided by `file.path`) to `.DSC/.dsc` or `.par` (depending on `origin` parameter) `text` files, including instrumental parameters and provided by the EPR machine.
`origin`	Character string, corresponding to software used to acquire EPR spectra. The files are slightly different depending on whether they were recorded by the "WinEpr",`origin = "winepr"`, "Xenon" (default: `origin = "xenon"`) or by the "Magnettech" (ESR5000 [11-0422], `origin = "magnettech"`).
`interact`	Character string, whether to display interactive tables by the `datatable`. Default: `interact = NULL`. Interactive table with parameters can be displayed by `interact = "params"` or to display the additional information table: `interact = "info"`.

Value

List of data frames/tables containing:

params: Instrumental parameters with their numeric values and units.
info: Information character string, such as date, operator, comment...etc.

Both data frames may be depicted in the form of interactive tables by the interact function argument.

Examples

## loading built-in example file =>
## "AcridineDeriv_Irrad_365nm.dsc" by `Magnettech`
## spectrometer software
AcridinRad.data.file <-
  load_data_example("AcridineDeriv_Irrad_365nm.dsc")
## reading and displaying parameters as data frame
AcridinRad.params.data <-
  readEPR_params_tabs(AcridinRad.data.file,
                      origin = "magnettech")
#
## parameters preview
AcridinRad.params.data$params
#
## info preview
AcridinRad.params.data$info
#
## built-in example file => "TMPD_specelchem_accu_b.par"
## by the `WinEPR` spectrometer software
tmpd.params.file <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
## reading and displaying parameters as data frame
tmpd.params.tab <-
  readEPR_params_tabs(tmpd.params.file,
                      origin = "winepr")
#
## preview
tmpd.params.tab$params
##
## the same data frame, now in interactive table form
readEPR_params_tabs(tmpd.params.file,
                    origin = "winepr",
                    interact = "params")


## loading built-in example file =>
## "AcridineDeriv_Irrad_365nm.dsc" by `Magnettech`
## spectrometer software
AcridinRad.data.file <-
  load_data_example("AcridineDeriv_Irrad_365nm.dsc")
## reading and displaying parameters as data frame
AcridinRad.params.data <-
  readEPR_params_tabs(AcridinRad.data.file,
                      origin = "magnettech")
#
## parameters preview
AcridinRad.params.data$params
#
## info preview
AcridinRad.params.data$info
#
## built-in example file => "TMPD_specelchem_accu_b.par"
## by the `WinEPR` spectrometer software
tmpd.params.file <-
  load_data_example(file = "TMPD_specelchem_accu_b.par")
## reading and displaying parameters as data frame
tmpd.params.tab <-
  readEPR_params_tabs(tmpd.params.file,
                      origin = "winepr")
#
## preview
tmpd.params.tab$params
##
## the same data frame, now in interactive table form
readEPR_params_tabs(tmpd.params.file,
                    origin = "winepr",
                    interact = "params")

Read Simulated ASCII EPR Spectrum

Description

Loading the ASCII data like .txt,.asc or .csv, related to simulated EPR spectrum from different sources like "EasySpin" (Matlab), "Xenon" (EPR spectrometer), "SimFonia" (WinEPR system) or "csv" (comma separated values, universal format or MS Excel). Finally, they are automatically converted into data frames by the fread.

Usage

readEPR_Sim_Spec(
  path_to_ASC,
  B.unit = "G",
  Intensity.sim = "dIeprSim_over_dB",
  sim.origin = "easyspin"
)
readEPR_Sim_Spec(
  path_to_ASC,
  B.unit = "G",
  Intensity.sim = "dIeprSim_over_dB",
  sim.origin = "easyspin"
)

Arguments

`path_to_ASC`	Character string, path to ASCII file/table with simulated spectral data ( $Intensity\,\,vs\,\,B$ (Field) obtained from various sources. Path can be alternatively defined by the `file.path` function.
`B.unit`	Character string, pointing to unit of magnetic flux density coming from the original data which is to be presented on the $B$ -axis of an EPR spectrum, like `"G"` ("Gauss"), `"mT"` ("millitesla"). Default: `B.unit = "G"`.
`Intensity.sim`	Character string, pointing to intensity data frame column name, corresponding to simulated EPR spectrum. If used together with the quantification of radicals, this argument must be equal to that of the `quantify_EPR_Sim_series`.
`sim.origin`	Character string, referring to the "origin" of a simulated spectrum ASCII data. There are four possibilities $\Rightarrow$ `sim.orimgin = "easyspin"` (default), `"xenon"`, `"simfonia"` as well as universal `"csv"`.

Value

Data frame, consisting of magnetic flux density (Bsim_mT or Bsim_G) and intensity variable/column (depending on the Intensity.sim argument), corresponding to simulated EPR spectrum.

Examples

## Not run: 
readEPR_Sim_Spec(path_to_ASC =
                  "./Simulations/TEMPO_simulation.txt",
                 sim.origin = "xenon")
#
readEPR_Sim_Spec("Cu_complex_simulation.txt",
                 B.unit = "mT",
                 sim.origin = "easyspin")

## End(Not run)



## Not run: 
readEPR_Sim_Spec(path_to_ASC =
                  "./Simulations/TEMPO_simulation.txt",
                 sim.origin = "xenon")
#
readEPR_Sim_Spec("Cu_complex_simulation.txt",
                 B.unit = "mT",
                 sim.origin = "easyspin")

## End(Not run)

Reading Solvent Properties from `solvents_ds` Dataset

Description

Gathering the solvent properties from solvents_ds in order to filter out specific solvent and its corresponding properties (by the prop argument). See also vignette("datasets").

Usage

readEPR_solvent_props(solvent, prop = NULL)
readEPR_solvent_props(solvent, prop = NULL)

Arguments

`solvent`	Character string, pointing to solvent name (or any string from the solvent name/abbreviation), such as `solvent = "DMSO"`,`solvent = "acetone"`, `solvent = "xylene"`. If more than one rows/observations are being returned (e.g. in case of `solvent = "xylene"`) => additional solvent specification must be provided e.g. `solvent = "o-xylene"`.
`prop`	Character string related to a data frame variable/column/property e.g. `"boiling"`, `"formula"`, `"dens"`, `"dielectric"`...etc (see also `solvents_ds`).

Value

Data frame with row/rows of selected solvent(s) and the corresponding properties. If a specific property is called like code = "melting" ( $\equiv$ melting point in °C), the function returns value/character.

Examples

## Properties of `DMSO`:
solvent_01 <- readEPR_solvent_props("DMSO")
head(solvent_01)
#
## All `xylene` solvent specifications:
solvent_02 <- readEPR_solvent_props(solvent = "xylene")
head(solvent_02)
#
## Boiling point of `o-xylene`:
readEPR_solvent_props(solvent = "o-xylene",
                      prop = "boiling")



## Properties of `DMSO`:
solvent_01 <- readEPR_solvent_props("DMSO")
head(solvent_01)
#
## All `xylene` solvent specifications:
solvent_02 <- readEPR_solvent_props(solvent = "xylene")
head(solvent_02)
#
## Boiling point of `o-xylene`:
readEPR_solvent_props(solvent = "o-xylene",
                      prop = "boiling")

Read EPR Simulation Parameters and Information from MATLAB `.mat` File

Description

Function is based on the readMat and provides the reading of a .mat simulation file content from EasySpin MATLAB, including structures/variables and fields. It can be also used to read and store simulated EPR spectrum in the form of R data frame (see Examples).

Usage

readMAT_params_file(path_to_MAT, str.var = NULL, field.var = NULL)
readMAT_params_file(path_to_MAT, str.var = NULL, field.var = NULL)

Arguments

`path_to_MAT`	Character string, path to `.mat` MATLAB file with all variables saved in MATLAB workspace. The file path can be also defined by the `file.path`.
`str.var`	Character string, denoting structure/variable, which may contain `fields`, such as `Sys` and `g` => Sys.g, respectively. Default: `str.var = NULL`.
`field.var`	Character string, corresponding to field variable after 'dot', which is available only for certain structures/variables, see e.g. example above (Sys.g). Therefore, the default value is `NULL` and the `string` is applied only for structures with fields.

Value

Unless the str.var and/or field.var are not specified, the output is list with the all original parameters/structures from MATLAB file. Otherwise, the function returns either numeric/character vector/value or list depending on class of the original parameter/field variable.

Examples

## loading the package built-in
## `Aminoxyl_radical_a.mat` file as an example
aminoxyl.mat.file <-
  load_data_example(file = "Aminoxyl_radical_a.mat")
#
## reading the entire `mat` file as list
## and assign variable
aminoxyl.mat.list <-
  readMAT_params_file(aminoxyl.mat.file)
#
## read the `Sim1` structure/variable content into list
aminoxyl.mat.sim1 <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "Sim1")
#
## list preview
aminoxyl.mat.sim1
#
## compare the previous simulation parameters with
## those obtained by the `eval_sim_EPR_isoFit()`
## function (look at the corresponding examples)
#
## alternatively the `Sim1` (its dimension > 2)
## can be also read by the following command
## however, the returned output has a complex
## array-list structure
aminoxyl.mat.list$Sim1[, , 1]
#
## read the `Sim1` structure/variable
## and the field `Nucs` corresponding to nuclei
## considered in the EPR simulation
aminoxyl.mat.sim1.nucs <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "Sim1",
                      field.var = "Nucs")
#
## preview
aminoxyl.mat.sim1.nucs
#
## reading the magnetic flux density
## `B` column/vector corresponding to simulated
## and experimental EPR spectrum
aminoxyl.B.G <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "B")
#
## preview of the first 6 values
aminoxyl.B.G[1:6]
#
## reading the intensity related to simulated
## EPR spectrum
aminoxyl.sim.fitSpec <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "fit1",
                      field.var = "fitSpec")
#
## for the newer EasySpin version (> 6.0.0),
## the "fitSpec" is replaced by the simple "fit",
## all additional parameters (array) are stored under
## the "pfit_full" variable
#
## preview of the first 6 values
aminoxyl.sim.fitSpec[1:6]
#
## The last two examples can be used
## to load the simulated EPR spectrum
## by the `EasySpin` from `mat` file =>
simulation.aminoxyl.spectr.df <-
  data.frame(Bsim_G = aminoxyl.B.G,
             dIeprSim_over_dB = aminoxyl.sim.fitSpec)
#
## preview
head(simulation.aminoxyl.spectr.df)


## loading the package built-in
## `Aminoxyl_radical_a.mat` file as an example
aminoxyl.mat.file <-
  load_data_example(file = "Aminoxyl_radical_a.mat")
#
## reading the entire `mat` file as list
## and assign variable
aminoxyl.mat.list <-
  readMAT_params_file(aminoxyl.mat.file)
#
## read the `Sim1` structure/variable content into list
aminoxyl.mat.sim1 <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "Sim1")
#
## list preview
aminoxyl.mat.sim1
#
## compare the previous simulation parameters with
## those obtained by the `eval_sim_EPR_isoFit()`
## function (look at the corresponding examples)
#
## alternatively the `Sim1` (its dimension > 2)
## can be also read by the following command
## however, the returned output has a complex
## array-list structure
aminoxyl.mat.list$Sim1[, , 1]
#
## read the `Sim1` structure/variable
## and the field `Nucs` corresponding to nuclei
## considered in the EPR simulation
aminoxyl.mat.sim1.nucs <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "Sim1",
                      field.var = "Nucs")
#
## preview
aminoxyl.mat.sim1.nucs
#
## reading the magnetic flux density
## `B` column/vector corresponding to simulated
## and experimental EPR spectrum
aminoxyl.B.G <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "B")
#
## preview of the first 6 values
aminoxyl.B.G[1:6]
#
## reading the intensity related to simulated
## EPR spectrum
aminoxyl.sim.fitSpec <-
  readMAT_params_file(aminoxyl.mat.file,
                      str.var = "fit1",
                      field.var = "fitSpec")
#
## for the newer EasySpin version (> 6.0.0),
## the "fitSpec" is replaced by the simple "fit",
## all additional parameters (array) are stored under
## the "pfit_full" variable
#
## preview of the first 6 values
aminoxyl.sim.fitSpec[1:6]
#
## The last two examples can be used
## to load the simulated EPR spectrum
## by the `EasySpin` from `mat` file =>
simulation.aminoxyl.spectr.df <-
  data.frame(Bsim_G = aminoxyl.B.G,
             dIeprSim_over_dB = aminoxyl.sim.fitSpec)
#
## preview
head(simulation.aminoxyl.spectr.df)

Rearrangement of $A_{iso}$ / $a_{iso}$ from Quantum Chemical (QCH) Computations

Description

Providing table, based on Gaussian/ORCA/...etc. output text files in order to summarize the mean $A_{iso}$ / $a_{iso}$ values of groups with equivalent nuclei, according to proposed molecular structure/symmetry.

Usage

rearrange_aAiso_QCHcomp(path_to_ASC, col.names, nuclei.list.slct)
rearrange_aAiso_QCHcomp(path_to_ASC, col.names, nuclei.list.slct)

Arguments

`path_to_ASC`	Character string, pointing to path of ASCII file (`txt`,`csv`...etc, it may be also provided by the `file.path` function). The file must include characteristic $A_{iso}$ or $a_{iso}$ values.
`col.names`	Character string vector, containing names of all columns from QCH computational output, for the names see example in `Details`, they must contain atomic/structure number, isotop value with element label (nucleus characterization) and $A$ in MHz as well as $a$ in Gauss.
`nuclei.list.slct`	List of numeric values for the rearrangement of selected atoms/nuclei according to symmetry, e.g. `nuclei.list.slct <- list(3,c(21,22),c(20,23),c(24,25),c(27,26))` where the numbers correspond to indices of proposed equivalent nuclei in the ASCII text file.

Details

The $A_{iso}$ / $a_{iso}$ values are computed for each atom/nucleus (with its corresponding atomic number within the structure as well as with the characteristic isotopic number/value), such an entire table can be copied e.g. from Gaussian output (after 'Isotropic Fermi Contact Couplings' line) or can be constructed from ORCA (or any other) output, example for such a file structure (from Gaussian):

No_atom	Atom_Nucleus	MegaHertz	Gauss	1e-4_cm-1
1	N(14)	0.00643	0.00229	0.00214
17	N(14)	13.99707	4.9945	4.66892
28	H(1)	16.34971	5.83398	5.45368

The input table/data frame, like the previous one, must include following columns: atomic/nucleus number, atom/nucleus notation, hyperfine coupling constant in MHz and finally hyperfine splitting constant in G. These columns/variables are essential for the evaluation.

Value

Data frame/Table of $A_{iso}$ / $a_{iso}$ mean values corresponding to groups of equivalent nuclei within the structure/symmetry.

Examples

## Not run: 
rearrange_aAiso_QCHcomp(
"./iso_values_Gaussian.txt",
c("No","Nucleus","au","Megahertz","Gauss","10^n4_cm^n1"),
list(3,c(21,22),c(20,23),c(24,25),c(27,26))
)

## End(Not run)


## Not run: 
rearrange_aAiso_QCHcomp(
"./iso_values_Gaussian.txt",
c("No","Nucleus","au","Megahertz","Gauss","10^n4_cm^n1"),
list(3,c(21,22),c(20,23),c(24,25),c(27,26))
)

## End(Not run)

Rearrangement of $A_{iso}$ / $a_{iso}$ from Gaussian & ORCA Computations

Description

Providing table, specifically from Gaussian or ORCA output text files to summarize the $A_{iso}$ / $a_{iso}$ mean values of groups with equivalent nuclei, according to proposed molecular structure/symmetry (see also the rearrange_aAiso_QCHcomp).

Usage

rearrange_aAiso_QCHorgau(
  path_to_QCHoutput,
  N.nuclei,
  nuclei.list.slct,
  origin = "gaussian",
  output.text.origin = FALSE,
  output.text.path = NULL
)
rearrange_aAiso_QCHorgau(
  path_to_QCHoutput,
  N.nuclei,
  nuclei.list.slct,
  origin = "gaussian",
  output.text.origin = FALSE,
  output.text.path = NULL
)

Arguments

`path_to_QCHoutput`	Character string, corresponding to path of `Gaussian` or `ORCA` output text files.
`N.nuclei`	Numeric value that equals to number of atoms/nuclei within the calculated structure.
`nuclei.list.slct`	List of numeric values for the rearrangement of selected atoms/nuclei according to symmetry, e.g. `nuclei.list.slct <- list(3,c(21,22),c(20,23),c(24,25),c(27,26))` where the numbers correspond to indices of proposed equivalent nuclei in the ASCII text file.
`origin`	Character string, pointing to origin of DFT EPR calculation parameters <=> which software package was used. Only two values are available => `"gaussian"` (default) or `"orca"`.
`output.text.origin`	Logical, whether to write a text file containing the extracted $A_{iso}$ / $a_{iso}$ values from the the original output file defined by the `path_to_QCHoutput`. Default: `output.text.origin = FALSE`.
`output.text.path`	Character string, setting the path to file containing the extracted $A_{iso}$ / $a_{iso}$ values from the original output file defined by the `path_to_QCHoutput`. See also the previous argument.

Value

Data frame/Table of $A_{iso}$ / $a_{iso}$ mean values, corresponding to groups of proposed equivalent nuclei within the structure/symmetry constructed directly from Gaussian or ORCA output text files.

Examples

## built-in file and path
gauss.file.path <-
  load_data_example(file = "TMPDAradCatEPRa.inp.log.zip")
gauss.file <- unzip(gauss.file.path)
symmetry.As.df <-
  rearrange_aAiso_QCHorgau(gauss.file,
    N.nuclei = 28,
    nuclei.list.slct =
    list(c(7, 8), ## 2 x 14N
         c(13, 14, 15, 16), ## 4 x 1H (aromatic)
         c(17, 18, 19, 20,
           21, 22, 23, 24,
           25, 26, 27, 28) ## 12 x 1H (methyl groups)
         )
     )
#
## preview
symmetry.As.df


## built-in file and path
gauss.file.path <-
  load_data_example(file = "TMPDAradCatEPRa.inp.log.zip")
gauss.file <- unzip(gauss.file.path)
symmetry.As.df <-
  rearrange_aAiso_QCHorgau(gauss.file,
    N.nuclei = 28,
    nuclei.list.slct =
    list(c(7, 8), ## 2 x 14N
         c(13, 14, 15, 16), ## 4 x 1H (aromatic)
         c(17, 18, 19, 20,
           21, 22, 23, 24,
           25, 26, 27, 28) ## 12 x 1H (methyl groups)
         )
     )
#
## preview
symmetry.As.df

Smoothing and Fitting of an EPR Spectrum by Splines

Description

Smoothing of the EPR spectra by non-parametric fitting a smoothing spline, ss from npreg package, onto the experimental EPR spectrum/spectra.

Usage

smooth_EPR_Spec_by_npreg(
  data.spectr,
  B = "B_mT",
  B.unit = "mT",
  lineSpecs.form = "derivative",
  Intensity = "dIepr_over_dB",
  method = "BIC",
  output.vec = FALSE,
  ...
)
smooth_EPR_Spec_by_npreg(
  data.spectr,
  B = "B_mT",
  B.unit = "mT",
  lineSpecs.form = "derivative",
  Intensity = "dIepr_over_dB",
  method = "BIC",
  output.vec = FALSE,
  ...
)

Arguments

data.spectr

Spectrum data frame object where the magnetic flux density (in mT or G or T) column can be labeled as Field or B_G and that of the derivative intensity as dIepr_over_dB or single integrated intensity like Integrated_Intensity (index column might be included as well).

B

Character string, pointing to magnetic flux density column of the EPR spectrum data frame data.spectr either in "millitesla"/"tesla" or in "gauss", that is B = "B_mT" (default) or B = "B_G"/B = "T" or B = "Bsim_G" to include simulated EPR spectra as well.

B.unit

Character string, denoting the magnetic flux density unit e.g. B.unit = "G" (gauss, default) or B.unit = "mT"/"T" (millitesla/tesla).

lineSpecs.form

Character string, describing either "derivative" (default) or "integrated" (i.e. "absorption" which can be used as well) line form of the analyzed EPR spectrum/data.

Intensity

Character string, pointing to intensity column if other than dIepr_over_dB name/label is used (e.g. for simulated spectra), default: Intesity = "dIepr_over_dB"

method

Character string, corresponding to method in order to fit an EPR spectrum by a smoothing spline from {npreg} package (see the method argument in ss). The following methods are available (they are shortly described in Nathaniel's E. Helwig Introduction or additional information may be found in References) =>

Method	Short Description
"GCV"	Generalized Cross-Validation
"OCV"	Ordinary Cross-Validation
"GACV"	Generalized Approximate Cross-Validation
"ACV"	Approximate Cross-Validation
"REML"	Restricted Maximum Likelihood
"ML"	Maximum Likelihood
"AIC"	Akaike’s Information Criterion
"BIC"	Bayesian Information Criterion (default)

output.vec

Logical, whether the function output have to be vectorized, i.e. only the vector of smoothed EPR intensity is provided. This is especially useful for the EPR spectral (time) series, which can be handily processed by the group_by using the pipe operators (%>%). Default: output.vec = FALSE.

...

additional arguments passed to the function (see also the ss).

Details

The EPR spectrum is fitted by splines which, by default, correspond to cubic Bernoulli polynomials like

$I_{\text{EPR}}(B) = B^3 - (3/2)\,B^2 + (1/2)\,B$

where $I_{\text{EPR}}$ equals to general EPR intensity and $B$ is the magnetic flux density. This may be applied to both derivative or single integrated EPR spectrum forms. Also a higher/lower polynomial degree may be applied by the method (see the argument description) and by the m optional argument (see ... additional arguments) which is a penalty order (integer). For the above-mentioned cubic spline/polynomial m = 2. Linear polynomial corresponds to m = 1 and the highest quintic polynomial/spline is referred as m = 3:

$I_{\text{EPR}}(B) = B^5 - (5/2)\,B^4 + (5/3)\,B^3 - (1/6)\,B$

If the optional argument bernoulli is set to FALSE then "classic" definition of a smoothing spline is produced. In such case, the function estimate is a piece-wise polynomial function with pieces of degree 2m−1. Additional optional arguments from ss like knots definition, equivalent degrees of freedom, vector of weights...etc. can be applied as well.

Value

If output.vec = TRUE the output corresponds to vector of the smoothed EPR intensity (either derivative lineSpecs.form = "derivative" or integrated lineSpecs.form = "integrated"/"absorption") with the length of the original Intensity. Contrarily, if the output.vec is set to FALSE the following list is returned =>

df: Original data frame with the addition column, corresponding to smoothed EPR intensity (derivative or integrated).
plot: Plot object (list) EPR intensity vs. B with the experimental data and its corresponding smoothed relation performed by splines.
rss: Weighted (if the optional parameter w is defined) sum of residual squares.
degs.freedom: Equivalent degrees of freedom used.
fit: List with elements to characterize the spline fit (Details see fit value in the ss function documentation).
sigma: Estimated standard deviation.
aic: Akaike’s Information Criterion (if the method = "AIC"). A negative number that has the largest modulus (deepest down in the negative territory) indicates the preferred model.
bic: Bayesian Information Criterion (if the method = "BIC"). A negative number that has the largest modulus (deepest down in the negative territory) indicates the preferred model.
log.likehood: Likelihood logarithm, if the method = "REML"/"ML". Log likelihood value is a measure of goodness of fit for any model. The higher the value, the better the model.

References

Berry LN, Helwig NE (2021). “Cross-Validation, Information Theory, or Maximum Likelihood? A Comparison of Tuning Methods for Penalized Splines.” Stats, 4(3), 701–724, https://doi.org/10.3390/stats4030042.

Elezović N (2016). “Generalized Bernoulli Polynomials and Numbers, Revisited.” Mediterr. J. Math., 13(1), 141–151. ISSN 1660-5454, https://doi.org/10.1007/s00009-014-0498-7.

Weisstein EW (2023). “Bernoulli Polynomial”, https://mathworld.wolfram.com/BernoulliPolynomial.html, MathWorld–A Wolfram Web Resource.

Helwig NE (2022). "Non-parametric Regression via Smoothing Splines", R package version 1.0-9, https://cran.r-project.org/web/packages/npreg/npreg.pdf.

Examples

## loading the built-in package example
## time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
    dir_ASC = tempdir(),
    dir_dsc_par =
      system.file("extdata",
                  package = "eprscope")
   )
#
## select the first spectrum
triarylamine.decay.series.data1st <-
   triarylamine.decay.series.data$df %>%
     dplyr::filter(time_s ==
       triarylamine.decay.series.data$time[1])
#
## smoothing the 1st EPR spectrum with default
## arguments/parameters
triarylamine.1st.spec.smooth <-
  smooth_EPR_Spec_by_npreg(data.spectr =
    triarylamine.decay.series.data1st
    )
#
## plot preview
triarylamine.1st.spec.smooth$plot
#
## sum of residual squares preview
triarylamine.1st.spec.smooth$rss
#
## estimated standard deviation
triarylamine.1st.spec.smooth$sigma
#
## smoothing of all EPR spectra in the series
## with default arguments using the data
## "pipe" ("%>%") `dplyr` processing
triarylamine.all.spec.smooth <-
  triarylamine.decay.series.data$df %>%
    dplyr::group_by(time_s) %>%
    dplyr::mutate(smoothed =
      smooth_EPR_Spec_by_npreg(
        dplyr::pick(B_mT,dIepr_over_dB),
        output.vec = TRUE
     )
  )
#
## data frame preview
head(triarylamine.all.spec.smooth)
#
## plot all smoothed spectra in the series
plot_EPR_Specs(data.spectra =
          triarylamine.all.spec.smooth,
  Intensity = "smoothed",
  var2nd.series = "time_s",
  var2nd.series.slct.by = 10,
  line.colors = c("darkorange",
                  "darkblue"),
  legend.title = "Time (s)",
  yTicks = TRUE
  )


## loading the built-in package example
## time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
    "Triarylamine_radCat_decay_series",
    dir_ASC = tempdir(),
    dir_dsc_par =
      system.file("extdata",
                  package = "eprscope")
   )
#
## select the first spectrum
triarylamine.decay.series.data1st <-
   triarylamine.decay.series.data$df %>%
     dplyr::filter(time_s ==
       triarylamine.decay.series.data$time[1])
#
## smoothing the 1st EPR spectrum with default
## arguments/parameters
triarylamine.1st.spec.smooth <-
  smooth_EPR_Spec_by_npreg(data.spectr =
    triarylamine.decay.series.data1st
    )
#
## plot preview
triarylamine.1st.spec.smooth$plot
#
## sum of residual squares preview
triarylamine.1st.spec.smooth$rss
#
## estimated standard deviation
triarylamine.1st.spec.smooth$sigma
#
## smoothing of all EPR spectra in the series
## with default arguments using the data
## "pipe" ("%>%") `dplyr` processing
triarylamine.all.spec.smooth <-
  triarylamine.decay.series.data$df %>%
    dplyr::group_by(time_s) %>%
    dplyr::mutate(smoothed =
      smooth_EPR_Spec_by_npreg(
        dplyr::pick(B_mT,dIepr_over_dB),
        output.vec = TRUE
     )
  )
#
## data frame preview
head(triarylamine.all.spec.smooth)
#
## plot all smoothed spectra in the series
plot_EPR_Specs(data.spectra =
          triarylamine.all.spec.smooth,
  Intensity = "smoothed",
  var2nd.series = "time_s",
  var2nd.series.slct.by = 10,
  line.colors = c("darkorange",
                  "darkblue"),
  legend.title = "Time (s)",
  yTicks = TRUE
  )

Solvent Properties Data Frame (Dataset) for EPR/ENDOR

Description

Data frame summarizing the most important solvent properties for EPR/ENDOR which are required for variable temperature (VT) experiments and EPR spectroelectrochemistry.

Usage

solvents_ds
solvents_ds

Format

A data frame with 46 rows and 10 variables/columns:

Solvent: Character, solvent name.
Formula: Character, ponting to molecular formula.
MW: Numeric, pointing to relative molecular weight.
Boiling_Point_oC: Numeric, corresponding to boling point in °C.
Melting_Point_oC: Numeric, corresponding melting point in °C.
Density_gmL: Numeric, corresponding to density in $\text{g}\,\text{mL}^{-1}$ .
Solubility_g100gW: Character, pointing to solubility in water expressed in $\text{g}\,(100\,\text{g}~\text{of}~\text{H}_2\text{O})^{-1}$ . 2. Solubility of THF in water is rather complex.
Dielectric_Const: Character, corresponding to relative permittivity.
Flash_Point_oC: Numeric, pointing to flash point in °C.
Viscosity_cp: Character, corresponding to solvent dynamic viscosity in $\text{cp}\equiv 1\,\text{mPa}\,\text{s}$ . The values were collected from Sigma-Aldrich for 20°C; PubChem NCBI for 20°C and 25°C and from ACCU DYNE TEST for 20°C, 25°C or 30°C.

Details

The main properties were collected from the Division of Organic Chemistry of the ACS and the Sigma-Aldrich. Additional resources (e.g. for viscosities) are PubChem NCBI and ACCU DYNE TEST. Besides that, the polarity of solvents (expressed by the relative permitivity Dielectric_Const) is important parameter to decide which tube/cell has to be used for an experiment at specific temperature (unless the measurements performed directly in liquid $\text{N}_2$ ) => for the polar solvents use capillaries or special "flat" cells (e.g. for EPR spectroelectrochemistry), while for the less polar solvents, common quartz tubes (with the i.d. of $(2-4)\,\text{mm}$ ) can be applied. See also vignette("datasets").

Source

https://organicchemistrydata.org/solvents/

https://www.sigmaaldrich.com/deepweb/assets/sigmaaldrich/marketing/global/documents/614/456/labbasics_pg144.pdf

https://pubchem.ncbi.nlm.nih.gov/

https://www.accudynetest.com/visc_table.html

Package 'eprscope'

Help Index

Convert Coupling Constants into Splitting Ones.

Description

Usage

Arguments

Details

Value

See Also

Examples

Convert Splitting Constants into Coupling Ones.

Description

Usage

Arguments

Details

Value

See Also

Examples

Conversion of Magnetic Flux Density

Description

Usage

Arguments

Value

See Also

Examples

Convert Time ttt into Variable Linearly Depending on ttt.

Description

Usage

Arguments

Details

Value

See Also

Examples

Time Correction for the Experimental CW EPR Time Series.

Description

Usage

Arguments

Details

Value

See Also

Examples

Basic Quarto Reproducible Project File/Folder Structure for the EPR Reports

Description

Usage

Arguments

Details

Value

References

Examples

Draw Molecule by {rcdk} Defined by SMILES or SDF

Description

Usage

Arguments

Value

See Also

Examples

Calculation of EPR/ENDOR Spectrum Linewidth ( e.g. ΔBpp\Delta B_{pp}ΔBpp​)

Description

Usage

Arguments

Value

See Also

Examples

Transferred Charge and Number of Electrons from Chronoamperogram

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Find Intensity Extremes within the EPR/ENDOR Spectrum

Description

Usage

Arguments

Value

See Also

Examples

Evaluating Full Width at Half-Maximum (FWHM) from Integrated EPR Spectrum

Convert Time $t$ into Variable Linearly Depending on $t$ .

Draw Molecule by `{rcdk}` Defined by SMILES or SDF

Calculation of EPR/ENDOR Spectrum Linewidth ( e.g. $\Delta B_{pp}$ )

Basic Calculation of $g$ -factor

Calculation of $g$ -factor from Quantum Chemical Computational Output

Calculation of $g$ -factor ("Position") from EPR Spectrum/Data