prep_sig: Prepare fatty acid signature data for analysis
In qfasar: Quantitative Fatty Acid Signature Analysis in R

Description Usage Arguments Value Details References Examples

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).

1	prep_sig(df_sig, fa_names, use_fa, zero_rep = 75, scale = 3)

`df_sig`	A data frame containing prey fatty acid signature data. `qfasar` has strict formatting requirements for `df_sig`; please see Details and/or the vignette.
`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.

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 by type and id.
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 and id, 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.

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.

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.

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))