cc_aug: Calibration coefficient for an augmented signature proportion
In qfasar: Quantitative Fatty Acid Signature Analysis in R

Description Usage Arguments Value Details References Examples

cc_aug computes the optimal calibration coefficient for an augmented signature proportion (Bromaghin et al. 2016). If signature augmentation is to be used, the user must call cc_aug after first calling prep_sig with the prey signature data, in order to derive a calibration coefficient for the augmented signature.

1	cc_aug(sig_rep, sig_scale, cc_all, use_fa, dist_meas = 1, gamma = 1)

`sig_rep`	A numeric matrix containing fatty acid signatures with proportions from all fatty acids. See Details.
`sig_scale`	A numeric matrix containing fatty acid signatures with proportions from a subset of all fatty acids and an augmented proportion. See Details.
`cc_all`	A numeric vector of calibration coefficients for the fatty acids in `sig_rep`.
`use_fa`	A logical vector denoting the fatty acids in `sig_rep` that are also in `sig_scale`.
`dist_meas`	An integer indicator of the distance measure to compute. Default value 1.
`gamma`	The power parameter of the chi-square distance measure. Default value 1.

A list containing the following elements:

cc: A numeric vector of calibration coefficients for the augmented signatures.
err_code: An integer error code (0 if no error is detected).
err_message: A string contains a brief summary of the execution.

Calibration coefficients provide a one-to-one mapping between the prey and predator spaces (Bromaghin et al. 2015). However, when using signature augmentation (Bromaghin et al. 2016), no calibration coefficient is available for the augmented proportion and the function cc_aug was developed to remedy that lack.

cc_aug transforms complete prey signatures in sig_rep to the predator space, censors them using fa, and then augments them. The subset of calibration coefficients in cc_all corresponding to fa are combined with a calibration coefficient for the augmented proportion, the censored signatures in sig_scale are also transformed to the predator space, and the distance between the two sets of censored signatures is computed. The calibration coefficient for the augmented proportion is taken as the value that minimizes the distance. The function Rsolnp::solnp() is used to minimize the distance.

The entity passed as the argument fa is intended to be the corresponding entity returned by a call to prep_fa. Similarly, the entities passed as the arguments sig_rep and sig_scale are intended to be the corresponding entities returned by a call to prep_sig with data in a prey library. Consequently, no error checks are made on these objects. Please refer to the documentation for prep_fa and prep_sig for additional details.

Use of Rsolnp::solnp limits the ability to return any errors from the function dist_between_2_sigs. A crash may be caused by passing invalid values for the arguments dist_meas or gamma. Please refer to documentation for the function dist_between_2_sigs for additional information about valid values for these arguments.

Utility and external functions called by cc_aug:

dist_between_2_sigs
Rsolnp::solnp

Bromaghin, J.F., S.M. Budge, and G.W. Thiemann. 2016. Should fatty acid signature proportions sum to 1 for diet estimation? Ecological Research 31:597-606.

Bromaghin, J.F., K.D. Rode, S.M. Budge, and G.W. Thiemann. 2015. Distance measures and optimization spaces in quantitative fatty acid signature analysis. Ecology and Evolution 5:1249-1262.

cc_aug(sig_rep = matrix(c(0.05, 0.10, 0.30, 0.55,
                          0.04, 0.11, 0.29, 0.56,
                          0.10, 0.05, 0.35, 0.50), ncol = 3),
       sig_scale = matrix(c(0.40, 0.50, 0.10,
                            0.45, 0.49, 0.06,
                            0.35, 0.45, 0.20), ncol = 3),
       cc_all = c(0.75, 1.05, 1.86, 0.80),
       use_fa = c(FALSE, FALSE, TRUE, TRUE))

cc_aug(sig_rep = matrix(c(0.05, 0.10, 0.30, 0.55,
                          0.04, 0.11, 0.29, 0.56,
                          0.10, 0.05, 0.35, 0.50), ncol = 3),
       sig_scale = matrix(c(0.40, 0.50, 0.10,
                            0.45, 0.49, 0.06,
                            0.35, 0.45, 0.20), ncol = 3),
       cc_all = c(0.75, 1.05, 1.86, 0.80),
       use_fa = c(FALSE, FALSE, TRUE, TRUE),
       dist_meas = 1)

cc_aug(sig_rep = matrix(c(0.05, 0.10, 0.30, 0.55,
                          0.04, 0.11, 0.29, 0.56,
                          0.10, 0.05, 0.35, 0.50), ncol = 3),
       sig_scale = matrix(c(0.40, 0.50, 0.10,
                            0.45, 0.49, 0.06,
                            0.35, 0.45, 0.20), ncol = 3),
       cc_all = c(0.75, 1.05, 1.86, 0.80),
       use_fa = c(FALSE, FALSE, TRUE, TRUE),
       dist_meas = 2)

cc_aug(sig_rep = matrix(c(0.05, 0.10, 0.30, 0.55,
                          0.04, 0.11, 0.29, 0.56,
                          0.10, 0.05, 0.35, 0.50), ncol = 3),
       sig_scale = matrix(c(0.40, 0.50, 0.10,
                            0.45, 0.49, 0.06,
                            0.35, 0.45, 0.20), ncol = 3),
       cc_all = c(0.75, 1.05, 1.86, 0.80),
       use_fa = c(FALSE, FALSE, TRUE, TRUE),
       dist_meas = 3,
       gamma = 0.25)

cc_aug(sig_rep = matrix(c(0.05, 0.10, 0.30, 0.55,
                          0.04, 0.11, 0.29, 0.56,
                          0.10, 0.05, 0.35, 0.50), ncol = 3),
       sig_scale = matrix(c(0.40, 0.50, 0.10,
                            0.45, 0.49, 0.06,
                            0.35, 0.45, 0.20), ncol = 3),
       cc_all = c(0.75, 1.05, 1.86, 0.80),
       use_fa = c(FALSE, FALSE, TRUE, TRUE),
       dist_meas = 3)