R/get_data.R

In bpresentati/surveyR: surveyR: Get things done with LimeSurvey!

#' This is a very simple function to setup access to limesurvey for the user
#'
#' Writes the parameters as global options, which can be used by all of the functions
#' @param url this is the url to the limesurvey instance's remotecontrol
#' @param username this is the individual's / team's LS username
#' @param password this is the individual's / team's LS password
#' @keywords Setup
#' @export
#' @examples
#' Setup_Limesurvey(url = 'https://survey.statista-research.com/admin/remotecontrol', username = 'beepee', password = '23908fjkh')
Setup_Limesurvey <- function(url, username, password){
  base::options(lime_api = url)
  base::options(lime_username = username)
  base::options(lime_password = password)
}




#' Convert the base64 encoded raw data from LS into a csv-type.
#'
#' Note: download of a multi-part survey will fail with an error that base64 conversion could not be made if at least one of the survey components has no data. This does not mean this function has a problem- it means you should wait for the data!
#' @param x this is the data stream from limesurvey
#' @keywords Basis function
#' @export
#' @examples
#' bp_base64_to_df()
bp_base64_to_df <- function(x) {
  raw_csv <- base::rawToChar(base64enc::base64decode(x))

  return(utils::read.csv(base::textConnection(raw_csv), stringsAsFactors = FALSE, sep = ";", fileEncoding = "UTF-8", encoding="UTF-8"))
}




#' This is the Limesurvey download function
#'
#' Note: download of a multi-part survey will fail with an error that base64 conversion could not be made if at least one of the survey components has no data. This does not mean this function has a problem- it means you should wait for the data!
#' @param Survey_IDs this is a vector with the Limesurvey survey IDs of all the parts in the correct order
#' @param language this is a two character text string defining the survey language- "en" for English, "fr" for French, "de" for German, etc.
#' @keywords Download Limesurvey Surveys
#' @export
#' @examples Cint_Surveys_0 <- Get_Surveys_with_Clickouts_dt(Survey_IDs_Cint)
#' @import magrittr
Get_Surveys_with_Clickouts_dt <- function(Survey_IDs, language = "en"){

  get_session_key()  # Log in

  Survey_IDs <- Survey_IDs
  Surveys <- list()

  for (i in Survey_IDs)
  {
    Surveys[[match(i,Survey_IDs)]] <-  call_limer(method = "export_responses",
                                                  params = list(iSurveyID = i,
                                                                sDocumentType = "csv",
                                                                sLanguageCode = language,
                                                                sCompletionStatus = "all",
                                                                sHeadingType = "code",
                                                                sResponseType = "short"))%>%bp_base64_to_df()%>%data.table::setDT()
  } # end for loop
  return(Surveys)
  release_session_key() # Log out
} # end function Get_Surveys_with_Clickouts_dt




#' NEW NEW NEW (20210804)
#' This is a more general Limesurvey download function- it detects their (base) language automatically
#'
#' Note: download of a multi-part survey (or multiple single surveys) will fail with an error that base64 conversion could not be made if at least one of the surveys/components has no data. This does not mean this function has a problem- it means you should wait for the data!
#' @param Survey_IDs this is a vector with the Limesurvey survey IDs of all the parts in the correct order (if they are ordered survey parts)
#' @param DocumentType The default value is "csv". This is the format that you wish to have returned- possible options are "pdf", "csv", "xls", "doc", and "json"- none of which have been tested! There's no real reason to change this from the default! Use at your own risk!
#' @param CompletionStatus The default value is "all". Other options are "complete", and "incomplete".
#' @param HeadingType The default value is "code". Other options include "full", and "abbreviated".
#' @param ResponseType The default value is "short". Other options include "long".
#' @keywords Download Limesurvey Surveys
#' @export
#' @examples Cint_Surveys_0 <- Get_Surveys_Automatic(Survey_IDs_Cint)
#' @import magrittr
Get_Surveys_Automatic <- function(Survey_IDs, DocumentType = "csv", CompletionStatus = "all", HeadingType = "code", ResponseType = "short"){

  get_session_key()  # Log in

  # Error Message:
  Error_Message <- data.table::data.table(dummy = 1, Error_Text = "Error: This survey is either inactive or does not seem to have any data to export")

  # Get the general survey list in order to look up the Limesurvey Survey Names
  Limesurvey_Survey_List <- call_limer(method = "list_surveys",
                                       params = list(
                                       ))%>%data.table::setDT()


  Survey_IDs <- Survey_IDs
  Surveys <- list()

  for (i in Survey_IDs)
  {

    possibleError <- tryCatch(
      {
        survey_properties <-  call_limer(method = "get_survey_properties",
                                         params = list(iSurveyID = i
                                         ))


        Surveys[[paste0(i)]] <-  call_limer(method = "export_responses",
                                            params = list(iSurveyID = i,
                                                          sDocumentType = DocumentType,
                                                          sLanguageCode = survey_properties[["language"]],
                                                          sCompletionStatus = CompletionStatus,
                                                          sHeadingType = HeadingType,
                                                          sResponseType = ResponseType))%>%bp_base64_to_df()%>%data.table::setDT()

        Surveys[[paste0(i)]]$surveyName <- Limesurvey_Survey_List[sid == paste0(i)]$surveyls_title
        Surveys[[paste0(i)]]$surveyId <- i
        setcolorder(Surveys[[paste0(i)]], neworder = c("surveyName", "surveyId"))


      }, # end first part of tryCatch
      error = function(e) e)

    # If there's a problem:
    if(inherits(possibleError, "error"))
    {
      Surveys[[paste0(i)]] <- Error_Message
    }

  } # end for loop

  return(Surveys)
  release_session_key() # Log out
} # end function Get_Surveys_Automatic