From fd82f17fb65a0abe86970e92e2468ef10ec7209d Mon Sep 17 00:00:00 2001
From: Walmes Zeviani <walmeszeviani@gmail.com>
Date: Sun, 13 Sep 2015 23:04:08 -0300
Subject: [PATCH] Documents the defoliation dataset.

---
 R/legTools.R       | 124 +++++++++++++++++++++++++++++++++++++--------
 man/defoliation.Rd |  83 ++++++++++++++++++++++++++++++
 2 files changed, 187 insertions(+), 20 deletions(-)
 create mode 100644 man/defoliation.Rd

diff --git a/R/legTools.R b/R/legTools.R
index bd4334f..9cbf85e 100644
--- a/R/legTools.R
+++ b/R/legTools.R
@@ -12,11 +12,12 @@ NULL
 #' @title Feeding type in pig weight gain
 #'
 #' @description This is an artifial dataset corresponding a experiment
-#' to study the effect of feeding type (factor with 4 categorical
-#' nominal levels) in pig weight gain. The experiment was a randomized
-#' complete design with five experimental units per treatment level. The
-#' experimental unit was a pig. The response measured was weight gain
-#' from the beggining to the end of the experiment.
+#'     to study the effect of feeding type (factor with 4 categorical
+#'     nominal levels) in pig weight gain. The experiment was a
+#'     randomized complete design with five experimental units per
+#'     treatment level. The experimental unit was a pig. The response
+#'     measured was weight gain from the beggining to the end of the
+#'     experiment.
 #'
 #' \itemize{
 #'     \item \code{ft} feeding type, a categorical factor with 4
@@ -32,8 +33,8 @@ NULL
 #'
 #' @format a \code{data.frame} with 20 records and 2 variables.
 #'
-#' @source Frederico, P. (2009). Curso de Estatística Experimental
-#' (15th ed.). Piracicaba, São Paulo: FEALQ. (page 62)
+#' @source Frederico, P. (2009). Curso de Estatística Experimental (15th
+#'     ed.). Piracicaba, São Paulo: FEALQ. (page 62)
 #'
 #' @examples
 #'
@@ -51,9 +52,9 @@ NULL
 #' @title Potato variety competition experiment
 #'
 #' @description These data are from an experiment done by the engineer
-#' Oscar A. Garay at Balcare, Argentina. The experiment was done in a
-#' randomized complete block design with 4 blocks. Potato yield (t/ha)
-#' was recorded in each experimental unit.
+#'     Oscar A. Garay at Balcare, Argentina. The experiment was done in
+#'     a randomized complete block design with 4 blocks. Potato yield
+#'     (t/ha) was recorded in each experimental unit.
 #'
 #' \itemize{
 #'     \item \code{block} a categorical unordered factor with 4 levels.
@@ -70,8 +71,8 @@ NULL
 #'
 #' @format a \code{data.frame} with 32 records and 3 variables.
 #'
-#' @source Frederico, P. (2009). Curso de Estatística Experimental
-#' (15th ed.). Piracicaba, São Paulo: FEALQ. (page 76)
+#' @source Frederico, P. (2009). Curso de Estatística Experimental (15th
+#'     ed.). Piracicaba, São Paulo: FEALQ. (page 76)
 #'
 #' @examples
 #' require(lattice)
@@ -89,12 +90,12 @@ NULL
 #' @title Plowing level on corn yield
 #'
 #' @description These data are from an experiment done by the engineer
-#' Duvilio Ometto to study the effect of plowing level on corn yield. It
-#' was used 2 levels of plowing: normal (or superficial) and deep. The
-#' experiment was done in a randomized complete block design with 6
-#' blocks. Corn yield (t/ha) was recorded in each experimental unit
-#' but in this experiment there was 2 experimental units for each factor
-#' level in each block.
+#'     Duvilio Ometto to study the effect of plowing level on corn
+#'     yield. It was used 2 levels of plowing: normal (or superficial)
+#'     and deep. The experiment was done in a randomized complete block
+#'     design with 6 blocks. Corn yield (t/ha) was recorded in each
+#'     experimental unit but in this experiment there was 2 experimental
+#'     units for each factor level in each block.
 #'
 #' \itemize{
 #'     \item \code{block} a categorical unordered factor with 6 levels.
