One box time series and twa values

- one_box() creates decline time series from mkinfit objects or simply
  from a half-life
- sawtooth() generates sawtooth curves for arbitrary application
  patterns and decline models
- twa() calculates moving window averages
- max_twa() gives their maxima and
- plot.one_box() can plot series generated by one_box() or sawtooth(),
  optionally adding a greay rectangle to illustrate the maximum moving
  window time weighted average

5 files changed, 167 insertions, 0 deletions

diff --git a/man/max_twa.Rd b/man/max_twa.Rd
new file mode 100644
index 0000000..13e7bbf
--- /dev/null
+++ b/man/max_twa.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/twa.R
+\name{max_twa}
+\alias{max_twa}
+\title{The maximum time weighted average concentration for a moving window}
+\usage{
+max_twa(x, window = 21)
+}
+\arguments{
+\item{x}{An object of type \code{\link{one_box}}}
+
+\item{window}{The size of the moving window}
+}
+\description{
+The maximum time weighted average concentration for a moving window
+}
+\seealso{
+twa
+}
diff --git a/man/one_box.Rd b/man/one_box.Rd
new file mode 100644
index 0000000..86440ce
--- /dev/null
+++ b/man/one_box.Rd
@@ -0,0 +1,45 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/twa.R
+\name{one_box}
+\alias{one_box}
+\alias{one_box.numeric}
+\alias{one_box.mkinfit}
+\title{Create a time series of decline data}
+\usage{
+one_box(x, t_end = 100, res = 0.01, ...)
+
+\method{one_box}{numeric}(x, t_end = 100, res = 0.01, ...)
+
+\method{one_box}{mkinfit}(x, t_end = 100, res = 0.01, ...)
+}
+\arguments{
+\item{x}{When numeric, this is the half-life to be used for an exponential
+decline. If x is an mkinfit object, the decline is calculated from this object}
+
+\item{t_end}{End of the time series}
+
+\item{res}{Resolution of the time series}
+
+\item{...}{Further arguments passed to methods}
+}
+\description{
+The time series starts with the amount specified for the first application.
+This does not create objects of type \code{\link{ts}}.
+}
+\examples{
+# Only use a half-life
+pred_0 <- one_box(10)
+plot(pred_0)
+
+# Use a fitted mkinfit model
+require(mkin)
+fit <- mkinfit("FOMC", FOCUS_2006_C)
+pred_1 <- one_box(fit)
+plot(pred_1)
+
+# Use a model with more than one observed variable
+m_2 <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"))
+fit_2 <- mkinfit(m_2, FOCUS_2006_D)
+pred_2 <- one_box(fit_2)
+plot(pred_2)
+}
diff --git a/man/plot.one_box.Rd b/man/plot.one_box.Rd
new file mode 100644
index 0000000..7d30bd2
--- /dev/null
+++ b/man/plot.one_box.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/twa.R
+\name{plot.one_box}
+\alias{plot.one_box}
+\title{Plot time series of decline data}
+\usage{
+\method{plot}{one_box}(x, xlim = range(time(x)), ylim = c(0, max(x)),
+  xlab = "Time", ylab = "Fraction of initial", max_twa = NULL,
+  max_twa_var = dimnames(x)[[2]][1], ...)
+}
+\arguments{
+\item{x}{The object of type \code{\link{one_box}} to be plotted}
+
+\item{xlim}{Limits for the x axis}
+
+\item{ylim}{Limits for the y axis}
+
+\item{xlab}{Label for the x axis}
+
+\item{ylab}{Label for the y axis}
+
+\item{max_twa}{If a numeric value is given, the maximum time weighted
+average concentration(s) is/are shown in the graph.}
+
+\item{max_twa_var}{Variable for which the maximum time weighted average should
+be shown if max_twa is not NULL.}
+
+\item{...}{Further arguments passed to methods}
+}
+\description{
+Plot time series of decline data
+}
+\examples{
+plot(sawtooth(one_box(10), 3, 7), max_twa = 21)
+}
diff --git a/man/sawtooth.Rd b/man/sawtooth.Rd
new file mode 100644
index 0000000..4576c8b
--- /dev/null
+++ b/man/sawtooth.Rd
@@ -0,0 +1,39 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/twa.R
+\name{sawtooth}
+\alias{sawtooth}
+\title{Create decline time series for multiple applications}
+\usage{
+sawtooth(x, n = 1, i = 365, applications = data.frame(time = seq(0, 0 + n
+  * i, length.out = n), amount = 1))
+}
+\arguments{
+\item{x}{A \code{\link{one_box}} object}
+
+\item{n}{The number of applications. If \code{applications} is specified, \code{n} is not used}
+
+\item{i}{The interval between applications. If \code{applications} is specified, \code{i} 
+is not used}
+
+\item{applications}{A data frame holding the application times in the first column and
+the corresponding amounts applied in the second column for each application cycle.
+If \code{n} is one, the application pattern specified here is used only once.}
+}
+\description{
+If the number of application cycles \code{n} is greater than 1, the
+application pattern specified in \code{applications} is repeated \code{n}
+times, with an interval \code{i}.
+}
+\examples{
+applications = data.frame(time = seq(0, 14, by = 7), amount = c(1, 2, 3))
+pred <- one_box(10)
+plot(sawtooth(pred, applications = applications))
+
+m_2 <- mkinmod(parent = mkinsub("SFO", "m1"), m1 = mkinsub("SFO"))
+fit_2 <- mkinfit(m_2, FOCUS_2006_D)
+pred_2 <- one_box(fit_2)
+pred_2_saw <- sawtooth(pred_2, 2, 7)
+plot(pred_2_saw, max_twa = 21, max_twa_var = "m1")
+
+max_twa(pred_2_saw)
+}
diff --git a/man/twa.Rd b/man/twa.Rd
new file mode 100644
index 0000000..a6afa87
--- /dev/null
+++ b/man/twa.Rd
@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/twa.R
+\name{twa}
+\alias{twa}
+\alias{twa.one_box}
+\title{Calculate a time weighted average concentration}
+\usage{
+twa(x, window = 21)
+
+\method{twa}{one_box}(x, window = 21)
+}
+\arguments{
+\item{x}{An object of type \code{\link{one_box}}}
+
+\item{window}{The size of the moving window}
+}
+\description{
+The moving average is built only using the values in the past, so
+the earliest possible time for the maximum in the time series returned
+is after one window has passed.
+}
+\examples{
+pred <- sawtooth(one_box(10),
+  applications = data.frame(time = c(0, 7), amount = c(1, 1)))
+max_twa(pred)
+}
+\seealso{
+max_twa
+}