Added comments

R/PA_dose_response.R

@@ -1,4 +1,4 @@
-#' Calculate RR given PA
+#' Calculate RR given PA - CURRENTLY NOT USED
 #' 
 #' Calculate RR for a disease given PA
 #' 

R/gen_ap_rr.R

@@ -41,7 +41,7 @@ gen_ap_rr <- function(pm_conc_pp){
                        function(x)
                          which(colnames(pm_rr_pp) == paste0("pm_conc_",x)))
 
-  ### iterating over all disease outcomes that are related to air pollution
+  ### iterate over all disease outcomes that are related to PM pollution levels
   for (j in c(1:nrow(DISEASE_INVENTORY))[DISEASE_INVENTORY$air_pollution == 1]) {
 
     # initialise columns to store results

R/gen_pa_rr.R

@@ -1,37 +1,63 @@
-#' Get RR for diseases given mMETs
+#' Get relative risk for diseases given mMETs
 #' 
-#' Computes the RR for individuals for each disease given mMETs (PA exposure)
+#' Computes the relative risks (RR) for individuals in the synthetic population for each disease given their mMETs (PA exposure)
+#' 
+#' This function performs the following steps:
+#' - loop through all diseases that are related to physical activity levels:
+#'    - set the quantile of the value of the dose response curves to be extracted. If running in 
+#'      constant mode, the quantile is usually set to 0.5, i.e. to the median of the dose response curves. 
+#'      If running in sample mode, then the quantile can be set to be sampled from a distribution in the 
+#'      input parameters.
+#'    - create one vector containing all the mMET values for all scenarios
+#'    - assign the relative risk for the given disease and quantile to the 
+#'      given mMET values for all people in the synthetic population for all 
+#'      scenarios by calling the drpa::dose_response function
+#'    - extract the RR for each scenario from the vector containing all RR for all scenarios
+#'    - if confidence intervals are required, also extract the RR upper and lower
+#'      confidence values for each scenario
+#
 #' 
 #' @param mmets_pp individual mMETs
 #' 
 #' @return data frame of relative risks per person per disease
 #' 
 #' @export
+
+
 gen_pa_rr <- function(mmets_pp, conf_int = F){
-  ### iterating over all all disease outcomes
+
+
   dose_columns <- match(paste0(SCEN_SHORT_NAME, '_mmet'),colnames(mmets_pp))
+
+  # create one long vector containing all mMET values for the synthetic population for all scenarios
   doses_vector <- unlist(data.frame(mmets_pp[,dose_columns]))
+
+  ### iterate over all all disease outcomes that are related to physical activity levels
   for (j in c(1:nrow(DISEASE_INVENTORY))[DISEASE_INVENTORY$physical_activity == 1]) {
+
     # get name of PA DR curve
     pa_dn <- as.character(DISEASE_INVENTORY$pa_acronym[j])
+    # define the potential outcomes as either fatal or fatal-and-non-fatal
     outcome <- ifelse(DISEASE_INVENTORY$outcome[j] == "deaths", "fatal",
                       "fatal-and-non-fatal")
+
     # get name of disease
     pa_n <- as.character(DISEASE_INVENTORY$acronym[j])
-    ##RJ apply PA DR function to all doses as one long vector
-    #return_vector <- PA_dose_response(cause = pa_dn,dose = doses_vector)
+
+
 
     # Set quantile to the default value
     quant <- 0.5
     # Check if quantile for the the specific cause has been declared. 
-    # If yes, then use it instead
+    # If yes, then use the declared value instead
     if (exists(paste0('PA_DOSE_RESPONSE_QUANTILE_',pa_dn)))
       quant <- get(paste0('PA_DOSE_RESPONSE_QUANTILE_',pa_dn))
 
-    # Add quantile as the parameter
+    #Apply PA DR function to all doses as one long vector
     return_vector <- drpa::dose_response(cause = pa_dn, outcome_type = outcome,
                                          dose = doses_vector, quantile = quant, confidence_intervals = conf_int)
-    ##RJ take segments of returned vector corresponding to scenario
+
+    ##take segments of returned vector corresponding to each scenario
     for (i in 1:length(SCEN_SHORT_NAME)) {
       scen <- SCEN_SHORT_NAME[i]
       mmets_pp[[paste('RR_pa', scen, pa_n, sep = '_')]] <- return_vector$rr[(1 + (i - 1)*nrow(mmets_pp)):(i*nrow(mmets_pp))]