#' Convert from SHE scale to another electrochemical or physical scale
#'
#' Convert an arbitrary number of potentials vs SHE to another electrochemical
#' scale (or the vacuum scale).
#' The available target scales are those listed by \code{\link{potentials.as.SHE}}.
#'
#' @param potential potential in volt
#' @param scale name of the target scale
#' @param electrolyte optional, specify electrolyte solution, e.g., "KCl(aq)". Must match one of the values in \code{\link{potentials.as.SHE}$electrolyte}
#' @param concentration of electrolyte in mol/L, or as the string "saturated"
#' @param temperature of system in degrees Celsius
#' @param as.SHE.data by default this parameter reads the full dataset \code{\link{potentials.as.SHE}}
#'
#' @return potential in the specified target scale
#' @export
from.SHE<-function(potential,
scale,
electrolyte="",
concentration="saturated",
temperature=25,
as.SHE.data=potentials.as.SHE()){
# make this work for arbitrary-length vectors of potential and scale
# make sure potential and scale args have the same length
if (length(potential)==0|length(scale)==0){
stop("Arguments potential or scale cannot be empty!")
}elseif (length(potential)!=length(scale)){
stop("Arguments potential and scale must have the same number of elements")
}
arglength<-length(potential)
# make the args concentration, temperature and electrolyte this same length,
# unless the user supplied them (only necessary for > 1)
if (arglength>1){
# handle two cases:
# 1. user did not touch concentration, temperature and electrolyte args.
# Assume they forgot and reset their length and print a message
# 2. user did change concentration or temperature or electrolyte, but still failed to
# ensure length equal to arglength. In this case, abort.
# note: we can get the default value set in the function call using formals()
if (identical(concentration,formals(from.SHE)$concentration)&
message(paste0("Default concentration (",formals(from.SHE)$concentration,"), temperature (",formals(from.SHE)$temperature,"C) used for all supplied potential and scale values."))
concentration<-rep(concentration,arglength)
temperature<-rep(temperature,arglength)
electrolyte<-rep(electrolyte,arglength)
}else{
# case 2
stop("Concentration, temperature and electrolyte arguments must have the same number of elements as potential and scale!")
}
}
## we can now safely assume that length(<args>) == arglength
# place args into a single dataframe
# this way, we can correlate columns to each other by row
temperature = 25, as.SHE.data = potentials.as.SHE())
}
\arguments{
\item{potential}{potential in volt}
\item{scale}{name of the target scale}
\item{electrolyte}{optional, specify electrolyte solution, e.g., "KCl(aq)". Must match one of the values in \code{\link{potentials.as.SHE}$electrolyte}}
\item{concentration}{of electrolyte in mol/L, or as the string "saturated"}
\item{temperature}{of system in degrees Celsius}
\item{as.SHE.data}{by default this parameter reads the full dataset \code{\link{potentials.as.SHE}}}
}
\value{
potential in the specified target scale
}
\description{
Convert an arbitrary number of potentials vs SHE to another electrochemical
scale (or the vacuum scale).
The available target scales are those listed by \code{\link{potentials.as.SHE}}.
