\documentclass[12pt]{article}
% \VignetteIndexEntry{Analysis of a GRTS survey design for an area resource}
\author{Thomas Kincaid}
\title{Analysis of a GRTS Survey Design for an Area Resource}
\usepackage[colorlinks=true, urlcolor=blue]{hyperref}
\usepackage{Sweave}
\textwidth=6.5in
\textheight=9.0in
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.5in
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}

\begin{document}
\maketitle
\tableofcontents
\setkeys{Gin}{width=1.0\textwidth}

\section{Preliminaries}

This document presents analysis of a GRTS survey design for an area resource.  The area resource used in the analysis is estuaries in South Carolina.  Although a stratified survey design was used to sample estuaries, analyses will be conducted as if the design was unstratified.  Instead, strata will be used to define subpopulations for analysis.  The strata employed in the survey were: (1) open water and (2) tidal creeks.  The analysis will include calculation of three types of population estimates: (1) estimation of proportion and size (area of estuaries) for site evaluation status categorical variables; (2) estimation of proportion and size for estuary condition categorical variables; and (3) estimation of the cumulative distribution function (CDF) and percentiles for quantitative variables.  Testing for difference between CDFs from subpopulations also will be presented.

The initial step is to use the library function to load the spsurvey package.  After the package is loaded, a message is printed to the R console indicating that the spsurvey package was loaded successfully.

Load the spsurvey package.

<<preliminaries>>=
# Load the spsurvey package
library(spsurvey)

@
\begin{verbatim}
Version 3.3 of the spsurvey package was loaded successfully.
\end{verbatim}

\section{Load the survey design and analytical variables data set}
The next step is to load the data set, which includes both survey design variables and analytical variables.  The data function is used to load the data set and assign it to a data frame named SC\_estuaries.  The nrow function is used to determine the number of rows in the SC\_estuaries data frame, and the resulting value is assigned to an object named nr. Finally, the initial six lines and the final six lines in the SC\_estuaries data frame are printed using the head and tail functions, respectively.

Load the survey design and analytical variables data set

<<data>>=
# Load the data set and determine the number of rows in the data frame
data(SC_estuaries)
nr <- nrow(SC_estuaries)

@
Display the initial six lines in the data file.

<<data>>=
# Display the initial six lines in the data file
head(SC_estuaries)

@
Display the final six lines in the data file.

<<data>>=
# Display the final six lines in the data file
tail(SC_estuaries)

@
The location of sample sites in South Carolina estuaries is displayed in Figure~\ref{fig:SCestuaries}.  The sites for each stratum are displayed using a unique color.

\begin{figure}
\centering
\includegraphics{Area_Analysis_plot}
\caption{Location of estuaries that were sampled in South Carolina by the U.S. Environmental Protection Agency during the National Lakes Assessment (NLA) conducted in 1999 and 2000.}
\label{fig:SCestuaries}
\end{figure}
\newpage

\section{Analysis of site status evaluation variables}

The first analysis that will be examined is calculation of extent estimates for a site status evaluation variable.  Extent is measured both by the proportion of the resource in status evaluation categories and by size of the resource in each category.  For an area resource like estuaries, size refers to the area of estuaries in a category.  For calculating extent estimates (and for all of the analyses we will consider), survey design weights are incorporated into the calculation process.  Weights used in the analyses were modified from the original survey design weights to ensure that the weights sum to the known size of the resource.  Further information regarding weight adjustment is provided in the help page for the adjwgt (weight adjustment) function.  The site status variable named status will be examined, which classifies estuaries into two evaluation categories: "Sampled" and "NonTarget".  The table and addmargins functions are used to create tables displaying the count for each code (level) of the status variable.

\begin{verbatim}
> addmargins(table(SC_estuaries$Status))
\end{verbatim}

