[Vegan-commits] r1658 - in pkg/permute/inst: . doc
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Jun 26 22:22:01 CEST 2011
Author: gsimpson
Date: 2011-06-26 22:22:01 +0200 (Sun, 26 Jun 2011)
New Revision: 1658
Added:
pkg/permute/inst/doc/
pkg/permute/inst/doc/Z.cls
pkg/permute/inst/doc/permutations.Rnw
pkg/permute/inst/doc/permute.bib
Log:
first stab at a vignette
Added: pkg/permute/inst/doc/Z.cls
===================================================================
--- pkg/permute/inst/doc/Z.cls (rev 0)
+++ pkg/permute/inst/doc/Z.cls 2011-06-26 20:22:01 UTC (rev 1658)
@@ -0,0 +1,247 @@
+\def\fileversion{1.2}
+\def\filename{Z}
+\def\filedate{2007/02/12}
+%%
+%% Package `Z' to use with LaTeX2e for Z reports
+%% Copyright (C) 2004 Achim Zeileis
+%%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{Z}[\filedate\space\fileversion\space Z class by Achim Zeileis]
+
+%% options
+\LoadClass[10pt,a4paper,twoside]{article}
+\newif\if at notitle
+\@notitlefalse
+\newif\if at noheadings
+\@noheadingsfalse
+\newif\if at shortnames
+\@shortnamesfalse
+\DeclareOption{notitle}{\@notitletrue}
+\DeclareOption{noheadings}{\@noheadingstrue}
+\DeclareOption{shortnames}{\@shortnamestrue}
+\ProcessOptions
+
+%% required packages
+\RequirePackage{graphicx,a4wide,color,hyperref,ae,fancyvrb,thumbpdf}
+\RequirePackage[T1]{fontenc}
+%% bibliography
+\if at shortnames
+ \usepackage[authoryear,round]{natbib}
+\else
+ \usepackage[authoryear,round,longnamesfirst]{natbib}
+\fi
+\bibpunct{(}{)}{;}{a}{}{,}
+\bibliographystyle{jss}
+
+%% paragraphs
+\setlength{\parskip}{0.7ex plus0.1ex minus0.1ex}
+\setlength{\parindent}{0em}
+
+%% for all publications
+\newcommand{\Plaintitle}[1]{\def\@Plaintitle{#1}}
+\newcommand{\Shorttitle}[1]{\def\@Shorttitle{#1}}
+\newcommand{\Plainauthor}[1]{\def\@Plainauthor{#1}}
+\newcommand{\Keywords}[1]{\def\@Keywords{#1}}
+\newcommand{\Plainkeywords}[1]{\def\@Plainkeywords{#1}}
+\newcommand{\Abstract}[1]{\def\@Abstract{#1}}
+
+%% defaults
+\author{Firstname Lastname\\Affiliation}
+\title{Title}
+\Abstract{---!!!---an abstract is required---!!!---}
+\Plainauthor{\@author}
+\Plaintitle{\@title}
+\Shorttitle{\@title}
+\Keywords{---!!!---at least one keyword is required---!!!---}
+\Plainkeywords{\@Keywords}
+
+%% Sweave(-like)
+\DefineVerbatimEnvironment{Sinput}{Verbatim}{fontshape=sl}
+\DefineVerbatimEnvironment{Soutput}{Verbatim}{}
+\DefineVerbatimEnvironment{Scode}{Verbatim}{fontshape=sl}
+\newenvironment{Schunk}{}{}
+\setkeys{Gin}{width=0.8\textwidth}
+
+%% new \maketitle
+\def\maketitle{
+ \begingroup
+ \def\thefootnote{\fnsymbol{footnote}}
+ \def\@makefnmark{\hbox to 0pt{$^{\@thefnmark}$\hss}}
+ \long\def\@makefntext##1{\parindent 1em\noindent
+ \hbox to1.8em{\hss $\m at th ^{\@thefnmark}$}##1}
+ \@maketitle \@thanks
+ \endgroup
+ \setcounter{footnote}{0}
+
+ \if at noheadings
+ %% \thispagestyle{empty}
+ %% \markboth{\centerline{\@Shorttitle}}{\centerline{\@Plainauthor}}
+ %% \pagestyle{myheadings}
+ \else
+ \thispagestyle{empty}
+ \markboth{\centerline{\@Shorttitle}}{\centerline{\@Plainauthor}}
+ \pagestyle{myheadings}
+ \fi
+
+ \let\maketitle\relax \let\@maketitle\relax
+ \gdef\@thanks{}\gdef\@author{}\gdef\@title{}\let\thanks\relax
+}
+
+% Author information can be set in various styles:
+% For several authors from the same institution:
+% \author{Author 1 \and ... \and Author n \\
+% Address line \\ ... \\ Address line}
+% if the names do not fit well on one line use
+% Author 1 \\ {\bf Author 2} \\ ... \\ {\bf Author n} \\
+% For authors from different institutions:
+% \author{Author 1 \\ Address line \\ ... \\ Address line
+% \And ... \And
+% Author n \\ Address line \\ ... \\ Address line}
+% To start a seperate ``row'' of authors use \AND, as in
+% \author{Author 1 \\ Address line \\ ... \\ Address line
+% \AND
+% Author 2 \\ Address line \\ ... \\ Address line \And
+% Author 3 \\ Address line \\ ... \\ Address line}
+
+\def\@maketitle{\vbox{\hsize\textwidth \linewidth\hsize
+ {\centering
+ {\LARGE\bf \@title\par}
+ \vskip 0.2in plus 1fil minus 0.1in
+ {
+ \def\and{\unskip\enspace{\rm and}\enspace}%
+ \def\And{\end{tabular}\hss \egroup \hskip 1in plus 2fil
+ \hbox to 0pt\bgroup\hss \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\ignorespaces}%
+ \def\AND{\end{tabular}\hss\egroup \hfil\hfil\egroup
+ \vskip 0.1in plus 1fil minus 0.05in
+ \hbox to \linewidth\bgroup\rule{\z@}{10pt} \hfil\hfil
+ \hbox to 0pt\bgroup\hss \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\ignorespaces}
+ \hbox to \linewidth\bgroup\rule{\z@}{10pt} \hfil\hfil
+ \hbox to 0pt\bgroup\hss \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\@author
+ \end{tabular}\hss\egroup
+ \hfil\hfil\egroup}
+ \vskip 0.3in minus 0.1in
+ \hrule
+ \begin{abstract}
+ \@Abstract
+ \end{abstract}}
+ \textit{Keywords}:~\@Keywords.
+ \vskip 0.1in minus 0.05in
+ \hrule
+ \vskip 0.2in minus 0.1in
+}}
+
+%% \def\@maketitle{\vbox{\hsize\textwidth \linewidth\hsize
+%% {\centering
+%% {\LARGE\bf \@title\par}
+%% \def\And{\end{tabular}\hfil\linebreak[0]\hfil
+%% \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\ignorespaces}%
+%% \begin{tabular}[t]{c}\large\bf\rule{\z@}{24pt}\@author\end{tabular}%
+%% \vskip 0.3in minus 0.1in
+%% \hrule
+%% \begin{abstract}
+%% \@Abstract
+%% \end{abstract}}
+%% \textit{Keywords}:~\@Keywords.
+%% \vskip 0.1in minus 0.05in
+%% \hrule
+%% \vskip 0.2in minus 0.1in
+%% }}
+
+
+%% sections, subsections, and subsubsections
+\newlength{\preXLskip}
+\newlength{\preLskip}
+\newlength{\preMskip}
+\newlength{\preSskip}
+\newlength{\postMskip}
+\newlength{\postSskip}
+\setlength{\preXLskip}{1.8\baselineskip plus 0.5ex minus 0ex}
+\setlength{\preLskip}{1.5\baselineskip plus 0.3ex minus 0ex}
+\setlength{\preMskip}{1\baselineskip plus 0.2ex minus 0ex}
+\setlength{\preSskip}{.8\baselineskip plus 0.2ex minus 0ex}
+\setlength{\postMskip}{.5\baselineskip plus 0ex minus 0.1ex}
+\setlength{\postSskip}{.3\baselineskip plus 0ex minus 0.1ex}
+
+\newcommand{\jsssec}[2][default]{\vskip \preXLskip%
+ \pdfbookmark[1]{#1}{Section.\thesection.#1}%
+ \refstepcounter{section}%
+ \centerline{\textbf{\Large \thesection. #2}} \nopagebreak
+ \vskip \postMskip \nopagebreak}
+\newcommand{\jsssecnn}[1]{\vskip \preXLskip%
+ \centerline{\textbf{\Large #1}} \nopagebreak
+ \vskip \postMskip \nopagebreak}
+
+\newcommand{\jsssubsec}[2][default]{\vskip \preMskip%
+ \pdfbookmark[2]{#1}{Subsection.\thesubsection.#1}%
+ \refstepcounter{subsection}%
+ \textbf{\large \thesubsection. #2} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+\newcommand{\jsssubsecnn}[1]{\vskip \preMskip%
+ \textbf{\large #1} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+
+\newcommand{\jsssubsubsec}[2][default]{\vskip \preSskip%
+ \pdfbookmark[3]{#1}{Subsubsection.\thesubsubsection.#1}%
+ \refstepcounter{subsubsection}%
+ {\large \textit{#2}} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+\newcommand{\jsssubsubsecnn}[1]{\vskip \preSskip%
+ {\textit{\large #1}} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+
+\newcommand{\jsssimplesec}[2][default]{\vskip \preLskip%
+%% \pdfbookmark[1]{#1}{Section.\thesection.#1}%
+ \refstepcounter{section}%
+ \textbf{\large #1} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+\newcommand{\jsssimplesecnn}[1]{\vskip \preLskip%
+ \textbf{\large #1} \nopagebreak
+ \vskip \postSskip \nopagebreak}
+
+\renewcommand{\section}{\secdef \jsssec \jsssecnn}
+\renewcommand{\subsection}{\secdef \jsssubsec \jsssubsecnn}
+\renewcommand{\subsubsection}{\secdef \jsssubsubsec \jsssubsubsecnn}
+
+%% colors
+\definecolor{Red}{rgb}{0.5,0,0} %%{0.7,0,0}
+\definecolor{Blue}{rgb}{0,0,0.5} %%{0,0,0.8}
+\hypersetup{%
+ hyperindex = {true},
+ colorlinks = {true},
+ linktocpage = {true},
+ plainpages = {false},
+ linkcolor = {Blue},
+ citecolor = {Blue},
+ urlcolor = {Red},
+ pdfstartview = {Fit},
+ pdfpagemode = {UseOutlines},
+ pdfview = {XYZ null null null}
+}
+
+\AtBeginDocument{
+ \hypersetup{%
+ pdfauthor = {\@Plainauthor},
+ pdftitle = {\@Plaintitle},
+ pdfkeywords = {\@Plainkeywords}
+ }
+}
+\if at notitle
+ %% \AtBeginDocument{\maketitle}
+\else
+ \AtBeginDocument{\maketitle}
+\fi
+
+%% commands
+\makeatletter
+\newcommand\code{\bgroup\@makeother\_\@makeother\~\@makeother\$\@codex}
+\def\@codex#1{{\normalfont\ttfamily\hyphenchar\font=-1 #1}\egroup}
+\makeatother
+%%\let\code=\texttt
+\let\proglang=\textsf
+\newcommand{\pkg}[1]{{\normalfont\fontseries{b}\selectfont #1}}
+\newcommand{\email}[1]{\href{mailto:#1}{\normalfont\texttt{#1}}}
+\newcommand{\doi}[1]{\href{http://dx.doi.org/#1}{\normalfont\texttt{doi:#1}}}
+\newcommand{\E}{\mathsf{E}}
+\newcommand{\VAR}{\mathsf{VAR}}
+\newcommand{\COV}{\mathsf{COV}}
+\newcommand{\Prob}{\mathsf{P}}
Added: pkg/permute/inst/doc/permutations.Rnw
===================================================================
--- pkg/permute/inst/doc/permutations.Rnw (rev 0)
+++ pkg/permute/inst/doc/permutations.Rnw 2011-06-26 20:22:01 UTC (rev 1658)
@@ -0,0 +1,167 @@
+\documentclass[article,shortnames]{Z}
+\usepackage{thumbpdf}
+
+%\VignetteIndexEntry{Restricted permutations; using the permute package}
+%\VignettePackage{permute}
+%\VignetteDepends{vegan}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% almost as usual
+\author{Gavin L. Simpson\\Environmental Change Research Centre --- UCL}
+\title{Restricted permutations; using the \pkg{permute} Package}
+
+%% for pretty printing and a nice hypersummary also set:
+\Plainauthor{Gavin L. Simpson} %% comma-separated
+\Plaintitle{Using the permute Package} %% without formatting
+\Shorttitle{Using the permuet Package} %% a short title (if necessary)
+
+%% an abstract and keywords
+\Abstract{
+}
+\Keywords{permutations, restricted permutations, time series, transects, spatial grids, split-plot designs, Monte Carlo resampling, \proglang{R}}
+\Plainkeywords{permutations, restricted permutations, time series, transects, spatial grids, split-plot designs, Monte Carlo resampling, R} %% without formatting
+%% at least one keyword must be supplied
+
+%% publication information
+%% NOTE: This needs to filled out ONLY IF THE PAPER WAS ACCEPTED.
+%% If it was not (yet) accepted, leave them commented.
+%% \Volume{13}
+%% \Issue{9}
+%% \Month{September}
+%% \Year{2004}
+%% \Submitdate{2004-09-29}
+%% \Acceptdate{2004-09-29}
+
+%% The address of (at least) one author should be given
+%% in the following format:
+% \Address{
+% Gavin L. Simpson\\
+% Environmental Change Research Centre\\
+% UCL Department of Geography\\
+% Pearson Building\\
+% Gower Street\\
+% London, UK, WC1E 6BT\\
+% E-mail: \email{gavin.simpson at ucl.ac.uk}\\
+% URL: \url{http://www.homepages.ucl.ac.uk/~ucfagls/}
+% }
+%% It is also possible to add a telephone and fax number
+%% before the e-mail in the following format:
+%% Telephone: +43/1/31336-5053
+%% Fax: +43/1/31336-734
+
+%% for those who use Sweave please include the following line (with % symbols):
+%% need no \usepackage{Sweave.sty}
+
+%% end of declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\begin{document}
+
+%% include your article here, just as usual
+%% Note that you should use the \pkg{}, \proglang{} and \code{} commands.
+<<preliminary,results=hide,echo=false>>=
+options("prompt" = "R> ", "continue" = "+ ")
+options(useFancyQuotes="UTF-8")
+@
+\section{Introduction}
+In classical frequentist statistics, the significance of a relationship or model is determined by reference to a null distribution for the test statistic. This distribution is derived mathematically and the probability of achieving a test statistic as large or larger if the null hypothesis were true is looked-up from this null distribution. In deriving this probability, some assumptions about the data or the errors are made. If these assumptions are violated, then the validity of the derived $p$-value may be questioned.
+
+An alternative to deriving the null dsitribution from theory is to generate a null distribution for the test statistic by randomly shuffling the data in some manner, refitting the model and deriving values for the test statistic for the permuted data. The level of significance of the test can be computed as the proportion of values of the test statistic from the null distribution that are equal to or larger than the observed value.
+
+In many data sets, simply shuffling the data at random is inappropriate; under the null hypothesis, that data are not freely exchangeable. If there is temporal or spatial correlation, or the samples are clustered in some way, such as multiple samples collected from each of a number of fields. The \pkg{permute} was designed to provide facilities for generating these restricted permutations for use in randomisation tests.
+
+\section{Simple randomisation}
+As an illustration of both randomisation and the use of the \pkg{permute} package we consider a small data set of mandible length measurements on specimens of the golden jackal (\emph{Canis aureus}) from the British Museum of Natural History, London, UK. These data were collected as part of a study comparing prehistoric and modern canids \citep{higham80}, and were analysed by \citet{manly07}. There are ten measurements of mandible length on both male and female specimens. The data are available in the \code{jackal} data frame supplied with \pkg{permute}.
+
+<<load_jackal>>=
+require(permute)
+data(jackal)
+jackal
+@
+
+The interest is whether there is a difference in the mean mandible length between male and femal golden jackals. The null hypothesis is that there is no difference in mandible length betwene the two sexes, whilst the alternative hypothesis is that males have larger mandibles. The usual statistical test of this hypothesis is a one-sided $t$ test, which can be applied using \code{t.test()}
+
+<<ttest_jackal>>=
+jack.t <-t.test(Length ~ Sex, data = jackal, var.equal = TRUE, alternative = "greater")
+jack.t
+@
+
+The observed $t$ is \Sexpr{with(jack.t, round(statistic, 3))} with \Sexpr{with(jack.t, parameter)} df. The probability of observing a value this large or larger if the null hypothesis were true is \Sexpr{with(jack.t, round(p.value, 4))}. Several assumptions have been made in deriving this $p$-value, namely
+
+\begin{enumerate}
+ \item random sampling of individuals from the populations of interest,
+ \item equal population standard deviations for males and females, and
+ \item that the mandible lengths are normally distributed within the sexes.
+\end{enumerate}
+
+Assumption 1 is unlikely to be valid for museum specimens such as these, that have been collected in some unknown manner. Assumption 2 may be valid, Fisher's $F$-test and a Fligner-Killeen test both suggest that the standard deviations of the two populations do not differ significantly
+<<ftest_jackal>>=
+var.test(Length ~ Sex, data = jackal)
+fligner.test(Length ~ Sex, data = jackal)
+@
+This assumption may be relaxed using \code{var.equal = FALSE} (the default) in our call to \code{t.test()}, to employ Welch's modification for un-equal variances. Assumption 3 may be valid, but with such a small sample we are able to reliably test this.
+
+A randomisation test of the same hypothesis can be performed by randomly allocating ten of the mandible lengths to the male group and the remaining lengths to the female group. This randomisation is justified under the null hypothesis because the observed difference in mean mandible length between the two sexes is just a typical value for the difference in a sample if there were no difference in the population. An appropriate test statistic needs to be selected. We could use the $t$ statistic as derived in the $t$-test. Alternatively, we could base our randomisation test on the difference of means $D_i$ (male - female).
+
+The main function in \pkg{permute} for providing random permutations is \code{shuffle()}. We can write our own randomisation test for the \code{jackal} data by first creating a function to compute the difference of means for two groups
+<<meanFun>>=
+meanDif <- function(x, grp) {
+ mean(x[grp == "Male"]) - mean(x[grp == "Female"])
+}
+@
+which can be used in a simple \code{for()} loop to generate the null distribution for the difference of means. First, we allocate some storage to hold the null difference of means; here we use 4999 random permutations so allocate a vector of length 5000. Then we iterate, randomly generating an ordering of the \code{Sex} vector and computing the difference means for that permutation.
+<<randJackal>>=
+Djackal <- numeric(length = 5000)
+N <- nrow(jackal)
+set.seed(42)
+for(i in seq_len(length(Djackal) - 1)) {
+ perm <- shuffle(N)
+ Djackal[i] <- with(jackal, meanDif(Length, Sex[perm]))
+}
+Djackal[5000] <- with(jackal, meanDif(Length, Sex))
+@
+The observed difference of means was added to the null distribution, because under the null hypothesis the observed allocation of mandible lengths to male and female jackals is just one of the possible random allocations.
+
+The null distribuion of $D_i$ can be visualised using a histogram, as shown in Figure~\ref{hist_jackal}. The observed difference of means (\Sexpr{round(Djackal[5000], 2)}) is indicated by the red tickmark.
+
+<<hist_jackal, fig=false, echo=true, eval=false, keep.source=true>>=
+hist(Djackal, main = "",
+ xlab = expression("Mean difference (Male - Female) in mm"))
+rug(Djackal[5000], col = "red", lwd = 2)
+@
+The number of values in the randomisation distribution equal to or larger than the observed difference is
+<<>>=
+(Dbig <- sum(Djackal >= Djackal[5000]))
+@
+giving a permutational $p$-value of
+<<>>=
+Dbig / length(Djackal)
+@
+which is comparable with that determined from the frequestist $t$-test, and indicate strong evidence against the null hypothesis of no difference.
+\begin{figure}[t]
+ \centering
+<<draw_hist_jackal, fig=true, echo=false>>=
+<<hist_jackal>>
+@
+\caption{\label{hist_jackal}Distribution of the difference of mean mandible length in random allocations, ten to each sex.}
+\end{figure}
+
+In total there $^{20}C_{10} = \Sexpr{formatC(choose(20,10), big.mark = ",", format = "f", digits = 0)}$ possible allocations of the 20 observations to two groups of ten
+<<>>=
+choose(20, 10)
+@
+so we have only evaluted a small proportion of these in the randomisation test.
+
+The main workhorse function we used above was \code{shuffle()}. In this example, we could have used the base R function \code{sample()} to generate the randomised indices \code{perm} that were used to permute the \code{Sex} factor. Where \code{shuffle()} comes into it's own is for generating permutation indicies from restricted permutation designs.
+
+\section{The shuffle() function}
+In the previous section I introduced the \code{shuffle()} function to generate permutation indicies for use in a randomisation test. Now we will take a closer look at \code{shuffle()} and explore the various restricted permutation designs from which it can generate permutation indicies.
+
+\section*{Computational details}
+<<seesionInfo, results=tex>>=
+toLatex(sessionInfo())
+@
+\bibliography{permute}
+\end{document}
Added: pkg/permute/inst/doc/permute.bib
===================================================================
--- pkg/permute/inst/doc/permute.bib (rev 0)
+++ pkg/permute/inst/doc/permute.bib 2011-06-26 20:22:01 UTC (rev 1658)
@@ -0,0 +1,18 @@
+ at Article{higham80,
+ author = {Higham, C.F.W and Kijngam, A. and Manly, B.F.J.},
+ title = {An analysis of prehistoric canid remains from {T}hailand},
+ journal = {Journal of Archaeological Science},
+ year = {1980},
+ volume = {7},
+ pages = {149--165}
+}
+
+ at Book{manly07,
+ author = {Manly, B.F.J.},
+ title = {Randomization, bootstrap and Monte Carlo methods in biology},
+ publisher = {Chapman \& Hall/CRC},
+ year = {2007},
+ address = {Boca Raton},
+ edition = {3rd}
+}
+
More information about the Vegan-commits
mailing list