\documentclass[a4paper]{article}

%\VignetteIndexEntry{Introduction to surveydata package}
%\VignettePackage{surveydata}

% Definitions
%\newcommand{\slan}{{\tt S}}
%\newcommand{\rlan}{{\tt R}}
\newcommand{\sdata}{{\tt surveydata}}
\newcommand{\code}[1]{{\tt #1}}
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
\setlength{\oddsidemargin}{10mm}

\title{Introduction to the \sdata{} package for working with survey data.}
\author{Andrie de Vries}

\begin{document}
\SweaveOpts{concordance=TRUE}

\maketitle

\sdata{} is a package that makes it easy to work with typical survey data that originated in SPSS or other formats.

A surveydata object consists of:

\begin{itemize}

  \item{A data frame with a row for each respondent and a column for each question.   Column names are typically names in the pattern Q1, Q2\_1, Q2\_2, Q3 - where underscores separate the subquestions when these originated in a grid (array) of questions.}

  \item{Question metadata gets stored in the \texttt{variable.labels} attribute of the data frame. This typically contains the original questionnaire text for each question.}
  
  \item{Information about the subquestion separator (typically an underscore) is stored in the \texttt{patterns} attribute.}
  
\end{itemize}


Data processing a survey file can be tricky, since the standard methods for dealing with data frames does not conserve the \texttt{variable.labels} attribute.  The \sdata{} package defines a \texttt{surveydata} class and the following methods that knows how to deal with the \texttt{variable.labels} attribute:

\begin{itemize}
  \item {\texttt{as.surveydata}}
  \item {\texttt{[.surveydata}}
  \item {\texttt{[<-.surveydata}}
  \item {\texttt{\$.surveydata}}
  \item {\texttt{\$<-.surveydata}}
  \item {\texttt{merge.surveydata}}
\end{itemize}

In addition, \sdata{} defines the following convenient methods for extracting and working with the variable labels:

\itemize{
  \item {varlabels}
  \item{varlabels<-}
}

\section{Defining a surveydata object}

First load the \sdata{} package.

<<Setup>>=
library(surveydata)
@

Next, create sample data. A data frame is the ideal data structure for survey data, and the convention is that data for each respondent is stored in the rows, while each column represents answers to a specific question.

<<sample-data>>=

sdat <- data.frame(
    id   = 1:4,
    Q1   = c("Yes", "No", "Yes", "Yes"),
    Q4_1 = c(1, 2, 1, 2), 
    Q4_2 = c(3, 4, 4, 3), 
    Q4_3 = c(5, 5, 6, 6), 
    Q10 = factor(c("Male", "Female", "Female", "Male")),
    crossbreak  = c("A", "A", "B", "B"), 
    weight      = c(0.9, 1.1, 0.8, 1.2)
)

@


The survey metadata consists of the questionnaire text.  For example, this can be represented by a character vector, with an element for each question.

To assign this metadata to the survey data, use the \texttt{varlabels} function.  This function assigns the questionnaire text to the \texttt{variable.labels} attribute of the data frame.

<<varlabels>>=

varlabels(sdat) <- c(
    "RespID",
    "Question 1", 
    "Question 4: red", "Question 4: green", "Question 4: blue", 
    "Question 10",
    "crossbreak",
    "weight"
  )
@


Finally, create the surveydata object. To do this, call the \texttt{as.surveydata} function.  The argument \texttt{renameVarlabels} controls whether the \texttt{varlabels} get renamed with the same names as the data.  This is an essential step, and ensures that the question text remains in synch with the column names.

<<init>>=
sv <- as.surveydata(sdat, renameVarlabels=TRUE)
@


\section{Extracting specific questions}

It is easy to extract specific questions with the \texttt{[} operator. This works very similar to extraction of data frames. However, there are two iiomportant differences:

\begin{itemize}
\item{The extraction operators will always return a \sdata{} object, even if only a single column is returned. This is different from the behaviour of data frames, where a single column is simplified to a vector.}
\item{Extracing a question with multiple subquestions, e.g. "Q4" returns multiple columns.}
\end{itemize}


<<extract>>=

sv[, "Q1"]
sv[, "Q4"]
@

The extraction makes use of the underlying metadata, contained in the \texttt{varlabels} and \texttt{pattern} attributes:

<<attributes>>=

varlabels(sv)
pattern(sv)
@

\section{Working with question columns}

It is easy to query the surveydata object to find out which questions it contains, as well as which columns store the data for those questions.

<<questions>>=
questions(sv)
which.q(sv, "Q1")
which.q(sv, "Q4")
@

\section{Reading the questionnaire text}

The function \texttt{qText} gives access to the questionnaire text.

<<qtext>>=
qText(sv, "Q1")
qText(sv, "Q4")

qTextCommon(sv, "Q4")
qTextUnique(sv, "Q4")
@


\section{Final thoughts}

The last word.


% Start a new page
% Not echoed, not evaluated
% ONLY here for checkVignettes so that all output doesn't
% end up on one enormous page

\end{document}




