R/results_get.R

In cloudyr/crowdflower: R Client for the CrowdFlower API

#' @title Retrieve rows with judgment information for a job.
#' @description \code{results_get} retrieves rows with judgment information for the job ID indicated in the request. Specifying \code{unit} retrieves only judgments for a specific row (unit).
#' @details Note that multiple choice responses get aggregated by collapsing all responses into a single value.
#' @param id A character string containing an ID for job.
#' @param n Number of rows to return. Specify only \code{n} or \code{unit}, but not both.
#' @param unit A \dQuote{unit id} for a specific row. Specify only \code{n} or \code{unit}, but not both.
#' @param type How responses should be aggregated ("aggregate", to take aggregated responses; or "full" for all responses)
#' @param verbose A logical indicating whether to print additional information about the request.
#' @param ... Additional arguments passed to \code{\link{cf_query}}.
#' @return A data.frame containing judgment information
#' @examples
#' \dontrun{
#' # create new job
#' f1 <- system.file("templates/instructions1.html", package = "crowdflower")
#' f2 <- system.file("templates/cml1.xml", package = "crowdflower")
#' j <- job_create(title = "Job Title", 
#'                 instructions = readChar(f1, nchars = 1e8L),
#'                 cml = readChar(f2, nchars = 1e8L))
#'
#' # add data
#' d <- data.frame(variable = 1:3)
#' job_add_data(id = j, data = d)
#'
#' # launch job
#' job_launch(id = j)
#' 
#' # get first result
#' results_get(id = j, n = 1)
#' 
#' # get all results
#' results_get(id = j)
#' 
#' # delete job
#' job_delete(j)
#' }
#' @seealso \code{\link{job_status}}, \code{\link{report_get}}
#' @keywords jobs data
#' @export
results_get <- function(id, n=Inf, unit = NULL, type = c("aggregated", "full"), verbose = TRUE, ...){

    if (!is.null(unit)) {
        # initial API request
        endpoint <- paste0('jobs/', id, 'units/', unit, '/judgments.json')
        rows <- cf_query(endpoint, ...)
        dat <- rowDataToDF(rows, match.arg(type))
    } else {
        # initial API request
        endpoint <- paste0('jobs/', id, '/judgments.json')
        rows <- newrows <- cf_query(endpoint, query = list(page = 1), ...)
        
        if (verbose) {
            message(length(rows), ' rows downloaded')
        }

        if (n > 100) {
            # if more than 100 are requested, continue until
            # n is reached, or when no more data is returned        
            page <- 2
            while (length(rows) <= n && length(newrows) > 0) {
                newrows <- cf_query(endpoint, query = list(page = page), ...)
                if (length(newrows) > 0) {
                    rows <- c(rows, newrows)
                    page <- page + 1
                    if (verbose) {
                        message(length(rows), ' rows downloaded')
                    }
                }
            }
        }
        dat <- rowDataToDF(rows, match.arg(type))
    }
    return(dat)
}