--- title: "Introduction to nexus" author: "N. Frerebeau" date: "`r Sys.Date()`" output: markdown::html_format: options: toc: true number_sections: true bibliography: bibliography.bib vignette: > %\VignetteIndexEntry{Introduction to nexus} %\VignetteEngine{knitr::knitr} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` Provenance studies rely on the identification of probable sources, such that the variability between two sources is greater than the internal variability of a single source (the so-called *provenance postulate*; Weigand, Harbottle, and Sayre 1977). This assumes that a unique signature can be identified for each source on the basis of several criteria. **nexus** is designed for chemical fingerprinting and source tracking of ancient materials. It provides provides tools for exploration and analysis of compositional data in the framework of Aitchison (1986). If you are unfamiliar with the concepts and challenges of compositional data analysis, the following publications are a good place to start: - Egozcue, J. J., Gozzi, C., Buccianti, A. & Pawlowsky-Glahn, V. (2024). Exploring Geochemical Data Using Compositional Techniques: A Practical Guide. *Journal of Geochemical Exploration*, 258 :107385. DOI: [10.1016/j.gexplo.2024.107385](https://doi.org/10.1016/j.gexplo.2024.107385). - Greenacre, M. & Wood, J. R. (2024). A Comprehensive Workflow for Compositional Data Analysis in Archaeometry, with Code in R. *Archaeological and Anthropological Science*. - Grunsky, E., Greenacre, M. & Kjarsgaard, B. (2024). GeoCoDA: Recognizing and Validating Structural Processes in Geochemical Data. A Workflow on Compositional Data Analysis in Lithogeochemistry. *Applied Computing and Geosciences*, 22: 100149. DOI: [10.1016/j.acags.2023.100149](https://doi.org/10.1016/j.acags.2023.100149). # Get started ```{r setup} ## Install extra packages (if needed) # install.packages("folio") library(nexus) ``` **nexus** provides a set of S4 classes that represent different special types of matrix. The most basic class represents a compositional data matrix, i.e. quantitative (positive) descriptions of the parts of some whole, carrying relative, rather than absolute, information (Aitchison 1986; Greenacre 2021). *It assumes that you keep your data tidy*: each variable must be saved in its own column and each observation (sample) must be saved in its own row. This class is of simple use as it inherits from base `matrix`: ```{r} ## Mineral compositions of rock specimens ## Data from Aitchison 1986 data("hongite") head(hongite) ## Coerce to compositional data coda <- as_composition(hongite) head(coda) ``` A `CompositionMatrix` represents a *closed* composition matrix: each row of the matrix sum up to 1 (only relative changes are relevant in compositional data analysis). The original row sums are kept internally, so that the source data can be restored: ```{r} ## Coerce to count data counts <- as_amounts(coda) all.equal(hongite, as.data.frame(counts)) ``` The `parts` argument of the function `as_composition()` is used to define the columns to be used as the compositional part. If `parts` is `NULL` (the default), all non-integer numeric columns (i.e. of type `double`) are used. In the case of a `data.frame` coercion, additional columns are removed. ```{r} ## Create a data.frame X <- data.frame( type = c("A", "A", "B", "A", "B", "C", "C", "C", "B"), Ca = c(7.72, 7.32, 3.11, 7.19, 7.41, 5, 4.18, 1, 4.51), Fe = c(6.12, 5.88, 5.12, 6.18, 6.02, 7.14, 5.25, 5.28, 5.72), Na = c(0.97, 1.59, 1.25, 0.86, 0.76, 0.51, 0.75, 0.52, 0.56) ) ## Coerce to a compositional matrix ## (the 'type' column will be removed) Y <- as_composition(X) ``` # Working with (reference) groups Provenance studies typically rely on two approaches, which can be used together: * Identification of groups among the artifacts being studied, based on mineralogical or geochemical criteria (*clustering*). * Comparison with so-called reference groups, i.e. known geological sources or archaeological contexts (*classification*). When coercing a `data.frame` to a `CompositionMatrix` object, **nexus** allows to specify whether an observation belongs to a specific group (or not): ```{r} ## Data from Wood and Liu 2023 data("bronze", package = "folio") ## Use the third column (dynasties) for grouping coda <- as_composition(bronze, groups = 3) ``` `groups(x)` and `groups(x) <- value` allow to retrieve or set groups of an existing `CompositionMatrix`. Missing values (`NA`) or empty strings can be used to specify that a sample does not belong to any group. Once groups have been defined, they can be used by further methods (e.g. plotting). Note that for better readability, you can `select` only some of the parts (e.g. major elements): ```{r barplot, fig.width=7, fig.height=7, out.width='100%'} ## Compositional bar plot barplot(coda, select = is_element_major(coda), order_rows = "Cu", space = 0) ``` # Descriptive statistics ```{r mean, eval=FALSE} ## Compositional mean by artefact coda <- condense(coda, by = list(bronze$dynasty, bronze$reference)) ``` # Log-ratio transformations The package provides the following (inverse) transformations: centered log ratio (*CLR*, Aitchison 1986), additive log ratio (*ALR*, Aitchison 1986), isometric log ratio (*ILR*, Egozcue et al. 2003) and pivot log-ratio (*PLR*, Hron et al. 2017). ```{r transform, fig.width=7, fig.height=8, out.width='100%'} ## CLR clr <- transform_clr(coda) ## Back transform back <- transform_inverse(clr) all.equal(back, coda) ``` # Multivariate Analysis ```{r} ## Assume that about a third of the samples does not belong to any group grp <- groups(coda) grp[sample(length(grp), size = 100)] <- NA ## Set groups groups(coda) <- grp ## Retrieve groups # groups(coda) ``` ## Log-Ratio Analysis ```{r pca, fig.width=7, fig.height=7, out.width='50%', fig.show='hold'} ## CLR clr <- transform_clr(coda, weights = TRUE) ## PCA lra <- pca(clr) ## Visualize results viz_individuals(lra, color = c("#004488", "#DDAA33", "#BB5566")) viz_hull(x = lra, border = c("#004488", "#DDAA33", "#BB5566")) viz_variables(lra) ``` ## MANOVA The log-transformed data can be assigned to a new column, allowing us to keep working with the data in the context of the original `data.frame`: ```{r manova} ## ILR ilr <- transform_ilr(coda) bronze$ilr <- ilr ## MANOVA fit <- manova(ilr ~ groups(ilr), data = bronze) summary(fit) ``` The MANOVA results suggest that there are statistically significant differences between groups. ## Linear Discriminant Analysis ```{r lda, fig.width=7, fig.height=7, out.width='100%'} ## LDA discr <- MASS::lda(groups(ilr) ~ ilr, data = bronze) plot(discr) ## Back transform results transform_inverse(discr$means, origin = ilr) ``` # References Aitchison, J. (1986). *The Statistical Analysis of Compositional Data. Monographs on Statistics and Applied Probability*. Londres, UK ; New York, USA: Chapman and Hall. Egozcue, J. J., Pawlowsky-Glahn, V., Mateu-Figueras, G. and Barceló-Vidal, C. (2003). Isometric Logratio Transformations for Compositional Data Analysis. *Mathematical Geology*, 35(3): 279-300. DOI: [10.1023/A:1023818214614](https://doi.org/10.1023/A:1023818214614). Greenacre, M. (2021). Compositional Data Analysis. *Annual Review of Statistics and Its Application*, 8(1): 271-299. DOI: [10.1146/annurev-statistics-042720-124436](https://doi.org/10.1146/annurev-statistics-042720-124436). Hron, K., Filzmoser, P., de Caritat, P., Fišerová, E. and Gardlo, A. (2017). Weighted Pivot Coordinates for Compositional Data and Their Application to Geochemical Mapping. *Mathematical Geosciences*, 49(6): 797-814. DOI : [10.1007/s11004-017-9684-z](https://doi.org/10.1007/s11004-017-9684-z). Weigand, P. C., Harbottle, G. and Sayre, E. (1977). Turquoise Sources and Source Analysisis: Mesoamerica and the Southwestern U.S.A. In J. Ericson & T. K. Earle (Eds.), *Exchange Systems in Prehistory*, 15-34. New York, NY: Academic Press.