read-incomplete-data.Rmd

---
title: "Read incomplete data"
author: "YASUMOTO Atsushi"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Read incomplete data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- © 2018 JAMSTEC -->

```{r setup, include = FALSE}
wd <- tempdir()
knitr::opts_chunk$set(
  root.dir = wd,
  fig.width = 7,
  fig.height = 7,
  collapse = TRUE,
  comment = "#>"
)
library(knitr)
library(data.table)
library(captioner)
tbl_n <- captioner(prefix = "Tab.")
extdata <- system.file(package = "qntmap", "extdata")
```

# Intro

This article introduces workarounds for errors from `read_qnt()` and `read_xmap()`
when files recording analytical conditions are missing or 
written in incompatible formats depending on instruments
(i.e., versions of EPMA hardware and software).

## Spot analysis data

Among the required files to read spot analysis data
([`r tbl_n("qnt-files", display = "cite")`](#tbl-qnt-files)),
`.cnd/elemw.cnd` and `Pos_001/data001.qnt` can be missing or 
be written in unexpected format.
In such case, prepare a csv file describing element names,
dwell time for peak and background, and relative positions of backgrounds in 
a given format ([`r tbl_n("qnt-meta", display = "cite")`](#qnt-meta)).
Then, following code will read spot analysis data.

```.r
qnt <- read_qnt(".qnt", conditions = "conditions_qnt.csv")
# First argument is path to the directory containing required files.
# "conditions" argument is a path to a user-prepared csv file.
```

```{r tbl-qnt-files, echo = FALSE}
.cap = tbl_n(
    name = "qnt-files", 
    caption = paste0(
      "[]{#tbl-qnt-files}",
      "Required files to retrieve spot analysis data"
    )
  )
kable(fread(file.path(extdata, "files-qnt.csv")), caption = .cap)
```



```{r tbl-qnt-meta, echo = FALSE}
.cap = tbl_n(
    name = "qnt-meta", 
    caption = paste0(
      "[]{#qnt-meta}",
      "An example csv file which records element names, ",
      "dwell time for peak and background, and relative positions of backgrounds. ",
      "[Download csv file from here.](https://raw.githubusercontent.com/atusy/qntmap/master/inst/extdata/minimal/conditions_qnt.csv)"
    )
  )
kable(fread(file.path(extdata, "minimal", "conditions_qnt.csv")), caption = .cap)
```

## Mapping data

Mapping data are expected to be saved as
ASCII converted files (`*.txt` or `*.csv`) and as
condition files (`*.cnd`) 
([`r tbl_n("map-files", display = "cite")`](#tbl-map-files)).
Asterisks are expected to be filled by 
the format of `#_map` or by `data#` where sharps are integers.
File names of ASCII converted files and condition files must be paired
(e.g, `1_map.txt` and `1_map.cnd`).
In case of irregular file names or missing condition files, 
prepare a csv file describing element name, file path, instrument, dwell time, 
probe current, X-Y coordinates of a starting pixel, step size, map size, 
and dead time ([`r tbl_n("map-meta", display = "cite")`](#tbl-map-meta)).
Then, following code will read spot analysis data.

```.r
xmap <- read_qnt(conditions = "conditions_xmap.csv")
# "conditions" argument is a path to a user-prepared csv file.
```

```{r tbl-map-files, echo = FALSE}
.cap = tbl_n(
    name = "map-files", 
    caption = paste0(
      "[]{#tbl-map-files}",
      "Required files to retrieve mapping data"
    )
  )
kable(fread(file.path(extdata, "files-map.csv")), caption = .cap)
```



```{r tbl-map-meta, echo = FALSE}
.cap = tbl_n(
    name = "map-meta", 
    caption = paste0(
      "[]{#map-meta}",
      "An example csv file which records element names, ",
      "dwell time for peak and background, and relative positions of backgrounds. ",
      "Except for 'Element' and 'File path', only values in a first row is used. ",
      "The other cells are ignored regardless of their contents. ",
      "[Download csv file from here.](https://raw.githubusercontent.com/atusy/qntmap/master/inst/extdata/minimal/conditions_xmap.csv)"
    )
  )
kable(fread(file.path(extdata, "minimal", "conditions_xmap.csv")), caption = .cap)
```