Quantify (Components) Areas of Series of Simulated EPR Spectra

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

Usage

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

Arguments

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

Value

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

If output.area.stat = TRUE (default), the resulting data frame consists of columns/variables like integrals/areas for each simulated and fitted EPR spectrum, where the components are denoted by the uppercase letters (Area_Sim_A, Area_Sim_B,...etc.); best fitted/optimized coefficients to multiply the intensities (Optim_CoeffInt_Sim_A, Optim_CoeffInt_Sim_B,...etc); best fitted/optimized intercept (or baseline constant, Optim_intercept); minimum sum of the residual squares (minLSQ_sum); 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	minLSQ_sum	N_evals	N_converg
6	0.020624473	0.052843937	5.508809e-10	2.289953e-07	198	4
21	0.020217930	0.051802287	5.401823e-10	2.438172e-07	177	4
36	0.018836579	0.048263010	5.029705e-10	2.662651e-07	201	4

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

Details

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

Examples

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