README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "doc/figures/readme-",
  fig.height=4,
  fig.align='center',
  out.width = "100%"
)

library(cvasi)
```

# cvasi: Calibration, Validation, and Simulation of TKTD models in R

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/cvasi)](https://cran.r-project.org/package=cvasi)
[![R-CMD-check](https://github.com/cvasi-tktd/cvasi/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/cvasi-tktd/cvasi/actions/workflows/R-CMD-check.yaml)
<!--[![Codecov test coverage](https://codecov.io/gh/xy/cvasi/branch/main/graph/badge.svg)](https://app.codecov.io/gh/xy/cvasi?branch=main)-->
<!-- badges: end -->

The `cvasi` package aims to ease the use of ecotox effect models by providing an
intuitive workflow. Model inputs and parameters are encapsulated in scenario
objects which can be piped to other functions. Operations can be chained using
the `tidyr` syntax. The most time-consuming processes can be run in parallel if
requested.

The package provides facilities to

* simulate effect models such as *GUTS-RED*, *DEB*, *Lemna*, *Myriophyllum*, and *Algae*
* calculate effect endpoints
* derive effect profiles (*EPx* values)
* import exposure time-series from *FOCUS TOXSWA*
* import fitted parameters from *morse*
* and more

A graphical user interface implemented in [Shiny](https://posit.co/products/open-source/rstudio/)
is also available, see the *[cvasi.ui](https://github.com/cvasi-tktd/cvasi.ui/)*
package. Please have a look at the [Changelog](NEWS.md)
for an overview of user-facing updates and changes.


## Installation

Install the package from CRAN:

```{r eval=FALSE}
install.packages("cvasi", dependencies=TRUE)
```

Or install the newest development version from *GitHub*:

```{r eval=FALSE}
install.packages("remotes", dependencies=TRUE)
remotes::install_github("cvasi-tktd/cvasi", dependencies=TRUE)
```

For installing `cvasi` from *GitHub* on Windows computers, please make sure that
you also have [*Rtools*](https://cran.r-project.org/bin/windows/Rtools/) installed
on your machine. *Rtools* are required to compile the package's C code.


## Documentation

The package contains the following vignettes

* [User Manual](https://github.com/cvasi-tktd/cvasi/blob/main/doc/cvasi-1-manual.md)
* [Modeling Howto](https://github.com/cvasi-tktd/cvasi/blob/main/doc/cvasi-2-howto.md)

They can also be accessed locally by executing an *R* statement such as:
```{r, eval=FALSE}
vignette("cvasi-1-manual", package="cvasi")
```


## Usage

Basic usage:
```{r,message=FALSE,out.width="70%"}
library(cvasi)

# create and parameterize a GUTS-RED-IT scenario
GUTS_RED_IT() %>%
  set_param(c(kd=0.0005, hb=0, alpha=0.4, beta=1.5)) %>%
  set_exposure(data.frame(time=c(0, 100, 101, 200, 201, 400),
                          conc=c(0, 0, 0.1, 0.1, 0, 0))) %>%
  set_times(1:400) -> scenario

# simulate scenario
results <- scenario %>% simulate()
tail(results)

# ... and plot simulation results
plot(results)
```

Calculation of effects:
```{r out.width="60%",warning=FALSE}
# calculate effect level
scenario %>% effect()

# create a dose-response curve
scenario %>% dose_response() -> drc
head(drc)

# plot the dose-response curve
plot(drc)

# derive EPx values
scenario %>% epx()
```

Multiple scenarios can be processed in parallel without modifications to the workflow:
```{r eval=FALSE}
# enable parallel processing
future::plan(future::multisession)

# derive EPx for a list of 100 scenarios in parallel
rep(c(scenario), 100) %>% epx()

# disable parallel processing
future::plan(future::sequential)
```

## License

The package and its source code is free and open-source software available under
the [GPL-3.0 license](https://github.com/cvasi-tktd/cvasi/blob/main/LICENSE.md).

## Issues

If you find any issues or bugs within the package, please create a
[new issue](https://github.com/cvasi-tktd/cvasi/issues) on GitHub.

## Contributing

Contributions to the project are welcome! Please have a look at the
[Contribution Guidelines](https://github.com/cvasi-tktd/cvasi/blob/main/CONTRIBUTING.md) before submitting a Pull Request.


## Acknowledgements

Financial support for creation and release of this software project was provided
by Bayer Crop Science. This R package started as an internal project at Bayer
Crop Science and the project owners would like to thank the people who have
contributed (in no particular order):

Nils Kehrein, Johannes Witt, André Gergs, Thomas Preuss, Julian Heinrich,
Zhenglei Gao, Tjalling Jager, Dirk Nickisch, Torben Wittwer, and Peter Vermeiren.