---
title: "Using-blindspiker"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using-blindspiker}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(blindspiker)
```

---
title: "Using blindspiker"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using blindspiker}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

The R package, `blindspiker`, was initially developed for the  Internal Dosimetry program at the Savannah River Site, based on an R script, "SRS Blind Spikes-4.R", written by Tom Labone. 

The first step in using the package is to use the `bs_prep_and_analysis` function. The package anticipates that your organization runs a blind spike program, providing test samples to a laboratory with known test values. Here, you need to supply two sets of data, the test sample data and the laboratory's analysis results. 

The `bs_prep_and_analysis` function requires two data sets. You can either load your data into R separately or use this function to load your comma separated variable (csv) file.

The `bs_prep_and_analysis` function runs a check of the data names, checks data types, merges the data sets, and identifies false positive and false negative results.

## Sample test data

### Test data must haves: 

* sample_ID
* analyte
* spike_value
* spike_unit

### Test data optional extras:
* provider_lab
* submission_date
* sv_unc
* sv_k

## Laboratory results data

### Laboratory results must haves:

* sample_ID
* analyte
* result_date
* result
* unc (analysis uncertainty)
* units
* det_lvl (laboratory's detection level)

### Laboratory results optional extras:

* k (coverage factor)

## Details

Sample test data details

* sample_ID = unique identifier for the sample
* analyte = name of analyte in the sample
* spike_value = quantity of the analyte
* spike_unit = unit of measurement for the spike value
* provider_lab = for the spiked samples - Optional, not currently used for any function
* submission_date = date the sample was delivered to the laboratory in format yyyy-mm-dd (optional, not currently used, but user could consider it for later analysis of results in the combined data)
* sv_unc = uncertainty in the spike value - Optional, default = 0
* sv_k = coverage factor for the spike value uncertainty - Optional, default = 2

Laboratory results data details

* sample_ID = unique identifier for the sample - must match spike data
* analyte = name of analyte in the sample - must match spike data
* result_date = date the sample was reported in format yyyy-mm-dd
* k = coverage factor for the laboratory's uncertainty of the result - Optional, default = 2
* result = analysis result
* unc = analysis uncertainty in same units as result
* units = laboratory units - must match spike value units
* det_lvl = laboratory's detection level

**Save the results** of the `bs_prep_and_analysis` function. In examples, we use `bs_df` as the name of the saved blind spike data frame. You can then evaluate the saved data. The following functions are available:

**`table_spike` summarizes all individual spike values** and

**`spike_combos` provides any combinations** of spike values in individual samples that the user chooses to have tallied.

**`plot_run` provides run charts** with the option of plotting in analysis units or by a ratio of the laboratory results to the blind spike values. Both versions show uncertainty ranges of the results. Uncertainty bars are shown on the laboratory results and the ratios. When there is no overlap with the spike values, the laboratory result is either a false positive or a false negative. False positives are excluded from the ratio version when there is no spike value to avoid division by zero. 

**`table_false` provides confidence intervals on error rates** for all laboratory results. 

**`plot_tat` plots the laboratory turnaround time** for each spike sample.

**`plot_qq` provides quantile-quantile plots** of the results. Random errors are expected to fluctuate in a normally distributed pattern. When the QQ plot shows a deviation from normal, further investigation in the underlying process may be needed.