operations update

R/arithmetic.R

@@ -72,18 +72,20 @@ NULL
 
 # adding abundances (i.e. isotope mixing/mass balance calculations)
 setMethod("+", signature(e1 = "Abundance", e2 = "Abundance"), function(e1, e2) {
+    e1 <- switch_notation(e1, "raw") # convert to raw for mass balance with the same units
+    e2 <- switch_notation(e2, "raw") # convert to raw for mass balance with the same units
+
     iso_attribs_check(e1, e2, exclude = c("weight", "compound"), check_length = FALSE, 
                       text = "trying to calculate the mass balance of two abundance objects")
     # FIXME: currently allowing to add vectors of different lengths to support adding a fixed value to a vector
     # but ideally checking here that only length(e1) == length(e2) or length(e1) == 1 or length(e2) ==1 is allowed
 
-    e1 <- switch_notation(e1, "raw") # convert to raw for mass balance with the same units
-    e2 <- switch_notation(e2, "raw") # convert to raw for mass balance with the same units
-
     weightsum <- get_weight(e1) + get_weight(e2)
     e1@.Data <- (get_weighted_value(e1) + get_weighted_value(e2))/weightsum
     e1@weight <- weightsum
     e1@compound <- paste(sub("^$", "?", c(e1@compound, e2@compound)), collapse = "+")
+    # don't propagate ?+?
+    if (e1@compound == "?+?") e1@compound <- ""
     validObject(e1)
 
     # FIXME: using default notation but should use the same notation the objects have if they are both the same and different from default
@@ -101,15 +103,15 @@ NULL
 
 # adding deltas (i.e. isotope mixing/mass balance calculations)
 setMethod("+", signature(e1 = "Delta", e2 = "Delta"), function(e1, e2) {
-    iso_attribs_check(e1, e2, exclude = c("weight", "compound"), text = "trying to calculate the mass balance of two delta values")
-
     e1 <- switch_notation(e1, "raw") # convert to raw for mass balance with the same units
     e2 <- switch_notation(e2, "raw") # convert to raw for mass balance with the same units
-
+    iso_attribs_check(e1, e2, exclude = c("weight", "compound"), text = "trying to calculate the mass balance of two delta values")    
     weightsum <- get_weight(e1) + get_weight(e2)
     e1@.Data <- (get_weighted_value(e1) + get_weighted_value(e2))/weightsum
     e1@weight <- weightsum
     e1@compound <- paste(sub("^$", "?", c(e1@compound, e2@compound)), collapse = "+")
+    # don't propagate ?+?
+    if (e1@compound == "?+?") e1@compound <- ""
     validObject(e1)
 
     # FIXME: using default notation but should use the same notation the objects have if they are both the same and different from default
@@ -148,7 +150,6 @@ setMethod("-", signature(e1 = "Delta", e2 = "Delta"), function(e1, e2) {
 })
 
 #' @usage alpha - 1
-#' @usage eps + 1
 #' @details
 #' \code{alpha - 1} is a shorthand for converting a fractionation factor from 
 #' alpha to epsilon notation. The ff object has to be in alpha notation,
@@ -181,43 +182,44 @@ setMethod("*", signature(e1 = "Isoval", e2 = "ANY"), function(e1, e2) operation_
 setMethod("*", signature(e1 = "ANY", e2 = "Isoval"), function(e1, e2) operation_error("Multiplication", e1, e2))
 setMethod("*", signature(e1 = "Isosys", e2 = "Isosys"), function(e1, e2) operation_error("Multiplication", e1, e2))
 
-#' @usage eps[raw] * 1000 
-#' @usage eps[permil] / 1000
-#' @usage delta[raw] * 1000 
-#' @usage delta[permil] / 1000
+#' @usage delta * 1000 
+#' @usage delta / 1000
 #' @details
 #' \code{delta * 1000} is a shorthand for converting a raw delta
-#' value to permil notation. The same works for fractionation factors
+#' value to permil notation or permil to ppm. The same works for fractionation factors
 #' in epsilon notation. \code{delta / 1000} is the reverse
 #' @name arithmetic 
 #' @rdname arithmetic
 NULL
 
-# 1000*alpha - FIXME: not unit tested!
 setMethod("*", signature(e1 = "FractionationFactor", e2 = "numeric"), function(e1, e2) {
-    if (e2 == 1000L && is(e1@notation, "Notation_eps"))
-        return(switch_notation(e1, "permil"))
-    callNextMethod(e1, NULL)
+    if (e2 == 1000 && is(e1@notation, "Notation_eps"))
+        return(switch_notation(e1, "permil")) # raw to permil
+    else if (e2 == 0.001 && is(e1@notation, "Notation_permil"))
+        return(switch_notation(e1, "eps")) # permil to raw
+    else if (e2 == 1000 && is(e1@notation, "Notation_permil"))
+        return(switch_notation(e1, "ppm")) # permil to ppm
+    else if (e2 == 0.001 && is(e1@notation, "Notation_ppm"))
+        return(switch_notation(e1, "permil")) # ppm to permil
+    callNextMethod(e1, e2)
 })
 setMethod("*", signature(e1 = "numeric", e2 = "FractionationFactor"), function(e1, e2) e2*e1)
-setMethod("/", signature(e1 = "FractionationFactor", e2 = "numeric"), function(e1, e2) {
-    if (e2 == 1000L && is(e1@notation, "Notation_permil"))
-        return(switch_notation(e1, "eps"))
-    callNextMethod(e1, NULL)
-})
+setMethod("/", signature(e1 = "FractionationFactor", e2 = "numeric"), function(e1, e2) e1 * (1/e2))
 
-# 1000*delta - FIXME: also not unit tested!
+# 1000*delta - this is actually tested
 setMethod("*", signature(e1 = "Delta", e2 = "numeric"), function(e1, e2) {
-    if (e2 == 1000L && is(e1@notation, "Notation_raw"))
-        return(switch_notation(e1, "permil"))
-    callNextMethod(e1, NULL)
+    if (e2 == 1000 && is(e1@notation, "Notation_raw"))
+        return(switch_notation(e1, "permil")) # raw to permil
+    else if (e2 == 0.001 && is(e1@notation, "Notation_permil"))
+        return(switch_notation(e1, "raw")) # permil to raw
+    else if (e2 == 1000 && is(e1@notation, "Notation_permil"))
+        return(switch_notation(e1, "ppm")) # permil to ppm
+    else if (e2 == 0.001 && is(e1@notation, "Notation_ppm"))
+        return(switch_notation(e1, "permil")) # ppm to permil
+    callNextMethod(e1, e2)
 })
 setMethod("*", signature(e1 = "numeric", e2 = "Delta"), function(e1, e2) e2*e1)
-setMethod("/", signature(e1 = "Delta", e2 = "numeric"), function(e1, e2) {
-    if (e2 == 1000L && is(e1@notation, "Notation_permil"))
-        return(switch_notation(e1, "raw"))
-    callNextMethod(e1, NULL)
-})
+setMethod("/", signature(e1 = "Delta", e2 = "numeric"), function(e1, e2) e1 * (1/e2))
 
 
 
@@ -299,8 +301,8 @@ setMethod("/", signature(e1 = "Ratio", e2 = "Ratio"), function(e1, e2) {
 
 #' @usage ff / ff
 #' @details
-#' \code{alpha/ alpha} allows the creation of another isotope \code{\link{alpha}} object but requires that
-#' either the denominator names or numerator names of the two alpha objects are identical (i.e. they "cancel").
+#' \code{ff/ff} allows the creation of another isotope \code{\link{fractionation_factor}} object but requires that
+#' either the denominator names or numerator names of the two objects are identical (i.e. they "cancel").
 #' This is a shorthand for the \link{to_ff} function.
 #' @name arithmetic 
 #' @rdname arithmetic

R/conversion.R

@@ -206,22 +206,18 @@ setMethod("to_abundance", "Delta", function(iso) {
 
 # to.ff =============================================
 
-# FIXME!!
-
 #' Fractionation factor
 #' 
 #' @description
-#' Calculate/convert to isotope fractionation factors (\code{ff} values).
+#' Calculate/convert to an isotope \code{\link{fractionation_factor}}
 #' 
-#' @usage to_ff(iso1, iso2, notation = "alpha")
+#' @usage to_ff(iso1, iso2)
 #' @details
-#' FIXME
 #' The \code{frac_factor(...)} function calculates the fractionation factor between two isotope data objects
-#' (for example two delta values, two epsilons, two ratios, or two alpha values).
-#' 
-#'
+#' (for example two \code{\link{delta}} values, two \code{\link{ratio}}, or two \code{\link{ff}}).
 #' All calculatinos are only permissible if the isotope values have matching
-#' attributes.
+#' attributes and fractionation factors will be returend in the default notation
+#' (see \code{\link{set_iso_opts}} for details)
 #'
 #' @param iso1 the top compound in the fractionation factor
 #' @param iso2 the bottom compound in the fractionation factor

R/isotopia.R

@@ -2,9 +2,11 @@
 #' 
 #' This package provides several isotopic data types that can be initialized 
 #' by calling the respective \code{\link{ratio}}, \code{\link{abundance}},
-#' \code{\link{delta}} and \code{\link{intensity}} functions. Each data type
+#' \code{\link{delta}}, \code{\link{fractionation_factor}} and \code{\link{intensity}} functions. 
+#' Each data type
 #' has additional attributes (such as name of the major isotope for all data
-#' types, reference ratio for \code{\link{delta}} values, unit for \code{\link{intensity}})
+#' types, reference ratio for \code{\link{delta}} values, notation for \code{\link{delta}}
+#' and \code{\link{fractionation_factor}}, unit for \code{\link{intensity}})
 #' and these are described in detail in the help for each function. The attributes of any
 #' existing isotope data object can be modified easily by calling \code{\link{set_attrib}}
 #' 
@@ -24,7 +26,7 @@
 #' 
 #' Isotope data objects (both single vectors and isotope systems) can then be converted 
 #' to different data types using the respective \code{\link{to_ratio}}, \code{\link{to_abundance}},
-#' \code{\link{to_delta}} functions. 
+#' \code{\link{to_delta}} functions. Notations can also be changed using \code{\link{switch_notation}}
 #' 
 #' Global options for isotopia can be set using \code{\link{set_iso_opts}} and 
 #' standard reference ratios can be registered using \code{\link{register_standard}}

R/notation.R

@@ -11,7 +11,6 @@ NULL
 #'  \item{\code{\link{delta}}: }{'raw', 'permil', 'ppm'}
 #'  \item{\code{\link{fractionation_factor}}: }{'alpha', 'eps', 'permil', 'ppm'}
 #' }
-#' Note: eps, the 'epsilon' value is considered the 'raw' unit of a fractionation factor 
 #' 
 #' @usage switch_notation(iso, to)
 #' @param iso isotopic data object (\code{\link{ff}}, \code{\link{abundance}}, \code{\link{delta}})

R/operations.R

@@ -12,6 +12,7 @@ NULL
 #' @param exact - whether to calculate mass balance of delta values exactly (default FALSE), 
 #' use exact_mass_balance to set this paramter globally 
 #' @return weighted abundance or delta value object that represents the combination of the parameters
+#' @family operations
 #' @method mass_balance
 #' @export
 setGeneric("mass_balance", function(iso, iso2, ..., exact = exact_mass_balance()) standardGeneric("mass_balance"))
@@ -42,18 +43,18 @@ setMethod("mass_balance", signature("Deltas", "Deltas"), function(iso, iso2, ...
 })
 
 #' Fractionate an isotopic value
-#' FIXME: this documentation is confused, go fix it
-#' This function calculates the outcome of isotopic fractionation on an isotopic value and
-#' is defined for a number of different combinations (how an \code{\link{alpha}} fractionation
-#' factor fractionates a single \code{\link{ratio}} or a \code{\link{delta}} value, how it fractionates another
-#' \code{\link{alpha}} value; how a \code{\link{epsilon}} value does the same, etc.)
-#' @param frac the isotope object used to fractionate the isotope value
+#' 
+#' This function calculates the outcome of isotopic fractionation by a \code{\link{fractionation_fractor}}
+#' and can be applied to \code{\link{ratio}} data, \code{\link{delta}} values or other
+#' \code{\link{fractionation_fractor}} objects.
+#' @param frac the fractionation factor \code{\link{ff}} used to fractionate the isotope value
 #' @param iso the isotope object to fractionate
 #' @return an object of the same type as \code{iso}
 #' @note Several of these calculations are also
 #' implemented with an \code{\link{arithmetic}} shorthand. All calculatinos are
 #' only permissible if the fractionation factors and isotope values have matching
 #' attributes.
+#' @family operations
 #' @method fractionate
 #' @export
 setGeneric("fractionate", function(frac, iso) standardGeneric("fractionate"))
@@ -103,6 +104,7 @@ setMethod("fractionate", signature("FractionationFactor", "Delta"), function(fra
 #' also implemented with an \code{\link{arithmetic}} shorthand. All calculatinos are
 #' only permissible if the fractionation factors and isotope values have matching
 #' attributes.
+#' @family operations
 #' @method shift_reference
 #' @export
 setGeneric("shift_reference", function(iso, ref) standardGeneric("shift_reference"))

man/arithmetic.Rd

@@ -11,7 +11,7 @@ delta +- delta
 
 alpha - 1
 
-eps[raw] * 1000
+delta * 1000
 
 ff * ratio
 
@@ -48,7 +48,7 @@ and the result will no longer be an isotope object.
 \code{eps  + 1} is the reverse operation.
 
 \code{delta * 1000} is a shorthand for converting a raw delta
-value to permil notation. The same works for fractionation factors
+value to permil notation or permil to ppm. The same works for fractionation factors
 in epsilon notation. \code{delta / 1000} is the reverse
 
 \code{ff*ratio}, \code{ff*ff}, \code{ff*delta} are a shorthand for
@@ -65,8 +65,8 @@ for details
 \code{ratio/ratio} allows the creation of an isotope \code{\link{fractionation_factor}}
 This is a shorthand for the \link{to_ff} function.
 
-\code{alpha/ alpha} allows the creation of another isotope \code{\link{alpha}} object but requires that
-either the denominator names or numerator names of the two alpha objects are identical (i.e. they "cancel").
+\code{ff/ff} allows the creation of another isotope \code{\link{fractionation_factor}} object but requires that
+either the denominator names or numerator names of the two objects are identical (i.e. they "cancel").
 This is a shorthand for the \link{to_ff} function.
 
 \code{delta/delta} creates an \code{\link{alpha}} fractionation factor object that

man/fractionate.Rd

@@ -1,35 +1,31 @@
 % Generated by roxygen2 (4.0.0): do not edit by hand
 \name{fractionate}
 \alias{fractionate}
-\title{Fractionate an isotopic value
-FIXME: this documentation is confused, go fix it
-This function calculates the outcome of isotopic fractionation on an isotopic value and
-is defined for a number of different combinations (how an \code{\link{alpha}} fractionation
-factor fractionates a single \code{\link{ratio}} or a \code{\link{delta}} value, how it fractionates another
-\code{\link{alpha}} value; how a \code{\link{epsilon}} value does the same, etc.)}
+\title{Fractionate an isotopic value}
 \usage{
 fractionate(frac, iso)
 }
 \arguments{
-\item{frac}{the isotope object used to fractionate the isotope value}
+\item{frac}{the fractionation factor \code{\link{ff}} used to fractionate the isotope value}
 
 \item{iso}{the isotope object to fractionate}
 }
 \value{
 an object of the same type as \code{iso}
 }
 \description{
-Fractionate an isotopic value
-FIXME: this documentation is confused, go fix it
-This function calculates the outcome of isotopic fractionation on an isotopic value and
-is defined for a number of different combinations (how an \code{\link{alpha}} fractionation
-factor fractionates a single \code{\link{ratio}} or a \code{\link{delta}} value, how it fractionates another
-\code{\link{alpha}} value; how a \code{\link{epsilon}} value does the same, etc.)
+This function calculates the outcome of isotopic fractionation by a \code{\link{fractionation_fractor}}
+and can be applied to \code{\link{ratio}} data, \code{\link{delta}} values or other
+\code{\link{fractionation_fractor}} objects.
 }
 \note{
 Several of these calculations are also
 implemented with an \code{\link{arithmetic}} shorthand. All calculatinos are
 only permissible if the fractionation factors and isotope values have matching
 attributes.
 }
+\seealso{
+Other operations: \code{\link{mass_balance}};
+  \code{\link{shift_reference}}
+}
 

man/isotopia-package.Rd

@@ -10,9 +10,11 @@ R interface for working with isotopic data (abundances, ratios, delta values, et
 \details{
 This package provides several isotopic data types that can be initialized
 by calling the respective \code{\link{ratio}}, \code{\link{abundance}},
-\code{\link{delta}} and \code{\link{intensity}} functions. Each data type
+\code{\link{delta}}, \code{\link{fractionation_factor}} and \code{\link{intensity}} functions.
+Each data type
 has additional attributes (such as name of the major isotope for all data
-types, reference ratio for \code{\link{delta}} values, unit for \code{\link{intensity}})
+types, reference ratio for \code{\link{delta}} values, notation for \code{\link{delta}}
+and \code{\link{fractionation_factor}}, unit for \code{\link{intensity}})
 and these are described in detail in the help for each function. The attributes of any
 existing isotope data object can be modified easily by calling \code{\link{set_attrib}}
 
@@ -32,7 +34,7 @@ an isotope system that are not named generate columns named \code{iso, iso.1, is
 
 Isotope data objects (both single vectors and isotope systems) can then be converted
 to different data types using the respective \code{\link{to_ratio}}, \code{\link{to_abundance}},
-\code{\link{to_delta}} functions.
+\code{\link{to_delta}} functions. Notations can also be changed using \code{\link{switch_notation}}
 
 Global options for isotopia can be set using \code{\link{set_iso_opts}} and
 standard reference ratios can be registered using \code{\link{register_standard}}

man/mass_balance.Rd

@@ -19,4 +19,8 @@ This function calculates the isotope mass balance from combining multiple weight
 isotope \code{\link{abundance}} or \code{\link{delta}} value objects. This calculation
 is also implemented with an \code{\link{arithmetic}} shorthand.
 }
+\seealso{
+Other operations: \code{\link{fractionate}};
+  \code{\link{shift_reference}}
+}
 

man/shift_reference.Rd

@@ -24,4 +24,8 @@ also implemented with an \code{\link{arithmetic}} shorthand. All calculatinos ar
 only permissible if the fractionation factors and isotope values have matching
 attributes.
 }
+\seealso{
+Other operations: \code{\link{fractionate}};
+  \code{\link{mass_balance}}
+}
 

man/switch_notation.Rd

@@ -23,7 +23,6 @@ Valid notations depend on the data type:
  \item{\code{\link{delta}}: }{'raw', 'permil', 'ppm'}
  \item{\code{\link{fractionation_factor}}: }{'alpha', 'eps', 'permil', 'ppm'}
 }
-Note: eps, the 'epsilon' value is considered the 'raw' unit of a fractionation factor
 }
 \seealso{
 Other data type attributes: \code{\link{get_label}},

man/to_ff.Rd

@@ -3,7 +3,7 @@
 \alias{to_ff}
 \title{Fractionation factor}
 \usage{
-to_ff(iso1, iso2, notation = "alpha")
+to_ff(iso1, iso2)
 }
 \arguments{
 \item{iso1}{the top compound in the fractionation factor}
@@ -14,16 +14,14 @@ to_ff(iso1, iso2, notation = "alpha")
 isotope \code{\link{fraction_factor}} object if parameters can be converted, an error otherwise
 }
 \description{
-Calculate/convert to isotope fractionation factors (\code{ff} values).
+Calculate/convert to an isotope \code{\link{fractionation_factor}}
 }
 \details{
-FIXME
 The \code{frac_factor(...)} function calculates the fractionation factor between two isotope data objects
-(for example two delta values, two epsilons, two ratios, or two alpha values).
-
-
+(for example two \code{\link{delta}} values, two \code{\link{ratio}}, or two \code{\link{ff}}).
 All calculatinos are only permissible if the isotope values have matching
-attributes.
+attributes and fractionation factors will be returend in the default notation
+(see \code{\link{set_iso_opts}} for details)
 }
 \note{
 Some of the conversions are also implemented in arithmetic shorthand, for example to generate