---
title: "Introduction to LW1949"
author: "Jean V. Adams"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to LW1949}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The R package **LW1949** automates the steps taken in Litchfield and Wilcoxon's (1949) manual approach to evaluating dose-effect experiments (Adams et al. 2016).  Letting the computer do the work saves time and yields the best fit possible using the Litchfield Wilcoxon approach (by minimizing the chi-squared statistic).
You can also try a brief demonstration of **LW1949** in this [web app](https://jvadams.shinyapps.io/LW1949demo).

### Install

Install

```{r install_package, eval=FALSE}
install.packages("LW1949")
```

and load the **LW1949** package.

```{r load_package}
library(LW1949)
```

### Prepare data

Use the `dataprep` function to create a data frame with the results of a dose-effect experiment.  Provide information on three key input variables,

- chemical concentration (`dose`), 
- total number tested (`ntot`), and 
- number affected (`nfx`).

```{r dose-effect_data}
conc <- c(0.0625, 0.125, 0.25, 0.5, 1, 2, 3)
numtested <- rep(8, 7)
numaffected <- c(1, 4, 4, 7, 8, 8, 8)
mydat <- dataprep(dose=conc, ntot=numtested, nfx=numaffected)
```

The `dataprep` function puts the input variables into a data frame along with several new variables,

- record number (`rec`), 
- proportional effects (`pfx`),
- log10 transformed dose (`log10dose`), 
- probit transformed effects (`bitpfx`), 
- an effects category (`fxcateg`) identifying none (0), partial (50), and complete (100) effects, and 
- a column (`LWkeep`) to identify observations to keep when applying Litchfield and Wilcoxon's (1949) method (their step A).

```{r dataprep()_output}
mydat
```

### Fit model

Use the `fitLWauto` and `LWestimate` functions to fit a dose-effect relation following Litchfield and Wilcoxon's (1949) method.

```{r fit_LW}
intslope <- fitLWauto(mydat)
fLW <- LWestimate(intslope, mydat)
```

The output from `fitLWauto` is a numeric vector of length two, the estimated intercept and slope of the best fitting line on the log10-probit scale..

```{r fitLWauto_output}
intslope
```

The output from `LWestimate` is a list with three elements,

- `chi`, the chi-squared test comparing observed and expected effects, including the expected effects, the "corrected" expected effects (step B in Litchfield and Wilcoxon 1949), and the contribution to the chi-squared statistic (their step C);
- `params`, the estimated intercept and slope on the log10-probit scale; and
- `LWest`, additional estimates calculated in the process of using Litchfield and Wilcoxon's (1949) method (their steps D and E).

```{r LWestimate_output}
fLW
```

### Predict

Use the `predlinear` function and the fitted Litchfield and Wilcoxon model to estimate the effective doses for specified percent effects (with 95% confidence limits).

```{r estimate_LW}
pctaffected <- c(25, 50, 99.9)
predlinear(pctaffected, fLW)
```

### Plot

Use the `plotDELP` and `plotDE` functions to plot the raw data on the log10-probit and arithmetics scales.  Observations with no or 100% affected are plotted using white filled circles (at 0.1 and 99.9% respectively in the log10-probit plot).  

Use the `predLinesLP` and `predLines` functions to add the L-W predicted relations to both plots, with 95% **horizontal** confidence intervals for the predicted dose to elicit a given percent affected.

```{r plot_fits, fig.width=5, fig.height=5}
plotDELP(mydat)
predLinesLP(fLW)

plotDE(mydat)
predLines(fLW)
```

### References

Adams, J. V., K. S. Slaght, and M. A. Boogaard.  2016.  An automated approach to Litchfield and Wilcoxon's evaluation of dose-effect experiments using the R package LW1949.  *Environmental Toxicology and Chemistry* 35(12):3058-3061.  [DOI 10.1002/etc.3490](https://doi.org/10.1002/etc.3490)

Litchfield, J. T. Jr. and F. Wilcoxon. 1949. [A simplified method of evaluating dose-effect experiments](http://jpet.aspetjournals.org/content/96/2/99.abstract). *Journal of Pharmacology and Experimental Therapeutics* 96(2):99-113.

LW1949. An automated approach (R package) to Litchfield and Wilcoxon's (1949) evaluation of dose-effect experiments.  Available on [Cran](https://CRAN.R-project.org/package=LW1949), with the latest development version on [GitHub](https://github.com/JVAdams/LW1949).