Update README and vignette

DESCRIPTION

@@ -37,7 +37,7 @@ Imports:
     utils
 Suggests: 
     cluster,
-    folio (>= 1.4.0),
+    folio (>= 1.5.0),
     igraph,
     knitr,
     markdown,

README.Rmd

@@ -40,10 +40,11 @@ This package is currently *experimental*. This means that it is functional, but
 
 Exploration and analysis of compositional data in the framework of @aitchison1986. **nexus** provides tools for chemical fingerprinting and source tracking of ancient materials. This package provides methods for compositional data analysis:
 
-* Logratio transformations: `transform_lr()`, `transform_clr()`, `transform_alr()`, `transform_ilr()`, `transform_plr()`.
 * Compositional statistics.
+* Compositional data visualization.
+* Logratio transformations: `transform_lr()`, `transform_clr()`, `transform_alr()`, `transform_ilr()`, `transform_plr()`.
 * Zero and missing value replacement.
-* Outlier detection: `outliers()`.
+* Outlier detection: `detect_outlier()`.
 
 This package also includes methods for provenance studies:
 
@@ -101,18 +102,17 @@ groups(coda) <- bronze$dynasty
 
 ```{r barplot, fig.width=5, fig.height=7}
 ## Compositional barplots of major elements
-barplot(coda, select = is_element_major(coda), border = NA, space = 0)
+barplot(coda, select = is_element_major(coda), order_rows = "Cu",
+        border = NA, space = 0)
 ```
 
 ```{r lra, fig.width=7, fig.height=7, out.width='50%', fig.show='hold'}
-## Compositional mean by artefact
-coda <- condense(coda, by = list(bronze$dynasty, bronze$reference))
-
 ## Log-ratio analysis
 ## (PCA of centered log-ratio; outliers should be removed first)
 clr <- transform_clr(coda, weights = TRUE)
 lra <- pca(clr)
 
+## Visualize results
 viz_individuals(lra, color = c("#004488", "#DDAA33", "#BB5566"))
 viz_hull(x = lra, border = c("#004488", "#DDAA33", "#BB5566"))
 

README.md

@@ -45,11 +45,12 @@ Aitchison (1986). **nexus** provides tools for chemical fingerprinting
 and source tracking of ancient materials. This package provides methods
 for compositional data analysis:
 
+- Compositional statistics.
+- Compositional data visualization.
 - Logratio transformations: `transform_lr()`, `transform_clr()`,
   `transform_alr()`, `transform_ilr()`, `transform_plr()`.
-- Compositional statistics.
 - Zero and missing value replacement.
-- Outlier detection: `outliers()`.
+- Outlier detection: `detect_outlier()`.
 
 This package also includes methods for provenance studies:
 
@@ -123,20 +124,19 @@ groups(coda) <- bronze$dynasty
 
 ``` r
 ## Compositional barplots of major elements
-barplot(coda, select = is_element_major(coda), border = NA, space = 0)
+barplot(coda, select = is_element_major(coda), order_rows = "Cu",
+        border = NA, space = 0)
 ```
 
 ![](man/figures/README-barplot-1.png)<!-- -->
 
 ``` r
-## Compositional mean by artefact
-coda <- condense(coda, by = list(bronze$dynasty, bronze$reference))
-
 ## Log-ratio analysis
 ## (PCA of centered log-ratio; outliers should be removed first)
 clr <- transform_clr(coda, weights = TRUE)
 lra <- pca(clr)
 
+## Visualize results
 viz_individuals(lra, color = c("#004488", "#DDAA33", "#BB5566"))
 viz_hull(x = lra, border = c("#004488", "#DDAA33", "#BB5566"))
 
@@ -226,6 +226,15 @@ Compositional Data Analysis.” *Mathematical Geology* 35 (3): 279–300.
 
 </div>
 
+<div id="ref-egozcue2024" class="csl-entry">
+
+Egozcue, Juan José, Caterina Gozzi, Antonella Buccianti, and Vera
+Pawlowsky-Glahn. 2024. “Exploring Geochemical Data Using Compositional
+Techniques: A Practical Guide.” *Journal of Geochemical Exploration* 258
+(March): 107385. <https://doi.org/10.1016/j.gexplo.2024.107385>.
+
+</div>
+
 <div id="ref-egozcue2023" class="csl-entry">
 
 Egozcue, Juan José, and Vera Pawlowsky-Glahn. 2023. “Subcompositional
@@ -318,6 +327,16 @@ Taylor & Francis Group.
 
 </div>
 