<<Statuseval, echo=FALSE>>=
# Use the table and addmargins functions to create a table displaying the count
# for each code of the status variable
cat("\nA table displaying the number of values for each level of the status
variable follows:\n")
addmargins(table(SC_estuaries$Status))

@
The cat.analysis function in the spsurvey package will be used to calculate extent estimates.  Four data frames constitute the primary input to the cat.analysis function.  The first column (variable) in the four data frames provides the unique identifier (site ID) for each sample site and is used to connect records among the data frames.  The siteID variable in the SC\_estuaries data frame is assigned to the siteID variable in the data frames.  The four data frames that will be created are named as follows: sites, subpop, design, and data.cat.  The sites data frame identifies sites to use in the analysis and contains two variables: (1) siteID - site ID values and (2) Use - a logical vector indicating which sites to use in the analysis.  The rep (repeat) function is used to assign the value TRUE to each element of the Use variable.  Recall that nr is an object containing the number of rows in the SC\_estuaries data frame.  The subpop data frame defines populations and, optionally, subpopulations for which estimates are desired.  Unlike the sites and design data frames, the subpop data frame can contain an arbitrary number of columns.  The first variable in the subpop data frame identifies site ID values and each subsequent variable identifies a type of population, where the variable name is used to identify type.  A type variable identifies each site with a character value.  If the number of unique values for a type variable is greater than one, then the set of values represent subpopulations of that type.  When a type variable consists of a single unique value, then the type does not contain subpopulations.  For this analysis, the subpop data frame contains three variables: (1) siteID - site ID values, (2) All\_Estuaries - which will be used to calculate estimates for all of the sample sites combined, and (3) Estuary\_Type - which will be used to calculate estimates for each stratum individually.  The stratum variable in the SC\_estuaries data frame is assigned to the Estuary\_Type variable in the subpop data frame.  The design data frame consists of survey design variables.  For the analysis under consideration, the design data frame contains the following variables: (1) siteID - site ID values; (2) wgt - final, adjusted, survey design weights; (3) xcoord - x-coordinates for location; and (4) ycoord - y-coordinates for location.  The wgt, xcoord, and ycoord variables in the design data frame are assigned values using variables with the same names in the SC\_estuaries data frame.  Like the subpop data frame, the data.cat data frame can contain an arbitrary number of columns.  The first variable in the data.cat data frame identifies site ID values and each subsequent variable identifies a response variable. The response variable is Status, which is assigned the status variable in the SC\_estuaries data frame. Missing data (NA) is allowed for the response variables, which are the only variables in the input data frames for which NA values are allowed.

Create the sites data frame.
\begin{verbatim}
> sites <- data.frame(siteID=SC_estuaries$siteID,
+                     Use=rep(TRUE, nr))
\end{verbatim}

<<Statuseval, echo=FALSE>>=
#
# Conduct an analysis of site status evaluation variables
#

# Create the sites data frame, which identifies sites to use in the analysis
# Note that all sites will be used to estimate number of estuaries in each category
sites <- data.frame(siteID=SC_estuaries$siteID,
                    Use=rep(TRUE, nr))

@
Create the subpop data frame.
\begin{verbatim}
> subpop <- data.frame(siteID=SC_estuaries$siteID,
+                      All_Estuaries=rep("All Estuaries", nr),
+                      Estuary_Type=SC_estuaries$Stratum)
\end{verbatim}

<<Statuseval, echo=FALSE>>=
# Create the subpop data frame, which defines populations and subpopulations for
# which estimates are desired
subpop <- data.frame(siteID=SC_estuaries$siteID,
                     All_Estuaries=rep("All Estuaries", nr), 
							       Estuary_Type=SC_estuaries$Stratum)

@
Create the design data frame.
\begin{verbatim}
> design <- data.frame(siteID=SC_estuaries$siteID,
+                      wgt=SC_estuaries$wgt,
+                      xcoord=SC_estuaries$xcoord,
+                      ycoord=SC_estuaries$ycoord)
\end{verbatim}

<<Statuseval, echo=FALSE>>=
# Create the design data frame, which identifies the stratum code, weight,
#    x-coordinate, and y-coordinate for each site ID
design <- data.frame(siteID=SC_estuaries$siteID,
                     wgt=SC_estuaries$wgt,
                     xcoord=SC_estuaries$xcoord,
                     ycoord=SC_estuaries$ycoord)

@
Create the data.cat data frame.
\begin{verbatim}
> data.cat <- data.frame(siteID=SC_estuaries$siteID,
+                        Status=SC_estuaries$Status)
\end{verbatim}

<<Statuseval, echo=FALSE>>=
# Create the data.cat data frame, which specifies the variables to use in the
# analysis
data.cat <- data.frame(siteID=SC_estuaries$siteID,
                       Status=SC_estuaries$Status)

@
Use the cat.analysis function to calculate extent estimates for the site status evaluation variables.

<<Statuseval>>=
# Calculate extent estimates for the site status evaluation variables
Extent_Estimates <- cat.analysis(sites, subpop, design, data.cat)

@
The extent estimates are displayed using the print function.  The object produced by cat.analysis is a data frame containing thirteen columns.  The first five columns identify the population (Type), subpopulation (Subpopulation), response variable (Indicator), levels of the response variable (Category), and number of values in a category (NResp).  A category labeled "Total" is included for each combination of population, subpopulation, and response variable.  The next four columns in the data frame provide results for the proportion estimates: the proportion estimate (Estimate.P), standard error of the estimate (StdError.P), lower confidence bound (LCB95Pct.P), and upper confidence bound (UCB95Pct.P).  Argument conf for cat.analysis allows control of the confidence bound level.  The default value for conf is 95, hence the column names for confidence bounds contain the value 95.  Supplying a different value to the conf argument will be reflected in the confidence bound names.  Confidence bounds are obtained using the standard error and the Normal distribution multiplier corresponding to the confidence level.  The final four columns in the data frame provide results for the size (units) estimates: the units estimate (Estimate.U), standard error of the estimate (StdError.U), lower confidence bound (LCB95Pct.U), and upper confidence bound (UCB95Pct.U).  Note that the size estimate for the Total category will be equal to the sum of the survey design weights.

<<Statuseval>>=
# Print the extent estimates
print(Extent_Estimates)

@
The write.csv function is used to store the extent estimates as a comma-separated value (csv) file.  Files in csv format can be read by programs such as Microsoft Excel.
\begin{verbatim}
> write.csv(Extent_Estimates, file="Extent_Estimates.csv")
\end{verbatim}

<<Statuseval, echo=FALSE>>=
# Write results as a comma-separated value (csv) file
write.csv(Extent_Estimates, file="Extent_Estimates.csv")

@
\section{Analysis of estuary condition variables}

The second analysis that will be examined is estimating resource proportion and size for estuary condition variables.  Two estuary condition variables will be examined: (1) IBI\_Status, which classifies estuaries by benthic IBI (index of biotic integrity) status categories and (2) WQ\_Status, which classifies estuaries by WQ (water quality) status categories.  The table and addmargins functions are used to create tables displaying the count for each level of the two estuary condition variables.

\begin{verbatim}
> addmargins(table(SC_estuaries$IBI_status))
\end{verbatim}

<<Conditioneval, echo=FALSE>>=
# Use the table and addmargins functions to create a table displaying the count
# for each code of the IBI status variable
cat("\nA table displaying the number of values for each level of the IBI status
variable follows:\n")
addmargins(table(SC_estuaries$IBI_status))

@
\begin{verbatim}
> addmargins(table(SC_estuaries$WQ_status))
\end{verbatim}

<<Conditioneval, echo=FALSE>>=
# Use the table and addmargins functions to create a table displaying the count
# for each code of the WQ status variable
cat("\nA table displaying the number of values for each level of the WQ status variable follows:\n")
addmargins(table(SC_estuaries$WQ_status))

@
As for extent estimates, the cat.analysis function will be used to calculate condition estimates.  The sites data frame for this analysis differs from the one used to calculate extent estimates.  The Use logical variables in sites is set equal to the value "Sampled", so that only sampled sites are used in the analysis. The subpop and design data frames created in the prior analysis can be reused for this analysis.  The data.cat data frame contains the two estuary condition variables: IBI\_Status and WQ\_Status.  Variables IBI\_status and WQ\_status in the SC\_estuaries data frame are assigned to IBI\_Status and WQ\_Status, respectively.
  
Create the sites data frame.

\begin{verbatim}
> sites <- data.frame(siteID=SC_estuaries$siteID,
+                     Use=SC_estuaries$Status == "Sampled")
\end{verbatim}

<<Conditioneval, echo=FALSE>>=
#
# Conduct an analysis of estuary condition variables
#

# Create the sites data frame
# Note that only sampled sites are used
sites <- data.frame(siteID=SC_estuaries$siteID,
                    Use=SC_estuaries$Status == "Sampled")

# Note that the existing subpop and design data frames can be reused

@
Create the data.cat data frame.
\begin{verbatim}
> data.cat <- data.frame(siteID=SC_estuaries$siteID,
+                        IBI_Status=SC_estuaries$IBI_status,
+                        WQ_Status=SC_estuaries$WQ_status)
\end{verbatim}

<<Conditioneval, echo=FALSE>>=
# Create the data.cat data frame, which specifies the variables to use in the
# analysis
data.cat <- data.frame(siteID=SC_estuaries$siteID,
                       IBI_Status=SC_estuaries$IBI_status,
                       WQ_Status=SC_estuaries$WQ_status)

@
Use the cat.analysis function to calculate estimates for the estuary condition variables.

<<Conditioneval>>=
# Calculate estimates for the categorical variables
Condition_Estimates <- cat.analysis(sites, subpop, design, data.cat)

@
Print the estuary condition estimates for all sites combined.

<<Conditioneval>>=
# Print the condition estimates for all basins combined
print(Condition_Estimates[c(1:4, 13:16),])

@
Use the write.csv function to write the condition estimates as a csv file.
\begin{verbatim}
> write.csv(Condition_Estimates, file="Condition_Estimates.csv")
\end{verbatim}

<<Conditioneval, echo=FALSE>>=
# Write results as a csv file
write.csv(Condition_Estimates, file="Condition_Estimates.csv")

@
\section{Analysis of estuary condition variables correcting for population size}

The frame is a data structure containing spatial location data in addition to other attributes regarding a resource of interest and is used to create a survey design.  A frame often takes the form of a shapefile.  The frame can be used to obtain size values (e.g., area of estuaries) for the populations and subpopulations examined in an analysis.  Examination of the Estimates.U column in the Condition\_Estimates data frame produced by cat.analysis reveals that the estimated Total value for both condition variables and each combination of population value and subpopulation value does not sum to the corresponding frame size value.  For example, the Total entry in the Estimate.U column for the IBI\_status variable, population "All\_Estuaries" and subpopulation "All Estuaries" is 698 square kilometers (rounded to a whole number).  This value is an estimate of the size of the sampled resource.  The corresponding frame size value is 734 square kilometers.  The popsize (population size) argument to cat.analysis provides a mechanism for forcing the size estimates to sum to a desired value, e.g., the frame size value.  Note that including popsize as an argument results in assigning the popsize value to the Total category of the size estimates.  Use of the popsize argument assumes that sites which were evaluated but not sampled were missing at random.  The missing at random asumption may not be a valid assumption, e.g., sites for which access was denied by the landowner may not be the same as sites that were sampled.  For the current analysis, we will assume that the assumption is valid.  As a first step for use of the popsize argument, the c (combine) function is used to create a named vector of frame size values for each basin. Output from the c function is assigned to an object named framesize.  The popsize argument is a list, which is a particular type of R object.  The popsize list must include an entry for each population type included in the subpop data frame, i.e., All\_Estuaries and Estuary\_Type for this analysis.  The sum function applied to framesize is assigned to the All\_Estuaries entry in the popsize list.  Recall that the Estuary\_Type population contains subpopulations, i.e., stratum categories.  When a population type contains subpopulations, the entry in the popsize list also is a list.  The as.list function is applied to framesize, and the result is assigned to the Estuary\_Type entry in the popsize list.

Assign frame size values.
\begin{verbatim}
> framesize <- c("Open Water"=628.509298, "Tidal Creek"=105.829522)

\end{verbatim}

<<Conditionevalpop, echo=FALSE>>=
#
# Conduct an analysis of estuary condition variables correcting for population
# size
#

# Note that the existing sites, subpop, design, and data.cont data frames can be
# reused

# Assign frame size values
framesize <- c("Open Water"=628.509298, "Tidal Creek"=105.829522)

@
Use the cat.analysis function to calculate estimates for the estuary condition variables.
\begin{verbatim}
> Condition_Estimates_popsize <- cat.analysis(sites, subpop, design, data.cat,
+   popsize=list(All_Estuaries=sum(framesize),
+                Estuary_Type=as.list(framesize)))
\end{verbatim}

<<Conditionevalpop, echo=FALSE>>=
# Calculate estimates for the estuary condition variables
Condition_Estimates_popsize <- cat.analysis(sites, subpop, design, data.cat,
   popsize=list(All_Estuaries=sum(framesize),
                Estuary_Type=as.list(framesize)))

@
Print the estuary condition estimates for all sites combined.

<<Conditionevalpop>>=
# Print the estuary condition estimates for all sites combined
print(Condition_Estimates_popsize[c(1:4, 13:16),])

@
Use the write.csv function to write the condition estimates as a csv file.
\begin{verbatim}
> write.csv(Condition_Estimates_popsize, file="Condition_Estimates_popsize.csv")
\end{verbatim}

<<Conditionevalpop, echo=FALSE>>=
# Write results as a csv file
write.csv(Condition_Estimates_popsize, file="Condition_Estimates_popsize.csv")

@
\section{Analysis of quantitative variables}

The third analysis that will be examined is estimating the CDF and percentiles for quantitative variables.  Two quantitative variables will be examined: (1) IBI\_score - IBI score and (2) WQ\_score - WQ score.  The summary function is used to summarize the data structure of the two quantitative variables.

\begin{verbatim}
> summary(SC_estuaries$IBI_score)
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Use the summary function to summarize the data structure of the IBI score
# variable
cat("\nSummarize the data structure of the IBI score variable:\n")
summary(SC_estuaries$IBI_score)

@
\begin{verbatim}
> summary(SC_estuaries$WQ_score)
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Use the summary function to summarize the data structure of the WQ score
# variable
cat("\nSummarize the data structure of the WQ score variable:\n")
summary(SC_estuaries$WQ_score)

@
The cont.analysis function will be used to calculate estimates for quantitative variables.  Input to the cont.analysis function is the same as input for the cat.analysis function except that the data frame containing response variables is named cont.data rather than cat.data.  The sites, subpop, and design data frames created in the analysis of estuary condition variables can be reused for this analysis.  The data.cont data frame contains the two quantitative variables: IBI\_Score and WQ\_Score, which contain the numeric scores for the IBI and WQ variables, respectively.  Variables IBI\_score and WQ\_score in the SC\_estuaries data frame are assigned to IBI\_Score and WQ\_Score, respectively.  The popsize argument is included in the call to cont.analysis.
  
Create the data.cont data frame.
\begin{verbatim}
> data.cont <- data.frame(siteID=SC_estuaries$siteID,
+                         IBI_Score=SC_estuaries$IBI_score,
+                         WQ_Score=SC_estuaries$WQ_score)
\end{verbatim}

<<Quanteval, echo=FALSE>>=
#
# Conduct an analysis of quantitative variables
#

# Note that the existing sites, subpop, and design data frames can be reused

# Create the data.cont data frame, which specifies the variables to use in the
# analysis
data.cont <- data.frame(siteID=SC_estuaries$siteID,
                        IBI_Score=SC_estuaries$IBI_score,
                        WQ_Score=SC_estuaries$WQ_score)

@
Use the cont.analysis function to calculate CDF and percentile estimates for the quantitative variables.

\begin{verbatim}
> CDF_Estimates <- cont.analysis(sites, subpop, design, data.cont,
+   popsize=list(All_Estuaries=sum(framesize),
+                Estuary_Type=as.list(framesize)))
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Calculate CDF estimates for the quantitative variables
CDF_Estimates <- cont.analysis(sites, subpop, design, data.cont,
   popsize=list(All_Estuaries=sum(framesize),
                Estuary_Type=as.list(framesize)))

@
The object produced by cont.analysis is a list containing two objects: (1) CDF, a data frame containing the CDF estimates and (2) Pct, a data frame containing percentile estimates plus estimates of population values for mean, variance, and standard deviation.  Format for the CDF data frame is analogous to the data frame produced by cat.analysis.  For the CDF data frame, however, the fourth column is labeled Value and contains the value at which the CDF was evaluated.  Unlike the data frames produced by the other analysis functions we have examined, the Pct data frame contains only nine columns since there is a single set of estimates rather than two sets of estimates.  In addition, the fourth column is labeled Statistic and identifies either a percentile or the mean, variance, or standard deviation.  Finally, since percentile estimates are obtained by inverting the CDF estimate, the percentile estimates do not have a standard error value associated with them.

Use the write.csv function to write the CDF estimates as a csv file.

\begin{verbatim}
> write.csv(CDF_Estimates$CDF, file="CDF_Estimates.csv")
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Write CDF estimates as a csv file
write.csv(CDF_Estimates$CDF, file="CDF_Estimates.csv")

@
The cont.cdfplot function in spsurvey can be used to produce a PDF file containing plots of the CDF estimates.  The primary arguments to cont.cdfplot are a character string containing a name for the PDF file and the CDF data frame in the CDF\_Estimates object.

Produce a PDF file containing plots of the CDF estimates.

<<Quanteval>>=
cont.cdfplot("CDF_Estimates.pdf", CDF_Estimates$CDF)

@
Print the percentile estimates for IBI score for all sites combined.

<<Quanteval>>=
# Print the percentile estimates for IBI score for all sites combined
print(CDF_Estimates$Pct[1:10,])

@
Use the write.csv function to write the percentile estimates as a csv file.

\begin{verbatim}
> write.csv(CDF_Estimates$Pct, file="Percentile_Estimates.csv")
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Write percentile estimates as a csv file
write.csv(CDF_Estimates$Pct, file="Percentile_Estimates.csv", row.names=FALSE)

@
The cont.cdftest function in spsurvey can be used to test for statistical difference between the CDFs from subpopulations.  For this analysis we will use the cont.cdftest function to test for statistical difference between the CDFs from the two strata.  Arguments to cont.cdftest are the same as arguments to cont.analysis. Since we are interested only in testing among strata, the subpop data frame is subsetted to include only the siteID and Estuary\_Type variables.  Note that the popsize argument was modified from prior examples to include only the entry for Estuary\_Type.

\begin{verbatim}
> CDF_Tests <- cont.cdftest(sites, subpop[,c(1,3)], design, data.cont,
+    popsize=list(Estuary_Type=as.list(framesize)))
\end{verbatim}

<<Quanteval, echo=FALSE>>=
# Test for statistical difference between CDFs for strata
CDF_Tests <- cont.cdftest(sites, subpop[,c(1,3)], design, data.cont,
   popsize=list(Estuary_Type=as.list(framesize)))

@
The print function is used to display results for IBI score of the statistical tests for difference between CDFs for strata.  The object produced by cont.cdftest is a data frame containing eight columns. The first column (Type) identifies the population.  The second and third columns (Subpopulation\_1 and Subpopulation\_2) identify the subpopulations.  The fourth column (Indicator) identifies the response variable.  Column five contains values of the test statistic.  Six test statistics are available, and the default statistic is an F-distribution version of the Wald statistic, which is identified in the data frame as "Wald-F".  The default statistic is used in this analysis.  For further information about the test statistics see the help file for the cdf.test function in spsurvey, which includes a reference for the test for differences in CDFs.  Columns six and seven (Degrees\_of\_Freedom\_1 and Degrees\_of\_Freedom\_2) provide the numerator and denominator degrees of freedom for the Wald test.  The final column (p\_Value) provides the p-value for the test.

<<Quanteval>>=
# Print results of the statistical tests for difference between strata CDFs for
# IBI score and WQ score
print(CDF_Tests, digits=3)

@
Use the write.csv function to write CDF test results as a csv file.

<<Quanteval>>=
# Write CDF test results as a csv file
write.csv(CDF_Tests, file="CDF_Tests.csv", row.names=FALSE)

@
\end{document}
