%\VignetteDepends{}
%\VignetteIndexEntry{Implementing S4 objects in your package: Exercises}
%\VignettePackage{AdvancedR2011}

\documentclass{article}

\usepackage{BioconductorVignette}
\usepackage{underscore}

\SweaveOpts{keep.source=TRUE, eps=FALSE, include=FALSE}

\title{Implementing S4 objects in your package: Exercises}

\author{Herv\'e Pag\`es\footnote{Fred Hutchinson Cancer Research Center, Seattle, WA 98008}}
\date{17-18 February, 2011}

\begin{document}

<<setup, echo=FALSE>>=
options(width = 60)
@

\maketitle

\tableofcontents


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

Throughout this lab you will implement a class, named \Rclass{GWASdata},
which purpose is to bind together the experimental data and metadata from
a genome-wide association study. We will assume that the GWAS experimental
data is a matrix (with 1 row per subject and 1 col per SNP) stored in a
NetCDF file and that the metadata associated with the subjects and SNPs
are stored in an SQLite db file.

Implementing an S4 class typically consists in the following steps:
\begin{enumerate}
  \item A class definition where the name and type of each slot
        is specified. Unlike with other OO programming languages,
        the methods that will operate on this class are not part of
        the class definition.

  \item A constructor so we can create \Rclass{GWASdata} instances.
        A common practise is to define an ordinary function named like
        the class itself for this. Note that this is not enforced by
        by the S4 class system, just a consensual practise among the
        Bioconductor core developpers.
        This \Rfunction{GWASdata} function will take care of doing
        some basic argument checking and to populate the slots of the
        instance to be returned.

  \item Some accessor methods to get values from (or set values to) the
        slots of a \Rclass{GWASdata} object. Note that direct slot
        manipulation by the end user via the \code{@} operator is
        generally not recommended. Providing our own set of accessors
        will hopefully discourage the user of our objects from doing
        this. It's also a way for us to formally specify which slots
        are ok to be accessed and how they should be accessed
        (read-only slot or read-write slot).

  \item Other accessor-like methods that are not \textit{slot} accessors
        (i.e. they are not getting or setting the content of a slot,
        strictly speaking) but are returning some combination of slot
        values (e.g. \Rfunction{dim}) or some data that is retrieved from
        disk (e.g. \Rfunction{getCols}).

  \item A \Rmethod{show} method, so our objects display nicely with
        some useful information.

  \item A \textit{validity method} that will take care of checking
        that our \Rclass{GWASdata} objects are valid i.e. that their
        slots contain values that make sense individually and \textit{as a
        whole}. Note that this certainly requires some extra effort whose
        benefits maybe aren't immediatly obvious, but it is considered
        good practise since it makes your class implementation more robust
        and it pays off in the long term maintenance of your package.
        In this lab, because of time constraints, we will implement
        an incomplete \textit{validity method} for our \Rclass{GWASdata}
        objects.

  \item Some \textit{coercion methods} to turn our \Rclass{GWASdata} objects
        into other types of objects, with or without loss of information.
        In this lab, we will implement a \textit{coercion method} for turning
        a \Rclass{GWASdata} object into a \Rclass{raw} matrix.

  \item Other high-level methods that don't fall into any of the
        previous categories (i.e. not accessor, show, validity or
        coercion methods). Depending on the kind of object that is
        being implemented, those can be methods for subsetting,
        plotting, normalizing, generating an HTML report, etc...
\end{enumerate}

This is really what we mean when we say \textit{implementing S4 objects}.

The lab is divided in 2 parts:
\begin{itemize}
  \item Part I: Implement the \Rclass{GWASdata} class in a standalone
        file.

  \item Part II: Integrate this work to the \Rpackage{StudentGWAS} package.
        This means: add the file with the code produced in Part I to
        the package, modify the \code{Collate} field, import the
        \Rpackage{methods} package (if not already done), modify the
        \code{NAMESPACE} file, and add a man page documenting the
        class. Once everything is in place, we will be able to build
        and check our package with \code{R CMD build} and \code{R CMD check}.
\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Part I: Implementing the \Rclass{GWASdata} class}


