[Dplr-commits] r800 - in pkg/dplR: R man vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Apr 9 19:12:42 CEST 2014
Author: andybunn
Date: 2014-04-09 19:12:41 +0200 (Wed, 09 Apr 2014)
New Revision: 800
Modified:
pkg/dplR/R/detrend.series.R
pkg/dplR/man/detrend.series.Rd
pkg/dplR/vignettes/dplR.sty
pkg/dplR/vignettes/intro-dplR.Rnw
Log:
added help for Ar method. Added a code{} tag to dplR.sty (need a way to call out functions like rwl.stats and even data.frame). This is not a great fix. Should mimic the Rd fil formatting? I don't know.
Modified: pkg/dplR/R/detrend.series.R
===================================================================
--- pkg/dplR/R/detrend.series.R 2014-04-09 15:21:41 UTC (rev 799)
+++ pkg/dplR/R/detrend.series.R 2014-04-09 17:12:41 UTC (rev 800)
@@ -136,6 +136,8 @@
if("Ar" %in% method2){
## Fit an ar model - aka prewhiten
Ar <- ar.func(y2)
+ # this will propogate NA to rwi as a result of detrending.
+ # Other methods don't. Problem?
resids$Ar <- Ar / mean(Ar,na.rm=TRUE)
do.ar <- TRUE
} else {
Modified: pkg/dplR/man/detrend.series.Rd
===================================================================
--- pkg/dplR/man/detrend.series.Rd 2014-04-09 15:21:41 UTC (rev 799)
+++ pkg/dplR/man/detrend.series.Rd 2014-04-09 17:12:41 UTC (rev 800)
@@ -92,6 +92,12 @@
contains zeros or negative values, which would lead to invalid
ring-width indices.
+ The \code{"Ar"} approach is also known as prewhitening where the detrended
+ series is the residuals of an \code{\link{ar}} model divided by the
+ mean of those residuals to yield a series with white noise and a mean of one.
+ This method removes all the but the high frequency variation in the series
+ and should only be used as such.
+
These methods are chosen because they are commonly used in
dendrochronology. There is a rich literature on detrending
and many researchers are particularly skeptical of the use of the
Modified: pkg/dplR/vignettes/dplR.sty
===================================================================
--- pkg/dplR/vignettes/dplR.sty 2014-04-09 15:21:41 UTC (rev 799)
+++ pkg/dplR/vignettes/dplR.sty 2014-04-09 17:12:41 UTC (rev 800)
@@ -14,3 +14,5 @@
pdfkeywords = {dendrochronology, dplR, R},
}
}
+\newcommand{\code}[1]{\texttt{#1}}
+
Modified: pkg/dplR/vignettes/intro-dplR.Rnw
===================================================================
--- pkg/dplR/vignettes/intro-dplR.Rnw 2014-04-09 15:21:41 UTC (rev 799)
+++ pkg/dplR/vignettes/intro-dplR.Rnw 2014-04-09 17:12:41 UTC (rev 800)
@@ -43,8 +43,8 @@
dendrochronologists to handle data processing and analysis. This
document gives just a brief introduction of some of the most commonly
used functions in dplR. There is more detailed information
-available in the help files and in the literature including \cite{Bunn2008} and
-\cite{Bunn2010}.
+available in the help files and in the literature including \cite{Bunn2008}
+and \cite{Bunn2010}.
In this vignette, we will walk through the most basic activities of working
with tree-ring data in roughly the order that a user might follow. E.g.,
@@ -58,17 +58,19 @@
\href{http://www.ncdc.noaa.gov/paleo/treeinfo.html#formats}{Tucson} (decadal)
format file of ring widths to the more complex
\href{http://www.tridas.org/}{TRiDaS format}. We generally refer to these as
-rwl objects for ``ring width length'' but there is no reason these can't be
+\code{rwl} objects for ``ring width length'' but there is no reason these can't be
other types of tree-ring data (e.g., density).
-The workhorse function for getting tree-ring data into R is dplR's read.rwl
-function. This function reads files in ``tucson'', ``compact'', ``tridas'', and
-``heidelberg'' formats. The onboard rwl data sets in dplR (i.e., co021, ca533,
-gp.rwl) were all imported into R using this function.
+The workhorse function for getting tree-ring data into R is dplR's
+\code{read.rwl} function. This function reads files in ``tucson'',
+``compact'', ``tridas'', and ``heidelberg'' formats. The onboard \code{rwl} data
+sets in dplR (i.e., co021, ca533, gp.rwl) were all imported into R
+using this function.
-Throughout this vignette we will use the onboard data set ca533 which gives the
-raw ring widths for bristlecone pine \emph{Pinus longaeva} at Campito Mountain
-in California, USA. There are 34 series spanning over 1358 years.
+Throughout this vignette we will use the onboard data set \code{ca533}
+which gives the raw ring widths for bristlecone pine \emph{Pinus longaeva} at
+Campito Mountain in California, USA. There are 34 series spanning over 1358
+years.
These objects are structured very simply as a data.frame with the series in
columns and the years as rows. The series IDs are the column names and the
@@ -85,10 +87,11 @@
@
\subsection{Describing and Plotting Ring-Width Data}
-One a rwl data set has been read into R, there are a variety of ways to
-describe and visualize those data. For instance, we can plot an rwl object by
-showing either the segments arranged over time as straight lines or as a
-``spaghetti plot.''
+One a \code{rwl} data set has been read into R, there are a variety of ways to
+describe and visualize those data. For instance, we can plot an \code{rwl}
+object by showing either the segments arranged over time as straight lines or
+as a ``spaghetti plot.'' The \code{rwl} objects have a generic S3 method for
+\code{plot} and \code{summary}.
<<a, fig=TRUE>>=
plot(ca533, plot.type="spag")
@@ -101,7 +104,7 @@
\end{figure}
\section{Detrending}
-Analysts typically (but not always) detrend a rwl data set to create a
+Analysts typically (but not always) detrend a \code{rwl} data set to create a
ring-width index (rwi) object. The dplR package contains most standard
detrending methods including detrending via splines, fitting negative
exponential curves, and so on. There are also dplR functions for
@@ -112,14 +115,16 @@
\cite{Fritts2001}. This vignette is not intended to teach you about how to do
tree-ring analysis. It's intended to teach you how to use the package.}
-A rwi object has the same basic properties as the rwl object from which it is
+A rwi object has the same basic properties as the \code{rwl} object from which it is
made. I.e., it has the same number of rows and columns, the same names, and so
on. The difference is that each series has been standardized by dividing the
ringwidths against a growth model (e.g., a stiff spline, a negative
expontential, etc.). This give each series a mean of one (thus referred to
-as ``indexed'') and allows a chronology to be built (next section). As read.rwl
-is the primary function for getting data into R, detrend is the primary
-function for standardizing rwl objects (but see cms, rcs, as well).
+as ``indexed'') and allows a chronology to be built (next section). As
+\code{read.rwl} is the primary function for getting data into R,
+\code{detrend} is the primary function for standardizing \code{rwl}
+objects (but see \code{cms}, \code{rcs}, \code{bai.in}, and
+\code{bai.out} as well).
\subsection{Common Detrending Methods}
As any dendrochronologist will tell you, detrending is a dark art. In dplR we
@@ -130,27 +135,29 @@
dimensionless ring-width index (RWI).
We'll discuss detrending via fitting a nonlinear function using
-nls (the ``ModNegExp'' method of detrend) and detrending via cubic smoothing
-spline (the ``Spline'' method of detrend). Much of the text that follows is
-from the help page of detrend.
+\code{nls} (the ``ModNegExp'' method of \code{detrend}) and detrending
+via cubic smoothing spline (the ``Spline'' method of detrend). Much of the
+text that follows is modified from the help page of \code{detrend}.
Probably the most common method for detrending is what is often
called the ``conservative'' approach of attempting to fit a negative exponential
curve to a series In the dplR implementation the ``ModNegExp'' method of detrend
attempts to fit a classic nonlinear model of biological growth of the form
-f(t) = a exp(b t) + k, where the argument of the function is time, using nls.
-See \cite{Fritts2001} for details about the parameters. If a suitable
-nonlinear model cannot be fit (function is non-decreasing or some values are
-not positive) then a linear model is fit. That linear model can have a positive
-slope unless pos.slope is FALSE in which case the series is standardized by its
-mean (method ``Mean'' in detrend).
+f(t) = a exp(b t) + k, where the argument of the function is time, using
+\code{nls}. See \cite{Fritts2001} for details about the parameters. If a
+suitable nonlinear model cannot be fit (function is non-decreasing or some
+values are not positive) then a linear model is fit using \code{lm}. That
+linear model can have a positive slope unless pos.slope is FALSE in which
+case the series is standardized by its mean (method ``Mean'' in
+\code{detrend}).
For instance every series in the ca533 object can be detrended at once via:
<<>>=
ca533.rwi <- detrend(rwl = ca533, method = "ModNegExp")
@
-This saves the results in ca533.rwi which is a data.frame with
-the same dimensions as the rwl object ca533 and each series standardized.
+This saves the results in ca533.rwi which is a \code{data.frame} with
+the same dimensions as the \code{rwl} object \code{ca533} and each series
+standardized.
<<>>=
dim(ca533)
dim(ca533.rwi)
@@ -183,21 +190,23 @@
Often, a user will want to interactively detrend each series and fit a negative
exponential curve to one series and a spline to another. This can be done via
-the i.detrend and i.detrend.series functions. See their help pages for details.
+the \code{i.detrend} and \code{i.detrend.series} functions. See
+their help pages for details.
\subsection{Other Detrending Methods}
There are other detrending methods that are less commonly used but have
distinct theoretical advantages. These include regional curve standardization
-(function rcs), C-Method Standardization (function cms), and converting
-measurements of ring widths to basal area increment (functions bai.in and
-bai.out). See help pages for further information.
+(function \code{rcs}), C-Method Standardization (function \code{cms}),
+and converting measurements of ring widths to basal area increment (functions
+\code{bai.in} and \code{bai.out}). See help pages for further
+information.
\section{Descriptive Statistics}
Either before or after standardization, it would be natural to want to look at
-some common (and not-so common) descriptive statistics of an rwl object. The
-rwl.stats function is typically used on raw ring widths (the rwl object) and
-produces summary statistics. Here are summary statistics on the first five
-series in ca533.
+some common (and not-so common) descriptive statistics of an \code{rwl} object. The
+\code{rwl.stats} function is typically used on raw ring widths
+(the \code{rwl} object) and produces summary statistics. Here are summary
+statistics on the first five series in \code{ca533}.
<<>>=
rwl.stats(ca533)[1:5, ]
@
@@ -205,17 +214,18 @@
These are common summary statistics like mean, median, etc. but also statistics
that are more specific to dendrochronology like the first-order autocorrelation
(ar1) and mean sensitivity (sens1 and sens 2). We'd be remiss if we didn't here
-mention that mean sensitivity is a actually terrible statistic that should rarely,
-if ever, be used \citep{Bunn2013}.
+mention that mean sensitivity is a actually terrible statistic that should
+rarely, if ever, be used \citep{Bunn2013}.
It's also easy in dplR to compute commonly used descriptive statistics that
describe the correlation between series (both within and between tree
correlations) as well as the expressed population signal and signal-to-noise
-ratio a data set. These are done in dplR using the rwi.stats function
-so-named because these statistics are typically (but not always) carried out
-on detrended and standardized ring-width indices. If a data set has more than
-one core taken per tree this information can be used in the calculations to
-calculate within vs. between tree correlation:
+ratio for a data set. These are done in dplR using the \code{rwi.stats}
+function so-named because these statistics are typically (but not always)
+carried out on detrended and standardized ring-width indices. If a data set
+has more than one core taken per tree this information can be used in the
+calculations to calculate within vs. between tree correlation. The function
+\code{read.ids} is used to identify which trees have multiple cores.
<<>>=
ca533.ids <- read.ids(ca533, stc = c(3, 2, 3))
@@ -223,11 +233,12 @@
@
There is (at least) one other way of looking at the average interseries
-correlation of a dataset. The interseries.cor function in dplR gives a measure of
-average interseries correlation that is different than the rbar measurements
-from rwi.stats. In this function, correlations are calculated serially between
-each tree-ring series and a master chronology built from all the other series
-in the rwl object (leave-one-out principle). The average of those correlations
+correlation of a dataset. The \code{interseries.cor} function in dplR
+gives a measure of average interseries correlation that is different than
+the rbar measurements from \code{rwi.stats}. In this function,
+correlations are calculated serially between each tree-ring series and a
+master chronology built from all the other series in the \code{rwl} object
+(leave-one-out principle). The average of those correlations
is sometimes called the ``overall interseries correlation.'' This number is
typically higher than rbar. We are showing just the first five series and the
mean for all series here:
@@ -245,9 +256,9 @@
\section{Building a Mean Value Chronology}
After detrending, a user will typically build a chronology by averaging across
-the years of the rwi object. In dplR the function for doing this is chron which
-by default uses Tukey's biweight robust mean which is an average that
-is unaffected by outliers.
+the years of the rwi object. In dplR the function for doing this is
+\code{chron} which by default uses Tukey's biweight robust mean (an average
+that is unaffected by outliers).
<<>>=
ca533.crn <- chron(ca533.rwi, prefix = "CAM")
@
@@ -259,8 +270,8 @@
dim(ca533.crn)
@
-The chronology can be plotted using the chron.plot function which has many
-arguments for customization. Here we'll just make a simple plot of the
+The chronology can be plotted using the \code{chron.plot} function which
+has many arguments for customization. Here we'll just make a simple plot of the
chronology with a smoothing spline added.
<<c, fig=TRUE>>=
chron.plot(ca533.crn, add.spline=TRUE, nyrs=20)
More information about the Dplr-commits
mailing list