Introduction

RWebPPL

RWebPPL is an R package providing an interface to WebPPL, a probabilistic programming language. The purpose of this introduction is to provide an overview of basic functionality. See rwebppl README.md for installation instructions.

Section 1 focuses on the primary interface to the Webppl programming language through rwebppl::webppl().

Section 2 provides examples of passing data from R to your WebPPL program.

Section 3 lists additional functionality included in the rwebppl package.

Section 1: rwebppl::webppl()

The rwebppl::webppl() function is the primary interface with the WebPPl programming language. This first section provides an overview of this function.

Basic webppl() ingredients

• A model written in the probabilistic programming language webppl instantiated as a string or in an external file with .wppl extension.
• [Optional] A data object, typically a data.frame in R.
• [Optional] Inference parameters. (See the Full webppl function argument list section for more detail.)

Example calls:

webppl(model)                             # Pass model object only (see `Running a simple model`).
webppl(model, data_var=my_data, data=df)  # Pass model object and data (see `Passing data from R to WebPPL`).

Running a simple model

Example: we instantiate a webppl model in the my_model variable. This is passed to webppl().

my_model <- "
  var model = function () {
   var a = flip(0.3)
   var b = flip(0.6)
   return a + b
  }
  model()
"
webppl(program_code=my_model)  # call with string

Alternatively, if my_model is saved in an external file (e.g. path/to/model/model.wppl) we could call:

webppl(program_file="path/to/model/model.wppl")  # call with file

Running more complex models

WebPPL packages can be used in more complex models:

webppl(program_file="path/to/model/model.wppl", packages=c("linked-list", "timeit"))

Full webppl() function argument list

• program_code: A string of a webppl program
• program_file: A file containing a webppl program
• data: A data frame (or other serializable object) to be passed from R to the webppl program
• data_var: A name by which the data can be referenced in the webppl program
• packages: A character vector of names of external webppl package to use
• model_var: When using inference opts, the name by which the model be referenced in the program.
• inference_opts: A list with options for inference of a particular model in the program. (see http://webppl.readthedocs.io/en/master/inference.html) [N.B.: requires using model_var]
• random_seed: Seed for random number generator.
• sort_by: Sort probability table by probability or support.
• chains: Number of times to run program (defaults to 1).
• cores: Number of cores to use when running multiple chains (defaults to 1).

Section 2: Passing data from R to WebPPL programs

Data can be passed directly from R to WebPPL as in:

my_model <- "
  var model = function () {
    var a = flip(0.3)
    var b = flip(0.6)
    var scores = map( function(d) {
    return a + b - d
  }, myDF)
  return scores
}
model()
"

webppl(my_model,
     data = df,
     data_var = "myDF")

In this example, myDF is not defined inside the WebPPL program, but is passed into it from R, using data = df. The argument data_var tells WebPPL what the data should be called.

Structure of data when passing

If myDF looks like this in R:

Participant	Condition	Response
1	A	0.4
1	B	0.8
2	A	0.2

It will exist in WebPPL as a list of js objects e.g.

[
  {
    participant: 0,
    condition: "A",
    response: 0.4
  },
  {
    participant: 0,
    condition: "B",
    response: 0.8
  },
  {
    participant: 1,
    condition: "A",
    response: 0.2
  },
  ...
]

Section 3: Other useful functions

• install_webppl: install webppl on local machine. Supports both official npm versions (e.g. '0.9.7') and also commit hashes from github repository for custom configurations.

  install_webppl('0.9.7')                                     # install version 0.9.7
  install_webppl('4bd2452333d24c122aee98c3206584bc39c6096a')  # install from github commit hash
  

• get_webppl_version: Return current webppl version.

  get_webppl_version()
  

• install_webppl_package: Install an npm package to webppl's global installation.

  install_webppl_package("PapaParse")
  

• uninstall_webppl_package: Uninstall an npm package from webppl's global installation.

  uninstall_webppl_package("PapaParse")
  

• get_samples: Convert webppl "histogram" into samples.

  num_samples <- 10
  df <- data.frame(prob = c(0.1, 0.3, 0.5, 0.1), support = c("a","b","c","d"))
  get_samples(df, num_samples)
  

• kill_webppl: Kill rwebppl process.

  kill_webppl()
  kill_webppl(6939)  # passing optional pid(s)
  

Also make sure to look at this list of useful packages.