The process of designing and implementing a new class requires that the
developper spends some time thinking about:
\begin{itemize}
  \item what s/he wants to achieve exactly with the class,
  \item how is the class going to be used, by who, for doing what,
  \item what are the typical use cases,
  \item what is the typical size of the data that will be manipulated,
        small (< 1 Mb), big (> 100 Mb), very big (> 10 Gb),
  \item how the class will interact with other packages and classes
        in CRAN/Bioconductor,
  \item how the facilities provided by the class will fit within the
        tools and file formats commonly used inside or outside
        Bioconductor,
  \item etc...
\end{itemize}

It's generally considered good design to avoid storing redundant
information (although some exceptions can be made for performance
considerations) and to keep things as simple as possible.


\subsection{Class definition}

For our \Rclass{GWASdata} class, we want the following slots:
\begin{itemize}
  \item \code{datapath}: the path to a NetCDF file containing the GWAS
        experimental data (a matrix). This will be of type
        \Rclass{character}.

  \item \code{dataconn}: the connection to the NetCDF file pointed by
        \code{datapath}. A connection to a NetCDF file is an object of
        class \Rclass{ncdf}. Note that there is a complication here
        due to the fact that the \Rclass{ncdf} class is defined in the
        \Rpackage{ncdf} package and that this package has no NAMESPACE.
        This makes it impossible to import the \Rpackage{ncdf} package in
        our \Rpackage{StudentGWAS} package, and, in particular, we can't
        use \Rcode{"ncdf"} to specify the type of our slot.
        So we will use the type \Rcode{"list"} for this slot. This works
        because \Rclass{ncdf} is an S3 class (aka \textit{old style}
        class) and in the S3 class system, every object is a list with
        a class attribute attached to it.

  \item \code{metadatapath}: the path to an SQLite db file containing
        the GWAS metadata. This will be of type \Rclass{character}.

  \item \code{metadataconn}: the connection to the SQLite db pointed by
        \code{metadatapath}. This will be of type \Rclass{SQLiteConnection}.

  \item \code{nrow}: the nb of rows in the GWAS matrix (this is also the
        nb or rows in the \code{subjects} table contained in the SQLite db).
        This will be of type \Rclass{integer}.

  \item \code{ncol}: the nb of cols in the GWAS matrix (this is also the
        nb or rows in the \code{snps} table contained in the SQLite db).
        Also of class \Rclass{integer}.
\end{itemize}

