added doc for Param_Fn...

... plus other small fixes

.Rbuildignore

@@ -1,3 +1,4 @@
 ^\.git$
 cran-comments.md
-^\.travis\.yml$
+^\.travis\.yml$
+^examples$

NAMESPACE

@@ -4,6 +4,7 @@ export(Build_TMB_Fn)
 export(Coherence)
 export(Crossvalidate_Fn)
 export(Data_Fn)
+export(Param_Fn)
 export(Plot_Overdispersion)
 export(Plot_factors)
 export(Summarize)

R/Build_TMB_Fn.R

@@ -57,8 +57,8 @@ function( TmbData, Version, Q_Config=TRUE, CovConfig=TRUE,
     # DataList=TmbData                                              # VAST:::
   if( length(Parameters)==1 && Parameters=="generate" ) Parameters = Param_Fn( Version=Version, DataList=TmbData, RhoConfig=RhoConfig )
 
-  # Which parameters are turned off                # VAST:::
-  if( length(Map)==1 && Map=="generate" ) Map = Make_Map( TmbData=TmbData, TmbParams=Parameters, CovConfig=CovConfig, Q_Config=Q_Config, RhoConfig=RhoConfig)
+  # Which parameters are turned off                #
+  if( length(Map)==1 && Map=="generate" ) Map = VAST:::Make_Map( TmbData=TmbData, TmbParams=Parameters, CovConfig=CovConfig, Q_Config=Q_Config, RhoConfig=RhoConfig)
 
   # Which are random
   if( length(Random)==1 && Random=="generate" ){

R/Param_Fn.R

@@ -1,3 +1,47 @@
+#' Calculate parameter inputs for TMB
+#'
+#' \code{Param_Fn} generates the \code{parameters} input for \code{TMB::MakeADFun}
+#'
+#' @param DataList list outputted from \code{VAST::Data_Fn}
+#' @inheritParams Data_Fn
+
+#' @return Tagged list containing starting values for all fixed effects (parameters) and random effects (coefficients)
+#' \describe{
+#'   \item{ln_H_input}{two parameters governing geometric anisotropy (rotation matrix H)}
+#'   \item{beta1_ct}{intercepts for encounter probability}
+#'   \item{gamma1_j}{effect of density covariates that are static over time on encounter prob}
+#'   \item{gamma1_ctp}{effect of density covariates that change over time on encounter prob}
+#'   \item{lambda1_k}{effect of catchability covariates on encounter prob}
+#'   \item{L1_z}{trimmed cholesky (i.e., parameters for square-root of covariance) for overdispersion in encounter prob}
+#'   \item{L_omega1_z}{trimmed cholesky pointwise variance in spatial variation in encounter prob}
+#'   \item{L_epsilon1_z}{trimmed cholesky pointwise variance in spatio-temporal variation in encounter prob}
+#'   \item{logkappa1}{governs decorrelation distance in encounter prob}
+#'   \item{Beta_mean1}{average intercept of encounter prob (used with RhoConfig options)}
+#'   \item{logsigmaB1}{SD for intercept of encounter prob (used with RhoConfig options)}
+#'   \item{Beta_rho1}{first-order autoregressive coefficient for intercept of encounter prob (used with RhoConfig options)}
+#'   \item{Epsilon_rho1}{first-order autoregressive coefficient for spatio-temporal variation of encounter prob (used with RhoConfig options)}
+#'   \item{eta1_vf}{overdispersion parameters (i.e., vessel or tow-level effects) on encounter prob}
+#'   \item{Omegainput1_sf}{Spatial variation in encounter prob}
+#'   \item{Epsiloninput1_sft}{Spatio-temporal variation in encounter prob}
+#'   \item{beta2_ct}{intercepts for positive catch rates}
+#'   \item{gamma2_j}{effect of density covariates that are static over time on positive catch rates}
+#'   \item{gamma2_ctp}{effect of density covariates that change over time on positive catch rates}
+#'   \item{lambda2_k}{effect of catchability covariates on positive catch rates}
+#'   \item{L2_z}{trimmed cholesky (i.e., parameters for square-root of covariance) for overdispersion in positive catch rates}
+#'   \item{L_omega2_z}{trimmed cholesky pointwise variance in spatial variation in positive catch rates}
+#'   \item{L_epsilon2_z}{trimmed cholesky pointwise variance in spatio-temporal variation in positive catch rates}
+#'   \item{logkappa2}{governs decorrelation distance in positive catch rates}
+#'   \item{Beta_mean2}{average intercept of positive catch rates (used with RhoConfig options)}
+#'   \item{logsigmaB2}{SD for intercept of positive catch rates (used with RhoConfig options)}
+#'   \item{Beta_rho2}{first-order autoregressive coefficient for intercept of positive catch rates (used with RhoConfig options)}
+#'   \item{Epsilon_rho2}{first-order autoregressive coefficient for spatio-temporal variation of positive catch rates (used with RhoConfig options)}
+#'   \item{eta2_vf}{overdispersion parameters (i.e., vessel or tow-level effects) on positive catch rates}
+#'   \item{Omegainput2_sf}{Spatial variation in positive catch rates}
+#'   \item{Epsiloninput2_sft}{Spatio-temporal variation in positive catch rates}
+#'   \item{logSigmaM}{variance parameters for positive catch ratesA}
+#' }
+
+#' @export
 Param_Fn <-
 function( Version, DataList, RhoConfig=c("Beta1"=0,"Beta2"=0,"Epsilon1"=0,"Epsilon2"=0) ){
   #

man/Coherence.Rd

@@ -4,22 +4,21 @@
 \alias{Coherence}
 \title{Calculate stability metrics}
 \usage{
-Coherence(Report, Data, covhat = NULL, year_set = NULL)
+Coherence(Report, Data, covhat = NULL, yearbounds_zz = matrix(c(1,
+  Data$n_t), nrow = 1))
 }
 \arguments{
 \item{Report}{output report, e.g., from \code{Report <- obj$report()}}
 
 \item{Data}{tagged list of input data}
 
 \item{covhat}{estimated covariance used for calculating coherence}
-
-\item{year_set}{subset of year-indices used when calculating buffering}
 }
 \value{
 Tagged list containing measures of synchrony
 \describe{
-  \item{phi_x}{Synchrony index for each site}
-  \item{phi}{weighted-average of \code{phi_x} weighted by community-abundance at each site}
+  \item{phi_xz}{Synchrony index for each site (x) and each period (row of \code{yearbounds_zz})}
+  \item{phi_z}{weighted-average of \code{phi_xz} for each period, weighted by average community-abundance at each site in that period}
   \item{psi}{Measure of proportion of variance explained by leading eigen-vectors}
   \item{L_c}{Cholesky decomposition of \code{covhat}}
 }

man/Data_Fn.Rd

@@ -9,9 +9,10 @@ Data_Fn(Version, FieldConfig, OverdispersionConfig = c(eta1 = 0, eta2 = 0),
   MeshList, GridList, Method, v_i = rep(0, length(b_i)), PredTF_i = rep(0,
   length(b_i)), X_xj = NULL, X_xtp = NULL, Q_ik = NULL, Aniso = 1,
   RhoConfig = c(Beta1 = 0, Beta2 = 0, Epsilon1 = 0, Epsilon2 = 0),
-  Options = c(SD_site_density = 0, SD_site_logdensity = 0, Calculate_Range =
-  0, Calculate_evenness = 0, Calculate_effective_area = 0, Calculate_Cov_SE =
-  0), CheckForErrors = TRUE)
+  CheckForErrors = TRUE, yearbounds_zz = NULL, Options = c(SD_site_density
+  = 0, SD_site_logdensity = 0, Calculate_Range = 0, Calculate_evenness = 0,
+  Calculate_effective_area = 0, Calculate_Cov_SE = 0, Calculate_Synchrony = 0,
+  Calculate_Coherence = 0))
 }
 \arguments{
 \item{Version}{a version number (see example for current default).}
@@ -54,9 +55,11 @@ Data_Fn(Version, FieldConfig, OverdispersionConfig = c(eta1 = 0, eta2 = 0),
 
 \item{RhoConfig}{OPTIONAL, vector of form c("Beta1"=0,"Beta2"=0,"Epsilon1"=0,"Epsilon2"=0) specifying whether either intercepts (Beta1 and Beta2) or spatio-temporal variation (Epsilon1 and Epsilon2) is structured among time intervals}
 
-\item{Options}{OPTIONAL, a vector of form c('SD_site_density'=0,'SD_site_logdensity'=0,'Calculate_Range'=0,'Calculate_evenness'=0,'Calculate_effective_area'=0,'Calculate_Cov_SE'=0), where Calculate_Range=1 turns on calculation of center of gravity, and Calculate_effective_area=1 turns on calculation of effective area occupied}
-
 \item{CheckForErrors}{OPTIONAL, whether to check for errors in input (NOTE: when CheckForErrors=TRUE, the function will throw an error if it detects a problem with inputs.  However, failing to throw an error is no guaruntee that the inputs are all correct)}
+
+\item{yearbounds_zz}{OPTIONAL, matrix with two columns, giving first and last years for defining one or more periods (rows) used to calculate changes in synchrony over time (only used if \code{Options['Calculate_Synchrony']=1})}
+
+\item{Options}{OPTIONAL, a vector of form c('SD_site_density'=0,'SD_site_logdensity'=0,'Calculate_Range'=0,'Calculate_evenness'=0,'Calculate_effective_area'=0,'Calculate_Cov_SE'=0,'Calculate_Synchrony'=0,'Calculate_Coherence'=0), where Calculate_Range=1 turns on calculation of center of gravity, and Calculate_effective_area=1 turns on calculation of effective area occupied}
 }
 \value{
 Tagged list containing inputs to function Build_TMB_Fn()

man/Param_Fn.Rd

@@ -0,0 +1,57 @@
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/Param_Fn.R
+\name{Param_Fn}
+\alias{Param_Fn}
+\title{Calculate parameter inputs for TMB}
+\usage{
+Param_Fn(Version, DataList, RhoConfig = c(Beta1 = 0, Beta2 = 0, Epsilon1 = 0,
+  Epsilon2 = 0))
+}
+\arguments{
+\item{Version}{a version number (see example for current default).}
+
+\item{DataList}{list outputted from \code{VAST::Data_Fn}}
+
+\item{RhoConfig}{OPTIONAL, vector of form c("Beta1"=0,"Beta2"=0,"Epsilon1"=0,"Epsilon2"=0) specifying whether either intercepts (Beta1 and Beta2) or spatio-temporal variation (Epsilon1 and Epsilon2) is structured among time intervals}
+}
+\value{
+Tagged list containing starting values for all fixed effects (parameters) and random effects (coefficients)
+\describe{
+  \item{ln_H_input}{two parameters governing geometric anisotropy (rotation matrix H)}
+  \item{beta1_ct}{intercepts for encounter probability}
+  \item{gamma1_j}{effect of density covariates that are static over time on encounter prob}
+  \item{gamma1_ctp}{effect of density covariates that change over time on encounter prob}
+  \item{lambda1_k}{effect of catchability covariates on encounter prob}
+  \item{L1_z}{trimmed cholesky (i.e., parameters for square-root of covariance) for overdispersion in encounter prob}
+  \item{L_omega1_z}{trimmed cholesky pointwise variance in spatial variation in encounter prob}
+  \item{L_epsilon1_z}{trimmed cholesky pointwise variance in spatio-temporal variation in encounter prob}
+  \item{logkappa1}{governs decorrelation distance in encounter prob}
+  \item{Beta_mean1}{average intercept of encounter prob (used with RhoConfig options)}
+  \item{logsigmaB1}{SD for intercept of encounter prob (used with RhoConfig options)}
+  \item{Beta_rho1}{first-order autoregressive coefficient for intercept of encounter prob (used with RhoConfig options)}
+  \item{Epsilon_rho1}{first-order autoregressive coefficient for spatio-temporal variation of encounter prob (used with RhoConfig options)}
+  \item{eta1_vf}{overdispersion parameters (i.e., vessel or tow-level effects) on encounter prob}
+  \item{Omegainput1_sf}{Spatial variation in encounter prob}
+  \item{Epsiloninput1_sft}{Spatio-temporal variation in encounter prob}
+  \item{beta2_ct}{intercepts for positive catch rates}
+  \item{gamma2_j}{effect of density covariates that are static over time on positive catch rates}
+  \item{gamma2_ctp}{effect of density covariates that change over time on positive catch rates}
+  \item{lambda2_k}{effect of catchability covariates on positive catch rates}
+  \item{L2_z}{trimmed cholesky (i.e., parameters for square-root of covariance) for overdispersion in positive catch rates}
+  \item{L_omega2_z}{trimmed cholesky pointwise variance in spatial variation in positive catch rates}
+  \item{L_epsilon2_z}{trimmed cholesky pointwise variance in spatio-temporal variation in positive catch rates}
+  \item{logkappa2}{governs decorrelation distance in positive catch rates}
+  \item{Beta_mean2}{average intercept of positive catch rates (used with RhoConfig options)}
+  \item{logsigmaB2}{SD for intercept of positive catch rates (used with RhoConfig options)}
+  \item{Beta_rho2}{first-order autoregressive coefficient for intercept of positive catch rates (used with RhoConfig options)}
+  \item{Epsilon_rho2}{first-order autoregressive coefficient for spatio-temporal variation of positive catch rates (used with RhoConfig options)}
+  \item{eta2_vf}{overdispersion parameters (i.e., vessel or tow-level effects) on positive catch rates}
+  \item{Omegainput2_sf}{Spatial variation in positive catch rates}
+  \item{Epsiloninput2_sft}{Spatio-temporal variation in positive catch rates}
+  \item{logSigmaM}{variance parameters for positive catch ratesA}
+}
+}
+\description{
+\code{Param_Fn} generates the \code{parameters} input for \code{TMB::MakeADFun}
+}
+