| 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 main emphasis is on continuous wave (CW) EPR/ENDOR, many functions may be also used for the integrated forms of 1D PULSED EPR spectra. The primary goal is 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. Therefore, processing of data/spectra for the analytical (quantitative) purposes belongs to the package core. The aim is to evaluate rate constants, considering different kinetic models, to describe the radical reactions. Following the 'reading' of EPR spectral data (also providing automatic procedures for the most common spectrometers/acquisition softwares) a transformation into the universal R 'data frame' format is supported. Subsequently, all the EPR spectra can be visualized and are fully consistent either with the 'ggplot2' package or with the interactive formats based on 'plotly'. Package also covers simulations and fitting of the isotropic (solution) EPR spectra. In addition, the advanced simulation parameters obtained 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-form in order to analyze the EPR spectra by the most effective way. Reproducible reports of the entire data processing and analysis can be created by the quarto publishing system, resulting in various formats like '.pdf','.docx','.html'. |
| Authors: | Ján Tarábek [aut, cre] (ORCID: <https://orcid.org/0000-0003-0116-3824>) |
| Maintainer: | Ján Tarábek <[email protected]> |
| License: | GPL (>= 3) + file LICENSE |
| Version: | 0.1.17 |
| Built: | 2026-06-05 06:31:25 UTC |
| Source: | https://github.com/jatanrt/eprscope |
Converting hyperfine coupling constants (HFCCs, values in MHz)
into hyperfine splitting ones (HFSCs, values in mT).
convert_A_MHz_2a(A.MHz, g.val = 2.0023193)convert_A_MHz_2a(A.MHz, g.val = 2.0023193)
A.MHz |
Numeric value/vector, corresponding to HFCCs in |
g.val |
Numeric value/vector, corresponding to actual |
Conversion performed according to the following relation:
where corresponds to Planck's constant and to Bohr's magneton.
Both latter are obtained by the constans::syms$h and constants::syms$mub, respectively,
using the constants package (see syms).
Conversion is suitable for the EPR simulations and/or ENDOR.
Numeric value/vector corresponding to HFSCs () in mT.
Other Conversions and Corrections:
convert_B(),
convert_a_mT_2A(),
convert_time2var(),
correct_time_Exp_Specs()
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)
Converting hyperfine splitting constants (HFSCs, values in mT)
into hyperfine coupling ones (HFCCs, values in MHz).
convert_a_mT_2A(a.mT, g.val = 2.0023193)convert_a_mT_2A(a.mT, g.val = 2.0023193)
a.mT |
Numeric value/vector of HFSCs in |
g.val |
Numeric value/vector, corresponding to actual |
Conversion performed according to the following relation:
where corresponds to Planck's constant and to Bohr's magneton.
Both latter are obtained by the constans::syms$h and constants::syms$mub, respectively,
using the constants package (see syms).
Conversion is suitable for the EPR simulations and/or ENDOR.
Numeric value/vector corresponding to HFCCs () in MHz.
Other Conversions and Corrections:
convert_A_MHz_2a(),
convert_B(),
convert_time2var(),
correct_time_Exp_Specs()
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/field (B) values depending on the input and the required output units.
convert_B(B.val, B.unit, B.2unit)convert_B(B.val, B.unit, B.2unit)
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 |
B.2unit |
Character string, referring to output magnetic flux density units.
Usually |
Numeric value or vector as a result of the B conversion. Depending on the output
unit (B.2unit) the values are rounded to:
7 decimal places
4 decimal places
3 decimal places
Other Conversions and Corrections:
convert_A_MHz_2a(),
convert_a_mT_2A(),
convert_time2var(),
correct_time_Exp_Specs()
## 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)
Conversion of time () into variable (), linearly changing in time.
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}" )
time.vals |
Numeric value or vector, corresponding to time (points) where the variable |
time.unit |
Character string, time unit defined by |
var0 |
Numeric, the initial value (ALSO WITH NEGATIVE SIGN, if required, e.g. negative electrochemical potential). |
var.switch |
Numeric, the switching point |
var.rate |
Numeric, corresponding to rate of linear |
var.rate.unit |
Character string, corresponding to |
The linear relationship between and time () can be expressed like
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 value depends on the switching one,
like =>
where the , corresponding to , are quantities
at the turning point( see also the var.switch argument).
Numeric value or vector of the variable such as electrochemical potential or temperature, linearly changing in time.
Other Conversions and Corrections:
convert_A_MHz_2a(),
convert_B(),
convert_a_mT_2A(),
correct_time_Exp_Specs()
## calculate potential in `V` after 50 s, starting from 200 mV ## into cathodic direction (reduction) by 5 mV s^{-1} convert_time2var(50,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 in `V` after 50 s, starting from 200 mV ## into cathodic direction (reduction) by 5 mV s^{-1} convert_time2var(50,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)
Providing more accurate time for EPR spectral line/spectrum appearance. It is assumed
that the middle (or , ...etc.) of the EPR spectrum
is set as the CF (central field) for the spectrum sweep.
correct_time_Exp_Specs(time.s, Nscans, sweep.time.s)correct_time_Exp_Specs(time.s, Nscans, sweep.time.s)
time.s |
Numeric value/vector/column in |
Nscans |
Numeric, number of accumulations (number of scans usually denoted as |
sweep.time.s |
Numeric, time (in |
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.
Numeric value/vector, corresponding to time at which the middle (-axis) of EPR
spectrum/spectra were recorded during the kinetic measurements (e.g. radical formation,
stability, electrochemical and/or photochemical measurements).
Other Conversions and Corrections:
convert_A_MHz_2a(),
convert_B(),
convert_a_mT_2A(),
convert_time2var()
## 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)
Creating files and folders for the basic Quarto project having
the structure shown in Details and corresponding to reproducible report with processing and analysis of EPR data.
The main .qmd ("quarto markdown") file, wd.subdir.name.qmd, is editable
(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 distributions: {tinytex} (R package),
Live or .
Instead of , the Quarto can be also used
in combination with the Typst markup language (written in Rust).
Please, refer to the Typst-Quarto documentation.
The complete, above-described R-environmental setup is also available
at Posit Cloud or at CoCalc,
which a is platform for collaborative calculations and data science.
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 )
title |
Character string, corresponding to title of the report like the default one:
|
path_to_wd |
Character string, setting up the path for working directory,
i.e. the parent one, where the project with |
wd.subdir.name |
Character string, pointing to |
citation.style |
Character string, referring to citation style used for |
Rproj.init |
Logical, whether to initiate the newly created repository/directory as
R-project
when working in RStudio. Therefore, default: |
git.init |
Logical, if |
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
.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 applied
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 | 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 intended for all raw files from EPR spectrometer, | | like .dsc/.DSC/.par, .DTA, .YGF | | | | | |—– EPR_ASCII | | | | | | | | |—–...folder intended for all additional text files from EPR spectrometer, | | like .txt, .csv, .asc | | | | | |—– EasySpin_Simulations | | | | | | | | |—–...folder intended 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/folders 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
formats stored under the _output. Among them, the .html output possesses
a distinctive position, because it preserves the structure of the 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. Additionally, if somebody wants
to use templates for ACS/Elsevier/PLOS/Nature-manuscripts, please refer
to the Quarto Jornal Articles Extenstion
for details of the installation and usage.
Users, applying a git version control of the project/report, may synchronize their entire directory
(as well as the corresponding changes) with the free remote services like Github
or Gitlab. If you've already set up your service account, create either public
or private repository (WITHOUT .gitignore, README and License !!) via desired web browser.
Afterwards, on your desktop/workstation, populate the file/folder structure, by the actual function (refer also
to the Examples), however DON'T FORGET to put git.init argument to TRUE! In the (IDE) terminal
(NOT IN THE R CONSOLE) set the path to your project (if it is not already set, check by pwd) and execute
the following commands step-by-step:
git remote add origin https://<service>/<user>/<remote repo name>.git, where the url address
can be copied by the clicking on the < > Code button when you're previewing the repository in the web browser.
git branch -M main, which renames the local master branch in order to match the remote name,
depending on the applied service. Please check the remote main/master branch name and adjust accordingly.
git push -u origin main. Before executing this command, please make sure that you've already created
a "Personal Access Token" (PAT) in your service account via the web browser, because it will be required upon
the command execution.
Refer to the
Github
or Gitlab documentation.
The strength of the local git - remote Github repositories synchronization lies
in the
seamless connection/integration
of your Zenodo and Github accounts in order to archive and point to the entire data
(DOI is automatically created) for a publication. The users may refer
to the Github repository example
in order to demonstrate such Github-Zenodo connection.
File-folder structure ("tree") for the basic Quarto report with R, which may be used for the reproducible data processing and analysis in Electron Paramagnetic Resonance (EPR) studies.
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.
Vanderhaeghe F (2022). "Set up Zenodo - Github Integration. How to configure Zenodo to publish each new release of a GitHub repository?", https://tutorials.inbo.be/tutorials/git_zenodo/.
## 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 ) # ## the following command will create "My_Lovely_EPR_Project" ## subdirectory/repository under the "Projects" (dir) entitled ## "EPR Studies on N-Centered Organic Radicals" using ## the `Positron` IDE (i.e. without `Rproj` initialization) create_qmdReport_proj( path_to_wd = "/home/Username/Projects", wd.subdir.name = "My_Lovely_EPR_Project", title = "EPR Studies on N-Centered Organic Radicals", Rproj.init = FALSE ) # ## afterwards, the `README.md` file can be generated by rendering ## the corresponding `.Rmd`, in the newly populated repo, ## which is automatically created upon executing ## the previous command ## 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 ) # ## the following command will create "My_Lovely_EPR_Project" ## subdirectory/repository under the "Projects" (dir) entitled ## "EPR Studies on N-Centered Organic Radicals" using ## the `Positron` IDE (i.e. without `Rproj` initialization) create_qmdReport_proj( path_to_wd = "/home/Username/Projects", wd.subdir.name = "My_Lovely_EPR_Project", title = "EPR Studies on N-Centered Organic Radicals", Rproj.init = FALSE ) # ## afterwards, the `README.md` file can be generated by rendering ## the corresponding `.Rmd`, in the newly populated repo, ## which is automatically created upon executing ## the previous command ## End(Not run)
{rcdk} Defined by SMILES or SDFDrawing a molecular structure based on rcdk package by using SMILES or SDF input data.
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, ... )
molecule |
Character input string => either SMILES strings (in case
of |
||||||||||||
type |
Character string referred to the original molecular type input =>
either |
||||||||||||
mol.label |
Character string, pointing to name of the molecule/compound, e.g.
|
||||||||||||
mol.label.color |
Character string, pointing to displayed font color of the chemical structure
label. Default: |
||||||||||||
mol.label.xy.posit |
Numeric vector of two values, matching the |
||||||||||||
sma |
Character string, allowing to highlight sub-structures using
|
||||||||||||
annotate |
Character string, whether to display ( |
||||||||||||
style |
Character string, denoting the plotting style like =>
Default: |
||||||||||||
abbr |
Character string, which controls how the structure is displayed. Following options
can be set => |
||||||||||||
suppressh |
Logical, denoting whether to suppress displaying of the hydrogen atoms.
The |
||||||||||||
... |
additional options/arguments for the |
Graphics/Figure object with molecular structure.
Other Visualizations and Graphics:
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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")
When comparing different (simulation) fits for the same experimental data (see
eval_sim_EPR_isoFit, eval_kinR_EPR_modelFit, eval_kinR_Eyring_GHS,
smooth_EPR_Spec_by_npreg or eval_sim_EPR_isoFit_space), they can be scored/ranked by different
metrics (e.g. by the minimum sum of residual squares or standard deviation of residuals), including
Akaike and Bayesian Information Criteria (AIC and BIC, respectively).
These are also applied for the best model selection in machine learning (refer to e.g.
Predictive Modelling and Machine Learning or
Error Estimation and Model Selection).
As described in details, both metrics depends on maximum logarithmic likelihood (based on residuals calculation)
to the same data. The smaller the (negative) AIC or BIC, the better the model/fit.
eval_ABIC_forFit(data.fit, residuals = NULL, k, residuals.distro = "auto")eval_ABIC_forFit(data.fit, residuals = NULL, k, residuals.distro = "auto")
data.fit |
Data frame object, usually containing variables/columns like |
residuals |
Character string, pointing to variable/column header with residuals/errors, depending
on the |
k |
Numeric value identical to number of parameters used for the model/fit
(see e.g. |
residuals.distro |
Character string, corresponding to proposed probability distribution that describes
the residuals/errors appearance. If set to default ( |
Estimation of model errors, that model/fit makes in respect to our (experimental) data, becomes
one of the most consequential aspects of a statistical (machine learning) analysis. Often, different
modelling/fitting approaches are used, with the attempt to identify or select the best model/fit. Therefore,
for such purpose, one tries to minimize the errors/residuals more and more with each model. Or to put it another way,
there is an information loss when the model/fit approximates the reality and a good model minimizes
those losses. The evaluation of AIC and BIC actually approaches the problem from the other side,
because it uses the technique called maximum likelihood estimate (MLE). The idea is to maximize the chance
that each observation in the sample follows a pre-selected distribution with specific
set of parameters (corresponding to a model/fit). For practical reasons a logarithmic likelihood
(or log-likelihood,) is used, and the formulae for both criteria read:
and
where and correspond to number of (model/fit) parameters and number of observations, respectively.
The 3rd term in the definition represents the correction for small sample/observation ensemble, which
for high number of observations becomes very small (and can be neglected,
see e.g. Burnham and Anderson (2004) in the References). For example, for EPR simulation
fit with 2048 points and 8 parameters it equals to . However, for
radical kinetic measurements with 42 EPR spectra and 3 parameters, the 3rd term results
in .
The original MLE/ calculation is based on the model. Nevertheless, such computation can be quite often
impractical or even impossible to perform. To overcome this difficulty, the formulae for both criteria
use a standard assumption that the model and the data residuals/errors are identically distributed.
Therefore, the residuals/errors are applied as a proxy for the MLE/ (see e.g. Rossi et al. (2020)
in the References). Evaluation of the latter, in the actual function, proceeds via sum
of three main probability distributions for residuals (additional distributions may be added in the newer package versions):
1. the stats::dnorm (for the normal/Gaussian distribution); 2. the stats::dt
(for the Student's t-distribution) and 3. the stats::dcauchy,
using the log = TRUE option. For t-distribution the df/
parameter is unknown, therefore it is optimized by the above-described
as well as by the optimize functions. Even though the Student's distribution approaches the normal
one at df > 29, sometimes the heavy tails of residuals for high number of observations can be modeled
by t-distribution with lower df. All probability distributions are included in the function because not always
the residuals/errors follow the normal one. Particularly, if heavier tails
appear, e.g. for EPR simulation fits (please, refer to the Examples in the eval_sim_EPR_isoFit).
Consequently, the function may automatically (see the argument residuals.distro) decide which distribution
fits the residuals/errors the best, based on the lowest AIC, BIC values. This is additionally supported by the Shapiro-Wilk
(shapiro.test) as well as by the Kolmogorov-Smirnov (ks.test) tests,
providing the information whether the residuals distribution is normal
(or not at all). It is recommended to evaluate/apply both information criteria.
The AIC tends to favor a more complex model (over a simpler one) and thus suggests to "overfit" the data, whereas
the BIC is in favor of simpler models because it possesses a stronger penalty () for complex models
than AIC (,see e.g. Fabozzi et al. (2014) and Zhang Y, Meng G (2023) in the References).
Function returns a list with the following components:
A numeric vector containing the values of estimated AIC and BIC, respectively.
Sentence (message), describing the residuals/errors appearance by the
probability distribution which has been proposed for the AIC and BIC calculation (see also
the residuals.distro argument). Such information is additionally supported by the Shapiro-Wilk
and/or by the Kolmogorov-Smirnov tests, whether the residuals distribution can be considered as a normal or not.
These tests are based on the corresponding p-values. However, in order to clearly support the lowest AIC/BIC,
depending on residuals distribution, a slightly "broader", than the commonly applied "sharp"/"rigid"
threshold, is applied. If , there is a stronger evidence against the null-hypothesis
that the residuals are normally distributed. Therefore, we can only weakly support the normal distribution,
however may prefer the other ones (Student's or Cauchy). Contrary, if , we may support
the null-hypothesis that the residuals are normally distributed. Consequently, there is less evidence
for other distributions like Student's or Cauchy. If the is from the "gray" (0.01,0.05) zone/interval
no support by the above-mentioned normality tests is provided.
Fabozzi FJ, Focardi FM, Rachev ST, Arshanapalli BG (2014). The Basics of Financial Econometrics: Tools, Concepts, and Asset Management Applications (Appendix E), John Wiley and Sons, Inc. ISBN 978-1-118-57320-4, https://onlinelibrary.wiley.com/doi/book/10.1002/9781118856406.
Soch J et al. (2024). StatProofBook/StatProofBook.github.io: The Book of Statistical Proofs (Version 2023)., https://statproofbook.github.io/, https://doi.org/10.5281/ZENODO.4305949.
Burnham KP, Anderson DR (2004). "Multimodel Interference: Understanding AIC and BIC in Model Selection", Sociol. Methods Res., 33(2), 261-304, https://doi.org/10.1177/0049124104268644.
Thulin M (2025). Modern Statistics with R: From Wrangling and Exploring Data to Inference and Predictive Modeling, 2nd edition (Version 2.0.2), CRC Press and Taylor and Francis Group, LLC. ISBN 978-1-032-51244-0, https://www.modernstatisticswithr.com/.
Zhang Y, Meng G (2023). "Simulation of an Adaptive Model Based on AIC and BIC ARIMA Predictions", J. Phys.: Conf. Ser., 2449, 012027-7, https://doi.org/10.1088/1742-6596/2449/1/012027.
Svetunkov I (2022). Statistics for Business Analytics, Version 2025, https://openforecast.org/sba/.
Rossi R, Murari R, Gaudio P, Gelfusa M (2020). "Upgrading Model Selection Criteria with Goodness of Fit Tests for Practical Applications", Entropy, 22(4), 447-13, https://doi.org/10.3390/e22040447.
Hyndman RJ, Athanasopoulos G (2021). Forecasting: Principles and Practise, 3rd edition, O Texts, ISBN 978-0-987-50713-6, https://otexts.com/fpp3/.
Hyndman RJ (2013). "Facts and Fallacies of the AIC", https://robjhyndman.com/hyndsight/aic/.
Other Simulations and Optimization:
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## Not run: ## to decide which probability distribution fits ## the best to residuals/errors calc.abic.list.01 <- eval_ABIC_forFit( data.fit = triaryl_model_kin_fit_01$df, residuals = "residuals", k = 2, residuals.distro = "auto" ) # ## AIC and BIC values calc.abic.list.01$abic.vec # ## ...and the corresponding message calc.abic.list.01$message # ## calculation of AIC and BIC, taking into ## account the Student's t-distribution: calc.abic.list.01 <- eval_ABIC_forFit( data.fit = best.sim.fit.df, residuals = "Errors", k = 8, residuals.distro = "t-distro" ) # ## for additional applications please, ## refer to the Examples in `eval_sim_EPR_isoFit()` ## or `eval_kinR_EPR_modelFit()` # ## End(Not run)## Not run: ## to decide which probability distribution fits ## the best to residuals/errors calc.abic.list.01 <- eval_ABIC_forFit( data.fit = triaryl_model_kin_fit_01$df, residuals = "residuals", k = 2, residuals.distro = "auto" ) # ## AIC and BIC values calc.abic.list.01$abic.vec # ## ...and the corresponding message calc.abic.list.01$message # ## calculation of AIC and BIC, taking into ## account the Student's t-distribution: calc.abic.list.01 <- eval_ABIC_forFit( data.fit = best.sim.fit.df, residuals = "Errors", k = 8, residuals.distro = "t-distro" ) # ## for additional applications please, ## refer to the Examples in `eval_sim_EPR_isoFit()` ## or `eval_kinR_EPR_modelFit()` # ## End(Not run)
Calculating the peak-to-peak (distance between the x-axis
projection of "min" and "max" derivative intensities) linewidth of an EPR/ENDOR spectrum.
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 )
data.spectr |
EPR/ENDOR spectrum data frame object with magnetic flux density B (in |
x |
Character string, pointing to name of the |
Intensity |
Character string, pointing to name of the |
xlim |
Numeric vector, corresponding to lower and upper limit of the selected x-region,
such as |
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.
Other Evaluations:
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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
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 vs 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 vs (time) or as vs
(potential, if available in the input data.at).
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 )
data.at |
Data frame (table) object, including required columns like |
time |
Character string, pointing to |
time.unit |
Character string, pointing to |
tlim |
Numeric vector of the |
Current |
Character string, indicating the |
Current.unit |
Character string, pointing to |
E |
Character string, referring to |
E.unit |
Character string, setting the potential unit (see |
ref.electrode |
Character string, corresponding to reference electrode notiation/label, e.g.
|
Ne.output |
Logical. Should be the number of transferred electrons ( |
separate.plots |
Logical. By default, both relations: |
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 () are evaluated from quantitative measurements (see also
quantify_EPR_Abs), whereas number of transferred electrons () is related
to charge (), according to:
where stands for the Avogadro's number and 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 are close (),
it reveals the presence of one-electron oxidation/reduction, while totally different numbers may point
to a more complex mechanism (such as comproportionation, follow-up reactions, multiple electron transfer).
List containing the following elements, depending on separate.plots:
If separate.plots = FALSE
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 ) and Ne (number of transferred
electrons, if Ne.output = TRUE).
Side-by-side plot object of vs
as well as vs .
If separate.plots = TRUE
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 ) and Ne (number of transferred
electrons, if Ne.output = TRUE).
Plot object of vs .
Plot object of vs .
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.
Other EPR Spectroelectrochemistry:
plot_ECh_VoC_amperogram()
## 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
Finding the x positions like B (in mT, G or T), 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 as well.
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" )
data.spectr |
EPR/ENDOR spectrum data frame object with magnetic flux density B (in |
x |
Character string, pointing to name of the |
Intensity |
Character string, pointing to name of the |
xlim |
Numeric vector, corresponding to lower and upper limit of the selected x-region,
such as |
extreme |
Character string with only two values allowed: |
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.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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_file = 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_file = 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)
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 ( and ) having the intensity
closest to the intensity maximum/2, corresponding to one individual EPR line/peak defined
by the xlim argument.
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 )
data.spectr.integ |
Data frame object, containing |
x |
Character string, pointing to name of the |
Intensity |
Character string, pointing to name of the |
xlim |
Numeric vector, corresponding to lower and upper limit of the selected x-region,
e.g. |
Numeric value of the FWHM, directly from EPR spectrum, depending on the x variable =>
either in mT/G/T or unitless in case if g-factor is presented on abscissa.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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" ) %>% plotly::layout( xaxis = list(range = c(3490,3500)) ) ## from the two central lines the following ## values can be read out 3495.568 - 3495.031 3497.375 - 3496.838## 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" ) %>% plotly::layout( xaxis = list(range = c(3490,3500)) ) ## from the two central lines the following ## values can be read out 3495.568 - 3495.031 3497.375 - 3496.838
Calculation of -factor according to fundamental formula (see Value).
The magnetic flux density (B.val) and microwave frequency (nu.val,)
can be defined, having the common units like G (Gauss) mT
(millitesla) or T (tesla) as well as GHz or Hz.
eval_gFactor(nu.val, nu.unit = "GHz", B.val, B.unit = "mT")eval_gFactor(nu.val, nu.unit = "GHz", B.val, B.unit = "mT")
nu.val |
Numeric, microwave Frequency value. |
nu.unit |
Character string, frequency unit defined by |
B.val |
Numeric, magnetic flux density value. |
B.unit |
Character string, magnetic flux density unit in |
-Value from . Physical constants (
and ) are taken from constants
package by the syms.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
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")
In the Gaussian and ORCA outputs, the -value (its 3 principal components) is presented in the form
of differences from the ( of the free electron). Therefore, the function takes those values
to calculate the entire -factor components or parses the corresponding -mean value
from the outputs.
eval_gFactor_QCHcomp(path_to_QCHoutput, mean = TRUE, origin = "gaussian")eval_gFactor_QCHcomp(path_to_QCHoutput, mean = TRUE, origin = "gaussian")
path_to_QCHoutput |
Character string, corresponding to path of "Gaussian" or "ORCA" output text files
including all |
mean |
Logical, whether to calculate the |
origin |
Character string, pointing to origin of the EPR calculation parameters <=> which
software package was used. Only two values are available => |
Numeric mean -factor value from the principal difference (from ) components
calculated by the QCH method (e.g. by DFT) or numeric vector with the principal -components
if mean = FALSE.
Other Evaluations and Quantum Chemistry:
rearrange_aAiso_QCHcomp(),
rearrange_aAiso_QCHorgau()
## 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-value according to fundamental formula, see eval_gFactor.
-related magnetic flux density (like or )
is directly taken from the EPR spectrum by the eval_peakPick_Spec. If positive and negative
derivative intensities of the spectral line are similar and their distances from the middle
point of the spectrum are close, the should be considered.
Otherwise, the must be taken
into account. In case of integrated EPR spectrum/data, the is/are used for
the -value calculation. If instead of one central two -values/lines appear,
the function automatically calculates the middle point between both.
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 )
data.spectr |
Spectrum data frame object where the magnetic flux density (in |
nu.GHz |
Numeric value, microwave frequency in |
B.unit |
Character string, denoting the magnetic flux density unit e.g. |
B |
Character string, pointing to magnetic flux density |
Intensity |
Character string, pointing to |
lineSpecs.form |
Character string, describing either |
Blim |
Numeric vector, magnetic flux density in |
iso |
Logical, whether to calculate the |
Numeric -value ('iso' = 'isotropic') or ,
from the EPR spectrum, according to .
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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_file = 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_file = 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))
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.
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, vectorize = 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, vectorize = FALSE )
data.spectr |
Spectrum data frame/table object with magnetic flux density (in |
B |
Character string, pointing to magnetic flux density column header (in the original
|
B.unit |
Character string pointing to unit of magnetic flux density, which
is to be presented on |
Intensity |
Character string, pointing to column name of either derivative
(e.g. |
lineSpecs.form |
Character string, describing either |
Blim |
Numeric vector, magnetic flux density in |
correct.integ |
Logical, whether to correct the integral by baseline polynomial model fit.
Default: |
BpeaKlim |
Numeric vector, magnetic flux density in |
poly.degree |
Numeric, degree of the polynomial function used to fit baseline under the single
integrated curve of the original EPR spectrum (see also |
sigmoid.integ |
Logical, whether to involve (column in data frame) double integral or single
integral (if the |
vectorize |
Logical, whether the integrals correspond to new columns within the original |
The relative error of the cumulative trapezoidal (cumtrapz) function is minimal,
usually falling into the range of 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 need B.units = "G"
(see Arguments). Hence, depending on -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 and .
Such corrections are already included in the actual function.
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.
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
(vectorize = FALSE) or vectors/vectors list, corresponding to individual baseline
corrected/uncorrected integrals (vectorize = 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 ) 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 or Intens_Integ_correct.
This is the case if correct.integ = TRUE
and sigmoid.integ = FALSE + vectorize = FALSE.
Data frame with single and double/sigmoid integral column/variable
(sigmoid_Integ), essential for the quantitative analysis. For such case it applies:
vectorize = FALSE and correct.integ = FALSE.
Data frame in case of correct.integ = TRUE, sigmoid.integ = TRUE
and vectorize = FALSE. It contains the original data frame columns + corrected
single integral (single_Integ_correct or Intens_Integ_correct in case of integrated
spectrum input) 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/intensity
in case of sigmoid.integ = FALSE + vectorize = TRUE.
List of numeric vectors (if vectorize = TRUE and sigmoid.integ = TRUE)
corresponding to:
Corrected or uncorrected single integral (in case of derivative form),
depending on the correct.integ argument.
Double integral (in case of derivative form) or single integral (in case of integrated spectral form) for quantitative analysis.
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.
Other Evaluations and Quantification:
eval_kinR_EPR_modelFit(),
eval_kinR_ODE_model(),
quantify_EPR_Abs(),
quantify_EPR_Norm_const()
## 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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") triarylamine.decay.series.ygf.path <- load_data_example(file = "Triarylamine_radCat_decay_series.YGF") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path, path_to_ygf = triarylamine.decay.series.ygf.path ) # ## 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 (2nd integ.,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, vectorize = 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, vectorize = TRUE)$sigmoid ) %>% dplyr::summarize(Area = max(sigmoid_Integ)) ## in such case `Blim` range is not defined by ## the `eval_integ_EPR_Spec`, however the `Blim = NULL` ## as well as the `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) # ## integral of the PNT EPR spectrum in integrated form, ## first generate the simulated spectrum/data pnt.sim.integ.iso <- eval_sim_EPR_iso(g.iso = 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 = "Integ_Intensity" ) ## data frame preview head(pnt.sim.integ.iso$df) # ## integrated EPR spectrum preview pnt.sim.integ.iso$plot # ## no integration in case of integrated `lineSpecs.form` ## if `sigmoid.integ = FALSE` intens.integ.NOcorrect.df <- eval_integ_EPR_Spec( data.spectr = pnt.sim.integ.iso$df, B = "Bsim_G", Intensity = "Integ_Intensity", lineSpecs.form = "integrated" ) ## data frame preview head(intens.integ.NOcorrect.df) # ## in order to obtain sigmoid integral, ## assign `sigmoid.integ = TRUE` sigmoid.integral.df <- eval_integ_EPR_Spec( data.spectr = pnt.sim.integ.iso$df, B = "Bsim_G", Intensity = "Integ_Intensity", lineSpecs.form = "integrated", sigmoid.integ = TRUE ) ## data frame preview head(sigmoid.integral.df) # ## plot previous integral plot_EPR_Specs( sigmoid.integral.df, x = "Bsim_G", x.unit = "G", Intensity = "sigmoid_Integ", lineSpecs.form = "integrated" )## 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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") triarylamine.decay.series.ygf.path <- load_data_example(file = "Triarylamine_radCat_decay_series.YGF") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path, path_to_ygf = triarylamine.decay.series.ygf.path ) # ## 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 (2nd integ.,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, vectorize = 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, vectorize = TRUE)$sigmoid ) %>% dplyr::summarize(Area = max(sigmoid_Integ)) ## in such case `Blim` range is not defined by ## the `eval_integ_EPR_Spec`, however the `Blim = NULL` ## as well as the `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) # ## integral of the PNT EPR spectrum in integrated form, ## first generate the simulated spectrum/data pnt.sim.integ.iso <- eval_sim_EPR_iso(g.iso = 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 = "Integ_Intensity" ) ## data frame preview head(pnt.sim.integ.iso$df) # ## integrated EPR spectrum preview pnt.sim.integ.iso$plot # ## no integration in case of integrated `lineSpecs.form` ## if `sigmoid.integ = FALSE` intens.integ.NOcorrect.df <- eval_integ_EPR_Spec( data.spectr = pnt.sim.integ.iso$df, B = "Bsim_G", Intensity = "Integ_Intensity", lineSpecs.form = "integrated" ) ## data frame preview head(intens.integ.NOcorrect.df) # ## in order to obtain sigmoid integral, ## assign `sigmoid.integ = TRUE` sigmoid.integral.df <- eval_integ_EPR_Spec( data.spectr = pnt.sim.integ.iso$df, B = "Bsim_G", Intensity = "Integ_Intensity", lineSpecs.form = "integrated", sigmoid.integ = TRUE ) ## data frame preview head(sigmoid.integral.df) # ## plot previous integral plot_EPR_Specs( sigmoid.integral.df, x = "Bsim_G", x.unit = "G", Intensity = "sigmoid_Integ", lineSpecs.form = "integrated" )
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,...etc from several experiments/observations.
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)
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:
|
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 |
The confidence interval evaluation suggests two-tailed Student's t-distribution,
which for number of observations approaches the normal -distribution.
Evaluation of the confidence interval and/or its limits can be well documented on -factor series example:
where is the mean value and the corresponds to the quantile
of the t-distribution having the significance level of (,
see the level.cnfd argument) and the degrees of freedom . Finally, the represents
the sample standard deviation, defined by the following relation (regarding the -value series example):
which is computed by the sd function. The above-mentioned -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.
Named vector of (mean) value and uncertaity or
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).
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.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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)
Fitting of the integrals/areas/concentration/...etc. vs time relation (either from experiment
or by integration of the EPR spectral time series) in order to find the kinetic parameters
(like rate constant, 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 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 by the integrals/areas vs time fit.
Therefore, the unit of might be expressed in terms of including units of integrals/areas,
e.g. procedure defined unit (see p.d.u.),
depending on the order of reaction (see the params.guess argument).
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, ... )
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.unit |
Character string, corresponding to time unit like |
||||||||||||||||
time |
Character string, pointing to |
||||||||||||||||
qvarR |
Character string, pointing to |
||||||||||||||||
model.react |
Character string, denoting a specific radical (
Couple of examples are also given in the |
||||||||||||||||
elementary.react |
Logical, if the model reaction should be considered as an elementary one,
i.e. the stoichiometric coefficients equal to the partial reaction orders. Such reaction proceeds without
identifiable intermediate species forming. Default: |
||||||||||||||||
params.guess |
Named vector, initial values of |
||||||||||||||||
params.guess.lower |
Numeric vector of lower bounds on each parameter in |
||||||||||||||||
params.guess.upper |
Numeric vector of upper bounds on each parameter in |
||||||||||||||||
fit.kin.method |
Character string, pointing to optimization/fitting method. So far,
the default one ( |
||||||||||||||||
solve.ode.method |
Character string, setting up the integrator (the |
||||||||||||||||
time.frame.model |
Numeric value, corresponding to interval time resolution, i.e. the smallest time difference
between two consecutive points in
where the |
||||||||||||||||
time.correct |
Logical, if time of recorded series of the EPR spectra needs to be corrected.
Default: |
||||||||||||||||
path_to_dsc_par |
Character string, path (also provided by the |
||||||||||||||||
origin |
Character string, corresponding to software which was used to acquire the EPR spectra,
essential to load the parameters by the |
||||||||||||||||
... |
additional arguments for |
List with the following components is available:
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 object Quantitative variable vs Time with the experimental data and the corresponding fit.
Simple residual analysis - a list consisting of 5 elements: diagnostic plots
plot.rqq() function, plot.histDens; original data frame (df) with residuals and their corresponding
standard deviation (sd). For details, please refer to the plot_eval_RA_forFit.
The last element (plot.acf) is a diagnostic graph of the autocorrelation function
acf (see also References). This can be considered as a primary
"lie detector" test for the time series/kinetic models and it is defined as a correlation of residuals
with its own past and future values vs their corresponding lag. For a decent model, the ACF values
(except the first one perfect self-correlation) usually lie within
the confidence band (the light blue area within the plot.acf) for all lags.
Hence, there is no obvious periodical or whatsoever pattern and only a "white noise" is observed (a small and random
ACF distribution within the confidence band). If the user cannot be sure about a lag exceeding the confidence band,
please perform the Ljung-Box test Box.test and look for the p.value, whether
the autocorrelation is less (>> 0.05) or highly probable (<< 0.05).
Data frame object containing the optimized (best fit) parameter values (Estimates),
their corresponding standard errors, t- as well as p-values.
Covariance matrix, consisting of fitted/optimized kinetic parameters/coefficients
(see also df.coeffs above). The corresponding variances (diagonal elements) should be small,
indicating that the estimates possess a lower uncertainties.
The off-diagonal elements show, how the two coefficient estimates change together. For a decent model they should be
as close to 0 as possible. Large values may indicate
multicollinearity
with positive sign suggesting the coefficient are overestimated, and with a negative one, indicating that one coefficient
is over-, while the other one is underestimated.
Correlation matrix of fitted/optimized kinetic parameters/coefficients
(see also df.coeffs and cov.coeffs above). Such matrix can be additionally nicely visualized
by a correlation plot created by the corrplot function.
The off-diagonal elements should be as small as possible
(ideally close to 0) in order to exclude the multicollinearity (see the cov.coeffs) and to trust
the output with the optimized kinetic parameters. Larger cor.ceoffs (typically > (0.7,0.8)) indicate
potential multicollinearity.
Total number of evaluations/iterations before the best fit is found.
Minimum sum of residual squares after N.evals.
A list consisting of Akaike and Bayesian information criteria (AIC & BIC) vector (abic.vec)
and message, denoting the distribution of residuals/errors, applied to evaluate
those criteria. To be used when comparing different kinetic models. The lower the (negative) values,
the better the fit. Please, refer to the eval_ABIC_forFit.
Covariance matrix of a data frame, consisting of qvarR (e.g. double integral/Area - experiment),
fitted (kinetic model fit) and the corresponding residuals as columns/variables. Covariance between
the experiment and kinetic model should be positive and strong for a decent fit. Contrary, the cov between
the kinetic model fit and residuals should be ideally close to 0, indicating no systematic relationship.
However, the covariance is scale-depended and must be "normalized". Therefore, for such a purpose, the correlation
is defined as shown below.
Correlation matrix of a data frame, consisting of qvarR (e.g. double integral/Area - experiment),
fitted (kinetic model fit) and the corresponding residuals as columns/variables.
Such matrix can be additionally nicely visualized by a correlation plot created
by the corrplot function. A higher positive correlation
(between the integrals and the kinetic model fit), with the value close to 1, indicates that the kinetic model
fit nicely follows the integral(s) vs time relation. Contrary, no clear correlation between the residuals
and the experiment and/or kinetic model must be visible. Therefore, such correlation should be ideally close to 0.
Vector, corresponding to residual sum of squares at each iteration/evaluation.
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.
Hyndman RJ, Athanasopoulos G (2021). Forecasting: Principles and Practice, 3rd edition. OTexts: Melbourne, Australia, https://otexts.com/fpp3/.
geeksforgeeks (2025). "How to Test the Autocorrelation of the Residuals in R?", https://www.geeksforgeeks.org/machine-learning/how-to-test-the-autocorrelation-of-the-residuals-in-r/.
Hanck C, Arnold M, Gerber A, Schmelzer M (2025). Introduction to Econometrics with R. University of Duisburg-Essen, https://www.econometrics-with-r.org/.
Other Evaluations and Quantification:
eval_integ_EPR_Spec(),
eval_kinR_ODE_model(),
quantify_EPR_Abs(),
quantify_EPR_Norm_const()
## 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; third plot demonstrates ## the probability density with the histogram of residuals triaryl_model_kin_fit_01$ra$plot.rqq() triaryl_model_kin_fit_01$ra$plot.histDens # ## autocorrelation (ACF) of residuals vs lag triaryl_model_kin_fit_01$ra$plot.acf # ## standard deviation of residuals triaryl_model_kin_fit_01$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution triaryl_model_kin_fit_01$abic # ## 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 # ## simple residual analysis, indicating ## the 1st order kinetics is less convenient ## model than that of the 2nd order (based on ## the decrease of EPR intensity/integral) triaryl_model_kin_fit_02$ra$plot.rqq() # ## autocorrelation (ACF) of residuals vs lag triaryl_model_kin_fit_02$ra$plot.acf # ## standard deviation of residuals triaryl_model_kin_fit_02$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) + ## + information about the residuals distribution triaryl_model_kin_fit_02$abic## 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; third plot demonstrates ## the probability density with the histogram of residuals triaryl_model_kin_fit_01$ra$plot.rqq() triaryl_model_kin_fit_01$ra$plot.histDens # ## autocorrelation (ACF) of residuals vs lag triaryl_model_kin_fit_01$ra$plot.acf # ## standard deviation of residuals triaryl_model_kin_fit_01$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution triaryl_model_kin_fit_01$abic # ## 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 # ## simple residual analysis, indicating ## the 1st order kinetics is less convenient ## model than that of the 2nd order (based on ## the decrease of EPR intensity/integral) triaryl_model_kin_fit_02$ra$plot.rqq() # ## autocorrelation (ACF) of residuals vs lag triaryl_model_kin_fit_02$ra$plot.acf # ## standard deviation of residuals triaryl_model_kin_fit_02$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) + ## + information about the residuals distribution triaryl_model_kin_fit_02$abic
Finding the temperature-dependence of a rate constant () related to the elementary radical reaction, using the essential
transition state theory (TST). The activation parameters, such as and
are obtained either by the non-linear fit (see the general nls R function) or by the linear fit
(using the lm) of the Eyring expression (or its logarithmic linear form) on the original
vs 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 () is calculated, using the optimized
and , for each temperature in the series.
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" )
data.kvT |
Data frame object, which must include two essential columns: rate constant ( |
rate.const |
Character string, pointing to rate constant column header in the actual |
rate.const.unit |
Character string, referring to rate constant unit. This has to be specified using
the |
Temp |
Character string, pointing to temperature column header within the original |
Temp.unit |
Character string, corresponding to temperature unit related to |
transmiss.coeff |
Numeric value, corresponding to probability that the activated complex is transformed into products.
Default: |
fit.method |
Character string, corresponding to method applied to fit the theoretical Eyring relation
(by optimizing the activation parameters, see |
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 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 () must be related to the associated vibration
frequency (). Thus, every time, if the AC is formed, the of AC-dissociation
actually equals to . 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
(see also the argument transmiss.coeff), where .
According to statistical thermodynamics, the equilibrium constant can be expressed by the partition function ()
of the reactants and that of the AC. By definition, each 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):
where the and are the Boltzmann and Planck constants, respectively, corresponds
to temperature and finally, the 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 . Therefore, considering the equilibrium between the reactants and the AC,
one may express the in terms of Gibbs activation energy (),
because and thus the Eyring equation reads:
where is the universal gas constant and the upper index
denotes the standard molar state (see IUPAC (2019) in the References). Previous formula is applied
as a model to fit the experimental (see the argument data.kvT) relation, where both
the and the (in the graphical output, are also denoted as
and , 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 linear one,like
with the slope/coefficient
and the
as intercept of the relation. Nevertheless, the latter is not recommended as a model for fitting
the experimental (see also Lente G, Fábián I, Poë AJ (2005) in the References).
The reason inherits in the misinterpretation of the extrapolation to (or )
by which the is obtained and thus it is unreliable. Accordingly, the original exponential
Eyring form is recommended as a model to fit the experimental . Contrary, it may happen that
can vary in several () orders of magnitude within the studied temperature range and therefore, it is necessary
to proportionally weight the (see also Lente G, Fábián I, Poë AJ (2005) in the References). For the linear form,
weighting does not make a difference because the transformed span over a narrow range of values.
Therefore, it is advisable to perform the original exponential fit as well as the linear one within the studied temperature range
and compare both outcomes (both methods are involved in this function, see the argument fit.method).
The -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 :
where the goes through stoichiometric coefficients (including the negative sign for reactants)
of the AC formation reaction (therefore the index 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 s may actually fall into the order
of (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. For reactions like radical-radical recombination, where the barriers are typically very low, the tunneling probability is low (when there's essentially "no barrier", there's nothing to tunnel through). In addition, such reactions can proceed relatively fast and therefore the TST (Eyring fit) can also strongly bias the activation parameters. However, for radical reactions, involving the H-atom transfer or abstraction the tunneling can be important.
As a result of the Eyring-relation fit, list with the following components is available:
Data frame, including the original data.kvT + the column of ,
with the name of DeltaG_active_kJ_per_mol, as well as fitted/predicted values of the rate constant
and finally, the corresponding residuals. If fit.method = "linear" additional columns like reciprocal_T
and lnk_per_T are available, corresponding to and , respectively.
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 , according to
Eyring model.
Static ggplot2-based object, showing graphical representation of the (non-)linear fit, together with the Eyring equation.
Simple residual analysis - a list consisting of 4 elements: diagnostic plots
plot.rqq() function, plot.histDens; original data frame (df) with residuals and their corresponding
standard deviation (sd). For details, please refer to the plot_eval_RA_forFit.
Data frame object, containing the optimized (best fit) parameter values (Estimates),
their corresponding standard errors, t- as well as p-values for the corresponding Eyring model.
Data frame object, containing model characteristics (including information criteria like the AIC and BIC,
see also eval_kinR_EPR_modelFit and eval_ABIC_forFit).
Covariance matrix of a data frame, consisting of rate constant ( or ,
depending on the fit.method argument),
fitted (Eyring fit) and the corresponding residuals as columns/variables. Covariance between
the experiment ( vs or vs ) and the "Eyring" should be positive
and strong for a decent fit. Contrary, the cov between the Eyring fit and residuals should be ideally close to 0,
indicating no systematic relationship. However, the covariance is scale-depended and must be "normalized".
Therefore, for such a purpose, the correlation is defined as shown below.
Correlation matrix of a data frame, consisting of rate constant ( or ,
depending on the fit.method argument),
fitted (Eyring fit) and the corresponding residuals as columns/variables.
Such matrix can be additionally nicely visualized by a correlation plot created
by the corrplot function. A higher positive correlation
(between the vs or vs and the Eyring fit),
with the value close to 1, indicates that the Eyring fit nicely follows the -temperature dependence.
Contrary, no clear correlation between the residuals and the experiment and/or the "Eyring" must be visible.
Therefore, such correlation should be ideally close to 0.
Numeric vector, consisting of as well as ,
together with their uncertainties, all in SI units like J / (mol(* K)). Calculation of uncertainties for linear model
is performed by the error propagation, implemented
in {errors} R package, using the first
order Taylor series method.
If the fit.method IS DIFFERENT FROM "linear" a list, containing fitting/optimization
characteristics like number of evaluations/iterations
(N.evals) and character denoting the (un)successful convergence (message).
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.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_nu_ENDOR(),
eval_peakPick_Spec()
## 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) ) # ## original "Eyring" model activ.kinet.test01.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.test01.data$df # ## preview of the non-linear fit plot activ.kinet.test01.data$plot # ## preview of the optimized (activated) ## ∆S and ∆H parameters activ.kinet.test01.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) J/(mol*K) & ## ∆H = (118.80 +- 0.41) kJ/mol # ## brief model summary activ.kinet.test01.data$df.model.HS # ## ...and the corresponding analysis of residuals activ.kinet.test01.data$ra$plot.histDens # ## graphical representation the correlation matrix ## corresponding to Eyring fit activ.kinet.test01.data$cor.df %>% corrplot::corrplot(addCoef.col = "#c2c2c2") # ## preview of the convergence activ.kinet.test01.data$converg # ## this was an untransformed dataset, ## when the k values span more than 2 orders ## of magnitude => a proportional weighting ## or linear logarithmic model might be applied # ## take the same above-defined dataset and assign ## it to a new variable kinet.test.data.new <- 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) ) # ## linear logarithmic Eyring model activ.kinet.test02.data <- eval_kinR_Eyring_GHS( data.kvT = kinet.test.data.new, rate.const = "k_per_M_per_s", rate.const.unit = "M^{-1}~s^{-1}", Temp = "T_oC", Temp.unit = "oC", fit.method = "linear" ) # ## preview of the original data ## + ∆G (activated) + fitted + residuals + ## + additional variables of the linear model activ.kinet.test02.data$df # ## preview of the linear fit plot ## also with confidence interval (99 %) activ.kinet.test02.data$plot # ## preview of the optimized (activated) ## ∆S and ∆H parameters together with ## their uncertainties activ.kinet.test02.data$vec.HS.uncert # ## compare values with those presented in ## https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf ## ∆S = (11.33 +- 0.45) J/(mol*K) & ## ∆H = (120.27 +- 0.15) kJ/mol # ## brief model summary activ.kinet.test02.data$df.model.HS # ## corresponding analysis of residuals ## with residual standard deviation activ.kinet.test02.data$ra$plot.rqq() activ.kinet.test02.data$ra$sd## 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) ) # ## original "Eyring" model activ.kinet.test01.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.test01.data$df # ## preview of the non-linear fit plot activ.kinet.test01.data$plot # ## preview of the optimized (activated) ## ∆S and ∆H parameters activ.kinet.test01.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) J/(mol*K) & ## ∆H = (118.80 +- 0.41) kJ/mol # ## brief model summary activ.kinet.test01.data$df.model.HS # ## ...and the corresponding analysis of residuals activ.kinet.test01.data$ra$plot.histDens # ## graphical representation the correlation matrix ## corresponding to Eyring fit activ.kinet.test01.data$cor.df %>% corrplot::corrplot(addCoef.col = "#c2c2c2") # ## preview of the convergence activ.kinet.test01.data$converg # ## this was an untransformed dataset, ## when the k values span more than 2 orders ## of magnitude => a proportional weighting ## or linear logarithmic model might be applied # ## take the same above-defined dataset and assign ## it to a new variable kinet.test.data.new <- 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) ) # ## linear logarithmic Eyring model activ.kinet.test02.data <- eval_kinR_Eyring_GHS( data.kvT = kinet.test.data.new, rate.const = "k_per_M_per_s", rate.const.unit = "M^{-1}~s^{-1}", Temp = "T_oC", Temp.unit = "oC", fit.method = "linear" ) # ## preview of the original data ## + ∆G (activated) + fitted + residuals + ## + additional variables of the linear model activ.kinet.test02.data$df # ## preview of the linear fit plot ## also with confidence interval (99 %) activ.kinet.test02.data$plot # ## preview of the optimized (activated) ## ∆S and ∆H parameters together with ## their uncertainties activ.kinet.test02.data$vec.HS.uncert # ## compare values with those presented in ## https://www.rsc.org/suppdata/nj/b5/b501687h/b501687h.pdf ## ∆S = (11.33 +- 0.45) J/(mol*K) & ## ∆H = (120.27 +- 0.15) kJ/mol # ## brief model summary activ.kinet.test02.data$df.model.HS # ## corresponding analysis of residuals ## with residual standard deviation activ.kinet.test02.data$ra$plot.rqq() activ.kinet.test02.data$ra$sd
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 numeric solution of the rate equations, using the Ordinary Differential Equations (ODE from the desolve R package). This function is inspired by the R-bloggers article.
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, ... )
model.react |
Character string, denoting a specific radical (
Couple of examples are also given in the |
||||||||||||||||
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 ( |
||||||||||||||||
elementary.react |
Logical, if the model reaction should be considered as an elementary one,
i.e. the stoichiometric coefficients equal to the partial reaction orders. Such reaction proceeds without
identifiable intermediate species forming. Default: |
||||||||||||||||
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
The |
||||||||||||||||
time.unit |
Character string, corresponding to time unit like |
||||||||||||||||
time.interval.model |
Numeric vector, including two values: starting and final time/termination
of the model reaction in |
||||||||||||||||
time.frame.model |
Numeric value, corresponding to interval time resolution, i.e. the smallest time difference
between two consecutive points in
where the |
||||||||||||||||
solve.ode.method |
Character string, setting up the integrator (the |
||||||||||||||||
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 |
Character string, pointing to |
||||||||||||||||
qvar.expr |
Character string, pointing to |
||||||||||||||||
... |
additional arguments passed to the ODE (see also |
According to IUPAC (2019), see also the References, the rate of a chemical reaction
with the radicals () involved (refer to the example in model.react argument)
is expressed via the time change of extent of the reaction ():
where are the stoichiometric coefficients. At constant volume () conditions
(or if volume changes are negligible) the amount ( in mole) of reactant/product
can be replaced by its corresponding concentration (). Such reaction rate
(expressed in moles per unit volume and per second) is function of temperature (),
pressure () as well as that of concentration of reactants/products.
For the reaction example shown above it applies (for radical ):
where is the rate constant and its pressure dependence is usually
small and therefore can be ignored, in the first approach. The coefficients and ,
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
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 () is defined.
However, in such case, the unit of must be expressed accordingly (see the kin.params argument).
Quantitative kinetic profiles (such as that
or described above) are not evaluated
by the common "analytical" 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 analytical 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. (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
((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 the 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. |
If the function is not used for fitting of the experimental and processed data,
the result is list consisting of:
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 object, containing time as -axis and qvar
(see df above) as -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 kinetic model.
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/.
Soetaert K, Petzoldt T, Setzer RW (2010). "Solving Differential Equations in R: Package deSolve." J. Stat. Softw., 33(9), 1-25, https://doi.org/10.18637/jss.v033.i09.
Other Evaluations and Quantification:
eval_integ_EPR_Spec(),
eval_kinR_EPR_modelFit(),
quantify_EPR_Abs(),
quantify_EPR_Norm_const()
## 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 of data frame head(kin.test.01$df,n = 10) # ## half-life (t1/2) of the second-order from data frame ## search for the value/point which is close to 0.08/2 t.half.01.a.idx <- which.min(abs(kin.test.01$df$R - 0.04)) t.half.01.a <- kin.test.01$df[t.half.01.a.idx,] %>% dplyr::pull(time) # ## theoretical (analytical) expression of half-life t.half.01.b <- 1 / (2 * 0.08 * 0.012) # t.half.01.a t.half.01.b # ## plot kinetic model profile with t1/2 kin.test.01$plot + ggplot2::geom_hline( yintercept = 0.08/2, linetype = "dashed", color = "blue" ) + ggplot2::geom_vline( xintercept = t.half.01.a, linetype = "dashed", color = "blue" ) + ggplot2::annotate( geom = "text", x = 640, y = 0.045, color = "blue", size = 5.4, label = "italic(t)[1/2]", parse = TRUE ) # ## 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.225, 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 of data frame head(kin.test.01$df,n = 10) # ## half-life (t1/2) of the second-order from data frame ## search for the value/point which is close to 0.08/2 t.half.01.a.idx <- which.min(abs(kin.test.01$df$R - 0.04)) t.half.01.a <- kin.test.01$df[t.half.01.a.idx,] %>% dplyr::pull(time) # ## theoretical (analytical) expression of half-life t.half.01.b <- 1 / (2 * 0.08 * 0.012) # t.half.01.a t.half.01.b # ## plot kinetic model profile with t1/2 kin.test.01$plot + ggplot2::geom_hline( yintercept = 0.08/2, linetype = "dashed", color = "blue" ) + ggplot2::geom_vline( xintercept = t.half.01.a, linetype = "dashed", color = "blue" ) + ggplot2::annotate( geom = "text", x = 640, y = 0.045, color = "blue", size = 5.4, label = "italic(t)[1/2]", parse = TRUE ) # ## 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.225, 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
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.
eval_nu_ENDOR(nucle_us_i, B.unit = "G", B.val)eval_nu_ENDOR(nucle_us_i, B.unit = "G", B.val)
nucle_us_i |
(Vector) character string in the form like |
B.unit |
Character string, denoting the magnetic flux density B unit. Default:
|
B.val |
Numeric, magnetic flux density |
The frequency in MHz is calculated according to relation
where is the Planck's constant, is the nuclear magneton
available from constants package (constants::syms$mun),
is the nuclear -factor of the specific nucleus (reported in the package
isotopes_ds data frame as g_Nuclear) and finally, the denotes the magnetic flux
density at which the ENDOR spectra are recorded (see also B.val in arguments). The 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 )
or clockwise (, if , Levitt MH (2013)).
Numeric value or vector of nuclear Larmor/ENDOR frequencies in MHz for selected
nuclei at = B.val.
Levitt MH (2013). Spin Dynamics: Basics of Nuclear Magnetic Resonance. Wiley, ISBN 978-1-118-68184-8, https://books.google.cz/books?id=bysFAa4MPQcC.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_peakPick_Spec()
## 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)
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 the geom_label).
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, ... )
data.spectr |
Data frame object/table, containing |
x |
Character string, pointing to |
x.unit |
Character string, pointing to unit of |
xlim |
Numeric vector, referring to lower and upper limit of the selected |
Intensity |
Character string, pointing to |
Ilim |
Numeric vector, corresponding to visualization limits of the selected |
lineSpecs.form |
Character string, describing either |
only.peak.pn |
Character string, setting up the selection of positive ( |
min.peak.height |
Numeric, setting the |
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
where such formula corresponds to |
min.peak.width |
Numeric (integer > 0), setting the minimum peak-width (points) to fit the vertex
parabola expression (see also the |
max.peak.width |
Numeric (integer > 0), pointing to maximum peak-width (points) to find the peaks.
Default: |
double.sided |
Logical. Should be the peaks found for both intensity sites
( |
line.color |
Character string, line color to plot the EPR/ENDOR spectrum.
All |
peak.color |
Character string, "point" color to visualize/emphasize the peaks.
Similarly, as for the |
peak.text.angle |
Numeric, setting the angle (in deg) of the peak value (projection onto
the |
peak.text.size |
Numeric, pointing to peak annotation text size
(in mm, see the |
peak.point.size |
Numeric, size (in mm) of the peak "point" in graphical representation of the peak picking.
Please consult the |
peak.point.shape |
Numeric (integer between 0 and 24), controlling the "point" symbol like square,
triangle, circle, asterisk...etc,
refer to e.g. |
peak.text.overlap |
Logical, if |
... |
additional arguments specified, please refer to the |
List, consisting of following components, will be returned:
Data frame, corresponding to the original data.spectr, with all peaks (Intensity
vs x) found by findpeaks algorithm and the arguments defined above.
Graphical representation of found peaks in the EPR/ENDOR spectrum.
Other Evaluations:
eval_DeltaXpp_Spec(),
eval_FWHMx_Spec(),
eval_extremeX_Spec(),
eval_gFactor(),
eval_gFactor_Spec(),
eval_interval_cnfd_tVec(),
eval_kinR_Eyring_GHS(),
eval_nu_ENDOR()
## 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_file = 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.dist = 1, 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_file = 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.dist = 1, 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
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 -value,
spin quantum number as well as natural abundance of the isotopes, related to interacting nuclei,
must be known and are collected from the isotopes_ds. EPR spectra can be simulated
for the derivative as well as for the integrated line forms (see the argument lineSpec.form).
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 )
g.iso |
Numeric value, guess of the isotropic |
||||||||
instrum.params |
Named numeric vector, containing instrumental parameters required for the simulation =>
Default values are chosen to cover the EPR spectra of common organic radicals.
If |
||||||||
path_to_dsc_par |
Character string, path (can be also acquired by the |
||||||||
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" ( |
||||||||
B.unit |
Character string, pointing to unit of magnetic flux density which is to be presented
on |
||||||||
nuclear.system |
List, containing the information about groups of equivalent nuclei
interacting with the unpaired electron like |
||||||||
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: |
||||||||
lineSpecs.form |
Character string, describing either |
||||||||
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 |
||||||||
lineG.content |
Numeric value between |
||||||||
Intensity.sim |
Character string, pointing to column of simulated EPR intensity within the related output
data frame. Default: |
||||||||
plot.sim.interact |
Logical, whether to display the simulated spectrum by interactive |
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 (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 -region (magnetic flux density) and the resolution is 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 -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 s are computed by the fixed-point iterations,
because the corresponding -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 specified 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 (please, also
refer to the plot_eval_EPRtheo_mltiplet), as well as their natural abundance (if natur.abund = TRUE).
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:
ggplot2 static object showing the simulated EPR spectrum.
Data frame/table object related to the simulated spectrum.
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.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## 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 # ## check the g_{iso}-value ## of the previous spectrum eval_gFactor_Spec( sim.simple.a$df, nu.GHz = 9.8943, Intensity = "dIeprSim_over_dB", B = "Bsim_G" ) # ## 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 methyl-viologen radical cation (MV*+) ## as reported in following papers: ## https://doi.org/10.1039/C5CP04259C (PCCP 2015) ## https://doi.org/10.1021/ja00297a006 (JACS 1985) ## https://doi.org/10.1021/j150668a021 (JPC 1984) ## https://doi.org/10.1016/0022-2364(80)90258-9 ## (J MAGN RESON 1969) ## additionally, showing time (in seconds) spent ## for the computation/simulation (by the `system.time()`) system.time( methylViol.rad.cat.sim <- eval_sim_EPR_iso( g.iso = 2.0023, instrum.params = c( Bcf = 3400, Bsw = 60, Npoints = 2048, mwGHz = 9.53 ), nuclear.system = list( list("14N",2,11.85), # 4.23 G list("1H",6,11.18), # 3.99 G list("1H",4,4.46), # 1.59 G list("1H",4,3.78) # 1.35 G ), lineG.content = 0.5, lineGL.DeltaB = list(0.2,0.2) ) ) # ## simulated spectrum of MV*+ methylViol.rad.cat.sim$plot + ggplot2::coord_cartesian( xlim = c(3373,3427) )## 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 # ## check the g_{iso}-value ## of the previous spectrum eval_gFactor_Spec( sim.simple.a$df, nu.GHz = 9.8943, Intensity = "dIeprSim_over_dB", B = "Bsim_G" ) # ## 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 methyl-viologen radical cation (MV*+) ## as reported in following papers: ## https://doi.org/10.1039/C5CP04259C (PCCP 2015) ## https://doi.org/10.1021/ja00297a006 (JACS 1985) ## https://doi.org/10.1021/j150668a021 (JPC 1984) ## https://doi.org/10.1016/0022-2364(80)90258-9 ## (J MAGN RESON 1969) ## additionally, showing time (in seconds) spent ## for the computation/simulation (by the `system.time()`) system.time( methylViol.rad.cat.sim <- eval_sim_EPR_iso( g.iso = 2.0023, instrum.params = c( Bcf = 3400, Bsw = 60, Npoints = 2048, mwGHz = 9.53 ), nuclear.system = list( list("14N",2,11.85), # 4.23 G list("1H",6,11.18), # 3.99 G list("1H",4,4.46), # 1.59 G list("1H",4,3.78) # 1.35 G ), lineG.content = 0.5, lineGL.DeltaB = list(0.2,0.2) ) ) # ## simulated spectrum of MV*+ methylViol.rad.cat.sim$plot + ggplot2::coord_cartesian( xlim = c(3373,3427) )
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 those 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.
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 )
g.iso.vec |
Numeric vector with all |
||||||||
instrum.params |
Named numeric vector, containing instrumental parameters required for the simulation =>
Default values are chosen to cover the EPR spectra of common organic radicals.
If |
||||||||
B.unit |
Character string, pointing to unit of magnetic flux density which is to be presented
on |
||||||||
path_to_dsc_par |
Character string, path (can be also acquired by the |
||||||||
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" ( |
||||||||
nuclear.system |
Nested list with the elements corresponding to considered interacting nuclei for each EPR
spectral component. For example, the |
||||||||
natur.abund.vec |
Logical vector, whether to consider natural abundance of the interacting nuclei within
the components (see also |
||||||||
lineSpecs.form |
Character string, describing either |
||||||||
lineGL.DeltaB |
Nested list of the Gaussian and Lorentzian linewidths for all individual components
like |
||||||||
lineG.content.vec |
Numeric vector, corresponding to Gaussian line content for all individual components
of the EPR spectrum like |
||||||||
Intensity.sim |
Character string, pointing to column of simulated EPR intensity within the related output
data frame. Default: |
||||||||
Intensity.sim.coeffs.vec |
Numeric vector of multiplication coefficients related to EPR component intensities
like |
||||||||
plot.sim.interact |
Character string, indicating the interactive plot outputs, to visualize either individual
|
List of the following data frames and plots in case of
plot.sim.interact = NULL =>
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.
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).
Data frame with the overall intensity (+ magnetic flux density) as well as integral sum from all simulation components.
Overlay plot object with all simulated components with their
corresponding intensities defined by Intensity.sim.coeffs.vec.
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.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## 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.2) ) ), 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 BMPO spin trap *OH radical ## adduct consisting of two diastereomers (A,B), ## see at https://doi.org/10.1016/S0891-5849(01)00619-0 sim.hobmpo.spec <- eval_sim_EPR_iso_combo( g.iso.vec = c(2.005,2.005), nuclear.system = list( list( list("14N",1,38.06),# 13.6 G ) list("1H",1,34.52), # 12.3 G > DIASTEREOMER A, 81.6 % list("1H",1,1.85) # 0.70 G ) ), list( list("14N",1,37.8),# 13.5 G ) list("1H",1,42.96),# 15.3 G > DIASTEREOMER B, 18.4 % list("1H",1,1.74) # 0.60 G ) ) ), natur.abund.vec = c(TRUE,TRUE), lineGL.DeltaB = list( list(1.05,NULL), list(1.05,NULL) ), lineG.content.vec = c(1,1), Intensity.sim.coeffs.vec = c(0.816,0.184) # 81.6 % + 18.4 % ) # ## preview of both components and the overall EPR simulation, ## using the `{patchwork}` R package, ## see also at https://patchwork.data-imaginist.com/ library(patchwork) (sim.hobmpo.spec$plot.sum + ggplot2::coord_cartesian(xlim = c(3420,3560)) ) + (sim.hobmpo.spec$plot.comps + ggplot2::coord_cartesian(xlim = c(3420,3560)) ) + patchwork::plot_layout(ncol = 1,axis_titles = "collect") # ## ...and the corresponding areas/integrals sim.hobmpo.spec$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.2) ) ), 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 BMPO spin trap *OH radical ## adduct consisting of two diastereomers (A,B), ## see at https://doi.org/10.1016/S0891-5849(01)00619-0 sim.hobmpo.spec <- eval_sim_EPR_iso_combo( g.iso.vec = c(2.005,2.005), nuclear.system = list( list( list("14N",1,38.06),# 13.6 G ) list("1H",1,34.52), # 12.3 G > DIASTEREOMER A, 81.6 % list("1H",1,1.85) # 0.70 G ) ), list( list("14N",1,37.8),# 13.5 G ) list("1H",1,42.96),# 15.3 G > DIASTEREOMER B, 18.4 % list("1H",1,1.74) # 0.60 G ) ) ), natur.abund.vec = c(TRUE,TRUE), lineGL.DeltaB = list( list(1.05,NULL), list(1.05,NULL) ), lineG.content.vec = c(1,1), Intensity.sim.coeffs.vec = c(0.816,0.184) # 81.6 % + 18.4 % ) # ## preview of both components and the overall EPR simulation, ## using the `{patchwork}` R package, ## see also at https://patchwork.data-imaginist.com/ library(patchwork) (sim.hobmpo.spec$plot.sum + ggplot2::coord_cartesian(xlim = c(3420,3560)) ) + (sim.hobmpo.spec$plot.comps + ggplot2::coord_cartesian(xlim = c(3420,3560)) ) + patchwork::plot_layout(ncol = 1,axis_titles = "collect") # ## ...and the corresponding areas/integrals sim.hobmpo.spec$df.areas
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 ; coupling constants
(in MHz) for each group of equivalent nuclei; linewidth
(either or depending on the lineSpecs.form argument);
spectral baseline (see the baseline.correct argument) 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". For an extended version of this function
(including automatic lineG.content variations), please refer to the eval_sim_EPR_isoFit_space.
eval_sim_EPR_isoFit( data.spectr.expr, Intensity.expr = "dIepr_over_dB", Intensity.sim = "dIeprSim_over_dB", nu.GHz, B.unit = "G", Blim = NULL, nuclear.system.noA = NULL, baseline.correct = "constant", lineG.content = 0.5, lineSpecs.form = "derivative", optim.method = "neldermead", optim.params.init, optim.params.fix.id = NULL, optim.params.lower = NULL, optim.params.upper = NULL, Nmax.evals = 512, check.fit.plot = TRUE, msg.optim.progress = TRUE, output.list.forFitSp = FALSE, ... )eval_sim_EPR_isoFit( data.spectr.expr, Intensity.expr = "dIepr_over_dB", Intensity.sim = "dIeprSim_over_dB", nu.GHz, B.unit = "G", Blim = NULL, nuclear.system.noA = NULL, baseline.correct = "constant", lineG.content = 0.5, lineSpecs.form = "derivative", optim.method = "neldermead", optim.params.init, optim.params.fix.id = NULL, optim.params.lower = NULL, optim.params.upper = NULL, Nmax.evals = 512, check.fit.plot = TRUE, msg.optim.progress = TRUE, output.list.forFitSp = FALSE, ... )
data.spectr.expr |
Data frame object/table, containing the experimental spectral data with the magnetic flux density
( |
Intensity.expr |
Character string, pointing to column name of the experimental EPR intensity within
the original |
Intensity.sim |
Character string, pointing to column name of the simulated EPR intensity within the related output
data frame. Default: |
nu.GHz |
Numeric value, microwave frequency in |
B.unit |
Character string, denoting the magnetic flux density unit e.g. |
Blim |
Numeric vector, magnetic flux density in |
nuclear.system.noA |
List or nested list without estimated hyperfine coupling constant values,
such as |
baseline.correct |
Character string, referring to baseline correction of the simulated/fitted spectrum.
Corrections like |
lineG.content |
Numeric value between |
lineSpecs.form |
Character string, describing either |
optim.method |
Character string (vector), setting the optimization method(s) gathered within
the |
optim.params.init |
Numeric vector with the initial parameter guess (elements) where the first five elements are immutable
DO NOT PUT ANY OF THESE PARAMETERS to |
optim.params.fix.id |
Numeric value/vector of index/indices of the |
optim.params.lower |
Numeric vector (with the same element order like |
optim.params.upper |
Numeric vector (with the same element order like |
Nmax.evals |
Numeric value, maximum number of function evaluations and/or iterations.
The only one method, limited by this argument, is |
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,
|
msg.optim.progress |
Logical, whether to display message (in the R console) about progress of the |
output.list.forFitSp |
Logical. If |
... |
additional arguments specified, see also |
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:
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.
Simple residual analysis - a list consisting of 4 elements: diagnostic plots
plot.rqq() function, plot.histDens; original data frame (df) with residuals and their corresponding
standard deviation (sd). For details, please refer to the plot_eval_RA_forFit.
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.
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.
Minimum sum of residual squares (vector) after the least-square procedure.
Covariance matrix of a data frame, consisting of EPR experimental, simulated (best fit) and the residual
intensities as columns/variables. Covariance between the experiment and simulation should be positive and strong
for a decent fit. Contrary, the cov between the simulation and residuals should be ideally close to 0,
indicating no systematic relationship. However, the covariance is scale-depended and must be "normalized". Therefore,
for such a purpose, the correlation is defined as shown below.
Correlation matrix of a data frame, consisting of EPR experimental,
simulated (best fit) and residual intensities as columns/variables. Such matrix can be additionally nicely visualized
by a correlation plot created by the corrplot function.
A higher positive correlation (between the experiment
and the best fit), with the value close to 1, indicates that simulation best fit nicely follows
the experimental spectrum. Contrary, no clear correlation between the residuals and the experimental/fitted
EPR intensities must be visible. Therefore, such correlation should be ideally close to 0.
A list consisting of Akaike and Bayesian information criteria (AIC & BIC) vector (abic.vec)
and message, denoting the residuals/errors distribution, applied to evaluate
those criteria. To be used when comparing different simulation fits. The lower the (negative) values,
the better the fit. Please, refer to the eval_ABIC_forFit.
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.
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 successful convergence.
If output.list.forFitSp = TRUE, the function exclusively returns list with the two components,
which is to be applied for the eval_sim_EPR_isoFit_space.
A vector, containing the following elements:
The best fitting (optimized) parameters (related to the optim.params.init argument).
Minimum sum of residual squares (corresponding to previous item).
Standard deviation of residuals, after the (final) optim.method procedure.
Akaike Information Criterion/AIC metric (refer to eval_ABIC_forFit),
after the (final) optim.method.
Bayesian Information Criterion/BIC metric (refer to eval_ABIC_forFit),
after the (final) optim.method.
Visualization of the experimental as well as the best fitted EPR simulated spectra depending
on the check.fit.plot. It corresponds either to EPR spectra with residuals or to those with baseline correction,
(please, refer to the check.fit.plot argument description).
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) * 0.25. The coefficient 0.25(1/4) is
introduced in order to be sure that both of the experimental and initially simulated EPR spectra,
in the graphical output (see the Value), are clearly visible if check.fit.plot = TRUE.
Otherwise, the spectra may overlay and it will be difficult to differentiate between them. Of course,
any intensity multiplication coefficient, close to the experimental EPR intensity, can be applied as a starting
point to evaluate the fit.
To fix one or more simulation parameter(s) (i.e. parameter(s) which is/are not optimized) during
the fitting procedure, the corresponding optim.parms.lower as well as the optim.params.upper vector
element(s) must equal to that of the optim.params.init. Please, refer to the Examples below
for the simulation fit of aminoxyl radical EPR spectrum with bound constraints and fixed A(1 x 14N).
An alternative selection of a non-optimized/fixed simulation parameter can be also done by using
the optim.params.fix.id argument, which can be also applied to fix the simulation parameters when searching
for the best fit by the eval_sim_EPR_isoFit_space. Therefore, the latter function argument just selects
an element of the optim.params.init (by its corresponding index) and accordingly, the selected simulation
parameter value won't be optimized.
A simple EPR spectrum analysis by interactive simulation using the plot_eval_ExpSim_app
may return an .R script/code snippet for the initial simulation fit and therefore
the user does not have to write (or remember) the code required to run the eval_sim_EPR_isoFit.
Rather, she/he can instantly and seamlessly analyze an isotropic EPR spectrum by optimizing the simulation parameters.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## loading built-in example dataset which is simple ## EPR spectrum of the aminoxyl radical: aminoxyl.data.path <- load_data_example(file = "Aminoxyl_radical_a.DTA") aminoxyl.data <- readEPR_Exp_Specs( path_to_file = 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, msg.optim.progress = 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, including ## fixed A(1 x 14N) = 52.6 MHz: tempo.test.sim.fit.b <- eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data, nu.GHz = 9.806769, lineG.content = 0.75, optim.method = "pswarm", nuclear.system.noA = list("14N",1), baseline.correct = "constant", optim.params.init = c(2.0062,4.8,4.8,0,8e-3,52.68), optim.params.lower = c(2.0048,4.6,4.6,-1e-4,5e-3,52.68), optim.params.upper = c(2.0068,5.0,5.0,1e-4,1.5e-2,52.68), check.fit.plot = TRUE, eval.optim.progress = TRUE ## iterations, progress ) ## OUTPUTS: ## minimum sum of residual squares: tempo.test.sim.fit.b$min.rss # ## check and compare the previous value ## by residual analysis (`ra`) sum((tempo.test.sim.fit.b$ra$df$Residuals)^2) # ## number of evaluations / iterations: tempo.test.sim.fit.b$N.evals # ## best fit parameters: tempo.test.sim.fit.b$best.fit.params # ## correlation matrix of the EPR simulation fit: tempo.test.sim.fit.b$cor.df # ## visualization of the previous matrix: tempo.test.sim.fit.b$cor.df %>% corrplot::corrplot(addCoef.col = "#c2c2c2") # ## 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 # ## simple residual density plot ## together with standard deviation tempo.test.sim.fit.b$ra$plot.histDens tempo.test.sim.fit.b$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution tempo.test.sim.fit.b$abic # ## residual & Q-Q plots for the proposed normal ## distribution of residuals and confidence level 99% ## (default: 95%/0.95) tempo.test.sim.fit.b$ra$plot.rqq(confidence = 0.99) # ## residual & Q-Q plots for the proposed Student's ## distribution of residuals with degrees of freedom ## df = 6 (see the "$message" right above) tempo.test.sim.fit.b$ra$plot.rqq( residuals.distro = "t", df = 6 ) # ## 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 # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution tempo.test.sim.fit.c$abic## loading built-in example dataset which is simple ## EPR spectrum of the aminoxyl radical: aminoxyl.data.path <- load_data_example(file = "Aminoxyl_radical_a.DTA") aminoxyl.data <- readEPR_Exp_Specs( path_to_file = 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, msg.optim.progress = 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, including ## fixed A(1 x 14N) = 52.6 MHz: tempo.test.sim.fit.b <- eval_sim_EPR_isoFit(data.spectr.expr = aminoxyl.data, nu.GHz = 9.806769, lineG.content = 0.75, optim.method = "pswarm", nuclear.system.noA = list("14N",1), baseline.correct = "constant", optim.params.init = c(2.0062,4.8,4.8,0,8e-3,52.68), optim.params.lower = c(2.0048,4.6,4.6,-1e-4,5e-3,52.68), optim.params.upper = c(2.0068,5.0,5.0,1e-4,1.5e-2,52.68), check.fit.plot = TRUE, eval.optim.progress = TRUE ## iterations, progress ) ## OUTPUTS: ## minimum sum of residual squares: tempo.test.sim.fit.b$min.rss # ## check and compare the previous value ## by residual analysis (`ra`) sum((tempo.test.sim.fit.b$ra$df$Residuals)^2) # ## number of evaluations / iterations: tempo.test.sim.fit.b$N.evals # ## best fit parameters: tempo.test.sim.fit.b$best.fit.params # ## correlation matrix of the EPR simulation fit: tempo.test.sim.fit.b$cor.df # ## visualization of the previous matrix: tempo.test.sim.fit.b$cor.df %>% corrplot::corrplot(addCoef.col = "#c2c2c2") # ## 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 # ## simple residual density plot ## together with standard deviation tempo.test.sim.fit.b$ra$plot.histDens tempo.test.sim.fit.b$ra$sd # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution tempo.test.sim.fit.b$abic # ## residual & Q-Q plots for the proposed normal ## distribution of residuals and confidence level 99% ## (default: 95%/0.95) tempo.test.sim.fit.b$ra$plot.rqq(confidence = 0.99) # ## residual & Q-Q plots for the proposed Student's ## distribution of residuals with degrees of freedom ## df = 6 (see the "$message" right above) tempo.test.sim.fit.b$ra$plot.rqq( residuals.distro = "t", df = 6 ) # ## 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 # ## Akaike and Bayesian Criteria (AIC & BIC) ## + information about the residuals distribution tempo.test.sim.fit.c$abic
This is an extended version of the eval_sim_EPR_isoFit, providing a broader range of the initial simulation
parameters in order to find a more reliable simulation fit of an experimental isotropic EPR spectrum. The parameter space
(represented by data frame/matrix and/or vector(s)) is divided into several points (see the argument N.points.space)
where each of these points corresponds to starting values (see arguments optim.params.init +
optim.params.init.dvary as well as lineG.content + lineG.content.dvary), which are optimized
by the default eval_sim_EPR_isoFit setup. Because such procedure is computationally
highly demanding, the central loop, to iterate/evaluate parameters and the corresponding EPR spectra, uses
the {future.apply} package
(see also the future_Map function). It enables relatively seamless application
of parallel computing
(please, also refer to the processing argument),
regardless of the operating system (OS) to dramatically speed-up the entire searching for the best fit.
In addition to graphical outputs, function also provides an animated representation
(using the {animation} package) of the procedure progress
by showing the evaluated EPR spectra at each point (please also refer to the vignette("functionality")
and "Hyperfine (HF) Structure and Simulations" subsection).
eval_sim_EPR_isoFit_space( data.spectr.expr, nu.GHz, B.unit = "G", nuclear.system.noA = NULL, baseline.correct = "constant", lineG.content = 0.5, lineG.content.dvary = NULL, lineSpecs.form = "derivative", optim.method = "neldermead", optim.params.init, optim.params.init.dvary = NULL, Nmax.evals = 256, N.points.space = 16, check.fit.plot = TRUE, processing = "sequential", animation = "Fitting_of_sim_EPR", ... )eval_sim_EPR_isoFit_space( data.spectr.expr, nu.GHz, B.unit = "G", nuclear.system.noA = NULL, baseline.correct = "constant", lineG.content = 0.5, lineG.content.dvary = NULL, lineSpecs.form = "derivative", optim.method = "neldermead", optim.params.init, optim.params.init.dvary = NULL, Nmax.evals = 256, N.points.space = 16, check.fit.plot = TRUE, processing = "sequential", animation = "Fitting_of_sim_EPR", ... )
data.spectr.expr |
Data frame object/table, containing the experimental spectral data with the magnetic flux density
( |
nu.GHz |
Numeric value, microwave frequency in |
B.unit |
Character string, denoting the magnetic flux density unit e.g. |
nuclear.system.noA |
List or nested list without estimated hyperfine coupling constant values,
such as |
baseline.correct |
Character string, referring to baseline correction of the simulated/fitted spectrum.
Corrections like |
lineG.content |
Numeric value between |
lineG.content.dvary |
Numeric value, corresponding to initial variation of |
lineSpecs.form |
Character string, describing either |
optim.method |
Character string (vector), setting the optimization method(s) gathered within
the |
optim.params.init |
Numeric vector with the initial parameter guess (elements) where the first five elements are immutable
DO NOT PUT ANY OF THESE PARAMETERS to |
optim.params.init.dvary |
Numeric vector with initial variations of the corresponding
|
Nmax.evals |
Numeric value, maximum number of function evaluations and/or iterations.
The only one method, limited by this argument, is |
N.points.space |
Numeric value, identical to number of points by which the initial parameter-hyperspace
(see the |
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,
|
processing |
Character string, corresponding to |
animation |
Character string, pointing to name of the animated |
... |
additional arguments specified, see also the |
If the animation argument is different from NULL, the function will return a .gif
animation of the fitting procedure progress, showing the EPR spectra at each evaluation,
based on the check.fit.plot argument. The animation file will be stored in the working directory
of your project. Additionally, a message, appeared in the R console, informs that the animation file was created.
Regardless of the .gif animation a list with the following elements is provided:
A data frame object representing hyperspace of the initial EPR simulation fitting parameters
corresponding to optim.params.init and optim.params.init.dvary. Each variable/column corresponds
to EPR simulation parameter to be optimized and each observation/row is related to one N.points.space,
dividing the range for each parameter defined by the optim.params.init.dvary. The fitting/optimization
is performed for each row of the init.space.df.
Data frame object similar to init.space.df, however with optimized EPR simulation
parameters (after the fitting procedure). In addition, the optim.space.df contains the following metrics
of the optimization/fitting as variables/columns: sum of the residual squares RSS,
standard deviation of residuals residualSD, Akaike information criterion AIC and Bayesian information
criterion BIC. These four parameters are actually related to optimization/fitting path
(see the plot.optim.space below).
A ggplot2 object, corresponding to graphical representation of the init.space.df
created by the facet_wrap.
A ggplot2 object, corresponding to graphical representation of the optim.space.df
created by the facet_wrap. One can also easily recognize the best fit/optimized parameter set,
because the Evaluation with those parameters is highlighted by the green line. Additionally, each optimized parameter
vs evaluation relation is fitted by the loess function implemented
in the geom_smooth in order to show the trend and the confidence interval
of the parameter optimization. This is especially important for the RSS, residualSD, AIC and BIC,
as they represent "hills" and "valleys" of the optimization/fitting path to identify the minima.
Vector of the best final fitting (optimized) parameters (in the plot.optim.space distinguished
by the green line) and related to the optim.params.init argument.
Numeric value of the Gaussian line content of the simulated EPR spectrum.
If lineG.content.dvary = NULL it corresponds to the original/initial value (lineG.content).
Otherwise, a value from the corresponding vector, defined by the lineG.content + lineG.content.dvary
+ N.points.space, and related to the RSS minimum is returned.
List of individual EPR spectra, depending on the check.fit.plot argument and corresponding to
each Evaluation (refer also to the plot.optim.space). These are the actual spectra by which the animation
was created.
In order to monitor and compare load of the hardware resources when running processing = "parallel"
and "sequential", one might use the following applications depending on the OS.
For Windows: task manager GUI (graphical user interface), for Linux:
terminal applications like top/htop or system monitor GUI and for MacOS
terminal applications like top/htop or activity monitor GUI.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## Not run: ## run parallel processing to fit the EPR spectrum ## of the TMPD radical cation (+ zoom the spectrum ## output by `Blim`), animation ## "Fitting_of_sim_EPR.gif" stored in the working dir. listfit01 <- eval_sim_EPR_isoFit_space( data.spectr.expr = data.tmpd.spec, nu.GHz = data.tmpd.params.values[1,2], nuclear.system.noA = list( list("14N", 2), # 2 x 14N list("1H", 4), # 4 x 1H list("1H", 12) # 12 x 1H ), optim.params.init = c( 2.0030, 0.4, 0.4, 0, 2.5e5, 20.0, 5.5, 19 ), optim.params.init.dvary = c(0.0002,0.1,0.1,0, 2e4,2,1,2), ## or NULL # Nmax.evals = 256, # N.points.space = 16, # total number of iters. 4096 lineG.content = 0.3, lineG.content.dvary = 0.15, ## or NULL # optim.method = "neldermead", processing = "parallel" , ## or "sequential" Blim = c(3455,3545) ) # ## optimization/fitting progress ## (main graphical output) listfit01$plot.optim.space # ## run the similar processing and evaluation ## like before, but now with the fixed g-value ## (won't be optimized) and with 24 `N.points.space` listFit02 <- eval_sim_EPR_isoFit_space( data.spectr.expr = data.tmpd.spec, nu.GHz = data.tmpd.params.values[1,2], nuclear.system.noA = list( list("14N", 2), # 2 x 14N list("1H", 4), # 4 x 1H list("1H", 12) # 12 x 1H ), optim.params.init = c( 2.00305, 0.4, 0.4, 0, 1.25e4, 20.0, 5.5, 19 ), optim.params.init.dvary = c(0,0.1,0.1,0, # `.dvary` for g-value = 0 2e3,2,1,2), # Nmax.evals = 256, N.points.space = 24, # total number of iters. 6144 lineG.content = 0.3, lineG.content.dvary = 0.15, processing = "parallel" , optim.params.fix.id = 1, # fix g-value Blim = c(3455,3545) ) # ## space (plot) for initial parameters: listFit02$plot.init.space # ## space (plot) for optimized parameters listFit02$plot.optim.space ## End(Not run)## Not run: ## run parallel processing to fit the EPR spectrum ## of the TMPD radical cation (+ zoom the spectrum ## output by `Blim`), animation ## "Fitting_of_sim_EPR.gif" stored in the working dir. listfit01 <- eval_sim_EPR_isoFit_space( data.spectr.expr = data.tmpd.spec, nu.GHz = data.tmpd.params.values[1,2], nuclear.system.noA = list( list("14N", 2), # 2 x 14N list("1H", 4), # 4 x 1H list("1H", 12) # 12 x 1H ), optim.params.init = c( 2.0030, 0.4, 0.4, 0, 2.5e5, 20.0, 5.5, 19 ), optim.params.init.dvary = c(0.0002,0.1,0.1,0, 2e4,2,1,2), ## or NULL # Nmax.evals = 256, # N.points.space = 16, # total number of iters. 4096 lineG.content = 0.3, lineG.content.dvary = 0.15, ## or NULL # optim.method = "neldermead", processing = "parallel" , ## or "sequential" Blim = c(3455,3545) ) # ## optimization/fitting progress ## (main graphical output) listfit01$plot.optim.space # ## run the similar processing and evaluation ## like before, but now with the fixed g-value ## (won't be optimized) and with 24 `N.points.space` listFit02 <- eval_sim_EPR_isoFit_space( data.spectr.expr = data.tmpd.spec, nu.GHz = data.tmpd.params.values[1,2], nuclear.system.noA = list( list("14N", 2), # 2 x 14N list("1H", 4), # 4 x 1H list("1H", 12) # 12 x 1H ), optim.params.init = c( 2.00305, 0.4, 0.4, 0, 1.25e4, 20.0, 5.5, 19 ), optim.params.init.dvary = c(0,0.1,0.1,0, # `.dvary` for g-value = 0 2e3,2,1,2), # Nmax.evals = 256, N.points.space = 24, # total number of iters. 6144 lineG.content = 0.3, lineG.content.dvary = 0.15, processing = "parallel" , optim.params.fix.id = 1, # fix g-value Blim = c(3455,3545) ) # ## space (plot) for initial parameters: listFit02$plot.init.space # ## space (plot) for optimized parameters listFit02$plot.optim.space ## End(Not run)
Data frame/Dataset summarizing the essential characteristics of nuclei in EPR spectroscopy.
isotopes_dsisotopes_ds
A data frame with 351 rows and 9 variables/columns:
Numeric, proton number.
Character, ponting to isotope in format like "14N".
Character, pointing either to stable, "STB", or to radio-active, "RA", isotope.
Character, corresponding to isotope name.
Numeric, denoting the spin quantum number.
Numeric, corresponding to nuclear -factor ().
Numeric, pointing to natural abundance of an isotope in .
Numeric, corresponding to nuclear quadrupolar moment in .
Numeric, specific Larmor/ENDOR frequency ()
at .
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 =>
where is the Planck's constant, is the nuclear magneton
available from constants
package (constants::syms$mun,syms),
is the nuclear -factor of the specific nucleus (reported in the data frame as g_Nuclear)
and finally, the 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 ) or clockwise (, if )
Please, consult the vignette("datasets") as well.
https://easyspin.org/easyspin/documentation/isotopetable.html
Other Built-In Datasets:
solvents_ds
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").
load_data_example(file = NULL)load_data_example(file = NULL)
file |
Character string, corresponding to file name + extension. |
## 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-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.
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, eval.optim.progress = FALSE, fix.optim.x.0.id = 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, eval.optim.progress = FALSE, fix.optim.x.0.id = NULL, ... )
method |
Character string, pointing to applied optimization method/algorithm. One may choose one from
those listed in |
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,
where a more general parameterized one can be implemented in (see |
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 |
tol.step |
Numeric, the smallest optimization step (relative change) between
2 iterations to stop the optimization procedure. For the |
pswarm.size |
Numeric value, which equals to particle swarm size (i.e. number of particles),
if |
pswarm.diameter |
Numeric value, corresponding to diameter of the particle swarm search space
(in case
|
pswarm.type |
Character string, setting the type/version of particle swarm algorithm
if |
eval.optim.progress |
Logical. If |
fix.optim.x.0.id |
Numeric value/vector of the |
... |
additional arguments passed to the function. |
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.
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 the 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
or can be activated by the eval.optim.progress argument.
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.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## 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 max. 6 EPR simulated intensities, ## 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){ 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 max. 6 EPR simulated intensities, ## 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){ 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)
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).
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 )
data.vat |
Data frame (table) object, including required columns like |
x |
Character string, pointing to |
x.unit |
Character string, pointing to |
Current |
Character string, indicating the |
Current.unit |
Character string, pointing to |
xlim |
Numeric vector of the |
Ilim |
Numeric vector, characterizing the lower and upper visualization limit of the current, e.g. |
line.color |
Character string, pointing to line color of the voltammogram / chronoamperogram. All |
line.width |
Numeric, linewidth of the plot line in |
line.type |
Character string or integer, corresponding to width of the voltammogram/chronoamperogram line.
Following types can be specified: |
theme.basic |
Character string, calling a
|
axis.title.size |
Numeric, axis text title size in |
axis.text.size |
Numeric, text size in |
border.line.color |
Character string, referring to color of the plot graph/panel border line. Default:
|
border.line.width |
Numeric, width (in |
border.line.type |
Character string or integer, corresponding to width of the plot graph/panel border line. Following types
can be specified: |
ref.electrode |
Character string, corresponding to reference electrode notiation/label, e.g.
|
plot.interact |
Logical, whether the voltammogram or chronoamperogram is visualized as an interactive plot
by |
ticks |
Character string, corresponding to pointing direction of the axis ticks, either pointing into
the panel graph or outwards (default). If |
grid |
Logical, whether to display the |
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).
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.
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.
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.
Other EPR Spectroelectrochemistry:
eval_ECh_QNe_chronoamp()
## 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 )
.html,.pdf or .docx
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).
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)
p |
Plot object/variable name. |
size.width |
Numeric, |
size.height |
Numeric, |
res.ppi |
Numeric, |
Interactive plot format corresponding to that of the output document. If the desired document
format .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.withres.ppi x
size.heightres.ppi.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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)
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.).
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 )
data.spectra |
Data frame/table object, containing magnetic flux density, |
x |
Character string, pointing to |
x.unit |
Character string, pointing to unit of |
xlim |
Numeric vector, referring to lower and upper limit of the selected |
var2nd.series |
Character string, referred to name of the second independent variable/quantity
column in the original |
var2nd.series.slct.by |
Numeric, corresponding to each |
Intensity |
Character string, pointing to |
Ilim |
Numeric vector, corresponding to visualization limits of the selected |
lineSpecs.form |
Character string, describing either |
line.colors |
Character string, line color(s) to plot EPR spectrum/spectra.
All
|
line.width |
Numeric, linewidth of the plot line in |
line.type |
Character string or integer, corresponding to width of the (spectral) line(s). Following types
can be specified: |
border.line.width |
Numeric, width (in |
border.line.color |
Character string, referring to color of the plot graph/panel border line. Default:
|
border.line.type |
Character string or integer, corresponding to width of the plot graph/panel border line. Following types
can be specified: |
theme.basic |
Character string, calling a
|
axis.title.size |
Numeric, axis text title size in |
axis.text.size |
Numeric, text size in |
legend.title |
Character string identical to legend title, e.g. |
legend.title.size |
Numeric, legend text title size in |
legend.text.size |
Numeric, legend text size in |
grid |
Logical, whether to display the |
yTicks |
Logical, whether to display the |
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.
EPR spectrum/spectra ('overlay') plot object (corresponding to a specific value structure of plot components)
using the ggplot2 functionality, with the key parameter variations like line color, theme, grid...etc.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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.bin.file.path <- load_data_example("PNT_ENDOR_a.DTA") pnt.pars.file.path <- load_data_example("PNT_ENDOR_a.DSC") ## read the PNT CW ENDOR data without intensity ## normalization pnt.endor.data <- readEPR_Exp_Specs( path_to_file = pnt.bin.file.path, path_to_dsc_par = pnt.pars.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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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.bin.file.path <- load_data_example("PNT_ENDOR_a.DTA") pnt.pars.file.path <- load_data_example("PNT_ENDOR_a.DSC") ## read the PNT CW ENDOR data without intensity ## normalization pnt.endor.data <- readEPR_Exp_Specs( path_to_file = pnt.bin.file.path, path_to_dsc_par = pnt.pars.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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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)
eval_integ_EPR_Spec
Visualization (static plots based on ggplot2) of integrated EPR spectra
coming as data frame outputs from eval_integ_EPR_Spec.
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 )
data.spectra.integ |
Data frame object, inherited output from the |
B |
Character string, pointing to magnetic flux density |
B.unit |
Character string, denoting the magnetic flux density unit e.g. |
Blim |
Numeric vector, magnetic flux density in |
ylim |
Numeric vector, corresponding to lower and upper limit of the |
slct.integs |
Character string vector, pointing to selected integrals/columns/variables (of the original
|
line.width |
Numeric, linewidth of the plot line in |
line.type |
Character string or integer, corresponding to width of the (spectral) line(s). Following types
can be specified: |
axis.title.size |
Numeric, axis text title size in |
axis.text.size |
Numeric, text size in |
legend.title.size |
Numeric, legend text title size in |
legend.text.size |
Numeric, legend text size in |
separate.integs |
Logical, should be the integrals presented in overlay mode (in one graph/panel)
or on separated panels (by |
separate.integ.scales |
Character string related to |
output.df |
Logical, whether a transformed |
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
Data frame object with intensities of all selected integrals and magnetic flux density
variables/columns in tidy/long table format.
Plot object showing all integrated EPR spectra corresponding to df.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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 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.
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 )
data.spectra |
Spectrum data frame/table object, containing magnetic flux density, |
x |
Character string, pointing to |
x.unit |
Character string pointing to |
Intensity |
Character string, corresponding to the intensity column header in the original |
var2nd.series |
Character string, referred to name of the second independent variable/quantity
column in the original |
lineSpecs.form |
Character string, describing either |
line.colors |
Character string (vector). In case of of SIMPLE SPECTRUM
(NOT FOR |
line.width |
Numeric, linewidth of the plot line in |
line.type |
Character string or integer, corresponding to width of the (spectral) line(s). Following types
can be specified: |
bg.color |
Character string, corresponding to background color of the panel/graph.
Available colors are listed on the CSS Color Module Homepage.
Default: |
grid.color |
Character string, corresponding to grid lines color of the panel/graph.
Available colors are listed on the CSS Color Module Homepage.
Default: |
border.line.width |
Numeric, width (in |
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: |
legend.title |
Character string |
legend.title.size |
Numeric, text size (in |
axis.title.size |
Numeric, text size (in |
axis.text.size |
Numeric, text size (in |
Interactive plot object of EPR spectrum/spectra based on plotly package.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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_file = 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.DTA") ## 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_file = 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.DTA") ## 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)
Please wait for the images to load, while rendering the web page. 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.
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 )
data.spectra.series |
Spectrum data frame/table, object containing magnetic flux density, |
x |
Character string, pointing to |
Intensity |
Character string, corresponding to the intensity column header in the original |
var2nd.series |
Character string, referred to name of the second independent variable/quantity
column in the original |
plot.type |
Character string, inherited from |
scheme.color |
Character string, corresponding to |
contour.labels |
Logical, whether contours of intensity "hills" and "valleys" are projected
onto the |
xlim |
Numeric vector, pointing to lower and upper visual limit of the |
xlab |
Character string |
ylab |
Character string |
zlab |
Character string |
axis.title.size |
Numeric, text size (in |
axis.text.size |
Numeric, text size (in |
bg.x.color |
Character string, setting the background color of the |
grid.x.color |
Character string, pointing to color of |
bg.y.color |
Character string, setting the background color of the |
grid.y.color |
Character string, pointing to color of |
bg.z.color |
Character string, setting the background color of the |
grid.z.color |
Character string, pointing to color of |
output.matrix.df |
Logical, if |
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
Interactive object plot (see below).
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").
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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.dta.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.dta.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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.dta.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.dta.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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)
What is the expected EPR intensity pattern for a group of equivalent nuclei? One may use this function for a quick
prediction/visualization of EPR spectrum multiplets (without a specific hyperfine splitting). Its central code
(computation of binomial/multinomial coefficients) is implemented in the eval_sim_EPR_iso to provide
simulations of isotropic EPR spectra. The theoretical intensities/coefficients are returned either as a vector
or as a barplot using the geom_bar.
plot_eval_EPRtheo_mltiplet(nucle_us_i = "1H", I = NULL, N.nuclei = 1)plot_eval_EPRtheo_mltiplet(nucle_us_i = "1H", I = NULL, N.nuclei = 1)
nucle_us_i |
Character string, pointing to specific nucleus/nuclei in the form like |
I |
Numeric value, pointing to nuclear spin quantum number of proposed nucleus/nuclei interacting with unpaired electron.
|
N.nuclei |
Numeric value (integer), corresponding to number of interacting equivalent nuclei (within a group).
Default: |
A list consisting of:
A named vector of binomial/multinomial coefficients related to theoretical intensities
of isotropic EPR spectrum when the coupling between unpaired electron and the surrounding nuclei is present.
Coefficient/Vector names correspond to total spin quantum numbers (e.g. for one "14N" nucleus, the names
are represented by the c("-1","0","1") vector).
GGplot2 object - graphical representation of the intensity.vec list component.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## intensity multiplet for methyl group ## (3 x 1H equivalent nuclei) methyl.multipl <- plot_eval_EPRtheo_mltiplet( N.nuclei = 3 ) # ## vector of predicted ## intensities/coefficients methyl.multipl$intensity.vec # ## graphical repsentation methyl.multipl$plot # ## intensity multiplet for 2 x 14N ## in TMPD (Wuster's blue) radical cation tmpd.14N.multipl <- plot_eval_EPRtheo_mltiplet( I = 1, N.nuclei = 2 ) # tmpd.14N.multipl$plot## intensity multiplet for methyl group ## (3 x 1H equivalent nuclei) methyl.multipl <- plot_eval_EPRtheo_mltiplet( N.nuclei = 3 ) # ## vector of predicted ## intensities/coefficients methyl.multipl$intensity.vec # ## graphical repsentation methyl.multipl$plot # ## intensity multiplet for 2 x 14N ## in TMPD (Wuster's blue) radical cation tmpd.14N.multipl <- plot_eval_EPRtheo_mltiplet( I = 1, N.nuclei = 2 ) # tmpd.14N.multipl$plot
Launch this app in order to quickly check recorded individual EPR spectra with their instrumental parameters.
Additionally, you may try to interactively simulate the isotropic continuous wave (CW) EPR spectra
using the simple graphical user interface (GUI) based on the R Shiny and several
functions from the package (see Details). Screenshots of the app (e.g. visualization of g-Factor scale
as well as interactive simulation) you may find in the vignette("functionality").
plot_eval_ExpSim_app()plot_eval_ExpSim_app()
Based on the acquisition EPR spectrum origin, by using the graphical 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, respectively. Such spectrum is immediately depicted in the interactive
{plotly} format by plot_EPR_Specs2D_interact. The magnetic flux density
of the EPR spectrum can be converted from mT to G (or vice versa) and to g-values.
Moreover, if the compound/radical structure is already known, one can display its structure by entering
its corresponding SMILES code/character string, using the draw_molecule_by_rcdk.
All the data (spectrum + parameters) can be also used to interactively simulate
the isotropic EPR spectrum by the eval_sim_EPR_iso and to visualize it,
with its experimental counterpart, by the present_EPR_Sim_Spec. Additionally, one can also print
and download the corresponding data frame(s)/table(s) in several formats (.csv,.pdf or .xlsx)
and thus to use the data not only in the R environment but also within other software tools.
All instantaneously presented EPR spectra can be also exported in common formats like
.png, .jpeg as well as .pdf.
The result of the isotropic simulation (with the actual parameters)
can be additionally exported as an .R code snippet/script to eventually fit the simulated spectrum
(optimize simulation parameters) onto the experimental one by the eval_sim_EPR_isoFit.
By saving the script in the working directory, the isotropic simulation fit can be performed right after closing
the shiny app (window) in order to fine tune the simulation parameters and thus to speed up the analysis
of the EPR spectrum. If the shiny application is running within the web browser, the user may also print/save
the entire "dashboard" in the .pdf format to share/present results with/to students or colleagues.
## 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 = 1) observe({ if (isTRUE(input$normVec)){ norm_vec$val <- as.numeric( unlist(strsplit(input$vecNorm,",")) ) } else { norm_vec$val <- 1 } }) # ## conditions to read either ASCII or binary files ## from EPR spectrometer ascii.cond <- reactive({ # ## if `input$SpectrumFile` is NULL (no file yet), execution stops silently ## here — no error, no downstream cascade. shiny::req(input$SpectrumFile) # ## extension definition file.extens <- tolower(tools::file_ext(input$SpectrumFile$name)) # ## function and condition for `file.extens` extens.map.vec <- c( txt = 1, asc = 1, csv = 1, dta = 0, spc = 0 ) # ## ...if the extension is not recognized validate( need(file.extens %in% names(extens.map.vec), paste0("Unrecognised extension: '.", file.extens, "' of EPR data. Accepted: .txt, .csv, .asc, .DTA or .spc")) ) # extens.map.vec[[file.extens]] # }) # ## Load experimental spectrum data frame expr_data <- reactive({ # shiny::req(input$ParamsFile) shiny::req(input$SpectrumFile) # ## this is required. otherwise the `bin` files ## cannot be loaded (the `ascii` will load anyway) ascii.params.path <- input$ParamsFile$datapath file.spec.path <- input$SpectrumFile$datapath # spectr.data <- readEPR_Exp_Specs( path_to_file = file.spec.path, path_to_dsc_par = switch(2 - ascii.cond(),NULL,ascii.params.path), col.names = switch( 3 - origin.cond(orig = input$origin), c("index","B_G", "dIepr_over_dB"), c("B_G", "dIepr_over_dB"), switch( 2 - ascii.cond(), c("B_mT","dIepr_over_dB"), c("index","B_G", "dIepr_over_dB") ) ), x.unit = switch( 3 - origin.cond(orig = input$origin), "G", "G", ## `.csv` file with "mT", while binary with "G" switch(2 - ascii.cond(),"mT","G") ), 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 = 1) observe({ if (isTRUE(input$normVec)){ norm_vec$val <- as.numeric( unlist(strsplit(input$vecNorm,",")) ) } else { norm_vec$val <- 1 } }) # ## conditions to read either ASCII or binary files ## from EPR spectrometer ascii.cond <- reactive({ # ## if `input$SpectrumFile` is NULL (no file yet), execution stops silently ## here — no error, no downstream cascade. shiny::req(input$SpectrumFile) # ## extension definition file.extens <- tolower(tools::file_ext(input$SpectrumFile$name)) # ## function and condition for `file.extens` extens.map.vec <- c( txt = 1, asc = 1, csv = 1, dta = 0, spc = 0 ) # ## ...if the extension is not recognized validate( need(file.extens %in% names(extens.map.vec), paste0("Unrecognised extension: '.", file.extens, "' of EPR data. Accepted: .txt, .csv, .asc, .DTA or .spc")) ) # extens.map.vec[[file.extens]] # }) # ## Load experimental spectrum data frame expr_data <- reactive({ # shiny::req(input$ParamsFile) shiny::req(input$SpectrumFile) # ## this is required. otherwise the `bin` files ## cannot be loaded (the `ascii` will load anyway) ascii.params.path <- input$ParamsFile$datapath file.spec.path <- input$SpectrumFile$datapath # spectr.data <- readEPR_Exp_Specs( path_to_file = file.spec.path, path_to_dsc_par = switch(2 - ascii.cond(),NULL,ascii.params.path), col.names = switch( 3 - origin.cond(orig = input$origin), c("index","B_G", "dIepr_over_dB"), c("B_G", "dIepr_over_dB"), switch( 2 - ascii.cond(), c("B_mT","dIepr_over_dB"), c("index","B_G", "dIepr_over_dB") ) ), x.unit = switch( 3 - origin.cond(orig = input$origin), "G", "G", ## `.csv` file with "mT", while binary with "G" switch(2 - ascii.cond(),"mT","G") ), 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)
Three visual diagnostic tools (based on the {ggplot2}
package) and one metric (standard deviation of residuals) are applied to evaluate the appropriateness as well as to compare
different models/fits. 1. The first plot represents the Residuals vs Fitted/Simulated Values relation.
For a decent model/fit, it will exhibit randomly scattered values around 0 and displays a similar
variance over all predicted/fitted values. 2. Sample Quantiles (Residuals) vs Theoretical Quantiles (Q-Q plot)
shows, whether the appearance of residuals can be described by the three probability distributions:
c("norm","t","cauchy") (i.e. Normal or Student's t or Cauchy, see also the eval_ABIC_forFit function).
3. The latter is combined with a more detailed information about the distribution of residuals by the histogram
(geom_histogram) as well as by the probability density (geom_density,
including the residuals mean value, and median which in ideal case equal to 0).
plot_eval_RA_forFit( data.fit, residuals = NULL, fitted = NULL, resid.method.smooth = "loess", resid.xlab = NULL, k, level.cnfd = 0.95 )plot_eval_RA_forFit( data.fit, residuals = NULL, fitted = NULL, resid.method.smooth = "loess", resid.xlab = NULL, k, level.cnfd = 0.95 )
data.fit |
Data frame object, usually containing variables/columns like |
residuals |
Character string, pointing to variable/column header with residuals/errors, depending
on the |
fitted |
Character string, pointing to variable/column header with (model) fitted/predicted values, depending
on the |
resid.method.smooth |
Character string, corresponding to smoothing method (function) to follow
the trends of residual plot (Residuals vs Fitted/Predicted values).
Default: |
resid.xlab |
Character string, pointing to |
k |
Numeric value identical to number of parameters used for the model/fit
(see e.g. |
level.cnfd |
Numeric value, identical with level of the applied confidence interval
(see also the |
Analysis of residuals is a powerful statistical technique to check whether the model/fit has adequately
captured the information in the data (please, also refer to the eval_ABIC_forFit).
The -th residual/error (in the series) is defined as the difference between the -th observed response
value () and that of the predicted/fitted by the model ( or ):
One might think of residuals as "leftovers", i.e. these are the issues/items which are unexplained,
after the model/fit has been applied. The residual analysis therefore helps us to to determine whether
our model/fit missed an important pattern or not at all (see Chugani (2025) in the References).
Residuals are also used in least square fitting/optimization procedures where the sum of their squares
is to be minimized throughout the iterations (see e.g. eval_sim_EPR_isoFit
or eval_kinR_EPR_modelFit).
In addition to the original "raw" residuals defined above, one may come across other types,
like "Pearson" (or "scaled"),
"standardized" or "studentized". The latter two are helpful to identify outliers,
which are the data points that are significantly different from the rest of the data
(though, they can be also identified by the Q-Q plot and histogram-probability density).
For such reason the "raw" residuals () are divided by their standard
deviation ( see the Value below), including the the effect of leverage.
Thus, the formula for standardized residual reads: ,
where the stands for the diagonal element of the "leverage" matrix
(see e.g. References 11-13). The simple explanation of the leverage phenomenon is following
(see e.g. Speegle D, Clair B (2021) or The Pennsylvania State University (2018) in the References).
The fit or the regression line goes through the center of mass of the (experimental) data (,).
Lets assume two points and , where the -coordinate is close to the mean value
of predictors () and the possesses an extreme (far from the mean value).
Therefore, changing the will induce a small effect (low leverage) on the fit/regression line,
whereas the change will dramatically influence the fit (high leverage).
Both standardized and studentized residuals can be automatically calculated for linear models like
lm and glm, using
the stats::rstandard
and stats::rstudent. A very detailed analysis for linear models is provided
by the {ggResidpanel} package. Additionally, a series
of diagnostic plots can be also created in the base R, just by plot(var), where the var
represents the variable/object of the linear model. On the other hand, all these diagnostics are not
available for non-linear models like nls. Accordingly, such type of calculations
can be provided by other packages
(see e.g. {nlstools})
or must be performed "manually", evaluating the numerical approximation of the gradient
(please, refer to the jacobian)
as reported elsewhere (see Nguyen M (2020) in the References). Consequently, the calculations of standardized
and studentized residuals are not involved in this general plot_eval_RA_forFit function. Nevertheless, users are advised
to apply above-described options to obtain these specialized residuals or diagnostic plots for a specific model/fit
(also refer to the Value/df) if needed.
Considerations to support or exclude model/fit based on the residual plot. If the residuals exhibit
no clear pattern, like they are randomly scattered around the 0 with no systematic increase or decrease
in variance, we may trust our fit with the optimized parameters. Such pattern is homoscedastic.
However, if one recognizes curved ((inverted-)U shape, see e.g. Examples
in the eval_kinR_EPR_modelFit), wave or systematic increase (so called "fanning")
or decrease ("funelling"), the model/fit is untrustworthy and one would probably search for a different (better) one.
In particular, the curved pattern in the residual plot may indicate that a model does a poor job of fitting
and likely, we need additional parameter(s) to describe our data properly. In the case if residuals suffer
from unequal variance at different levels of the fitted values, the residuals are referred
to as heteroscedastic. In order to predict pattern of the residual plot, the corresponding relationship
is fitted by the loess (default) or lm/glm function (see the resid.method.smooth argument) where
the confidence level band of the fitted/regression line can be controlled by the level.cnfd argument
or by the Value output function plot.rqq() (and its confidence argument).
Considerations to support or exclude model/fit based on the Q-Q plot, histogram and probability density.
If the residuals are assumed to be normally distributed, one can use a normal Q-Q (Quantile-Quantile) plot
to check this assumption or its violation. Quantiles are often referred to as "percentiles". These are actually
the data points, dividing the distribution into equal portions. For instance, for a 0.5 quantile (or the 2nd quartile),
half of the data lie below this point and half of them above. This quantile is also referred to as median.
Similarly, the 0.25 quantile (or the 1st quartile) would mean, that of the data fall below this point.
Thus, the Q-Q plot presents quantiles from our sample (corresponding to residuals) related to the theoretical
ones calculated for a specific distribution. For such purpose the plot_eval_RA_forFit function supports
three residual distributions: the normal one, Student's t (including degrees of freedom, df) as well as the Cauchy one.
If the points follow the diagonal line (or are not far from this line), we may describe our residuals by the specific
distribution. Additionally, e.g. for normal "distro", the Q-Q plot can be also supported by the Shapiro-Wilk
(shapiro.test) and/or by the Kolmogorov-Smirnov (ks.test) which are both included
in the eval_ABIC_forFit. Therefore, the latter nicely works in combination with the actual function
to get residuals characteristics (distribution) and consequently, to decide which model/fit is the best.
Deviations from the diagonal/fitted line are also reflected in the histogram and probability density function/graph
(PDF, providing the chances that the value of a random continuous variable will
occur within a specific range of values). For the normal symmetric distribution it is represented by the bell-shaped
curve with the maximum at the mean (for residuals , median = mean). Thus, the PDF basically
corresponds to histogram with "extremely" high number of bins, having "extremely" small widths.
A Q-Q plot may exhibit several basic
deviations.
It can display a U-shaped pattern, which actually mirrors
the situation with the right skewed (or positively skewed, mean > median) PDF. Therefore, we find the extreme
values far from the peak on the high end more frequently than on the lower one (see e.g. Example in
eval_kinR_Eyring_GHS). Contrary, if the Q-Q plot shows
"hill" shape, the opposite situation is observed and the extreme values (outliers) far from the peak
on the low end appear more frequently than on the higher one (PDF is left skewed, mean < median).
Often, the heavy-tailed Q-Q plot with extreme residuals below and above minima and maxima of the diagonal line,
respectively, may appear and is somewhat problematic for e.g. normal distributions of residuals with outliers on both sides.
On the other hand, such kind of normality violation can be successfully described by Student's t-distribution
with lower degrees of freedom (see e.g. Examples in the eval_sim_EPR_isoFit.
Nevertheless, if the residuals, in the latter case,
do not exhibit heteroscedasticity, such model/fit is not necessarily untrustworthy.
In a very extreme case the heavy-tailed Q-Q plot may be transformed into situation where only a couple
of points around the "middle" quantile can be found on the diagonal line and the remaining points are represented
by the noticeable S-curve. This is reflected as bimodal behavior in the PDF and it might be the sign of a value clustering.
The Q-Q plot (with "pointwise" confidence bands for the diagonal/fitted line, obtained by the rlm)
in the actual function was built in the similar way like for the {qqplotr}
package. The "pointwise" bands are based on the normal confidence intervals.
The confidence level of those bands can be controlled by the level.cnfd argument
or by the Value output function plot.rqq() (and its confidence argument).
All the above-mentioned violations of the residuals (normal) distribution can disfavor our considered model/fit.
However, one has to perform different diagnostic methods and tests to analyze the residuals in order to compare
several models/fits and select the "best" one. Even in such case, this should be a compromise between
the fit accuracy (fitting the data as well as possible, including the physico-chemical reality of the system)
and the parsimony (using a simple and replicable model/fit, Kabacoff RI (2022) in the References).
A List, consisting of the following elements is returned:
Original data.fit data frame object, if additional processing/analysis
is required (see the Details or to perform Residuals vs Observation Order to verify
the assumption that the residuals are independent from one another).
Function, related to visual residual analysis), returning two main plots: Residuals vs Predicted/Fitted Values from the model/fit or simulation, and the Q-Q plot: Sample Quantiles vs Theoretical Quantiles, where the theoretical ones correspond to a specific distribution (normal/Student's/Cauchy). Therefore, function has the following arguments:
residuals.distro = c("norm","t","cauchy") (default: residuals.distro = "norm")
confidence = level.cnfd (default: confidence = level.cnfd = 0.95)
... additional arguments/parameters for the distro/distribution like df (degrees of freedom)
for the Student's t one.
Ggplot2 object, showing the histogram and the scaled probability density function for residuals. The corresponding residuals mean value and the median are identified by vertical lines.
Standard deviation of residuals (or residual standard error (RSE)) for the model/fit defined as:
where is the number of observations/points (see the data.fit argument) and
is the number of optimized parameters (see the argument k). Therefore, the smaller
the sd, the better the fit, when comparing different models/fits.
Kabacoff RI (2022). R in Action, 3rd edition, Manning Publications Co., ISBN 978-1-617-29605-5, https://www.manning.com/books/r-in-action-third-edition.
Svetunkov I (2022). Statistics for Business Analytics, Version 2025, https://openforecast.org/sba/.
Hyndman RJ, Athanasopoulos G (2021). Forecasting: Principles and Practise, 3rd edition, O Texts, ISBN 978-0-987-50713-6, https://otexts.com/fpp3/.
Chugani V (2025). "The Concise Guide to Residual Analysis", https://www.statology.org/concise-guide-residual-analysis/.
Boehmke B, Greenwell B (2020). Hand on Machine Learning with R, 1st edition, Chapman and Hall/CRC, ISBN 978-1-138-49568-5, https://bradleyboehmke.github.io/HOML/.
Kuhn M, Silge J (2023). Tidy Modelling with R, 1st edition (Version 1.0.0), O'Reilly Media, ISBN 978-1-492-09648-1, https://www.tmwr.org/.
Belzile L (2019). "lineaRmodels", https://lbelzile.github.io/lineaRmodels/
James G, Witten D, Hastie T, Tibshirani R (2021). An Introduction to Statistical Learning: with Applications in R, 2nd edition, Springer, ISBN 978-1-071-61417-4, https://www.statlearning.com/.
Speegle D, Clair B (2021). Probability, Statistics and Data: A Fresh Approach Using R, 1st edition (Version 2024), Chapman and Hall/CRC, ISBN 978-0-367-43667-4, https://probstatsdata.com/.
The Pennsylvania State University (2018). "STAT 462 Applied Regression Analysis, Lesson 9: Influential Points", https://online.stat.psu.edu/stat462/node/87/.
Nguyen M (2020). "A Guide on Data Analysis", https://bookdown.org/mike/data_analysis/.
Gray JB, Woodal WH (1994). "The Maximum Size of Standardized and Internally Studentized Residuals in Regression Analysis", Am. Stat., 48(2), 111-113, https://www.jstor.org/stable/2684258.
Frost J (2025). "Statistics by Jim: Making Statistics Intuitive", https://statisticsbyjim.com/.
Kross S (2016). "A Q-Q Plot Dissection Kit", https://seankross.com/2016/02/29/A-Q-Q-Plot-Dissection-Kit.html.
Walker JA (2020). "Normal Q-Q Plots - what is the robust Line and should we prefer it ?", https://rdoodles.rbind.io/posts-biocstyle/2020-10-15-normal-q-q-plots-what-is-the-robust-line-and-should-we-prefer-it.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
quantify_EPR_Sim_series(),
smooth_EPR_Spec_by_npreg()
## Not run: ## application example for an EPR simulation fit list.test <- plot_eval_RA_forFit( data.fit = data.sim.expr, residuals = "Residuals", fitted = "Simulation", resid.xlab = "Simulation", k = length(optim.params.init), level.cnfd = 0.99 ) # ## residual and the normal Q-Q plot list.test$plot.rqq() # ## residual and Q-Q plot for the Student's t distro ## with 4 degrees of freedom list.test$plot.rqq(residuals.distro = "t",df = 4) # ## histogram and probability density list.test$plot.histDens # ## standard deviation of residuals list.test$sd # ## from the data, quickly create the residuals vs ## observation order plot (assuming there ## is no index column in the data frame) dataframe <- list.test$df dataframe[["index"]] <- 1:nrow(dataframe) plot( dataframe$index, dataframe$Residuals, xlab = "Observation Order", ylab = "Residuals" ) # ## for additional examples, please, ## refer to the `eval_sim_EPR_isoFit` ## or `eval_kinR_EPR_modelFit` # ## End(Not run)## Not run: ## application example for an EPR simulation fit list.test <- plot_eval_RA_forFit( data.fit = data.sim.expr, residuals = "Residuals", fitted = "Simulation", resid.xlab = "Simulation", k = length(optim.params.init), level.cnfd = 0.99 ) # ## residual and the normal Q-Q plot list.test$plot.rqq() # ## residual and Q-Q plot for the Student's t distro ## with 4 degrees of freedom list.test$plot.rqq(residuals.distro = "t",df = 4) # ## histogram and probability density list.test$plot.histDens # ## standard deviation of residuals list.test$sd # ## from the data, quickly create the residuals vs ## observation order plot (assuming there ## is no index column in the data frame) dataframe <- list.test$df dataframe[["index"]] <- 1:nrow(dataframe) plot( dataframe$index, dataframe$Residuals, xlab = "Observation Order", ylab = "Residuals" ) # ## for additional examples, please, ## refer to the `eval_sim_EPR_isoFit` ## or `eval_kinR_EPR_modelFit` # ## End(Not run)
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.
plot_labels_xyz(quantity, unit, user.defined = FALSE)plot_labels_xyz(quantity, unit, user.defined = FALSE)
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 |
unit |
Variable String without quotation (some parts of the expression can be however quoted,
see examples below) referring to displayed physical quantity unit, like |
user.defined |
Logical, in order to bring more flexibility to customize quantities and units
to meet the users needs. Default: |
Axis labels/expressions for different plots.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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 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).
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" )
p |
|
data |
Data frame object in order to associate with the layout (optional). If not provided, arguments are evaluated
using the data frame in |
xlab |
Character string |
ylab |
Character string |
axis.title.x.family |
Character string, setting the font of the |
axis.title.x.color |
Character string, pointing to color of the |
axis.title.x.size |
Numeric, setting up the size of the |
axis.text.x.family |
Character string, setting the font of the |
axis.text.x.color |
Character string, pointing to color of the |
axis.text.x.size |
Numeric, setting up the size of the |
axis.title.y.family |
Character string, setting the font of the |
axis.title.y.color |
Character string, pointing to color of the |
axis.title.y.size |
Numeric, setting up the size of the |
axis.text.y.family |
Character string, setting the font of the |
axis.text.y.color |
Character string, pointing to color of the |
axis.text.y.size |
Numeric, setting up the size of the |
legend.title |
Character string |
legend.title.family |
Character string, setting the font of the legend title. Following |
legend.title.color |
Character string pointing to color of the legend title font, default:
|
legend.title.size |
Numeric, text size (in |
bg.color |
Character string, corresponding to background color of the panel/graph.
Available colors are listed on the CSS Color Module Homepage.
Default: |
grid.x |
Logical, whether to show ( |
grid.y |
Logical, whether to show ( |
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.line.width |
Numeric, width (in |
grid.line.type |
Character string, corresponding to type of the grid line. In addition to |
border.line.width |
Numeric, width (in |
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: |
List of the interactive plot object properties/parts, which can be used in the combination with
plot_EPR_Specs2D_interact or plot_ly.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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>ν</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>ν</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 )
ggplot2 Theme with Axis Ticks Oriented Inside the PanelChange 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.
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, ... )
axis.text.size |
Numeric, text size (in |
axis.title.size |
Numeric, text size (in |
grid |
Logical, whether to display the |
border.line.color |
Character string, setting up the color of the plot panel border line, default:
|
border.line.type |
Character string or integer, corresponding to width of the graph/plot panel border line. Following types
can be specified: |
border.line.width |
Numeric, width (in |
bg.transparent |
Logical, whether the entire plot background (excluding the panel)
should be transparent, default: |
... |
additional arguments specified by the |
Custom ggplot2 theme (list) with x,y-axis ticks pointing inside the graph/plot panel.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
## 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() )
ggplot2 Theme without Y Axis TicksChange 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. 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.
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, ... )
axis.text.size |
Numeric, text size (in |
axis.title.size |
Numeric, text size (in |
grid |
Logical, whether to display the |
border.line.color |
Character string, setting up the color of the plot panel border line, default:
|
border.line.type |
Character string or integer, corresponding to width of the graph/plot panel border line. Following types
can be specified: |
border.line.width |
Numeric, width (in |
bg.transparent |
Logical, whether the entire plot background (excluding the panel)
should be transparent, default: |
... |
additional arguments specified by the |
Custom ggplot2 theme (list) with x-axis ticks pointing inside the graph/plot panel,
and with y-ticks being not displayed.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_Out_ticks(),
present_EPR_Sim_Spec()
#' ## loading the aminoxyl radical CW EPR spectrum: aminoxyl.data.path <- load_data_example(file = "Aminoxyl_radical_a.DTA") 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.DTA") 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()
ggplot2 Theme with Axis Ticks Oriented Outside the PanelChange 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. 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.
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, ... )
axis.text.size |
Numeric, text size (in |
axis.title.size |
Numeric, text size (in |
grid |
Logical, whether to display the |
border.line.color |
Character string, setting up the color of the plot panel border line, default:
|
border.line.type |
Character string or integer, corresponding to width of the graph/plot panel border line. Following types
can be specified: |
border.line.width |
Numeric, width (in |
bg.transparent |
Logical, whether the entire plot background (excluding the panel)
should be transparent, default: |
... |
additional arguments specified by the |
Custom ggplot2 theme with x,y-axis ticks pointing outside of the graph/plot panel.
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
present_EPR_Sim_Spec()
## 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_file = 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::labs( x = "B (G)", y = "dIepr / dB (p.d.u.)", title = "EPR Spectrum" ) + 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_file = 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::labs( x = "B (G)", y = "dIepr / dB (p.d.u.)", title = "EPR Spectrum" ) + plot_theme_Out_ticks()
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.
present_EPR_Sim_Spec( data.spectr.expr, data.spectr.sim, B.unit = "G", Blim = NULL, 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", Blim = NULL, 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 )
data.spectr.expr |
Data frame object related to experimental spectrum, including the magnetic flux
density (in |
data.spectr.sim |
Data frame object related to experimental spectrum including the magnetic flux
density (in |
B.unit |
Character string, pointing to unit of magnetic flux density (coming from the original
datasets) which is to be presented on |
Blim |
Numeric vector, magnetic flux density in |
Intensity.expr |
Character string, referring to intensity column name if other
than |
Intensity.sim |
Character string, referring to intensity column name of the simulated spectrum
if other than |
Intensity.shift.ratio |
Numeric (CANNOT BE |
B.shift |
Numeric, difference between the |
lineSpecs.form |
Character string, describing either |
line.color.expr |
Character string, line color to plot simple EPR spectrum. All |
line.color.sim |
Character string, line color to plot simple EPR spectrum. All |
line.width |
Numeric, linewidth of the plot line in |
output.df |
Logical, whether the data frame, corresponding to graphic spectra comparison
(this actually corresponds to merging of the above-mentioned data frames
by |
Plot object 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).
Other Visualizations and Graphics:
draw_molecule_by_rcdk(),
plot_EPR_Specs(),
plot_EPR_Specs2D_interact(),
plot_EPR_Specs3D_interact(),
plot_EPR_Specs_integ(),
plot_EPR_present_interact(),
plot_labels_xyz(),
plot_layout2D_interact(),
plot_theme_In_ticks(),
plot_theme_NoY_ticks(),
plot_theme_Out_ticks()
## 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_file = 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 ## and narrower B-range present_EPR_Sim_Spec( data.spectr.expr = data.spectrum.expr, data.spectr.sim = data.spectrum.sim$df, Blim = c(3450,3550) ) + 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_file = 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 ## and narrower B-range present_EPR_Sim_Spec( data.spectr.expr = data.spectrum.expr, data.spectr.sim = data.spectrum.sim$df, Blim = c(3450,3550) ) + 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) )
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.
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 )
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 =>
Default: |
||||||||
path_to_dsc_par |
Character string, path (can be also acquired by the |
||||||||
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" ( |
||||||||
qValue |
Numeric value of the sensitivity |
||||||||
tube.sample.id.mm |
Numeric value, which equals to internal diameter (in |
||||||||
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 |
||||||||
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
|
||||||||
Temp.K |
Numeric value, temperature value in |
||||||||
S |
Numeric value, total spin sample quantum number. For radicals |
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),
,can be used to calculate the number of "spins"/radicals/paramagnetic species,
(see also References) =>
where the quantity notations possess the following meaning (parentheses denote whether it is an instrumental or sample dependent parameter):
| Quantity Symbol | Meaning/Short Desription |
|
Point sample calibration factor (instrumental). |
|
Spatial distribution of the microwave |
|
Receiver gain (commonly in |
|
Conversion time (commonly in |
|
Number of scans/accumulations during the experiment (instrumental). |
|
Microwave power (instrumental). |
|
Modulation amplitude (instrumental). |
|
Q-Value or Q-Factor characterizing the resonator/cavity/probehead sensitivity (unitless and instrumental). |
|
Boltzmann factor for temperature dependence (instrumental-sample). |
|
Total electronic spin quantum number (sample). Commonly, for radicals |
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 , where denotes
the energy difference between the basic spin states, is the Boltzmann constant
(available from syms) and the represents the temperature in .
For temperatures and continuous wave experiments where
the is constant, this factor may be very well estimated
by the following formula:
The term 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, , and modulation
amplitude, , influences the intensity of the sample predominantly along the -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.
List of the following quantities:
Number of spins per effective centimeter. It is defined
as the cm around the maximum, , of the intensity
distribution curve/polynomial fit within the cavity from
the equation shown in Details.
Number of spins per .
Concentration of spins/radicals in .
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.
Other Evaluations and Quantification:
eval_integ_EPR_Spec(),
eval_kinR_EPR_modelFit(),
eval_kinR_ODE_model(),
quantify_EPR_Norm_const()
## 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 used by quantify_EPR_Abs or to normalize
the EPR spectrum intensity. Calculation depends on the receiver gain expression.
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" )
conv.time.ms |
Numeric, conversion time in milliseconds. |
Nscans |
Numeric, number of scans. |
Npoints |
Numeric, number of points (resolution) corresponding to individual sweep,
if |
Bsw |
Numeric, experimental sweep width (magnetic flux density recording region,
|
rg |
Numeric, receiver gain value. |
rg.unit |
Character string corresponding to unit of the receiver gain.
Either |
For the receiver gain expressed in units the normalization constant is defined
by the following relation =>
where depicts the conversion time in ;
corresponds to number of scans and
is the receiver gain in . In the case that the receiver gain is unitless, the normalization
constant is defined by =>
where and correspond to unitless receiver gain
and sweep width in Gauss, respectively. 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.
Numeric value of the normalization constant for quantitative EPR and intensity normalization.
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.
Other Evaluations and Quantification:
eval_integ_EPR_Spec(),
eval_kinR_EPR_modelFit(),
eval_kinR_ODE_model(),
quantify_EPR_Abs()
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")
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. The maximum number of components is set to 10.
quantify_EPR_Sim_series( data.spectra.series, dir_ASC_sim, name.pattern.sim, origin.sim = "easyspin", var2nd.series = "time_s", B.unit = "G", col.names.sim = c("Bsim_G", "dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, Intensity.expr = "dIepr_over_dB", optim.method = "sbplx", optim.params.init, optim.params.lower = NULL, optim.params.upper = NULL, Nmax.evals = 512, single.integ = "single_IntegSim", double.integ = "double_IntegSim", msg.optim.progress = TRUE, output.area.stat = TRUE, ... )quantify_EPR_Sim_series( data.spectra.series, dir_ASC_sim, name.pattern.sim, origin.sim = "easyspin", var2nd.series = "time_s", B.unit = "G", col.names.sim = c("Bsim_G", "dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, Intensity.expr = "dIepr_over_dB", optim.method = "sbplx", optim.params.init, optim.params.lower = NULL, optim.params.upper = NULL, Nmax.evals = 512, single.integ = "single_IntegSim", double.integ = "double_IntegSim", msg.optim.progress = TRUE, output.area.stat = TRUE, ... )
data.spectra.series |
Spectrum data frame/table object containing magnetic flux density
as |
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 |
name.pattern.sim |
Character string pattern from file names related to simulated EPR spectral data
like |
origin.sim |
Character string, referring to "origin" of the simulated ASCII data.
There are four possibilities |
var2nd.series |
Character string referred to name of the second independent variable/quantity
column in the original |
B.unit |
Character string, pointing to unit of magnetic flux density
like |
col.names.sim |
Character string vector, pointing to column names/headers of the original ASCII data
series (refer also to the |
x.sim.id |
Numeric index related to the |
Intensity.sim.id |
Numeric index related to the |
Intensity.expr |
Character string, pointing to column name of the experimental EPR intensity within
the original |
optim.method |
Character string, pointing to applied optimization method/algorithm.
One may choose one from those listed in |
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.upper |
Numeric vector with the length of |
Nmax.evals |
Numeric value, maximum number of function evaluations and/or iterations.
The only one method, limited by this argument, is |
single.integ |
Character string, setting up the column/variable name related to single-integrated spectrum
within the output data frame, default: |
double.integ |
Character string, setting up the column/variable name related to double-integrated spectrum
within the output data frame, default: |
msg.optim.progress |
Logical, whether to display message (in the R console) about progress of the |
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 |
... |
additional arguments specified, see also |
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 (-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.
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 |
If output.area.stat = FALSE Tidy/long table format of the original data.spectra.series
with additional columns/variables (best fitted simulated intensities and their corresponding integrals)
for all spectral components: A, B, C, ...etc.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
smooth_EPR_Spec_by_npreg()
## 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) ## progressbar - activated # ## similar example with two components ## (simulated spectra) and tidy data frame ## output (not the summarized one) with all spectra ## and their corresponding integrals, additionally, ## display of the iteration progress for each EPR ## spectrum within the series is activated 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, eval.optim.progress = TRUE ) ## progressbar - deactivated # ## to implement the `.csv` outputs ## from `plot_eval_ExpSim_app()`, the following ## arguments must be used: ## origin.sim = "csv", ## col.names.sim = c( ## "Bsim_G", # or mT ## "B_G", # or mT ## "dIeprSim_over_dB", ## "dIepr_over_dB", ## "Norm_dIeprSim_over_dB" ## ), ## x.sim.id = 1, ## Intensity.sim.id = 3 # ## 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) ## progressbar - activated # ## similar example with two components ## (simulated spectra) and tidy data frame ## output (not the summarized one) with all spectra ## and their corresponding integrals, additionally, ## display of the iteration progress for each EPR ## spectrum within the series is activated 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, eval.optim.progress = TRUE ) ## progressbar - deactivated # ## to implement the `.csv` outputs ## from `plot_eval_ExpSim_app()`, the following ## arguments must be used: ## origin.sim = "csv", ## col.names.sim = c( ## "Bsim_G", # or mT ## "B_G", # or mT ## "dIeprSim_over_dB", ## "dIepr_over_dB", ## "Norm_dIeprSim_over_dB" ## ), ## x.sim.id = 1, ## Intensity.sim.id = 3 # ## End(Not run)
Based on the fread or readBin R functions,
the experimental EPR/ENDOR spectra (referred to as 1D- or 2D-Experiments) or other original (pre-processed)
data from the EPR spectrometers are transformed into data frames (tables). The function can read several data formats
such as .txt, .csv, .asc, .DTA, .spc as well as .YGF
with the latter three extensions, corresponding to binary files (function automatically recognizes which type of data,
ASCII or binary, are loaded). Reading of such data requires information (instrumental parameters
of the acquired spectra/data) provided by the .DSC/.dsc or .par files, respectively
(see the path_to_dsc_par as well as path_to_ygf arguments description). Because the original
file structure depends on the EPR spectrometer acquisition software or data processing, the origin argument
is necessary to specify the data/file source. Default function arguments are pre-configured for origin ="xenon".
readEPR_Exp_Specs( path_to_file, path_to_dsc_par = NULL, path_to_ygf = NULL, sep = "auto", skip = 1, header = FALSE, col.names = c("index", "B_G", "dIepr_over_dB"), x.id = 2, x.unit = "G", Intensity.id = 3, var2nd.series.id = NULL, convertB.unit = TRUE, qValue = NULL, norm.vec.add = NULL, origin = "xenon", data.structure = "spectra", ... )readEPR_Exp_Specs( path_to_file, path_to_dsc_par = NULL, path_to_ygf = NULL, sep = "auto", skip = 1, header = FALSE, col.names = c("index", "B_G", "dIepr_over_dB"), x.id = 2, x.unit = "G", Intensity.id = 3, var2nd.series.id = NULL, convertB.unit = TRUE, qValue = NULL, norm.vec.add = NULL, origin = "xenon", data.structure = "spectra", ... )
path_to_file |
Character string, path to any spectrometer/instrumental file,
having one the following extensions: |
||||||||||
path_to_dsc_par |
Character string, path (can be also provided by the |
||||||||||
path_to_ygf |
Character string, path (can be also provided by the |
||||||||||
sep |
Character string. The separator between columns/variables in the original ASCII text file.
Default: |
||||||||||
skip |
Numeric value, referring to the number of rows, at the beginning of ASCII text file, to be skipped
(not included by loading into the data frame). Default: |
||||||||||
header |
Logical. Does the first data line, in the original ASCII file, contain column names? Defaults according
to whether every non-empty field on the first data line is character type. If so, or TRUE is supplied, any empty column
names are given by a default name. Default: |
||||||||||
col.names |
Character string vector, corresponding to desired column/variable names/headers of the returned
data frame/table. A safe rule of thumb is to use column names incl. physical quantity notation
with its unit, |
||||||||||
x.id |
Numeric index related to |
||||||||||
x.unit |
Character string, corresponding to original |
||||||||||
Intensity.id |
Numeric index related to |
||||||||||
var2nd.series.id |
Numeric index related to |
||||||||||
convertB.unit |
Logical (default: |
||||||||||
qValue |
Numeric, Q value (quality factor, number) displayed at specific |
||||||||||
norm.vec.add |
Numeric vector. Additional (division) normalization constant(s) in the form of vector, including
all (in addition to |
||||||||||
origin |
Character string, corresponding to origin of the data and related to EPR acquisition software
at the spectrometer (from which the data are loaded automatically using the default parameters).
Options are summarized in the following table (any other specific
|
||||||||||
data.structure |
Character string, referring to structure of the ASCII data. Common spectral data files
with |
||||||||||
... |
additional arguments specified (see also the |
Right after the instrumental or pre-processed data/files are transformed into data frames,
they can be easily handled by the actual or additional R packages, e.g. by dplyr),
afterwards. Spectral intensities are 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 (it actually equals to 1),
it can be also defined as a component of the norm.vec.add. Finally, the normalized (derivative) intensity
is calculated by the following expression (depending on the qValue and/or norm.vec.add):
or
or
where the is iterating through all components of the norm.vec.add.
The structure of files depends on the origin/software used to acquire the EPR spectra.
This is mainly mirrored 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 configured like origin = "winepr" or origin = "magnettech" or even
any arbitrary string e.g. origin = "csv" (see also description of the origin argument).
For the latter, all arguments must be defined accordingly, as already demonstrated in Examples.
When reading the spectrometer files, any 2D-experiment (e.g. time/temperature/microwave power series)
can be loaded as well. This must be activated by the var2nd.series.id argument
(which is NULL by default to load the 1D-experiments), pointing to col.names element
index in order to define relevant column of the returned data frame. For example, if the second
variable series corresponds to time (in seconds) column:
e.g. col.names = c("index","B_G","time_s","dIepr_over_dB"), the id
must be defined as var2nd.series.id = 3.
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/function arguments.
For 2D experiments (spectral series) an additional column with the 2nd independent variable (like time, temperature
or microwave power, ...etc. ) is created. In such case the actual data frame is return
in the tidy/long table format.
Other Data Reading:
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## simple ASCII EPR spectrum acquired by "xenon" ## and with `B` conversion "G" <=> "mT" ## Loading the data aminoxyl.ascii.data.path <- load_data_example(file = "Aminoxyl_radical_a.txt") aminoxyl.data.01 <- readEPR_Exp_Specs( aminoxyl.ascii.data.path, qValue = 2100 ) ## preview head(aminoxyl.data.01) # ## the same EPR spectrum data, reading from ## the original `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data aminoxyl.bin.data.path <- load_data_example(file = "Aminoxyl_radical_a.DTA") aminoxyl.data.02 <- readEPR_Exp_Specs( aminoxyl.bin.data.path, qValue = 2100 ) ## preview head(aminoxyl.data.02) # # simple EPR spectrum acquired by "xenon" ## and without `B` conversion "G" <=> "mT" aminoxyl.data.03 <- readEPR_Exp_Specs(aminoxyl.bin.data.path, convertB.unit = FALSE, qValue = 2100) ## preview head(aminoxyl.data.03) # ## the simple spectrum acquired by "winepr" ## (and 20 scans) on a 1 mM sample concentration: ## Loading the data TMPD.ascii.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.asc") TMPD.data.01 <- readEPR_Exp_Specs( TMPD.ascii.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.01) # ## the same EPR spectrum data, reading from ## the original `.spc` binary (+ `.par` text) file(s) ## Loading the data TMPD.bin.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.spc") TMPD.data.02 <- readEPR_Exp_Specs( path_to_file = TMPD.bin.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.02) # ## the ENDOR spectrum recorded by "xenon" ## and 8 accumulation sweeps (ASCII data) ## loading the data PNT.ENDOR.ascii.data.path <- load_data_example(file = "PNT_ENDOR_a.txt") PNT.ENDOR.data.01 <- readEPR_Exp_Specs( PNT.ENDOR.ascii.data.path, col.names = c("index", "RF_MHz", "dIepr_over_dB"), x.unit = "MHz", norm.vec.add = 8 ) ## preview head(PNT.ENDOR.data.01) # ## previous ENDOR spectrum data, reading from ## the original `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data PNT.ENDOR.bin.data.path <- load_data_example(file = "PNT_ENDOR_a.DTA") PNT.ENDOR.data.02 <- readEPR_Exp_Specs( PNT.ENDOR.bin.data.path, col.names = c("index", "RF_MHz", "dIepr_over_dB"), x.unit = "MHz", norm.vec.add = 8 ) ## preview head(PNT.ENDOR.data.02) # ## reading the (pre-processed) ASCII ## data file (data.structure = "others") 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` by 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_file = 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.01 <- readEPR_Exp_Specs(acridineRad.data, col.names = c("B_mT","dIepr_over_dB"), x.unit = "mT", qValue = 1829, origin = "magnettech") ## preview head(acridineRad.data.01) # ## previous acridine EPR spectrum data, reading from ## the original `.DTA` binary (+ `.dsc` text) file(s) ## Loading the data acridineRad.bin.data.path <- load_data_example("AcridineDeriv_Irrad_365nm.DTA") acridineRad.data.02 <- readEPR_Exp_Specs( path_to_file = acridineRad.bin.data.path, origin = "magnetech", qValue = 1829 ) # ## preview head(acridineRad.data.02) # ## EPR time series (2D Experiment) acquired ## by the "Winepr"/"WinEpr", reading the original ## `.spc` binary (+ `.par` text) file(s) ## Loading the data TMPD.se.bin.data.2D.path <- load_data_example("TMPD_specelchem_CV_b.spc") TMPD.se.data.2D <- readEPR_Exp_Specs( path_to_file = TMPD.se.bin.data.2D.path, col.names = c( "B_G", "Slice", "dIepr_over_dB" ), var2nd.series.id = 2, origin = "winepr" ) # ## preview head(TMPD.se.data.2D) # ## EPR time series (2D experiment) acquired ## by the "Xenon", reading the original ## `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data triarylamine.rc.decay.series.path <- load_data_example("Triarylamine_radCat_decay_series.DTA") triarylamine.rc.decay.series.data <- readEPR_Exp_Specs( path_to_file = triarylamine.rc.decay.series.path, col.names = c( "index", "B_G", "time_s", "dIepr_over_dB" ), var2nd.series.id = 3, qValue = 1700 ) # ## preview head(triarylamine.rc.decay.series.data) # ## reading of the individual `.YGF` file (Xenon) ## into vector tam.rc.decay.series.ygf.path <- load_data_example("Triarylamine_radCat_decay_series.YGF") # ## file length tam.rc.decay.series.ygf.len <- readBin( con = tam.rc.decay.series.ygf.path, what = "raw", n = 1e+4 ) %>% length() # ## `.YGF` file reading tam.rc.decay.series.ygf <- readBin( con = tam.rc.decay.series.ygf.path, what = "numeric", size = 8, ## Xenon n = tam.rc.decay.series.ygf.len / 8, ## Xenon signed = TRUE, endian = "big" ## Xenon ) # ## preview of the first 10 values (time in s) tam.rc.decay.series.ygf[1:10] # ## Not run: ## read the `.csv` file which is an output ## from the 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 ASCII EPR spectrum acquired by "xenon" ## and with `B` conversion "G" <=> "mT" ## Loading the data aminoxyl.ascii.data.path <- load_data_example(file = "Aminoxyl_radical_a.txt") aminoxyl.data.01 <- readEPR_Exp_Specs( aminoxyl.ascii.data.path, qValue = 2100 ) ## preview head(aminoxyl.data.01) # ## the same EPR spectrum data, reading from ## the original `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data aminoxyl.bin.data.path <- load_data_example(file = "Aminoxyl_radical_a.DTA") aminoxyl.data.02 <- readEPR_Exp_Specs( aminoxyl.bin.data.path, qValue = 2100 ) ## preview head(aminoxyl.data.02) # # simple EPR spectrum acquired by "xenon" ## and without `B` conversion "G" <=> "mT" aminoxyl.data.03 <- readEPR_Exp_Specs(aminoxyl.bin.data.path, convertB.unit = FALSE, qValue = 2100) ## preview head(aminoxyl.data.03) # ## the simple spectrum acquired by "winepr" ## (and 20 scans) on a 1 mM sample concentration: ## Loading the data TMPD.ascii.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.asc") TMPD.data.01 <- readEPR_Exp_Specs( TMPD.ascii.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.01) # ## the same EPR spectrum data, reading from ## the original `.spc` binary (+ `.par` text) file(s) ## Loading the data TMPD.bin.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.spc") TMPD.data.02 <- readEPR_Exp_Specs( path_to_file = TMPD.bin.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.02) # ## the ENDOR spectrum recorded by "xenon" ## and 8 accumulation sweeps (ASCII data) ## loading the data PNT.ENDOR.ascii.data.path <- load_data_example(file = "PNT_ENDOR_a.txt") PNT.ENDOR.data.01 <- readEPR_Exp_Specs( PNT.ENDOR.ascii.data.path, col.names = c("index", "RF_MHz", "dIepr_over_dB"), x.unit = "MHz", norm.vec.add = 8 ) ## preview head(PNT.ENDOR.data.01) # ## previous ENDOR spectrum data, reading from ## the original `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data PNT.ENDOR.bin.data.path <- load_data_example(file = "PNT_ENDOR_a.DTA") PNT.ENDOR.data.02 <- readEPR_Exp_Specs( PNT.ENDOR.bin.data.path, col.names = c("index", "RF_MHz", "dIepr_over_dB"), x.unit = "MHz", norm.vec.add = 8 ) ## preview head(PNT.ENDOR.data.02) # ## reading the (pre-processed) ASCII ## data file (data.structure = "others") 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` by 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_file = 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.01 <- readEPR_Exp_Specs(acridineRad.data, col.names = c("B_mT","dIepr_over_dB"), x.unit = "mT", qValue = 1829, origin = "magnettech") ## preview head(acridineRad.data.01) # ## previous acridine EPR spectrum data, reading from ## the original `.DTA` binary (+ `.dsc` text) file(s) ## Loading the data acridineRad.bin.data.path <- load_data_example("AcridineDeriv_Irrad_365nm.DTA") acridineRad.data.02 <- readEPR_Exp_Specs( path_to_file = acridineRad.bin.data.path, origin = "magnetech", qValue = 1829 ) # ## preview head(acridineRad.data.02) # ## EPR time series (2D Experiment) acquired ## by the "Winepr"/"WinEpr", reading the original ## `.spc` binary (+ `.par` text) file(s) ## Loading the data TMPD.se.bin.data.2D.path <- load_data_example("TMPD_specelchem_CV_b.spc") TMPD.se.data.2D <- readEPR_Exp_Specs( path_to_file = TMPD.se.bin.data.2D.path, col.names = c( "B_G", "Slice", "dIepr_over_dB" ), var2nd.series.id = 2, origin = "winepr" ) # ## preview head(TMPD.se.data.2D) # ## EPR time series (2D experiment) acquired ## by the "Xenon", reading the original ## `.DTA` binary (+ `.DSC` text) file(s) ## Loading the data triarylamine.rc.decay.series.path <- load_data_example("Triarylamine_radCat_decay_series.DTA") triarylamine.rc.decay.series.data <- readEPR_Exp_Specs( path_to_file = triarylamine.rc.decay.series.path, col.names = c( "index", "B_G", "time_s", "dIepr_over_dB" ), var2nd.series.id = 3, qValue = 1700 ) # ## preview head(triarylamine.rc.decay.series.data) # ## reading of the individual `.YGF` file (Xenon) ## into vector tam.rc.decay.series.ygf.path <- load_data_example("Triarylamine_radCat_decay_series.YGF") # ## file length tam.rc.decay.series.ygf.len <- readBin( con = tam.rc.decay.series.ygf.path, what = "raw", n = 1e+4 ) %>% length() # ## `.YGF` file reading tam.rc.decay.series.ygf <- readBin( con = tam.rc.decay.series.ygf.path, what = "numeric", size = 8, ## Xenon n = tam.rc.decay.series.ygf.len / 8, ## Xenon signed = TRUE, endian = "big" ## Xenon ) # ## preview of the first 10 values (time in s) tam.rc.decay.series.ygf[1:10] # ## Not run: ## read the `.csv` file which is an output ## from the 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)
Reading the continuous wave (CW) EPR time series spectral data (recorded by e.g. 2D_Field_Delay
experiment in "Xenon" acquisition/processing software). Function is based on the readEPR_Exp_Specs
and includes automatic time correction for CW EPR time.series experiments
(see also the correct_time_Exp_Specs description and documentation). If the time series EPR spectra
are stored individually (one file per one spectrum, e.g. for origin = "Magnettech", ESR5000 [11-0422]),
such time series needs to be loaded by readEPR_Exp_Specs_multif. For origin = "WinEpr"
the time_s column usually possesses the form of spectrum slices, i.e. an integer number (0,1,2,...) is assigned
to each recorded spectrum. Therefore, for a radical kinetic analysis it has to be converted to time_s
(see the argument time.delta.slice).
readEPR_Exp_Specs_kin( path_to_file, path_to_dsc_par = NULL, path_to_ygf = NULL, time.unit = "s", time.delta.slice = NULL, col.names = c("index", "B_G", "time_s", "dIepr_over_dB"), x.unit = "G", var2nd.series.id = 3, origin = "xenon", qValue = NULL, ... )readEPR_Exp_Specs_kin( path_to_file, path_to_dsc_par = NULL, path_to_ygf = NULL, time.unit = "s", time.delta.slice = NULL, col.names = c("index", "B_G", "time_s", "dIepr_over_dB"), x.unit = "G", var2nd.series.id = 3, origin = "xenon", qValue = NULL, ... )
path_to_file |
Character string, path to any spectrometer/instrumental file,
having one the following extensions: |
||||||||||
path_to_dsc_par |
Character string, path (can be also provided by the |
||||||||||
path_to_ygf |
Character string, path (can be also provided by the |
||||||||||
time.unit |
Character string, specifying the |
||||||||||
time.delta.slice |
Numeric, time interval in |
||||||||||
col.names |
Character string vector, corresponding to desired column/variable names/headers of the returned
data frame/table. A safe rule of thumb is to use column names incl. physical quantity notation
with its unit, |
||||||||||
x.unit |
Character string, corresponding to original |
||||||||||
var2nd.series.id |
Numeric index related to |
||||||||||
origin |
Character string, corresponding to origin of the data and related to EPR acquisition software
at the spectrometer (from which the data are loaded automatically using the default parameters).
Options are summarized in the following table (any other specific
|
||||||||||
qValue |
Numeric, Q value (quality or sensitivity factor number) displayed at specific |
||||||||||
... |
additional arguments specified, see also the |
List of EPR spectrum time series data 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 (see arguments and examples).
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## loading the built-in package example to demonstrate ## the reading of time series EPR spectra/kinetics: triarylam.decay.series.dta.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") # ## loading the kinetics: triarylam.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylam.decay.series.dta.path ) # ## 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 # ## reading the EPR time series ## returned by the "WinEPR" software tmpd.se.cv.b.bin.path <- load_data_example("TMPD_specelchem_CV_b.spc") tmpd.se.cv.b.dat <- readEPR_Exp_Specs_kin( path_to_file = tmpd.se.cv.b.bin.path, col.names = c( "B_G", "Slice", "dIepr_over_dB" ), var2nd.series.id = 2, time.delta.slice = 18, # 18 seconds origin = "winepr" ) # ## data preview head(tmpd.se.cv.b.dat$df) # ## time preview tmpd.se.cv.b.dat$time## loading the built-in package example to demonstrate ## the reading of time series EPR spectra/kinetics: triarylam.decay.series.dta.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") # ## loading the kinetics: triarylam.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylam.decay.series.dta.path ) # ## 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 # ## reading the EPR time series ## returned by the "WinEPR" software tmpd.se.cv.b.bin.path <- load_data_example("TMPD_specelchem_CV_b.spc") tmpd.se.cv.b.dat <- readEPR_Exp_Specs_kin( path_to_file = tmpd.se.cv.b.bin.path, col.names = c( "B_G", "Slice", "dIepr_over_dB" ), var2nd.series.id = 2, time.delta.slice = 18, # 18 seconds origin = "winepr" ) # ## data preview head(tmpd.se.cv.b.dat$df) # ## time preview tmpd.se.cv.b.dat$time
Loading the EPR spectra from several/multiple 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 (individual spectra) 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.
readEPR_Exp_Specs_multif( name.pattern, dir_asc_bin, dir_dsc_par, read.ascii = TRUE, col.names = c("index", "B_G", "dIepr_over_dB"), x.unit = "G", 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_bin, dir_dsc_par, read.ascii = TRUE, col.names = c("index", "B_G", "dIepr_over_dB"), x.unit = "G", convertB.unit = TRUE, qValues = NULL, norm.list.add = NULL, names, tidy = FALSE, var2nd.series = NULL, var2nd.series.factor = FALSE, origin = "xenon", ... )
name.pattern |
Character string ('specimen'), inherited from |
||||||||||
dir_asc_bin |
Path (defined by |
||||||||||
dir_dsc_par |
Path (defined by |
||||||||||
read.ascii |
Logical, whether to read the ASCII EPR data files with the extensions |
||||||||||
col.names |
Character string vector, inherited from |
||||||||||
x.unit |
Character string pointing to unit of quantity (coming from the original data, see also
|
||||||||||
convertB.unit |
Logical (default: |
||||||||||
qValues |
Numeric vector of Q-values (sensitivity factors to normalize EPR intensities) either loaded from
the instrumental parameters ( |
||||||||||
norm.list.add |
Numeric list of vectors. Additional normalization constants in the form of vectors involving
all (i.e. in addition to |
||||||||||
names |
Character string vector, corresponding either to values of additional - 2nd variable/quantity
(e.g. temperature,microwave power...etc, |
||||||||||
tidy |
Logical, whether to transform the list of data frames into the long table ( |
||||||||||
var2nd.series |
Character string, if |
||||||||||
var2nd.series.factor |
Logical, whether to factorize |
||||||||||
origin |
Character string, corresponding to origin of the data and related to EPR acquisition software
at the spectrometer (from which the data are loaded automatically using the default parameters).
Options are summarized in the following table (any other specific
|
||||||||||
... |
additional arguments specified, see also |
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.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## 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.unit = "MHz", 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_", dir_asc_bin = "./RAW_EPR_data_dir", dir_dsc_par = "./DSC_EPR_data_dir", read.ascii = FALSE, col.names = c("B_G","dIepr_over_dB"), x.unit = "G", 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_bin = ".", dir_dsc_par = ".", names = c("a","b","c","d"), tidy = TRUE, var2nd.series = "sample", norm.list.add = rep(list(8),4)) # ## time series coming from `Magnettech` as individual EPR spectra ## (represented by binary files `.DTA`) recorded at different ## time in seconds -> see `names` argument readEPR_Exp_Specs_multif( name.pattern = "Kinetics_EPR_Spectra_", dir_asc_bin = "./Input_EPR_Data", dir_dsc_par = "./Input_EPR_Data", read.ascii = FALSE, names = c("20","40","60","80","100","120"), tidy = TRUE, var2nd.series = "time_s", origin = "magnettech" ) # ## time series coming from `Magnettech` as individual EPR spectra ## (represented by ASCII files `.csv`) recorded at different ## time in seconds -> see `names` argument data.time.series.mngtech <- readEPR_Exp_Specs_multif( name.pattern = "Kinetics_EPR_Spectra_", dir_asc_bin = "./Input_EPR_Data", dir_dsc_par = "./Input_EPR_Data", col.names = c("B_mT","dIepr_over_dB"), x.unit = "mT", names = as.character(c(1:12)), # total number of spectra: 12 tidy = TRUE, var2nd.series = "Slice", origin = "magnettech" ) # ## convert the `Slice` column (of the previous data) into `time_s`, ## using the `dplyr` package, time interval between recording ## of the two consecutive Slices/EPR spectra corresponds to 32 s: data.time.series.mngtech <- data.time.series.mngtech %>% mutate(time_s = (Slice - 1) * 32) # 32 s time interval ## correct time, if the middle of an individual spectrum ## appears at the sweep time half data.time.series.mngtech$time_s <- correct_time_Exp_Specs( time.s = data.time.series.mngtech$time_s, # how many accumulations per individual EPR spectrum ? : Nscans = 1, # experimental sweep time (for one EPR spectrum) in seconds: sweep.time.s = 26 ) # ## 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.unit = "MHz", 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_", dir_asc_bin = "./RAW_EPR_data_dir", dir_dsc_par = "./DSC_EPR_data_dir", read.ascii = FALSE, col.names = c("B_G","dIepr_over_dB"), x.unit = "G", 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_bin = ".", dir_dsc_par = ".", names = c("a","b","c","d"), tidy = TRUE, var2nd.series = "sample", norm.list.add = rep(list(8),4)) # ## time series coming from `Magnettech` as individual EPR spectra ## (represented by binary files `.DTA`) recorded at different ## time in seconds -> see `names` argument readEPR_Exp_Specs_multif( name.pattern = "Kinetics_EPR_Spectra_", dir_asc_bin = "./Input_EPR_Data", dir_dsc_par = "./Input_EPR_Data", read.ascii = FALSE, names = c("20","40","60","80","100","120"), tidy = TRUE, var2nd.series = "time_s", origin = "magnettech" ) # ## time series coming from `Magnettech` as individual EPR spectra ## (represented by ASCII files `.csv`) recorded at different ## time in seconds -> see `names` argument data.time.series.mngtech <- readEPR_Exp_Specs_multif( name.pattern = "Kinetics_EPR_Spectra_", dir_asc_bin = "./Input_EPR_Data", dir_dsc_par = "./Input_EPR_Data", col.names = c("B_mT","dIepr_over_dB"), x.unit = "mT", names = as.character(c(1:12)), # total number of spectra: 12 tidy = TRUE, var2nd.series = "Slice", origin = "magnettech" ) # ## convert the `Slice` column (of the previous data) into `time_s`, ## using the `dplyr` package, time interval between recording ## of the two consecutive Slices/EPR spectra corresponds to 32 s: data.time.series.mngtech <- data.time.series.mngtech %>% mutate(time_s = (Slice - 1) * 32) # 32 s time interval ## correct time, if the middle of an individual spectrum ## appears at the sweep time half data.time.series.mngtech$time_s <- correct_time_Exp_Specs( time.s = data.time.series.mngtech$time_s, # how many accumulations per individual EPR spectrum ? : Nscans = 1, # experimental sweep time (for one EPR spectrum) in seconds: sweep.time.s = 26 ) # ## End(Not run)
Extracting 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).
readEPR_param_slct(path_to_dsc_par, string, origin = "xenon")readEPR_param_slct(path_to_dsc_par, string, origin = "xenon")
path_to_dsc_par |
Character string, path to |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
string |
Character (vector) string (appeared at the line beginning) within
the
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
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", |
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.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## 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") )
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.
readEPR_params_slct_kin(path_to_dsc_par, origin = "xenon")readEPR_params_slct_kin(path_to_dsc_par, origin = "xenon")
path_to_dsc_par |
String, path to |
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", |
List containing:
Number of scans.
Sweep time in s required for time correction during the 2D_Field_Delay
(time series EPR experiment).Refer to the correct_time_Exp_Specs as well as to the
readEPR_Exp_Specs_kin functions.
Number of points (resolution of an EPR spectrum).
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## 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)
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 (
radical or paramagnetic species number determination, see the quantify_EPR_Abs function).
readEPR_params_slct_quant(path_to_dsc_par, origin = "xenon")readEPR_params_slct_quant(path_to_dsc_par, origin = "xenon")
path_to_dsc_par |
Character string, path (also provided by |
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", |
List consisting of:
Modulation amplitude value in mT.
Microwave source power in mW.
Experimental temperature in K.
Microwave frequency value in GHz.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## 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)
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).
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")
path_to_dsc_par |
Character string, path (also provided by |
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", |
B.unit |
Character string, pointing to unit of magnetic flux density which is the output
"unit", |
List consisting of:
Central field (magnetic flux density, B) value in B.unit.
Sweep width (magnetic flux density, B, experimental range) value in B.unit.
Number of points (spectral resolution).
Microwave frequency value in GHz.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## 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")
Extraction of 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 function.
readEPR_params_tabs(path_to_dsc_par, origin = "xenon", interact = NULL)readEPR_params_tabs(path_to_dsc_par, origin = "xenon", interact = NULL)
path_to_dsc_par |
Character string, path (also provided by |
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", |
interact |
Character string, whether to display interactive tables by the |
List of data frames/tables containing:
Instrumental parameters with their numeric values and units.
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.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_solvent_props(),
readMAT_params_file()
## 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")
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.
readEPR_Sim_Spec( path_to_ASC, B.unit = "G", col.names.sim = c("Bsim_G", "dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, origin.sim = "easyspin" )readEPR_Sim_Spec( path_to_ASC, B.unit = "G", col.names.sim = c("Bsim_G", "dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, origin.sim = "easyspin" )
path_to_ASC |
Character string, path to ASCII file/table
with simulated spectral data ( |
B.unit |
Character string, pointing to unit of magnetic flux density coming from the original data
which is to be presented on the |
col.names.sim |
Character string vector, pointing to column names/headers of the original ASCII data
(refer also to the |
x.sim.id |
Numeric index related to the |
Intensity.sim.id |
Numeric index related to the |
origin.sim |
Character string, referring to the "origin" of a simulated spectrum ASCII data.
There are four possibilities |
Data frame, consisting of magnetic flux density and intensity variable/column
(depending on the col.names.sim and .id arguments), corresponding to simulated EPR spectrum.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props(),
readMAT_params_file()
## Not run: readEPR_Sim_Spec(path_to_ASC = "./Simulations/TEMPO_simulation.txt", origin.sim = "xenon") # readEPR_Sim_Spec( "Cu_complex_simulation.txt", B.unit = "mT", col.names.sim = c("Bsim_G","dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, origin.sim = "easyspin" ) # ## load simulated EPR spectrum from `.csv` file ## generated by the `plot_eval_ExpSim_app()` function test.sim.df <- readEPR_Sim_Spec( "testicek_table.csv", col.names.sim = c( "Bsim_G", "B_G", "dIeprSim_over_dB", "dIepr_over_dB", "Norm_dIeprSim_over_dB" ), x.sim.id = 1, Intensity.sim.id = 3, origin.sim = "csv" ) # ## such `.csv` can be also used to load ## simulated EPR spectrum/spectra in order ## to get quantitative information ## by the `quantify_EPR_Sim_series()` function ## End(Not run)## Not run: readEPR_Sim_Spec(path_to_ASC = "./Simulations/TEMPO_simulation.txt", origin.sim = "xenon") # readEPR_Sim_Spec( "Cu_complex_simulation.txt", B.unit = "mT", col.names.sim = c("Bsim_G","dIeprSim_over_dB"), x.sim.id = 1, Intensity.sim.id = 2, origin.sim = "easyspin" ) # ## load simulated EPR spectrum from `.csv` file ## generated by the `plot_eval_ExpSim_app()` function test.sim.df <- readEPR_Sim_Spec( "testicek_table.csv", col.names.sim = c( "Bsim_G", "B_G", "dIeprSim_over_dB", "dIepr_over_dB", "Norm_dIeprSim_over_dB" ), x.sim.id = 1, Intensity.sim.id = 3, origin.sim = "csv" ) # ## such `.csv` can be also used to load ## simulated EPR spectrum/spectra in order ## to get quantitative information ## by the `quantify_EPR_Sim_series()` function ## End(Not run)
solvents_ds DatasetGathering 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").
readEPR_solvent_props(solvent, prop = NULL)readEPR_solvent_props(solvent, prop = NULL)
solvent |
Character string, pointing to solvent name (or any string from the solvent name/abbreviation),
such as |
prop |
Character string related to a data frame variable/column/property e.g. |
Data frame with row/rows of selected solvent(s) and the corresponding properties. If a specific property
is called like code = "melting" ( melting point in °C), the function returns
value/character.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readMAT_params_file()
## 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")
.mat FileFunction 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).
readMAT_params_file(path_to_MAT, str.var = NULL, field.var = NULL)readMAT_params_file(path_to_MAT, str.var = NULL, field.var = NULL)
path_to_MAT |
Character string, path to |
str.var |
Character string, denoting structure/variable, which may contain |
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 |
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.
Other Data Reading:
readEPR_Exp_Specs(),
readEPR_Exp_Specs_kin(),
readEPR_Exp_Specs_multif(),
readEPR_Sim_Spec(),
readEPR_param_slct(),
readEPR_params_slct_kin(),
readEPR_params_slct_quant(),
readEPR_params_slct_sim(),
readEPR_params_tabs(),
readEPR_solvent_props()
## 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" ## or "fitraw", corresponding to scaled and raw intensity ## of the simulated EPR spectrum, please refer also ## to the EasySpin documentantion: ## https://easyspin.org/easyspin/documentation/esfit.html # ## 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" ## or "fitraw", corresponding to scaled and raw intensity ## of the simulated EPR spectrum, please refer also ## to the EasySpin documentantion: ## https://easyspin.org/easyspin/documentation/esfit.html # ## 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)
Providing table, based on Gaussian/ORCA/...etc. output text files in order to summarize
the mean / values (including the sign) of groups with equivalent nuclei,
according to proposed molecular structure/symmetry.
rearrange_aAiso_QCHcomp(path_to_ASC, col.names, nuclei.list.slct)rearrange_aAiso_QCHcomp(path_to_ASC, col.names, nuclei.list.slct)
path_to_ASC |
Character string, pointing to path of ASCII file ( |
col.names |
Character string vector, containing names of all columns from QCH computational output,
for the names see example in |
nuclei.list.slct |
List of numeric values for the rearrangement of selected atoms/nuclei according to symmetry,
e.g. |
The / 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 a required file/table structure (e.g. for 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 label,
hyperfine coupling constant in MHz and finally hyperfine splitting constant in G. These columns/variables
are essential for the evaluation.
Data frame/Table of / mean values (including the signs) corresponding
to groups of equivalent nuclei within the structure/symmetry.
Other Evaluations and Quantum Chemistry:
eval_gFactor_QCHcomp(),
rearrange_aAiso_QCHorgau()
## 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)
Providing table, specifically from Gaussian (version G.09) or ORCA (version 5.0)
output text files to summarize the / mean values (including the sign) of groups with
equivalent nuclei, according to proposed molecular structure/symmetry (see also the rearrange_aAiso_QCHcomp).
For each group, a mean value is returned.
rearrange_aAiso_QCHorgau( path_to_QCHoutput, nuclei.list.slct, origin = "gaussian", output.text.origin = FALSE, output.text.path = NULL )rearrange_aAiso_QCHorgau( path_to_QCHoutput, nuclei.list.slct, origin = "gaussian", output.text.origin = FALSE, output.text.path = NULL )
path_to_QCHoutput |
Character string, corresponding to path of |
nuclei.list.slct |
List of numeric values for the rearrangement of selected atoms/nuclei according to symmetry,
e.g. |
origin |
Character string, pointing to origin of (DFT) EPR calculation parameters <=> which
software package was used. Only two values are available => |
output.text.origin |
Logical, whether to write a text file containing the extracted
|
output.text.path |
Character string, setting the path to file containing
the extracted |
Data frame/Table of / mean values (including the signs),
corresponding to groups of proposed equivalent nuclei within the structure/symmetry constructed directly
from Gaussian or ORCA output text files.
Other Evaluations and Quantum Chemistry:
eval_gFactor_QCHcomp(),
rearrange_aAiso_QCHcomp()
## 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, 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 knitr::kable( symmetry.As.df, caption = "DFT computed hyperfine couplings(Aiso)/splittings(aiso) for the TMPD radical cation." )## 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, 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 knitr::kable( symmetry.As.df, caption = "DFT computed hyperfine couplings(Aiso)/splittings(aiso) for the TMPD radical cation." )
Smoothing of the EPR spectra by non-parametric fitting a smoothing spline, ss
from the npreg package, onto the experimental
EPR spectrum/spectra.
smooth_EPR_Spec_by_npreg( data.spectr, B = "B_mT", B.unit = "mT", lineSpecs.form = "derivative", Intensity = "dIepr_over_dB", method = "BIC", vectorize = FALSE, ... )smooth_EPR_Spec_by_npreg( data.spectr, B = "B_mT", B.unit = "mT", lineSpecs.form = "derivative", Intensity = "dIepr_over_dB", method = "BIC", vectorize = FALSE, ... )
data.spectr |
Spectrum data frame object where the magnetic flux density (in |
||||||||||||||||||
B |
Character string, pointing to magnetic flux density |
||||||||||||||||||
B.unit |
Character string, denoting the magnetic flux density unit e.g. |
||||||||||||||||||
lineSpecs.form |
Character string, describing either |
||||||||||||||||||
Intensity |
Character string, pointing to |
||||||||||||||||||
method |
Character string, corresponding to method in order to fit an EPR spectrum by a smoothing spline
from
|
||||||||||||||||||
vectorize |
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 |
||||||||||||||||||
... |
additional arguments passed to the function (see also the |
The EPR spectrum is fitted by splines which, by default, correspond to cubic Bernoulli polynomials like
where equals to general EPR intensity and 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:
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.
If vectorize = 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 vectorize is set to FALSE the following list is returned =>
Original data frame with the addition column, corresponding to smoothed EPR intensity (derivative or integrated).
Plot object EPR intensity vs. B with the experimental data and its corresponding smoothed relation performed by splines.
Weighted (if the optional parameter w is defined) sum of residual squares.
Equivalent degrees of freedom used.
List with elements to characterize the spline fit (Details see fit value
in the ss function documentation).
Standard deviation of residuals.
Numeric vector/value of Akaike’s Information Criterion (if the method = "AIC")
or Bayesian Information Criterion (if the method = "BIC"). These are negative numbers,
having the largest modulus (deepest down in the negative territory) and therefore, indicating
the preferred model (the lower, the better, see also eval_ABIC_forFit.
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.
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.
Other Simulations and Optimization:
eval_ABIC_forFit(),
eval_sim_EPR_iso(),
eval_sim_EPR_isoFit(),
eval_sim_EPR_isoFit_space(),
eval_sim_EPR_iso_combo(),
optim_for_EPR_fitness(),
plot_eval_EPRtheo_mltiplet(),
plot_eval_RA_forFit(),
quantify_EPR_Sim_series()
## 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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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$ra.sd # ## Bayesian information criterion (BIC) triarylamine.1st.spec.smooth$abic # ## 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), vectorize = 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.bin.path <- load_data_example(file = "Triarylamine_radCat_decay_series.DTA") ## loading the kinetics: triarylamine.decay.series.data <- readEPR_Exp_Specs_kin( path_to_file = triarylamine.decay.series.bin.path, path_to_dsc_par = triarylamine.decay.series.dsc.path ) # ## 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$ra.sd # ## Bayesian information criterion (BIC) triarylamine.1st.spec.smooth$abic # ## 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), vectorize = 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 )
Data frame summarizing the most important solvent properties for EPR/ENDOR which are required for variable temperature (VT) experiments and EPR spectroelectrochemistry.
solvents_dssolvents_ds
A data frame with 46 rows and 10 variables/columns:
Character, solvent name.
Character, ponting to molecular formula.
Numeric, pointing to relative molecular weight.
Numeric, corresponding to boling point in °C.
Numeric, corresponding melting point in °C.
Numeric, corresponding to density in .
Character, pointing to solubility in water expressed
in . 2. Solubility of THF in water is rather complex.
Character, corresponding to relative permittivity.
Numeric, pointing to flash point in °C.
Character, corresponding to solvent dynamic viscosity
in . 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.
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 )
=> 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 ) can be applied.
See also vignette("datasets").
https://organicchemistrydata.org/solvents/
https://pubchem.ncbi.nlm.nih.gov/
https://www.accudynetest.com/visc_table.html
Other Built-In Datasets:
isotopes_ds
Taking several data frame objects from the (local/Global) R environment and transforming them into
one with the long table/tidy form. This is especially handy
if a quick comparison of similar plots/EPR spectra in one graph panel is required. Difference between
the readEPR_Exp_Specs_multif and the actual function lies in the object input/origin.
While the readEPR_Exp_Specs_multif takes the original files/data, coming from spectrometer,
the transform_dfs_2tidyDF collects temporary processed/stored data frame objects/variables
created meanwhile in the R environment.
transform_dfs_2tidyDF( ..., df.names, which.coly.norm = "dIepr_over_dB", norm.vec = rep(1, times = length(df.names)), var2nd.series = "Spectrum" )transform_dfs_2tidyDF( ..., df.names, which.coly.norm = "dIepr_over_dB", norm.vec = rep(1, times = length(df.names)), var2nd.series = "Spectrum" )
... |
Data frame object names (separated by comma |
df.names |
Character string vector of labels (in the form of e.g. |
which.coly.norm |
Character string, pointing to name of the column (in all data frame
objects) to be normalized, by the |
norm.vec |
Numeric vector, consisting of (division) normalization constants (see also
the |
var2nd.series |
Character string, pointing to name of the second variable which is "common denominator"
for the series of |
Tidy (long form) data frame/table object, carrying all the individual inputs, defined by the ...
argument and ready for the overlay/offset plot to compare the data in desired series.
In order to compare -values of different EPR spectra, prior to own transformation
check that all data frame objects contain g_Val(ue) variable/column. If this is not case,
the user may create those columns by the eval_gFactor function.
## compare TMPD*+ EPR spectrum with that of aminoxyl, ## first, define the path and variable for TMPD*+ data tmpd.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.asc") tmpd.data.df <- readEPR_Exp_Specs( tmpd.data.path, col.names = c("B_G","dIepr_over_dB"), qValue = 3500, origin = "winepr" ) # ## preview head(tmpd.data.df) # ## second, do the same for the aminoxyl data aminoxyl.data.path <- load_data_example(file = "Aminoxyl_radical_a.txt") aminoxyl.data.df <- readEPR_Exp_Specs( aminoxyl.data.path, qValue = 2100 ) # ## preview aminoxyl.data.df %>% head() # ## ...and the own transformation spectra.data.tidy.df <- transform_dfs_2tidyDF( tmpd.data.df, aminoxyl.data.df, df.names = c("TMPD","Aminoxyl"), norm.vec = c(5e+3,1e-5), var2nd.series = "Radical" ) # ## preview head(spectra.data.tidy.df) # ## plotting both EPR spectra together plot_EPR_Specs( data.spectra = spectra.data.tidy.df, x = "B_G", x.unit = "G", var2nd.series = "Radical", var2nd.series.slct.by = 1, xlim = c(3400,3600), line.colors = c("darkorange","blue2"), legend.title = "Radical" ) # ## ...and the interactive preview (B in mT) plot_EPR_Specs2D_interact( data.spectra = spectra.data.tidy.df, line.colors = c("darkorange","blue2"), var2nd.series = "Radical", legend.title = "Radical" )## compare TMPD*+ EPR spectrum with that of aminoxyl, ## first, define the path and variable for TMPD*+ data tmpd.data.path <- load_data_example(file = "TMPD_specelchem_accu_b.asc") tmpd.data.df <- readEPR_Exp_Specs( tmpd.data.path, col.names = c("B_G","dIepr_over_dB"), qValue = 3500, origin = "winepr" ) # ## preview head(tmpd.data.df) # ## second, do the same for the aminoxyl data aminoxyl.data.path <- load_data_example(file = "Aminoxyl_radical_a.txt") aminoxyl.data.df <- readEPR_Exp_Specs( aminoxyl.data.path, qValue = 2100 ) # ## preview aminoxyl.data.df %>% head() # ## ...and the own transformation spectra.data.tidy.df <- transform_dfs_2tidyDF( tmpd.data.df, aminoxyl.data.df, df.names = c("TMPD","Aminoxyl"), norm.vec = c(5e+3,1e-5), var2nd.series = "Radical" ) # ## preview head(spectra.data.tidy.df) # ## plotting both EPR spectra together plot_EPR_Specs( data.spectra = spectra.data.tidy.df, x = "B_G", x.unit = "G", var2nd.series = "Radical", var2nd.series.slct.by = 1, xlim = c(3400,3600), line.colors = c("darkorange","blue2"), legend.title = "Radical" ) # ## ...and the interactive preview (B in mT) plot_EPR_Specs2D_interact( data.spectra = spectra.data.tidy.df, line.colors = c("darkorange","blue2"), var2nd.series = "Radical", legend.title = "Radical" )