\begin{Exercise}
  Start a new file (let's name it \code{GWASdata-class.R}) and write
  the \Rcode{setClass} statement for the \Rclass{GWASdata} class.
\begin{verbatim}
  setClass("GWASdata",
      representation(
          datapath="character",
          ...
          ...
      )
  )
\end{verbatim}
\end{Exercise}


\subsection{Constructor}

For the \Rclass{GWASdata} constructor, we are going to write a function
that takes 2 arguments: \Rcode{datapath} and \Rcode{metadatapath}.
Those 2 arguments will contain the user-supplied paths to the NetCDF file
and SQLite db file, respectively.
The constructor must perform the following tasks:
\begin{enumerate}
  \item Open the NetCDF and SQLite connections.

  \item Drop the class attribute of the NetCDF connection (with
        \Rcode{class(dataconn) <- NULL}), otherwise it won't be possible
        to assign it to the \code{dataconn} slot.

  \item Obtain the values to assign to the \code{nrow} and \code{ncol}
        slots by counting the nb of rows in the \code{subjects} and
        \code{snps} SQL tables, respectively.

  \item Finally call \Rcode{new("GWASdata", ...)} with named arguments.
        The names of the arguments must correspond to slots in the class
        definition. Their values must correspond to the values to assign
        to the slots.
\end{enumerate}

\begin{Exercise}
  \begin{enumerate}
    \item Add the \Rclass{GWASdata} constructor to the \code{GWASdata-class.R}
          file.

    \item Start \R{}, manually load the \Rpackage{RSQLite} and \Rpackage{ncdf}
          packages, source the \code{GWASdata-class.R} file (or copy/paste its
          content into your session), do \Rcode{showClass("GWASdata")},
          and finally, try to use the \Rclass{GWASdata} constructor on the
          \code{small_snpData.nc} and \code{small_metadata.sqlite} files
          that are included in the \Rpackage{StudentGWAS} package.
          Note: if the \Rpackage{StudentGWAS} package is installed,
          the paths to those files can be obtained with:
\begin{verbatim}
  datapath <- system.file("extdata", "small_snpData.nc",
                          package="StudentGWAS")
  metadatapath <- system.file("extdata", "small_metadata.sqlite",
                              package="StudentGWAS")
\end{verbatim}
  \end{enumerate}
\end{Exercise}

Now we are able to create \Rclass{GWASdata} objects! Keep your \R{} session
live for further testing on the \Rclass{GWASdata} object you just created
(let's call this object \Rcode{gwas}).

It's pretty clear that we will need to implement a \Rmethod{show} method.
However it's better to start by implementing a few accessor methods so
we can use them later in the \Rmethod{show} method and in our code in general.


\subsection{Accessors}

In the next exercise we will implement the following accessors:
\begin{itemize}
  \item the \Rmethod{dataconn}, \Rmethod{nrow} and \Rmethod{ncol} slot
        accessors;
  \item the \Rmethod{dim} accessor (which is not a \textit{slot} accessor,
        strictly speaking).
\end{itemize}

Because of time constraints, we won't implement the full set of slot
accessors (for completeness, the \Rmethod{datapath}, \Rmethod{metadatapath}
and \Rmethod{metadataconn} slot accessors should also be provided).

We want to implement those accessors as \textit{methods} for
\Rclass{GWASdata} objects, not as ordinary functions. This is
\textit{the} recommended way to implement accessors.

Let's distinguish between 2 situations:
\begin{itemize}
  \item For accessors with a name that doesn't correspond to any existing
        function (e.g. \Rmethod{dataconn}), we need to define a
        \textit{generic} function before we can write a method for it.
        This is done with a \Rcode{setGeneric} statement.
        The simplest form of the \Rcode{setGeneric} statement is the
        following (for a generic function \Rfunction{foo} with a single
        argument):
\begin{verbatim}
  setGeneric("foo", function(x) standardGeneric("foo"))
\end{verbatim}

  \item For accessors with a name that corresponds to an existing function
        (e.g. \Rmethod{nrow}, \Rmethod{ncol} and \Rmethod{dim}), we
        generally don't need a \Rcode{setGeneric} statement.
        (If the existing function is not already a generic function, then
        it will be automatically turned into an \textit{implicit} generic
        function.)
        In that case the programmer must check the signature of the existing
        function and make sure that s/he uses exactly the same signature in
        his/her method definition.
\end{itemize}

The definition of the method itself is done with a \Rcode{setMethod}
statement. For example, in the case of a generic function dispatching
on 1 argument only (the most common situation), the \Rcode{setMethod}
statement looks like:
\begin{verbatim}
  setMethod("foo", "GWASdata",
      function(x)
      {
          ...
      }
  )
\end{verbatim}

\begin{Exercise}
  \begin{enumerate}
    \item Implement the \Rmethod{dataconn} accessor. Note that, for this
          accessor, we need to make the following small modification to
          the value of the \code{dataconn} slot (\Rcode{x@dataconn})
          before we return it:
\begin{verbatim}
  dataconn <- x@dataconn
  class(dataconn) <- "ncdf"
\end{verbatim}
          This is in order to restore the class attribute that was dropped
          by the constructor.
          Copy/paste the new code into your current \R{} session and test
          the \Rmethod{dataconn} accessor on your \Rclass{GWASdata} object.

    \item Implement the \Rmethod{nrow}, \Rmethod{ncol} and \Rmethod{dim}
          accessors. Test them.
  \end{enumerate}
\end{Exercise}

In the next exercise we implement the \Rmethod{getCols} method for
extracting a set of adjacent columns (specified by the user) from the
matrix of data stored in the NetCDF file. Of course we want to re-use
the \Rfunction{getGWAScols} utility function implemented in a previous
lab.

\begin{Exercise}
  \begin{enumerate}
    \item Define the \Rfunction{getCols} generic with the following
          arguments: \Rcode{(x, first, last = first)}.
          Note that we want to dispatch on the first argument only
          so we need to specify this with
\begin{verbatim}
  setGeneric("getCols", signature = "x", ... ... ...)
\end{verbatim}
          otherwise the generic function will dispatch on all its
          arguments (multiple dispatch).

    \item Implement the \Rmethod{getCols} method. Note that when
          writing code in a standalone file like \code{GWASdata-class.R},
          your code doesn't have access to the \Rfunction{getGWAScols}
          function that is defined in the \Rpackage{StudentGWAS} package
          and not exported. However, you can still put a call to
          \Rfunction{getGWAScols} in your code, and your code will work
          just fine later when we integrate it to the \Rpackage{StudentGWAS}
          package (because then it will have access to \emph{everything}
          that is defined in the package).

    \item Copy/paste the new code into your current \R{} session and test
          the \Rmethod{getCols} accessor on your \Rclass{GWASdata} object.
          Tip: for this to work, you will first need to load the
          \Rpackage{StudentGWAS} package and do:
\begin{verbatim}
  getGWAScols <- StudentGWAS:::getGWAScols
\end{verbatim}
          Note that it would be a bad idea to put a call like
          \Rcode{StudentGWAS:::getGWAScols()} inside the \Rmethod{getCols}
          method.
  \end{enumerate}
\end{Exercise}


\subsection{The \Rmethod{show} method}

\Rfunction{show} is a generic function defined in the \Rpackage{methods}
package (which is also the home of the \Rfunction{setClass},
\Rfunction{setGeneric} and \Rfunction{setMethod} functions and the
S4 class system in general). Do \Rcode{?show} in your \R{} session.
The important bit here is that the name of the argument is \code{object}
so that's what you need to use in your method definition.

\begin{Exercise}
  \begin{enumerate}
    \item Write a \Rmethod{show} method that displays something like:
\begin{verbatim}
  GWASdata instance with 50 subjects and 25 SNPs
\end{verbatim}
          Internally, use the \Rfunction{cat} function to print the
          information, and use the \Rmethod{nrow} and \Rmethod{ncol}
          accessors (instead of doing direct slot access with
          \Rcode{object@nrow} and \Rcode{object@ncol}).
          Also, even if you think you know the class of the object
          being displayed, it's better to use \Rcode{class(object)}
          than to \textit{hardcode} \Rcode{"GWASdata"}. You never
          know, maybe one day someone decides to extend your
          \Rclass{GWASdata} class. When this happens, your \Rmethod{show}
          method will work out-of-the-box on instances of the derived
          class (thanks to \textit{inheritance}), and, because you used
          \Rcode{class(object)}, it will correctly display their class.

    \item Copy/paste the definition of the \Rmethod{show} method into
          your current \R{} session and try to display your
          \Rclass{GWASdata} object again (by just typing the name of
          the object followed by <Enter>).
  \end{enumerate}
\end{Exercise}


\subsection{The validity method}

One limitation of the \Rcode{setClass} statement is that the
\Rcode{representation} component only allows us to specify the
types of the slots, but not their lengths or any other restriction
that we'd want to impose.

For example, the \Rcode{setClass} statement for our \Rclass{GWASdata}
class just requires the \code{datapath} slot to be a \Rclass{character}
vector, without imposing any restriction on its length or content.
But what we really want is a single string i.e. a \Rclass{character}
vector of length 1 that is not an \Rcode{NA}. A \Rclass{GWASdata}
object with a \Rclass{character} vector of length 0 or an \Rcode{NA} in
its \code{datapath} slot could fairly be considered broken. Of course, we
could put some sanity checkings in the \Rclass{GWASdata} constructor
in order to avoid this, but, a better approach is to define a
\textit{validity method} that will be in charge of those checkings.

Any S4 object can be validated at any time with a call to
\Rfunction{validObject}. By default (i.e. if no \textit{validity method}
is defined), the validation only consists in checking that the types of
the slot values are \textit{compatible} with the expected types i.e. with
the types that are specified in the class definition (\textit{compatible}
here means that the slot value belongs to the specified class or to one of
its subclasses). This validation is automatically performed by the low-level
constructor \Rfunction{new} (and this is why trying to create an object
with an incompatible slot value generates an error).

By defining a \textit{validity method} for his/her objects, the developper
can be much more specific about what values can go into each slot.
Furthermore, it allows him/her to validate an object \textit{as a whole}
by checking that the values in the different slots are compatible
with each other.

Defining a \textit{validity method} is done with a \Rcode{setValidity}
statement:
\begin{verbatim}
  setValidity("GWASdata",
      function(object)
      {
          ...
          ...
      }
  )
\end{verbatim}

The method should return \Rcode{TRUE} if the object is valid, and one
or more descriptive strings if any problems are found. It should never
generate an error.

In the next exercise, we implement a simple (incomplete) \textit{validity
method} for \Rclass{GWASdata} objects.

\begin{Exercise}
  \begin{enumerate}
    \item Implement a \textit{validity method} for \Rclass{GWASdata}
          objects that will be in charge of checking that:
          \begin{itemize}
            \item the \code{datapath} slot is a single string (i.e. a
                  \Rclass{character} vector of length 1 that is not an
                  \Rcode{NA});
            \item the \code{nrow} slot is a single non-negative
                  \Rclass{integer}.
          \end{itemize}
    \item Copy/paste the definition of the \textit{validity method} into
          your current \R{} session and call \Rfunction{validObject} on
          your \Rclass{GWASdata} object. Break the object by setting its
          \code{nrow} slot to -2 (note that doing \Rcode{gwas@nrow <- -2}
          won't work because \Rcode{-2} is not of type \Rclass{integer}
          in \R{}, but \Rcode{-2L} is). Call \Rfunction{validObject}
          again on the object.
  \end{enumerate}
\end{Exercise}


\subsection{Coercion methods}

It's often convenient for the user to be able to turn an object of a given
class (the \textit{original} class) into an object of another class (the
\textit{target} class).
This transformation is called \textit{coercion} in \R{} jargon
(\textit{explicit type-casting} or \textit{type conversion} in other
programming languages). Depending on the classes that are involved,
the coercion can be with or without loss of information.

When implementing an S4 class, it's good to think about potentially
useful coercions that the user might need. In the case of our
\Rclass{GWASdata} class for example, we'd like the user to be able
to turn a \Rclass{GWASdata} object into a \Rclass{raw} matrix.

\R{} supports 2 syntaxes for performing a coercion: (1) the
\Rcode{as.}\textit{targetclass}\Rcode{(x)} syntax, and (2) the
\Rcode{as(x, "targetclass")} syntax.

The former syntax only supports a limited set of \textit{target} classes
thru some predefined generic functions such as
\Rfunction{as.logical}, \Rfunction{as.integer}, \Rfunction{as.double},
\Rfunction{as.numeric}, \Rfunction{as.complex}, \Rfunction{as.character},
\Rfunction{as.raw}, \Rfunction{as.vector}, \Rfunction{as.list},
\Rfunction{as.factor}, \Rfunction{as.matrix}, \Rfunction{as.array},
\Rfunction{as.data.frame}, etc...

The latter syntax makes use of a single generic function, the
\Rfunction{as} generic. This is the preferred syntax when working
with S4 objects: it offers greater flexibility and better integration
to the S4 class system itself.

So we want our user to be able to turn a \Rclass{GWASdata} object
\Rcode{x} into a \Rclass{raw} matrix with \Rcode{as(x, "matrix")}.
For this to work, we need to implement a \textit{coercion method}.
This is done with a \Rcode{setAs} statement:
\begin{verbatim}
  setAs("GWASdata", "matrix",
      function(from)
      {
          ...
          ...
      }
  )
\end{verbatim}

The \code{from} argument contains the object to coerce. The method
should return the coerced object.

\begin{Exercise}
  \begin{enumerate}
    \item Implement the \textit{coercion method} from \Rclass{GWASdata}
          to \Rclass{matrix}. The method must extract the entire matrix
          of data stored in the NetCDF file and return it into a
          \Rclass{raw} matrix.

    \item Copy/paste the definition of this \textit{coercion method}
          into your current \R{} session and test it by doing
          \Rcode{as(gwas, "matrix")}.
  \end{enumerate}
\end{Exercise}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Part II: Integrating the \Rclass{GWASdata} class to the package}

We will now integrate the code produced in Part I to the
\Rpackage{StudentGWAS} package. This is done in 4 steps.


\subsection{Step 1: Add the \code{GWASdata-class.R} file to the package}

\begin{Exercise}
  \begin{enumerate}
    \item Put the \code{GWASdata-class.R} file under the \code{R/} folder
          of your package. In case you are using a \textit{revision control
          system} like Subversion to develop your code, don't forget to add
          the file to the system with e.g. \code{svn add}.

    \item Add the name of the new \code{.R} file to the \code{Collate} field
          of the \code{DESCRIPTION} file. The new file should be listed after
          any other file that contains material used in the new file. In
          the case of the \Rpackage{StudentGWAS} package, it should go after
          the \code{utils.R} file which contains low-level stuff used in the
          new file.
  \end{enumerate}
\end{Exercise}


\subsection{Step 2: Import the \Rpackage{methods} package and modify
            the \code{NAMESPACE} file}

\begin{Exercise}
  \begin{enumerate}
    \item Make sure the \Rpackage{methods} package is in the \code{Imports}
          field of your package. Add it if needed.

    \item Then make the following modifications to the \code{NAMESPACE} file
          of your package:
          \begin{itemize}
            \item Make sure the file contains the following directive:
\begin{verbatim}
  import(methods)
\end{verbatim}
                  If not, add it before any other imports.

            \item Export the \Rclass{GWASdata} class by adding the name
                  of the class inside the \code{exportClasses} directive.
                  Syntax:
\begin{verbatim}
  exportClasses(
      Class1,
      Class2,
      ...
      ...
  )
\end{verbatim}

            \item In the \code{export} directive: Add the \textit{functions}
                  (non-generic and generic) defined in your package that you
                  want to export. Note that what you export will need to be
                  documented in a man page. The stuff that is not intended
                  to be used directly by the user of your package should not
                  be exported (and not documented, of course, but that doesn't
                  mean it doesn't deserve some brief documentation in the
                  form of a short comment in your source code).

            \item In the \code{exportMethods} directive: Add the
                  \textit{methods} you want to export (usually all the methods
                  defined in your package, except the \textit{validity
                  method}).
                  Note that the names you need to put in the directive are
                  those of the corresponding generics with no specification of
                  the classes for which the methods are defined. This means
                  that if you implemented more than one method for the generic
                  \Rcode{foo}, then \code{foo} only needs to be listed once
                  in the \code{exportMethods} directive:
\begin{verbatim}
  exportMethods(
      ...
      foo,  # exports all the methods attached to this generic
      ...
  )
\end{verbatim}
                  Dont't forget to export the \textit{coercion methods}. This
                  is done by adding \code{coerce} to the \code{exportMethods}
                  directive.
          \end{itemize}
  \end{enumerate}
\end{Exercise}


\subsection{Step 3: Add a man page for the \Rclass{GWASdata} class}

Documenting the new class and its basic functionalities might not
be the most exciting part of the story but, unfortunately, it's an
indispensable one!
To help get us motivated, let's remember that undocumented functionalities
are probably not going to be used, or, in the best case, they'll make
our most adventurous users feel frustrated.

An easy approach would be to use \Rcode{promptClass("GWASdata")}
which automatically generates a minimalist man page for our class.
However, in our opinion, this automatic man page does not provide
useful information to the user. It's also a little bit misleading since
it encourages the user to create objects with direct calls to
\Rfunction(new) (instead of using our higher-level constructor)
and to manipulate slots directly (instead of using our accessors).

In our experience, using the following template for documenting our
classes leads to more valuable documentation than the
\Rfunction{promptClass} solution:

\begin{verbatim}
  \name{GWASdata-class}
  \docType{class}

  \alias{GWASdata-class}
  \alias{GWASdata}
  \alias{...}
  \alias{...}
  \alias{...}

  \title{GWASdata objects}

  \description{
    ~~ A concise (1-5 lines) description of what the class is. ~~
  }

  \section{Constructor}{
    \describe{
      \item{}{
        \code{GWASdata(...)}:
        ~~ A description of the constructor and its arguments. ~~
      }
    }
  }

  \section{Accessors}{
    In the code snippets below, \code{x} is a GWASdata object.

    \describe{
      \item{}{
        \code{accessor1(x)}:
        ~~ A description of accessor 1. ~~
      }
      \item{}{
        \code{accessor2(x)}:
        ~~ A description of accessor 2. ~~
      }

      ... etc ...

    }
  }

  \section{Coercion}{
    In the code snippets below, \code{x} is a GWASdata object.

    \describe{
      \item{}{
        \code{as(x, "class1")}:
        ~~ A description of what this coercion does. ~~
      }
      \item{}{
        \code{as(x, "class2")}:
        ~~ A description of what this coercion does. ~~
      }

      ... etc ...

    }
  }

  \references{
    ~~ Put references to the literature/web site here. ~~
  }

  \author{Student Name}

  \seealso{
    ~~ Put links of the form \code{\link{FUNCTIONNAME}} here ~~
    ~~ to link to other functions. ~~
    ~~ Put links of the form \code{\linkS4class{CLASSNAME}} here ~~
    ~~ to link to other classes. ~~
  }

  \examples{
    ~~ Put code here that illustrates at least the use of the ~~
    ~~ constructor, accessors and coercion methods (if any). ~~
  }

  \keyword{classes}

\end{verbatim}

\begin{Exercise}
  Use the above template to produce the \code{GWASdata-class.Rd}
  file. This file needs to be located under the \code{man/} folder
  of your package. In case you are using a \textit{revision control
  system}, don't forget to add the file to it.
  Note that:
  \begin{itemize}
    \item There must be an alias of the form
\begin{verbatim}
  \alias{foo}
\end{verbatim}
          for each exported function (ordinary or generic).
          Also there must be an alias for each exported method. The form
          of this alias depends on the number of arguments involved in
          the dispatch. It's
\begin{verbatim}
  \alias{foo,Class1-method}
\end{verbatim}
          for dispatch on 1 argument (e.g. for the accessor methods), and
\begin{verbatim}
  \alias{bar,Class1,Class2-method}
\end{verbatim}
          for dispatch on 2 arguments (e.g. for the \textit{coercion
          methods}), and so on...

    \item There is no alias for the \textit{validity methods} (they are not
          exported and they don't need to be documented). What needs to be
          documented with great details however is what the arguments of our
          high-level constructor are expected to be. In the case of paths to
          on-disk files like for our \Rclass(GWASdata) constructor, it's also
          a good idea to describe what the content of those files is expected
          to be.

    \item There must be an alias for the \Rmethod{show} method just to avoid
          an \code{R CMD check} warning (see below) even though it's ok to
          not document the method.

    \item The \code{examples} section is probably the most important part
          of any man page since most users tend to go directly there without
          taking the time to read the whole story (either because they already
          know it or because they are in a hurry).
  \end{itemize}
\end{Exercise}


\subsection{Step 4: Check the package}

\begin{Exercise}
  \begin{enumerate}
    \item Run \code{R CMD build} on the package source tree. This produces
          a \textit{source tarball}. Then run \code{R CMD check} on this
          source tarball and pay attention to any NOTE or WARNING that
          shows up. Fix them if necessary.

    \item Install the source tarball by running \code{R CMD INSTALL} on it.
          Start a fresh \R{} session, load the package, and try to use the
          new code. In particular, go to the new man page (\Rcode{?GWASdata})
          so you can see what it looks like from an end-user point of view.
  \end{enumerate}
\end{Exercise}

If you are using a \textit{revision control system} and are satisfied
with your work so far, then it's a good time to commit it.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}Sdata objects}

