prep_sig {qfasar} | R Documentation |
Prepare fatty acid signature data for analysis
Description
The function prep_sig
prepares raw fatty acid signatures for
analysis. Signature proportions that are missing, negative, or equal to zero
are replaced with a small user-specified constant and the signatures are
scaled to sum to 1.0. The fatty acids that are not to be used in the analysis
are censored and the signatures are scaled using one of three options
(Bromaghin et al. In press).
Usage
prep_sig(df_sig, fa_names, use_fa, zero_rep = 75, scale = 3)
Arguments
df_sig |
A data frame containing prey fatty acid signature data.
|
fa_names |
A character vector of all fatty acid names. |
use_fa |
A logical vector defining a fatty acid suite. |
zero_rep |
A constant associated with the method and value to replace signature proportions that are missing or less than or equal to 0. Default value 75. |
scale |
An integer indicator of the desired scaling option. Default value 3. |
Value
A list containing the following elements:
- type
A character vector of the type of each signature.
- id
A character vector of the unique sample ID of each signature.
- n_types
The number of unique types.
- uniq_types
A character vector of the unique types, sorted alphanumerically.
- n_sig
The total number of signatures.
- type_ss
The number of signatures for each unique
type
.- loc
A vector or matrix giving the first and last locations of the signatures of each
type
, after being sorted bytype
andid
.- sig_rep
A vector or matrix of the original signatures, with any values missing or less than or equal to 0 replaced, in column-major format.
- n_fa_rep
The number of fatty acids in
sig_rep
.- sig_scale
A vector or matrix of scaled signatures ready for analysis, sorted by
type
andid
, in column-major format.- n_fa_suite
The number of fatty acids in
sig_scale
.- fa_suite
A character vector of the names of fatty acids in the suite to be used in the analysis.
- zero_rep_val
A constant associated with the method and value to be used to replace proportions that are missing or less than or equal to 0. See Details.
- err_code
An integer error code (0 if no error is detected).
- err_message
A string contains a brief summary of the execution.
Details
This function is designed to be called by the user to prepare fatty acid
signatures for analysis. For most analyses, prep_sig
should be
called immediately after the fatty acid suites and fatty acid signatures have
been read into data frames, and after the fatty acid suites data frame has
been processed by the function prep_fa
. Please refer to the
vignette for additional information.
The data frame with fatty acid signatures must meet the following formatting requirements:
The file must be in row-major format, i.e., each row contains the information for an individual animal.
The first column must contain a designation of animal
type
. For prey data,type
often denotes species. For predator data,type
denotes classes of predators for which separate estimates of mean diet composition are desired.The second column must contain an identifier unique to each signature, i.e. a sample ID.
The remaining columns must contain fatty acid signature proportions or percentages.
The data frame must contain a header record, with a name for each column, such as "type", "id", name of fatty acid 1, name of fatty acid 2, ...
The file should contain data from all available fatty acids, rather than a subset. The fatty acid suite to be used in the analysis is defined by the argument
fa
.
Please refer to the documentation for the utility function
sig_rep_zero
for information regarding the argument
zero_rep
.
Please refer to the documentation for the utility function
sig_scale
for information regarding the argument
scale
.
References
Bromaghin, J.F., S.M. Budge, and G.W. Thiemann. In press. Should fatty acid signature proportions sum to 1 for diet estimation? Ecological Research.
Iverson, S.J., C. Field, W.D. Bowen, and W. Blanchard. 2004. Quantitative fatty acid signature analysis: A new method of estimating predator diets. Ecological Monographs 74:211-235.
Examples
prep_sig(df_sig = data.frame(type = c("Type_1", "Type_1", "Type_2",
"Type_2"),
id = c("ID_1", "ID_2", "ID_3", "ID_4"),
fa_1 = c(0.0, 0.2, 0.3, 0.6),
fa_2 = c(0.1, 0.3, 0.3, 0.4),
fa_3 = c(0.9, 0.5, 0.4, NA),
row.names = c("Prey_1", "Prey_2", "Prey_3",
"Prey_4")),
fa_names = c("fa_1", "fa_2", "fa_3"),
use_fa = c(TRUE, FALSE, TRUE),
zero_rep = 0.0001,
scale=2)
prep_sig(df_sig = data.frame(type = c("Type_1", "Type_1", "Type_2",
"Type_2"),
id = c("ID_1", "ID_2", "ID_3", "ID_4"),
fa_1 = c(0.0, 0.2, 0.3, 0.6),
fa_2 = c(0.1, 0.3, 0.3, 0.4),
fa_3 = c(0.9, 0.5, 0.4, NA),
row.names = c("Prey_1", "Prey_2", "Prey_3",
"Prey_4")),
fa_names = c("fa_1", "fa_2", "fa_3"),
use_fa = c(TRUE, FALSE, TRUE),
zero_rep = 90,
scale=1)
prep_sig(df_sig = data.frame(type = c("Type_1", "Type_1", "Type_2",
"Type_2"),
id = c("ID_1", "ID_2", "ID_3", "ID_4"),
fa_1 = c(0.0, 0.2, 0.3, 0.6),
fa_2 = c(0.1, 0.3, 0.3, 0.4),
fa_3 = c(0.9, 0.5, 0.4, NA),
row.names = c("Prey_1", "Prey_2", "Prey_3",
"Prey_4")),
fa_names = c("fa_1", "fa_2", "fa_3"),
use_fa = c(TRUE, FALSE, TRUE),
scale=3)
prep_sig(df_sig = data.frame(type = c("Type_1", "Type_1", "Type_2",
"Type_2"),
id = c("ID_1", "ID_2", "ID_3", "ID_4"),
fa_1 = c(0.0, 0.2, 0.3, 0.6),
fa_2 = c(0.1, 0.3, 0.3, 0.4),
fa_3 = c(0.9, 0.5, 0.4, NA),
row.names = c("Prey_1", "Prey_2", "Prey_3",
"Prey_4")),
fa_names = c("fa_1", "fa_2", "fa_3"),
use_fa = c(TRUE, FALSE, TRUE))