[Picante-commits] r159 - branches/gsoc/man

[noreply at r-forge.r-project.org]

Author: mrhelmus
Date: 2008-08-12 04:28:15 +0200 (Tue, 12 Aug 2008)
New Revision: 159

Modified:
   branches/gsoc/man/pblm.Rd
Log:
manual for pblmpredict

Modified: branches/gsoc/man/pblm.Rd
===================================================================
--- branches/gsoc/man/pblm.Rd	2008-08-04 10:04:19 UTC (rev 158)
+++ branches/gsoc/man/pblm.Rd	2008-08-12 02:28:15 UTC (rev 159)
@@ -1,11 +1,14 @@
 \name{pblm}
 \alias{pblm}
+\alias{pblmpredict}
 \title{ Phylogenetic Bipartite Linear Model }
 \description{
   Fits a linear model to the association strengths of a bipartite data set with or without phylogenetic correlation among the interacting species
 }
 \usage{
 pblm(assocs,tree1=NULL,tree2=NULL,covars1=NULL,covars2=NULL,bootstrap=FALSE,nreps=10,maxit=10000,pstart=c(.5,.5))
+pblmpredict(x,tree1.w.novel=NULL,tree2.w.novel=NULL,predict.originals=FALSE)
+
 }
 
 \arguments{
@@ -18,6 +21,10 @@
   \item{nreps}{ Number of bootstrap replicated data sets to estimate parameter CIs }
   \item{maxit}{ as in \code{\link{optim}} }
   \item{pstart}{ starting values of the two phylogenetic signal strength parameters passed to \code{\link{optim}} }
+  \item{x}{ object of class \code{pblm} }
+  \item{tree1.w.novel}{ A phylo tree object or a phylogenetic covariance matrix which corresponds to \code{tree1} of \code{x} with species to predict associations }
+  \item{tree2.w.novel}{ A phylo tree object or a phylogenetic covariance matrix which corresponds to \code{tree2} of \code{x} with species to predict associations } 
+  \item{predict.originals}{ if \code{TRUE} then the associations of each original species in the two phylogenies is predicted } 
 }
 
 \details{
@@ -28,11 +35,12 @@
  evolution; \emph{0<d<1} represents stabilizing selection; \emph{d=0} depicts the absence of phylogenetic correlation (i.e., a star phylogeny); and \emph{d>1} corresponds 
  to disruptive selection where phylogenetic signal is amplified. Confidence intervals for these and the other parameters can be estimated with 
  bootstrapping.
- 
+ \cr
+ \cr
+ The function \code{pblmpredict} predicts the associations of novel species following the methods given in appendix B of Ives and Godfray (2006). 
  }
 
 \value{
-	The function returns a list with:
   \item{MSE}{ total, full (each \emph{d} estimated), star (\emph{d=0}), and base (\emph{d=1}) mean squared errors }
   \item{signal.strength}{ two estimates of phylogenetic signal strength }
   \item{coefficients}{ estimated intercept and covariate coefficients with approximate 95 percent CIs for the three model types (full, star, base) }
@@ -40,17 +48,24 @@
   \item{variates}{ matrix of model variates (can be used for plotting) }
   \item{residuals}{ matrix of residuals from the three models (full, star and base) }
   \item{bootvalues}{ matrix of parameters estimated from the \code{nreps} bootstrap replicated data sets used to calculate CIs }
-  
+  \item{cors.1}{ correlations among predicted and observed associations for species of tree1, \code{NA} if \code{predict.originals=FALSE} }
+  \item{cors.2}{ correlations among predicted and observed associations for species of tree2,  \code{NA} if \code{predict.originals=FALSE} }
+  \item{pred.novels1}{ predicted associations for the novel speices of tree1 }
+  \item{pred.novels2}{ predicted associations for the novel speices of tree2 }
 }
 
+
+
 \note{Covariates that apply to both species sets (e.g., sampling site) should be supplied in the covariate matrix of the set with the most species.
 \cr
 \cr
 Bootstrapping CIs is slow due to the function \code{\link{optim}} used to estimate the model parameters. See appendix A in Ives and Godfray (2006) 
-for a discussion about this boostrapping procedure}
-
-
-
+for a discussion about this boostrapping procedure
+\cr
+\cr
+If \code{pblmpredict=TRUE} the function does not first remove each species in turn when predicting the associations of the original species as 
+is done in Ives and Godfray (2006).}
+ 
 \references{Ives A.R. & Godfray H.C. (2006) Phylogenetic analysis of trophic associations. The American Naturalist, 168, E1-E14 \cr
 \cr
 Blomberg S.P., Garland T.J. & Ives A.R. (2003) Testing for phylogenetic signal in comparative data: Behavioral traits are more labile. Evolution, 57, 717-745