+<div id="ref-grunsky2024" class="csl-entry">
+
+Grunsky, Eric, Michael Greenacre, and Bruce Kjarsgaard. 2024. “GeoCoDA:
+Recognizing and Validating Structural Processes in Geochemical Data. A
+Workflow on Compositional Data Analysis in Lithogeochemistry.” *Applied
+Computing and Geosciences* 22 (June): 100149.
+<https://doi.org/10.1016/j.acags.2023.100149>.
+
+</div>
+
 <div id="ref-hron2017" class="csl-entry">
 
 Hron, Karel, Peter Filzmoser, Patrice de Caritat, Eva Fišerová, and

vignettes/bibliography.bib

@@ -362,3 +362,29 @@ @inproceedings{aitchison1997
   eventtitle = {Third Annual Conference of the {{International Association}} for {{Mathematical Geology}}},
   langid = {english}
 }
+
+@article{egozcue2024,
+  title = {Exploring Geochemical Data Using Compositional Techniques: {{A}} Practical Guide},
+  shorttitle = {Exploring Geochemical Data Using Compositional Techniques},
+  author = {Egozcue, Juan José and Gozzi, Caterina and Buccianti, Antonella and Pawlowsky-Glahn, Vera},
+  date = {2024-03},
+  journaltitle = {Journal of Geochemical Exploration},
+  volume = {258},
+  pages = {107385},
+  issn = {03756742},
+  doi = {10.1016/j.gexplo.2024.107385},
+  langid = {english}
+}
+
+@article{grunsky2024,
+  title = {{{GeoCoDA}}: {{Recognizing}} and Validating Structural Processes in Geochemical Data. {{A}} Workflow on Compositional Data Analysis in Lithogeochemistry},
+  shorttitle = {{{GeoCoDA}}},
+  author = {Grunsky, Eric and Greenacre, Michael and Kjarsgaard, Bruce},
+  date = {2024-06},
+  journaltitle = {Applied Computing and Geosciences},
+  volume = {22},
+  pages = {100149},
+  issn = {25901974},
+  doi = {10.1016/j.acags.2023.100149},
+  langid = {english}
+}

vignettes/nexus.Rmd

@@ -23,7 +23,11 @@ knitr::opts_chunk$set(
 
 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).
+**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
 
@@ -88,35 +92,28 @@ Provenance studies typically rely on two approaches, which can be used together:
 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 Day et al. 2011
-data("kommos", package = "folio")
-kommos <- remove_NA(kommos, margin = 1) # Remove cases with missing values
+## Data from Wood and Liu 2023
+data("bronze", package = "folio")
 
-## Use the first column (ceramic types) for grouping
-coda <- as_composition(kommos, groups = 1)
+## 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):
-
-```{r}
-## Assume that a third of the samples does not belong to any group
-grp <- kommos$type
-grp[sample(length(grp), size = length(grp) / 3)] <- NA
+`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.
 
-## Set groups
-groups(coda) <- grp
-is_assigned(coda)
+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):
 
-## Retrieve groups
-groups(coda)
+```{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)
 ```
 
-Once groups have been defined, they can be used by further methods (e.g. plotting).
+# Descriptive statistics
 
-```{r barplot, fig.width=7, fig.height=7, out.width='100%'}
-## Compositional bar plot
-## (unassigned sample are not displayed)
-barplot(coda, order = "Ca")
+```{r mean, eval=FALSE}
+## Compositional mean by artefact
+coda <- condense(coda, by = list(bronze$dynasty, bronze$reference))
 ```
 
 # Log-ratio transformations
@@ -133,20 +130,34 @@ back <- transform_inverse(clr)
 all.equal(back, coda)
 ```
 
-# Multivariate methods
+# Multivariate Analysis
 
-## Principal Components 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)
+clr <- transform_clr(coda, weights = TRUE)
 
 ## PCA
-clr_pca <- pca(clr, scale = FALSE)
+lra <- pca(clr)
 
 ## Visualize results
-viz_individuals(x = clr_pca)
-viz_variables(clr_pca)
+viz_individuals(lra, color = c("#004488", "#DDAA33", "#BB5566"))
+viz_hull(x = lra, border = c("#004488", "#DDAA33", "#BB5566"))
+
+viz_variables(lra)
 ```
 
 ## MANOVA
@@ -157,10 +168,10 @@ The log-transformed data can be assigned to a new column, allowing us to keep wo
 ## ILR
 ilr <- transform_ilr(coda)
 
-kommos$ilr <- ilr
+bronze$ilr <- ilr
 
 ## MANOVA
-fit <- manova(ilr ~ type, data = kommos)
+fit <- manova(ilr ~ groups(ilr), data = bronze)
 summary(fit)
 ```
 
@@ -170,7 +181,7 @@ The MANOVA results suggest that there are statistically significant differences
 
 ```{r lda, fig.width=7, fig.height=7, out.width='100%'}
 ## LDA
-discr <- MASS::lda(type ~ ilr, data = kommos)
+discr <- MASS::lda(groups(ilr) ~ ilr, data = bronze)
 plot(discr)
 
 ## Back transform results