enumeratorerrorssummary.R

# WARNING - Generated by {fusen} from dev/function_documentation.Rmd: do not edit by hand


#' @name enumeratorErrorsSummary
#' @rdname enumeratorErrorsSummary
#' @title Create a dashboard displaying the number of errors by enumerators
#' @description This function display the number of errors made by the enumerator, one graph is generated by enumerator showing for each
#'
#' @param enumeratorID name of the field where the enumerator ID is stored: string
#' @param surveyConsent name of the field in the dataset where the survey consent is stored: string
#' @param consentForValidSurvey value defined in the kobo form to acknowledge the surveyed person gave his consent: string
#' @param reports reports names generated from the other checks included in this package, be sure when you choose the columns to be
#' included in each report generated that the enumeratorID is selected before including the report as a parameter to this function:
#' list of string(c(report1,report2,...))
#'
#' @return result a list that includes: 
#'   * dst      same dataset as the inputed one but with survey marked for deletion if errors are found and delete=TRUE (or NULL)
#'   * ret_log  list of the errors found (or NULL)
#'   * var      a list of value (or NULL)
#'   * graph    graphical representation of the results (or NULL)
#' @export enumeratorErrorsSummary
#' @examples
#'
#' # enumeratorID <- "enumerator_id"
#' # reports <- c( "isInterviewCompleted",
#' #               "isInterviewInTheCorrectSite",
#' #               "isInterviewTooShort",
#' #               "isInterviewTooShortForTheHouseholdSize",
#' #               "isInterviewWithConsent",
#' #               "isSurveyEndBeforeItStarts",
#' #               "isSurveyMadeInTheFuture",
#' #               "isSurveyOnMoreThanADay",
#' #               "isSurveyStartedBeforeTheAssessment",
#' #               "isuniquerespondantIDDuplicated",
#' #               "isuniquerespondantIDMissing")
#' # 
#' # result <- enumeratorErrorsSummary(enumeratorID=enumeratorID,ds = ds,
#'                                       # surveyDate=surveyDate,
#'                                       # dateFormat=dateFormat,
#'                                       # surveyConsent=surveyConsent
#' #                                     reports=reports)
#' # print(result[["graph"]])
#'
enumeratorErrorsSummary <- function(enumeratorID=NULL,
                                      reports=NULL){
  
  tmp <- data.frame(Enumerator=character(0), 
                    Error=character(0), 
                    Nb=character(0), 
                    stringsAsFactors = FALSE)
  
  for(i in reports){
    tmp2 <- data.frame(eval(parse(text=paste0(i, " %>% dplyr::group_by(Enumerator=.data[[ enumeratorID ]]) %>%
                                              dplyr::summarise(Nb=dplyr::n()) %>%
                                              dplyr::mutate(Error=stringi::stri_replace_all_fixed(\"", i,"\", \"report\", \"\")) %>%
                                              dplyr::select(Enumerator, Error, Nb)"))), stringsAsFactors = FALSE)
    tmp <- rbind(tmp, tmp2)
  }

  if(nrow(tmp)!=0){
    graph <- ggplot2::ggplot(tmp) +
      ggplot2::geom_col(ggplot2::aes(x=Error, y=Nb)) +
      ggplot2::scale_y_continuous(breaks=seq(0, max(tmp$Nb), by=ceiling(max(tmp$Nb)/5))) +
      unhcrthemes::theme_unhcr(font_size = 14) +
      ggplot2::labs(title = "Enumerator Errors Summary",
                    x = "Error types", 
                    y="Numbers") +
      ggplot2::facet_wrap(ggplot2::vars(Enumerator), ncol=floor(40/length(unique(tmp$Error)))) +
      ggplot2::theme(axis.text.x = ggplot2::element_text(margin = ggplot2::margin(t = .3, unit = "cm"), angle = 90, vjust = .5, hjust=1),
                     panel.grid=ggplot2::element_line(linetype=3))
  } else {graph <- NULL}

  
  result <- list( dst = NULL, #  same dataset as the inputed one but with survey marked for deletion if errors are found and delete=TRUE (or NULL)
                  ret_log  = NULL, # list of the errors found (or NULL)
                  var = NULL, #  a list of value (or NULL)
                  graph = graph) # graphical representation of the results (or NULL)
  
  
  return(result)
}