qntmap.Rmd

---
title: "Get started with qntmap"
author: "Atsushi YASUMOTO"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    df_print: kable
vignette: >
  %\VignetteIndexEntry{Get started with qntmap}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

<!-- © 2018 JAMSTEC -->

```{r setup, include = FALSE}
wd <- tempdir()
knitr::opts_chunk$set(
  root.dir = wd,
  fig.width = 5,
  fig.height = 5,
  collapse = TRUE,
  comment = "#>"
)
library(qntmap)
library(dplyr)
library(pipeR)
library(ggplot2)
library(stringr)
library(purrr)

formals(read_xmap)$renew <-
  formals(read_qnt)$renew <- 
  TRUE
```

# Prerequisite

Install `qntmap` package on [R](https://www.r-project.org/) and prepare EPMA data following ["Read me"](../index.html#epma-analysis).

# Preparation

## Load package

```{r load-qntmap, eval = FALSE}
library(qntmap)
```

## Go to working directory

```{r setwd, eval = FALSE}
wd <- tempdir() # Arbitrary
setwd(wd)
```

## Copy example data

```{r copy-files}
file.copy(
  from = system.file('extdata', 'minimal', package = 'qntmap'),
  to = wd,
  recursive = TRUE
)
```

`TRUE` indicates copying is successful. 
Check copied files by `dir()`.

```{r file-list}
dir(file.path(wd, 'minimal'), recursive = TRUE, all.files = TRUE)
```

# Analysis

## Specify directories containing data

```{r specify-directories, include = FALSE, eval = TRUE}
dir_map <- file.path(wd, 'minimal/.map/1')
dir_qnt <- file.path(wd, 'minimal/.qnt')
```

``` r
dir_map <- 'minimal/.map/1'
dir_qnt <- 'minimal/.qnt'
```

## Load data

```{r load-data, message = FALSE}
# Read X-ray mapping data
xmap <- read_xmap(dir_map)

# Read spot analysis data
qnt <- read_qnt(dir_qnt, renew = TRUE)
```

The example data contains olivine and quartz in the mapping area.
The phases are quantified 20 points each.

```{r tidy, message = FALSE, echo = FALSE, warning = FALSE}
epma <- tidy_epma(qnt, xmap) %>>%
  filter(elm == elm[[1]]) %>>%
  select(x_px, y_px, phase)
plot(xmap, 'Si', interactive = FALSE, colors = "gray") +
  geom_point(
    aes(y_px, x_px, colour = phase), data = epma, inherit.aes = FALSE
  ) +
  guides(
    fill = guide_colourbar(barheight = grid::unit(1, "npc") - unit(10, "line"))
  )
```


## Plot X-ray maps

Plots are **interactive** with Web UI.
Elements can be chosen by mouse actions.

```{.r}
plot(xmap)
# A following plot is non-interactive mode run by
# plot(xmap, 'Mg', interactive = FALSE)
```

```{r plot-mg, echo = FALSE}
plot(xmap, 'Mg', interactive = FALSE)
```


## Cluster analysis

### Initialize cluster centers

This step guesses initial cluster centers
(i.e., mean mapping intensities of each phase).
Check if results are adequate by comparing them with plots.
If inadequate, consider modifying values

```{r find-centers}
centers <- find_centers(xmap, qnt)
print(centers)
```

### Run cluster analysis {#run-cls}

A result is saved as a binary file and PNG images in `clustering` directory below the directory containing mapping data.

For a quick look, `plot()`{.r} function is also available.

```{r plot-clusters, eval = TRUE, fig.keep = "last"}
cluster <- cluster_xmap(xmap, centers)
plot(cluster, interactive = FALSE)
```


### Summarize cluster analysis

`summary()` function gives abundance ratios of phases in the map.

```{r summarize-cluster}
summary(cluster)
```

## Quantify

```{r quantify}
qmap <- quantify(xmap = xmap, qnt = qnt, cluster = cluster)
```

### Plot quantified map

Just like [X-ray map](#Plot X-ray map).

```{r plot-qmap}
plot(qmap, 'SiO2', interactive = FALSE)
```

### Summarize quantified map

```{r summarize-qmap}
summary(qmap)
```

Note also that this summary does not correct densities of phases.

```{r calc-expected-values, include = FALSE}
V <- unclass(table(cluster$cluster))
V <- V / sum(V)
E <- mean(qmap)
E <- setNames(round(E[['Whole area']], 2), E[['Element']])
```

According to compositions of olivine (57.29% MgO and 42.71 wt% SiO~2~),
and of quartz (100% SiO~2~),

$$
E(MgO^{\mathrm{bulk}}) = 
  57.29 \times `r V['Ol']` + 0 \times `r V['Qtz']` = 
  `r 57.29 * V['Ol']` \simeq 
  `r E['MgO']` \mathrm{,}
$$

and

$$
E(SiO^{\mathrm{bulk}}_{2}) = 
  42.71 \times `r V['Ol']` + 100 \times `r V['Qtz']` = 
  `r 42.71 * V['Ol'] + 100 * V['Qtz']` \simeq
  `r E['SiO2']` \mathrm{,}
$$

which are concordant to the above summary.

### Summary based on mask images

A simple use of `mean()` function returns `mean()` values of each elements.

```{r mean-qmap}
mean(qmap)
```

Further, by using 
**PNG format mask image width and height are same as mapping data**, 
`mean()` values of each element are calculated for each area with same colors in the mask image.

Let's use an image from cluster analysis [above](#run-cls).

Input path to the image to `segment` function.

```{r img-path, include = FALSE}
img <- dir(
    file.path(dir_map, "clustering"), pattern = "_map.png", full.names = TRUE
  )[[1]]
i <- segment(img)
```

``` r
i <- segment(dir("`r img`"))
```

Then, input the result of `segment()` to `index` parameter of `mean()`.

```{r mean-qmap-with-mask image}
mean(qmap, index = i)
```

Alternatively, `index` parameter can be given as a character vector such as name of phases (i.e. .
Thus, giving `index = cluster$cluster` returns a prettier result than the above.

```{r mean-qmap-with-cluster-names}
mean(qmap, index = cluster$cluster)
```

The above two `mean()` values are equivalent as black (`#000000`) corresponds to olivine cluster,
and white (`#FFFFFF`) to quartz cluster.

This feature is useful to find average compositions of each minearls, 
local bulk compositions of domains (layer, symplectite), and so on.

```{r unlink-files, include = FALSE}
unlink(c('centers0.csv', 'phase_list0.csv'))
```