surveybigvalues.R

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


#' @name surveyBigValues
#' @rdname surveyBigValues
#' @title Report the values greater than a specified value per specified fields
#' @description This function provide a report showing all values which are greater than a certain threshold for a specified list of fields.
#'
#' @param ds dataset containing the survey (from kobo): labelled data.frame
#' @param checkperiod if not null number of day before today when the check should be made
#' @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 questionsSurveyBigValues columns name from the dataset and value you want to check against (c(col1=value1,col2=value2,...)): named list of integer
#' @param uniquerespondantID name of the field where the survey unique ID is stored: string
#' @param enumeratorID name of the field where the enumerator ID is stored: string
#' @param reportingColumns (Optional, by default it is built from the enumeratorID and the uniquerespondantID) name of the columns from the dataset you want in the result: list of string (c('col1','col2',...))
#' @param enumeratorCheck (Optional, by default set to FALSE) specify if the report has to be displayed for each enumerator or not: boolean (TRUE/FALSE)
#'
#' @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 surveyBigValues
#' @examples
#' load(system.file("sample_dataset.RData", package = "HighFrequencyChecks")) 
#' ds <- sample_dataset
#' questionsSurveyBigValues <-c(consent_received.food_security.spend_food=25000,
#'                               consent_received.food_security.spend_medication=25000,
#'                               consent_received.food_security.spend_education=25000,
#'                               consent_received.food_security.spend_fix_shelter=25000,
#'                               consent_received.food_security.spend_clothing=25000,
#'                               consent_received.food_security.spend_hygiene=25000,
#'                               consent_received.food_security.spend_fuel=25000,
#'                               consent_received.food_security.spend_hh_items=25000,
#'                               consent_received.food_security.spend_transport=25000,
#'                               consent_received.food_security.spend_communication=25000,
#'                               consent_received.food_security.spend_tobacco=25000,
#'                               consent_received.food_security.spend_rent=25000,
#'                               consent_received.food_security.spend_debts=25000,
#'                               consent_received.food_security.spend_other=25000)
#' enumeratorID <- "enumerator_id"
#' uniquerespondantID <- "X_uuid"
#' reportingColumns <- c(enumeratorID, uniquerespondantID)
#'
#' result <- surveyBigValues(ds = ds,
#'                                                 questionsSurveyBigValues=questionsSurveyBigValues,
#'                                                 enumeratorID=enumeratorID,
#'                                                 reportingColumns=reportingColumns,
#'                                                 enumeratorCheck=FALSE)
#' knitr::kable(head(result[["ret_log"]], 10))  
surveyBigValues <- function(ds=NULL,
                            questionsSurveyBigValues=NULL,
                            enumeratorID=NULL,
                            reportingColumns=c(enumeratorID, uniquerespondantID),
                            enumeratorCheck=FALSE){
  if(is.null(ds) | nrow(ds)==0 | !is.data.frame(ds)){
    stop("Please provide the dataset")
  }
  if(is.null(questionsSurveyBigValues)){
    stop("Please provide the fields you want to check for (c('field1','field2',...))")
  }
  if(is.null(reportingColumns) | !is.character(reportingColumns)){
    stop("Please provide the columns you want in the result (include the enumerator id column if you want to check by enumerator)")
  }
  if(is.null(enumeratorCheck) | !is.logical(enumeratorCheck)){
    stop("Please provide the enumeratorcheck action to be done (TRUE/FALSE)")
  }
  if(isTRUE(enumeratorCheck) & (is.null(enumeratorID) | !is.character(enumeratorID))){
    stop("Please provide the field where the enumerator ID is stored")
  }

  tmp <- data.frame(ds[reportingColumns], utils::stack(ds[names(questionsSurveyBigValues)]), stringsAsFactors = FALSE)
  # ret_log  <- subset(tmp, values>=value)
  ret_log  <- data.frame()
  for(i in 1:length(questionsSurveyBigValues)){
    ret_log  <- rbind(ret_log , subset(tmp[tmp$ind==names(questionsSurveyBigValues[i]),], values>=questionsSurveyBigValues[i]))
  }
   
 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  = ret_log , # list of the errors found (or NULL)
                  var = NULL, #  a list of value (or NULL)
                  graph = NULL) # graphical representation of the results (or NULL)
  
  
  return(result)
}