# Log Ratios of Measurements Function to compute the (base 10) log ratios of the measurements relative to standard reference values. The default reference and several alternative references are provided with the package. But the user can use their own references if desired. ```r LogRatios( data, ref = reference$Combi, identifiers = c("Taxon", "Element"), refMeasuresName = "Measure", refValuesName = "Standard", thesaurusSet = zoologThesaurus, taxonomy = zoologTaxonomy, joinCategories = NULL, mergedMeasures = NULL, useGenusIfUnambiguous = TRUE ) ``` ## Arguments - `data`: A dataframe with the input measurements. - `ref`: A dataframe including the measurement values used as references. The default `ref = reference$Combi` and other reference sets are provided with the package `zoolog`. - `identifiers`: A vector of column names in `ref` identifying a type of bone. By default `identifiers = c("Taxon", "Element")`. - `refMeasuresName`: The column name in `ref` identifying the type of bone measurement. - `refValuesName`: The column name in `ref` giving the measurement value. - `thesaurusSet`: A thesaurus allowing datasets with different nomenclatures to be merged. By default `thesaurusSet = zoologThesaurus`. - `taxonomy`: A taxonomy allowing the automatic detection of data and reference sharing the same genus (or higher taxonomic rank), although of different species. By default `taxonomy = zoologTaxonomy`. - `joinCategories`: A list of named character vectors. Each vector is named by a category in the reference and includes a set of categories in the data for which to compute the log ratios with respect to that reference. When `NULL` (default) no grouping is considered. - `mergedMeasures`: A list of character vectors or a single character vector. Each vector identifies a set of measures that the data presents merged in the same column, named as any of them. This practice only makes sense if only one of the measures can appear in each bone element. - `useGenusIfUnambiguous`: Boolean. If `TRUE` (default), data cases are matched to reference sharing the same genus, instead of sharing the same species. ## Returns A dataframe including the input dataframe and additional columns, one for each extracted log ratio for each relevant measurement in the reference. The name of the added columns are constructed by prefixing each measurement by the internal variable `logPrefix`. If the input dataframe includes additional S3 classes (such as "tbl_df"), they are also passed to the output. ## Details Each log ratio is defined as the decimal logarithm of the ratio of the variable of interest to a corresponding reference value. The `identifiers` are expected to determine corresponding columns in both data and reference. Each value in these columns identifies the type of bone. By default this is determined by a taxon and a bone element. For any case in the data, the log ratios are computed with respect to the reference values in the same bone type. If the reference does not include that bone type, the corresponding log ratios are set to `NA`. The taxonomy allows the matching of data and reference by genus, instead of by species. This is the default behaviour with `useGenusIfUnambiguous = TRUE`, unless there is some ambiguity: reference including more than one species for the same genus. For instance, `reference$Combi` includes a reference for **Sus scrofa**. If the data includes cases of **Sus domesticus**, their log ratios will be computed with respect to the provided reference for **Sus scrofa**. However, a warning is given to inform the user of this assumption, and let they know that this can be prevented by setting `useGenusIfUnambiguous = FALSE`. For some applications it can be interesting to group some set of bone types into the same reference category to compute the log ratios. The parameter `joinCategories` allows this grouping. `joinCategories` must be a list of named vectors, each including the set of categories in the data which should be mapped to the reference category given by its name. This can be applied to group different species into a single reference species. For instance **sheep**, **capra**, and doubtful cases between both (**sheep/goat**), can be grouped and matched to the same reference for **sheep**, by setting `joinCategories = list(sheep = c("sheep", "goat", "oc"))`. Indeed, the zoologTaxonomy can be used for that purpose using the function `SubtaxonomySet` as `joinCategories = list(sheep = SubtaxonomySet("Caprini"))`. Similarly, `joinCategories` can be applied to group different bone elements into a single reference (see the example below for undetermined phalanges). Note that the `joinCategories` option does not remove the distinction between the different bone types in the data, just indicates that for any of them the log ratios must be computed from the same reference. Using the taxonomy, the presence of cases identified by higher taxonomic ranks are also automatically detected. For instance, if some partially identified cases have been recorded as "Ovis/Capra", this is recognized to denote the tribe **Caprini**, which includes several possible species. Then a warning is given informing the user of the detection of these cases and of the option to use any of the corresponding species in the reference by using the argument `joinCategories` (unless this has been already done). There are some measures that, for most usual taxa, are restricted to a subset of bones. For instance, for **Bos**, **Ovis**, **Capra**, and **Sus**, the measure **GLl** is only relevant for the **astragalus**, while **GL** is not applicable to it. Thus, there cannot be any ambiguity between both measures since they can be identified by the bone element. This justifies that some users have simplified datasets where a single column records indistinctly **GL** or **GLl**. The optional parameter `mergedMeasures` facilitates the processing of this type of simplified dataset. For the alluded example, `mergedMeasures = list(c("GL", "GLl"))` automatically selects, for each bone element, the corresponding measure present in the reference. Observe that if `mergedMeasures` is set to non mutually exclusive measures, the behaviour is unpredictable. ## Examples ```r ## Read an example dataset: dataFile <- system.file("extdata", "dataValenzuelaLamas2008.csv.gz", package="zoolog") dataExample <- utils::read.csv2(dataFile, na.strings = "", encoding = "UTF-8") ## For illustration purposes we keep now only a subset of cases to make ## the example run sufficiently fast. ## Avoid this step if you want to process the full example dataset. dataExample <- dataExample[1:400, ] ## We can observe the first lines (excluding some columns for visibility): head(dataExample)[, -c(6:20,32:64)] ## Compute the log-ratios with respect to the default reference in the ## package zoolog: dataExampleWithLogs <- LogRatios(dataExample) ## The output data frame include new columns with the log-ratios of the ## present measurements, in both data and reference, with a "log" prefix: head(dataExampleWithLogs)[, -c(6:20,32:64)] ## Compute the log-ratios with respect to a different reference: dataExampleWithLogs2 <- LogRatios(dataExample, ref = reference$Basel) head(dataExampleWithLogs2)[, -c(6:20,32:64)] ## Define an altenative reference combining differently the references' ## database: refComb <- list(cattle = "Nieto", sheep = "Davis", Goat = "Clutton", pig = "Albarella", redDeer = "Basel") userReference <- AssembleReference(refComb) ## Compute the log-ratios with respect to this alternative reference: dataExampleWithLogs3 <- LogRatios(dataExample, ref = userReference) ## We can be interested in including the first and second phalanges without ## anterior-posterior identification ("phal 1" and "phal 2"), by computing ## their log ratios with respect to the reference of the corresponding ## anterior phalanges ("phal 1 ant" and "phal 2 ant", respectively). ## For this we use the optional argument joinCategories: categoriesPhalAnt <- list('phal 1 ant' = c("phal 1 ant", "phal 1"), 'phal 2 ant' = c("phal 2 ant", "phal 2")) dataExampleWithLogs4 <- LogRatios(dataExample, joinCategories = categoriesPhalAnt) head(dataExampleWithLogs4)[, -c(6:20,32:64)] ```

LogRatios function