Rpgcli

R Client for PopGen Web Service

A set of R functions for calling the PopGen web service and for extracting data from the response.

Installation

Use devtools::install_github() to download the package from version control and install it:

install.packages("devtools")
library(devtools)
install_github("HSL/Rpgcli")

You will require R version 3.1 or later.

Usage

If you are behind a firewall and internet access is via a proxy, configure access with:

store_proxy_settings("name_of_proxy_server", 8080)

If on a corporate network, you will need to supply credentials too:

store_proxy_settings("name_of_corporate_proxy_server", 8080, "kevin", "pass123!")

If you are not already a PopGen user, go to PopGen, enter your email address, and follow the instructions.

Use the email address to initialize the service inputs:

parameters <- list(PopGenUserName = "[email protected]")

Add other required inputs with typical values:

parameters <- apply_defaults(parameters)

Call the PopGen web service:

pop_gen_out <- generate_population(parameters)

Check for success:

summary(pop_gen_out)

Extract population data as data frame:

individuals <- extract_individuals(pop_gen_out)

A more complete example

The following code samples from PopGen's four datasets. As PopGen throttles access to the service, this may take a minute or two to run to completion:

datasets <- c("P3M", "ICRP", "HSE", "NDNS")
n_datasets <- length(datasets)

data <- lapply(1:n_datasets, function(i) {

  dataset <- datasets[i]

  parameters <- list(
    Dataset = dataset,
    PopGenUserName = "[email protected]",
    PopulationSize = 100
    )

  if (dataset == "NDNS") {

    # Must override defaults for this dataset.
    # See https://discover.ukdataservice.ac.uk/series/?sn=2000033#abstract

    parameters$AgeLower <- 2
    parameters$AgeUpper <- 4

    parameters$BodyMassIndexLower <- 10

    parameters$HeightLower <- 80
    parameters$HeightUpper <- 120

  }

  parameters <- apply_defaults(parameters)

  cat(paste("Sampling ", dataset, "\n", sep = ""))

  # call service with no activity feedback
  pop_gen_out <- generate_population(parameters, silent = T)

  if (generate_failed(pop_gen_out)) {

    # show error messages now
    print(summary(pop_gen_out))
    stop()

  }

  if (i < n_datasets) {

    # service is throttled - must pause here
    cat("Waiting for service to resume...\n")
    Sys.sleep(pop_gen_out$wait_for)

  }

  individuals <- extract_individuals(pop_gen_out)
  return(individuals)

})

names(data) <- datasets

Refer to the service's inputs schema for concise coverage of the input requirements.

Once installed, review the complete package API with:

help(package="Rpgcli")

License

Licensed under the MIT license. (More information here.)