@@ -110,8 +111,8 @@ NULL
 #'
 #' @format a \code{data.frame} with 24 records and 3 variables.
 #'
-#' @source Frederico, P. (2009). Curso de Estatística Experimental
-#' (15th ed.). Piracicaba, São Paulo: FEALQ. (page 91)
+#' @source Frederico, P. (2009). Curso de Estatística Experimental (15th
+#'     ed.). Piracicaba, São Paulo: FEALQ. (page 91)
 #'
 #' @examples
 #' require(lattice)
@@ -122,3 +123,86 @@ NULL
 #'        xlab="Plowing level")
 #'
 NULL
+
+#' @name defoliation
+#'
+#' @title Bolls in cotton as function of artifitial defoliation
+#'
+#' @description This dataset contais the result of a real experiment to
+#'     evaluate the effect of artifitial defoliation in combination with
+#'     phenological stage of occurence on the production of cotton
+#'     represented by the number of bolls produced at the end of the
+#'     crop cycle. The experiment is a \eqn{5\times 5} factorial with 5
+#'     replications casualized at random to the experimental units (a
+#'     randomized complete design). The experimental unit was a pot with
+#'     2 plants. An interesting fact about this data is that the
+#'     response is a count variable that shows underdispersion (sample
+#'     variance less than the sample mean).
+#'
+#' \itemize{
+#' \item \code{phenol} a categorical ordered factor with 5 levels
+#'     that represent the phenological stages of the cotton plant in
+#'     which defoliation was applied.
+#' \item \code{defol} a numeric factor with 5 levels that represents the
+#'     artifical level of defoliation (percent in leaf area removed with
+#'     scissors) applied for all leaves in the plant.
+#' \item \code{rept} index for each experimenal unit in each treatment cell.
+#' \item \code{bolls} the number of bolls produced (count variable)
+#'     evaluated at harvest.
+#' }
+#'
+#' @details The experiment was done in a greenhouse at Universidade
+#'     Federal da Grande Dourados. Visit
+#' \itemize{
+#' \item 1) \code{http://www.cabdirect.org/abstracts/20123299470.html}
+#' \item 2) \code{http://leg.ufpr.br/doku.php/publications:papercompanions:zeviani-jas2014}
+#' }
+#' 1 for an article discussing the effect of defoliation on cotton yield and
+#'     visit 2 for an article that evaluate a count regression model able to
+#'     deal with the underdispersion. See the references section also.
+#'
+#' @docType data
+#'
+#' @keywords datasets
+#'
+#' @usage data(defoliation)
+#'
+#' @format a \code{data.frame} with 125 records and 4 variables.
+#'
+#' @references Silva, A. M., Degrande, P. E., Suekane, R., Fernandes,
+#'     M. G., & Zeviani, W. M. (2012). Impacto de diferentes níveis de
+#'     desfolha artificial nos estádios fenológicos do
+#'     algodoeiro. Revista de Ciências Agrárias, 35(1), 163–172.
+#'
+#' Zeviani, W. M., Ribeiro, P. J., Bonat, W. H., Shimakura, S. E., &
+#'     Muniz, J. A. (2014). The Gamma-count distribution in the analysis
+#'     of experimental underdispersed data. Journal of Applied
+#'     Statistics, 41(12),
+#'     1–11. http://doi.org/10.1080/02664763.2014.922168
+#'
+#' @examples
+#'
+#' library(lattice)
+#' library(latticeExtra)
+#'
+#' ## x11(width=7, height=2.8)
+#' xyplot(bolls~defol|phenol, data=defoliation,
+#'        layout=c(NA, 1), type=c("p", "smooth"),
+#'        xlab="Artificial defoliation level",
+#'        ylab="Number of bolls produced",
+#'        xlim=extendrange(c(0:1), f=0.15), jitter.x=TRUE)
+#'
+#' ## Sample mean and variance in each treatment cell.
+#' mv <- aggregate(bolls~phenol+defol, data=defoliation,
+#'                 FUN=function(x) c(mean=mean(x), var=var(x)))
+#' str(mv)
+#'
+#' xlim <- ylim <- extendrange(c(mv$bolls), f=0.05)
+#'
+#' ## Evidence in favor of the underdispersion.
+#' xyplot(bolls[,"var"]~bolls[,"mean"], data=mv,
+#'        aspect="iso", xlim=xlim, ylim=ylim,
+#'        ylab="Sample variance", xlab="Sample mean")+
+#'     layer(panel.abline(a=0, b=1, lty=2))
+#'
+NULL
diff --git a/man/defoliation.Rd b/man/defoliation.Rd
new file mode 100644
index 0000000..d6ea686
--- /dev/null
+++ b/man/defoliation.Rd
@@ -0,0 +1,83 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/legTools.R
+\docType{data}
+\name{defoliation}
+\alias{defoliation}
+\title{Bolls in cotton as function of artifitial defoliation}
+\format{a \code{data.frame} with 125 records and 4 variables.}
+\usage{
+data(defoliation)
+}
+\description{
+This dataset contais the result of a real experiment to
+    evaluate the effect of artifitial defoliation in combination with
+    phenological stage of occurence on the production of cotton
+    represented by the number of bolls produced at the end of the
+    crop cycle. The experiment is a \eqn{5\times 5} factorial with 5
+    replications casualized at random to the experimental units (a
+    randomized complete design). The experimental unit was a pot with
+    2 plants. An interesting fact about this data is that the
+    response is a count variable that shows underdispersion (sample
+    variance less than the sample mean).
+
+\itemize{
+\item \code{phenol} a categorical ordered factor with 5 levels
+    that represent the phenological stages of the cotton plant in
+    which defoliation was applied.
+\item \code{defol} a numeric factor with 5 levels that represents the
+    artifical level of defoliation (percent in leaf area removed with
+    scissors) applied for all leaves in the plant.
+\item \code{rept} index for each experimenal unit in each treatment cell.
+\item \code{bolls} the number of bolls produced (count variable)
+    evaluated at harvest.
+}
+}
+\details{
+The experiment was done in a greenhouse at Universidade
+    Federal da Grande Dourados. Visit
+\itemize{
+\item 1) \code{http://www.cabdirect.org/abstracts/20123299470.html}
+\item 2) \code{http://leg.ufpr.br/doku.php/publications:papercompanions:zeviani-jas2014}
+}
+1 for an article discussing the effect of defoliation on cotton yield and
+    visit 2 for an article that evaluate a count regression model able to
+    deal with the underdispersion. See the references section also.
+}
+\examples{
+library(lattice)
+library(latticeExtra)
+
+## x11(width=7, height=2.8)
+xyplot(bolls~defol|phenol, data=defoliation,
+       layout=c(NA, 1), type=c("p", "smooth"),
+       xlab="Artificial defoliation level",
+       ylab="Number of bolls produced",
+       xlim=extendrange(c(0:1), f=0.15), jitter.x=TRUE)
+
+## Sample mean and variance in each treatment cell.
+mv <- aggregate(bolls~phenol+defol, data=defoliation,
+                FUN=function(x) c(mean=mean(x), var=var(x)))
+str(mv)
+
+xlim <- ylim <- extendrange(c(mv$bolls), f=0.05)
+
+## Evidence in favor of the underdispersion.
+xyplot(bolls[,"var"]~bolls[,"mean"], data=mv,
+       aspect="iso", xlim=xlim, ylim=ylim,
+       ylab="Sample variance", xlab="Sample mean")+
+    layer(panel.abline(a=0, b=1, lty=2))
+}
+\references{
+Silva, A. M., Degrande, P. E., Suekane, R., Fernandes,
+    M. G., & Zeviani, W. M. (2012). Impacto de diferentes níveis de
+    desfolha artificial nos estádios fenológicos do
+    algodoeiro. Revista de Ciências Agrárias, 35(1), 163–172.
+
+Zeviani, W. M., Ribeiro, P. J., Bonat, W. H., Shimakura, S. E., &
+    Muniz, J. A. (2014). The Gamma-count distribution in the analysis
+    of experimental underdispersed data. Journal of Applied
+    Statistics, 41(12),
+    1–11. http://doi.org/10.1080/02664763.2014.922168
+}
+\keyword{datasets}
+
-- 
GitLab