From b41c6345be3c0a5abc961888a3606ba2e82ad2f6 Mon Sep 17 00:00:00 2001
From: Jim Thorson <James.T.Thorson@gmail.com>
Date: Sun, 17 Nov 2024 10:47:51 -0800
Subject: [PATCH] update docs

---
 R/compute_nll.R    |  1 +
 R/ecostate.R       |  2 +-
 man/compute_nll.Rd | 12 +++++++++---
 man/ecostate.Rd    | 19 +++++++++++++++++++
 4 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/R/compute_nll.R b/R/compute_nll.R
index 34a1c53..fb4d54e 100644
--- a/R/compute_nll.R
+++ b/R/compute_nll.R
@@ -6,6 +6,7 @@
 #'
 #' @inheritParams add_equilibrium
 #' @inheritParams dBdt
+#' @inheritParams ecostate
 #'
 #' @param p list of parameters
 #' @param control output from \link{ecostate_control}
diff --git a/R/ecostate.R b/R/ecostate.R
index 3008eeb..486e869 100644
--- a/R/ecostate.R
+++ b/R/ecostate.R
@@ -4,7 +4,7 @@
 #' @description 
 #' Estimate parameters for an EcoState model
 #'
-#' @param taxa Character vector of taxa included in model. 
+#' @param taxa Character vector of taxa included in model.
 #' @param years Integer-vector of years included in model                  
 #' @param catch long-form data frame with columns \code{Mass}, \code{Year}
 #'        and  \code{Taxon}
diff --git a/man/compute_nll.Rd b/man/compute_nll.Rd
index 8aa7dbb..84d964d 100644
--- a/man/compute_nll.Rd
+++ b/man/compute_nll.Rd
@@ -11,9 +11,9 @@ compute_nll(
   n_species,
   project_vars,
   DC_ij,
-  logQB_i,
   Bobs_ti,
   Cobs_ti,
+  log_prior,
   control
 )
 }
@@ -31,12 +31,18 @@ compute_nll(
 
 \item{DC_ij}{Diet projections matrix}
 
-\item{logQB_i}{log of QB}
-
 \item{Bobs_ti}{matrix of biomass observations}
 
 \item{Cobs_ti}{matrix of catch observations}
 
+\item{log_prior}{A user-provided function that takes as input the list of
+parameters \code{out$obj$env$parList()} where \code{out} is the output from
+\code{ecostate()}, and returns a numeric vector
+where the sum is the log-prior probability.  For example
+\code{log_prior = function(p) dnorm( p$logq_i[1], mean=0, sd=0.1, log=TRUE)}
+specifies a lognormal prior probability for the catchability coefficient
+for the first \code{taxa} with logmean of zero and logsd of 0.1}
+
 \item{control}{output from \link{ecostate_control}}
 }
 \description{
diff --git a/man/ecostate.Rd b/man/ecostate.Rd
index 1010a09..f729c75 100644
--- a/man/ecostate.Rd
+++ b/man/ecostate.Rd
@@ -21,7 +21,10 @@ ecostate(
   fit_Q = vector(),
   fit_B0 = vector(),
   fit_EE = vector(),
+  fit_PB = vector(),
+  fit_QB = vector(),
   fit_eps = vector(),
+  log_prior = function(p) 0,
   control = ecostate_control()
 )
 }
@@ -78,9 +81,25 @@ to equilibrium biomass is estimated as a fixed effect}
 \item{fit_EE}{Character-vector listing \code{taxa} for which to estimate
 ecotrophic efficiency}
 
+\item{fit_PB}{Character-vector listing \code{taxa} for which equilibrium
+production per biomass is estimated.  Note that it is likely
+a good idea to include a prior for any species for which this is estimated.}
+
+\item{fit_QB}{Character-vector listing \code{taxa} for which equilibrium
+consumption per biomass is estimated.  Note that it is likely
+a good idea to include a prior for any species for which this is estimated.}
+
 \item{fit_eps}{Character-vector listing \code{taxa} for which the
 model should estimate annual process errors in dB/dt}
 
+\item{log_prior}{A user-provided function that takes as input the list of
+parameters \code{out$obj$env$parList()} where \code{out} is the output from
+\code{ecostate()}, and returns a numeric vector
+where the sum is the log-prior probability.  For example
+\code{log_prior = function(p) dnorm( p$logq_i[1], mean=0, sd=0.1, log=TRUE)}
+specifies a lognormal prior probability for the catchability coefficient
+for the first \code{taxa} with logmean of zero and logsd of 0.1}
+
 \item{control}{Output from \code{\link[=ecostate_control]{ecostate_control()}}, used to define user
 settings.}
 }