document densities functions

* issue #630

* update documentation style

inst/include/distributions/functors/density_components_base.hpp

@@ -33,13 +33,13 @@ struct DensityComponentBase : public fims_model_object::FIMSObject<Type> {
   // this is like a memory tracker.
   // Assigning each one its own ID is a way to keep track of
   // all the instances of the DensityComponentBase class.
-  static uint32_t id_g;
- fims::Vector<Type> observed_values;
- fims::Vector<Type> expected_values;
- fims::Vector<Type> nll_vec;
- std::string  nll_type; //prior, re, data
- bool osa_flag = false;
- bool simulate_flag = false;
+ static uint32_t id_g; /**< global unique identifier for distribution modules */
+ fims::Vector<Type> observed_values; /**< input value of distribution function */
+ fims::Vector<Type> expected_values; /**< expected value of distribution function */
+ fims::Vector<Type> nll_vec; /**< vector to record observation level negative log-likelihood values */
+ std::string  nll_type; /**< string classifies the type of the negative log-likelihood; options are: prior, re, data */
+ bool osa_flag = false; /**< Boolean; if true, osa residuals are calculated */
+ bool simulate_flag = false; /**< Boolean; if true, data are simulated from the distribution */
 
   /** @brief Constructor.
    */

inst/include/distributions/functors/lognormal_lpdf.hpp

@@ -1,3 +1,15 @@
+/*
+ * File:   lognormal_lpdf.hpp
+ *
+ * This File is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the
+ * source folder for reuse information.
+ *
+ * Lognormal Log Probability Density Function (LPDF) module file
+ * The purpose of this file is to define the Lognormal LPDF class and its fields
+ * and return the log probability density function.
+ *
+ */
 #ifndef LOGNORMAL_LPDF
 #define LOGNORMAL_LPDF
 
@@ -13,22 +25,30 @@ namespace fims_distributions
     template <typename Type>
     struct LogNormalLPDF : public DensityComponentBase<Type>
     {
-        fims::Vector<Type> log_sd;
-        fims::Vector<Type> mu;
-        fims::Vector<Type> sd;
-        std::vector<bool> is_na;
+        fims::Vector<Type> log_sd; /**< log of the standard deviation of the distribution on the log scale; can be a vector or scalar */
+        fims::Vector<Type> mu; /**< mean of the distribution on the log scale; can be a vector or scalar */
+        fims::Vector<Type> sd; /**< standard deviation of the distribution on the log scale; can be a vector or scalar */
+        std::vector<bool> is_na; /**< Boolean; if true, data observation is NA and the likelihood contribution is skipped */
         #ifdef TMB_MODEL
-        ::objective_function<Type> *of;
+        ::objective_function<Type> *of; /**< Pointer to the TMB objective function */
         #endif
-        Type nll = 0.0;
-        // data_indicator<tmbutils::vector<Type> , Type> keep;
+        Type nll = 0.0; /**< total negative log-likelihood contribution of the distribution */
+        // data_indicator<tmbutils::vector<Type> , Type> keep; /**< Indicator used in TMB one-step-ahead residual calculations */
 
+        /** @brief Constructor.
+         */
         LogNormalLPDF() : DensityComponentBase<Type>()
         {
         }
 
+        /** @brief Destructor.
+         */
         virtual ~LogNormalLPDF() {}
 
+        /**
+         * @brief Evaluates the negative log-likelihood of the lognormal probability density function
+         * @param do_log Boolean; if true, log densities are returned
+         */
         virtual const Type evaluate(const bool &do_log)
         {
             this->mu.resize(this->observed_values.size());

inst/include/distributions/functors/multinomial_lpmf.hpp

@@ -1,3 +1,16 @@
+/*
+ * File:   multinomial_lpmf.hpp
+ *
+ * This File is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the
+ * source folder for reuse information.
+ *
+ * Multinomial Log Probability Mass Function (LPMF) module file
+ * The purpose of this file is to define the Multinomial LPMF class and its fields
+ * and return the log probability mass function.
+ *
+ */
+
 #ifndef MULTINOMIAL_LPMF
 #define MULTINOMIAL_LPMF
 
@@ -13,20 +26,28 @@ namespace fims_distributions
     template <typename Type>
     struct MultinomialLPMF : public DensityComponentBase<Type>
     {
-        Type nll = 0.0;
-        fims::Vector<size_t> dims;
-        std::vector<bool> is_na;
+        Type nll = 0.0; /**< total negative log-likelihood contribution of the distribution */
+        fims::Vector<size_t> dims; /**< Dimensions of the number of rows and columns of the multivariate dataset */
+        std::vector<bool> is_na; /**< Boolean; if true, data observation is NA and the likelihood contribution for the entire row is skipped */
         #ifdef TMB_MODEL
-        ::objective_function<Type> *of;
+        ::objective_function<Type> *of; /**< Pointer to the TMB objective function */
         #endif
-        // data_indicator<tmbutils::vector<Type> , Type> keep;
+        // data_indicator<tmbutils::vector<Type> , Type> keep;  /**< Indicator used in TMB one-step-ahead residual calculations */
 
+        /** @brief Constructor.
+         */
         MultinomialLPMF() : DensityComponentBase<Type>()
         {
         }
 
+        /** @brief Destructor.
+         */
         virtual ~MultinomialLPMF() {}
 
+        /**
+         * @brief Evaluates the negative log-likelihood of the multinomial probability mass function
+         * @param do_log Boolean; if true, log densities are returned
+         */
         virtual const Type evaluate(const bool& do_log)
         {
             this->nll_vec.resize(dims[0]);

inst/include/distributions/functors/normal_lpdf.hpp

@@ -1,3 +1,16 @@
+/*
+ * File:   normal_lpdf.hpp
+ *
+ * This File is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the
+ * source folder for reuse information.
+ *
+ * Normal Log Probability Density Function (LPDF) module file
+ * The purpose of this file is to define the Normal LPDF class and its fields
+ * and return the log probability density function.
+ *
+ */
+
 #ifndef NORMAL_LPDF
 #define NORMAL_LPDF
 
@@ -11,22 +24,30 @@ namespace fims_distributions {
  */
 template<typename Type>
 struct NormalLPDF : public DensityComponentBase<Type> {
-    fims::Vector<Type> log_sd;
-    fims::Vector<Type> mu;
-    fims::Vector<Type> sd;
-    Type nll = 0.0;
-    std::vector<bool> is_na;
+    fims::Vector<Type> log_sd; /**< log of the standard deviation of the distribution; can be a vector or scalar */
+    fims::Vector<Type> mu; /**< mean of the distribution; can be a vector or scalar */
+    fims::Vector<Type> sd; /**< standard deviation of the distribution; can be a vector or scalar */
+    Type nll = 0.0; /**< total negative log-likelihood contribution of the distribution */
+    std::vector<bool> is_na; /**< Boolean; if true, data observation is NA and the likelihood contribution is skipped */
     #ifdef TMB_MODEL
-    ::objective_function<Type> *of;
+    ::objective_function<Type> *of; /**< Pointer to the TMB objective function */
     #endif
-    //data_indicator<tmbutils::vector<Type> , Type> keep;
+    //data_indicator<tmbutils::vector<Type> , Type> keep; /**< Indicator used in TMB one-step-ahead residual calculations */
 
+    /** @brief Constructor.
+     */
     NormalLPDF() : DensityComponentBase<Type>() {
 
     }
 
+    /** @brief Destructor.
+     */
     virtual ~NormalLPDF() {}
 
+    /**
+     * @brief Evaluates the negative log-likelihood of the normal probability density function
+     * @param do_log Boolean; if true, log densities are returned
+     */
     virtual const Type evaluate(const bool& do_log){
         this->mu.resize(this->observed_values.size());
         this->sd.resize(this->observed_values.size());

inst/include/interface/rcpp/rcpp_objects/rcpp_interface_base.hpp

@@ -74,12 +74,12 @@ uint32_t Parameter::id_g = 0;
  */
 class ParameterVector{
     static uint32_t id_g; /**< global identifier*/
-   
+
 public:
     Rcpp::List storage_m;  /**< list of parameter objects*/
     uint32_t id_m; /**< unique identifier*/
-    
-    
+
+
     /**
      *  @brief default constructor
      */
@@ -100,7 +100,8 @@ class ParameterVector{
     }
     /**
      *  @brief vector constructor
-     *  @param Rcpp::NumericVector, "size", number of elements to copy over.
+     *  @param x numeric vector
+     *  @param size number of elements to copy over
      */
     ParameterVector(Rcpp::NumericVector x, size_t size){
         this->id_m = ParameterVector::id_g++;
@@ -112,14 +113,14 @@ class ParameterVector{
 
     /**
      *  @brief Accessor. First index starts is zero.
-     *  @param return a Parameter at position "pos".
+     *  @param pos return a Parameter at position "pos".
      */
     inline Parameter operator[](R_xlen_t pos) {
         return this->storage_m[pos]; }
 
     /**
      *  @brief Accessor. First index is one. For calling from R.
-     *  @param return a Parameter at position "pos".
+     *  @param pos return a Parameter at position "pos".
      */
     SEXP at(R_xlen_t pos){
         if(pos == 0 || pos > this->storage_m.size()){
@@ -138,7 +139,7 @@ class ParameterVector{
 
     /**
      *  @brief resize to length "size"
-     *  @param resulting size.
+     *  @param size new length of vector to be resized
      */
     void resize(size_t size){
         size_t n = this->storage_m.size();
@@ -164,7 +165,7 @@ class ParameterVector{
     /**
      * @brief Sets all parameters within a vector as estimable
      *
-     * @param estimable A true value indicates the parameters are estimated in the model
+     * @param estimable Boolean; if true, all parameters are set to be estimated in the model
      */
     void set_all_estimable(bool estimable){
         for(R_xlen_t i = 0; i < this->storage_m.size(); i++){
@@ -177,7 +178,7 @@ class ParameterVector{
     /**
      * @brief Sets all parameters within a vector as random
      *
-     * @param random A true value indicates the parameters are random effects
+     * @param random Boolean; if true, all parameters are set to be random effects in the model
      */
     void set_all_random(bool random){
         for(R_xlen_t i = 0; i < this->storage_m.size(); i++){
@@ -202,7 +203,7 @@ class ParameterVector{
 
     /**
      * @brief Assigns the given values to the minimum value of all elements in the vector
-     * 
+     *
      * @param value The value to be assigned
      */
     void fill_min(double value){
@@ -215,7 +216,7 @@ class ParameterVector{
 
     /**
      * @brief Assigns the given values to the maximum value of all elements in the vector
-     * 
+     *
      * @param value The value to be assigned
      */
     void fill_max(double value){
@@ -225,7 +226,7 @@ class ParameterVector{
             this->storage_m[i] = Rcpp::wrap(p);
         }
     }
-    
+
 };
 uint32_t ParameterVector::id_g = 0;
 

inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp

@@ -66,7 +66,7 @@ class DnormDistributionsInterface : public DistributionsInterfaceBase {
   ParameterVector observed_values;    /**< observed data */
   ParameterVector expected_values; /**< mean of x for the normal distribution */
   ParameterVector log_sd;   /**< sd of x for the normal distribution */
-  Rcpp::LogicalVector is_na;
+  Rcpp::LogicalVector is_na; /**<Boolean; if true, data observation is NA and the likelihood contribution is skipped */
 
   DnormDistributionsInterface() : DistributionsInterfaceBase() {}
 
@@ -165,7 +165,7 @@ class DlnormDistributionsInterface : public DistributionsInterfaceBase {
   ParameterVector observed_values;       /**< observation */
   ParameterVector expected_values; /**< mean of the distribution of log(x) */
   ParameterVector log_sd;   /**< standard deviation of the distribution of log(x) */
-  Rcpp::LogicalVector is_na;
+  Rcpp::LogicalVector is_na; /**<Boolean; if true, data observation is NA and the likelihood contribution is skipped */
 
   DlnormDistributionsInterface() : DistributionsInterfaceBase() {}
 
@@ -267,8 +267,8 @@ class DmultinomDistributionsInterface : public DistributionsInterfaceBase {
   ParameterVector observed_values; /**< Vector of length K of integers */
   ParameterVector expected_values; /**< Vector of length K, specifying the probability
  for the K classes (note, unlike in R these must sum to 1). */
-  Rcpp::LogicalVector is_na;
-  Rcpp::NumericVector dims;
+  Rcpp::LogicalVector is_na; /**<Boolean; if true, data observation is NA and the likelihood contribution is skipped */
+  Rcpp::NumericVector dims; /**< Dimensions of the number of rows and columns of the multivariate dataset */
 
   DmultinomDistributionsInterface() : DistributionsInterfaceBase() {}