Modeling Syntax Reference (VenChurch)

Introduction

The Venture modeling language is the language in which model expressions, namely the arguments to the assume, observe, and predict instructions are written. The Venture inference language is the same language, but with a few additional predefined procedures and special forms.

The VenChurch surface syntax for the Venture modeling language is a pure-functional dialect of Scheme, which puts it in the Lisp family of programming languages. The major differences from Scheme are

• No mutation (only inference can effect mutation, and that only in a restricted way)
• A spare set of predefined procedures and special forms
• Predefined procedures for random choices according to various distributions.

Special Forms

The special forms in VenChurch are as follows:

• (quote datum): Literal data.

  The datum must be a Venture expression. As in Scheme, a quote form returns a representation of the given expression as Venture data structures.

• (lambda (param ...) body): Construct a procedure.

  The formal parameters must be Venture symbols. The body must be a Venture expression. The semantics are as in Scheme or Church. Unlike Scheme, the body must be a single expression, and creation of variable arity procedures is not supported.

• (if predicate consequent alternate): Branch control.

  The predicate, consequent, and alternate must be Venture expressions.

• (cond (predicate expression) ...): Multiple branching.

  Each predicate and each expression must be a Venture expression. If none of the predicates match, returns nil.

• (and exp1 exp2): Short-circuiting and.

• (or exp1 exp2): Short-circuiting or.

• (let ((param exp) ...) body): Evaluation with local scope.

  Each parameter must be a Venture symbol. Each exp must be a Venture expression. The body must be a Venture expression. The semantics are as Scheme’s let*: each exp is evaluated in turn, its result is bound to the param, and made available to subsequent exp s and the body.

• (letrec ((param exp) ...) body): Evaluation with local scope.

  Each parameter must be a Venture symbol. Each exp must be a Venture expression that evaluates to a procedure. The body must be a Venture expression. The semantics are as Scheme’s letrec: (TODO)

• (quasiquote <datum>): Data constructed by template instantiation.

  If the datum contains no unquote expressions, quasiquote is the same as quote. Otherwise, the unquoted expressions are evaluated and their results spliced in. This is particularly useful for constructing model program fragments in inference programs – so much so, that the modeling inference SPs automatically quasiquote their model arguments.

  TODO: Nested quasiquotation does not work properly: all unquoted expressions are evaluated regardless of quasiquotation level.

In addition, macros intended for the inference programming language are (as of this writing) expanded in expressions of the modeling language as well. The results are generally not useful, so it’s appropriate to treat those as reserved words when writing models:

• do, begin, call_back, collect, assume, observe, predict, force, sample, sample_all

Built-in Procedures

The following modeling procedures are built in to Venture (as of the generation date of this manual):

add(<number>, ...)

Return type:<number>

add returns the sum of all its arguments

Deterministic

sub(<number>, <number>)

Return type:<number>

sub returns the difference between its first and second arguments

Deterministic

mul(<number>, ...)

Return type:<number>

mul returns the product of all its arguments

Deterministic

div(<number>, <number>)

Return type:<number>

div returns the ratio of its first argument to its second

Deterministic

int_div(<number>, <number>)

Return type:<number>

div returns the integer quotient of its first argument by its second

Deterministic

int_mod(<number>, <number>)

Return type:<number>

mod returns the modulus of its first argument by its second

Deterministic

min(<number>, <number>)

Return type:<number>

min returns the minimum value of its arguments

Deterministic

eq(<object>, <object>)

Return type:<bool>

eq compares its two arguments for equality

Deterministic

gt(<object>, <object>)

Return type:<bool>

gt returns true if its first argument compares greater than its second

Deterministic

gte(<object>, <object>)

Return type:<bool>

gte returns true if its first argument compares greater than or equal to its second

Deterministic

lt(<object>, <object>)

Return type:<bool>

lt returns true if its first argument compares less than its second

Deterministic

lte(<object>, <object>)

Return type:<bool>

lte returns true if its first argument compares less than or equal to its second

Deterministic

floor(<number>)

Return type:<number>

floor returns the largest integer less than or equal to its argument (as a VentureNumber)

Deterministic

real(<atom>)

Return type:<number>

real returns the identity of its argument atom as a number

Deterministic

atom_eq(<atom>, <atom>)

Return type:<bool>

atom_eq tests its two arguments, which must be atoms, for equality

Deterministic

probability(<probability>)

Return type:<probability>

probability converts its argument to a probability (in direct space)

Deterministic

sin(<number>)

Return type:<number>

Returns the sin of its argument

Deterministic

cos(<number>)

Return type:<number>

Returns the cos of its argument

Deterministic

tan(<number>)

Return type:<number>

Returns the tan of its argument

Deterministic

hypot(<number>, <number>)

Return type:<number>

Returns the hypot of its arguments

Deterministic

exp(<number>)

Return type:<number>

Returns the exp of its argument

Deterministic

log(<number>)

Return type:<number>

Returns the log of its argument

Deterministic

pow(<number>, <number>)

Return type:<number>

pow returns its first argument raised to the power of its second argument

Deterministic

sqrt(<number>)

Return type:<number>

Returns the sqrt of its argument

Deterministic

atan2(<number>, <number>)

Return type:<number>

atan2(y,x) returns the angle from the positive x axis to the point x,y. The order of arguments is conventional.

Deterministic

not(<bool>)

Return type:<bool>

not returns the logical negation of its argument

Deterministic

xor(<bool>, <bool>)

Return type:<bool>

xor(x,y) returns true if exactly one of x and y is true

Deterministic

is_number(<object>)

Return type:<bool>

is_number returns true iff its argument is a <number>

Deterministic

is_integer(<object>)

Return type:<bool>

is_integer returns true iff its argument is a <integer>

Deterministic

is_probability(<object>)

Return type:<bool>

is_probability returns true iff its argument is a <probability>

Deterministic

is_atom(<object>)

Return type:<bool>

is_atom returns true iff its argument is a <atom>

Deterministic

is_boolean(<object>)

Return type:<bool>

is_boolean returns true iff its argument is a <bool>

Deterministic

is_symbol(<object>)

Return type:<bool>

is_symbol returns true iff its argument is a <symbol>

Deterministic

is_procedure(<object>)

Return type:<bool>

is_procedure returns true iff its argument is a <SP <object> ... -> <object>>

Deterministic

list(<object>, ...)

Return type:<list>

list returns the list of its arguments

Deterministic

pair(<object>, <object>)

Return type:<pair <object> <object>>

pair returns the pair whose first component is the first argument and whose second component is the second argument

Deterministic

is_pair(<object>)

Return type:<bool>

is_pair returns true iff its argument is a <pair <object> <object>>

Deterministic

first(<pair <object> <object>>)

Return type:<object>

first returns the first component of its argument pair

Deterministic

rest(<pair <object> <object>>)

Return type:<object>

rest returns the second component of its argument pair

Deterministic

second(<pair <object> <pair <object> <object>>>)

Return type:<object>

second returns the first component of the second component of its argument

Deterministic

to_list(<sequence <object>>)

Return type:<list <object>>

to_list converts its argument sequence to a list

Deterministic

array(<object>, ...)

Return type:<array>

array returns an array initialized with its arguments

Deterministic

vector(<number>, ...)

Return type:<array <number>>

vector returns an unboxed numeric array initialized with its arguments

Deterministic

is_array(<object>)

Return type:<bool>

is_array returns true iff its argument is a <array>

Deterministic

is_vector(<object>)

Return type:<bool>

is_vector returns true iff its argument is a <array <number>>

Deterministic

to_array(<sequence <object>>)

Return type:<array <object>>

to_array converts its argument sequence to an array

Deterministic

to_vector(<sequence <number>>)

Return type:<array <number>>

to_vector converts its argument sequence to a vector

Deterministic

dict(<list k>, <list v>)

Return type:<dict k v>

dict returns the dictionary mapping the given keys to their respective given values. It is an error if the given lists are not the same length.

Deterministic

is_dict(<object>)

Return type:<bool>

is_dict returns true iff its argument is a <dict>

Deterministic

matrix(<list <list <number>>>)

Return type:<matrix>

matrix returns a matrix formed from the given list of rows. It is an error if the given list is not rectangular.

Deterministic

is_matrix(<object>)

Return type:<bool>

is_matrix returns true iff its argument is a <matrix>

Deterministic

simplex(<probability>, ...)

Return type:<simplex>

simplex returns the simplex point given by its argument coordinates.

Deterministic

is_simplex(<object>)

Return type:<bool>

is_simplex returns true iff its argument is a <simplex>

Deterministic

lookup(<mapping k v>, k)

Return type:v

lookup looks the given key up in the given mapping and returns the result. It is an error if the key is not in the mapping. Lists and arrays are viewed as mappings from indices to the corresponding elements. Environments are viewed as mappings from symbols to their values.

Deterministic

contains(<mapping k v>, k)

Return type:<bool>

contains reports whether the given key appears in the given mapping or not.

Deterministic

size(<mapping k v>)

Return type:<number>

size returns the number of elements in the given collection (lists and arrays work too)

Deterministic

take(<integer>, <sequence k>)

Return type:<sequence k>

take returns the requested number of elements from the beginning of the given sequence, as another sequence of the same type.

Deterministic

arange(<integer>[, <integer>])

Return type:<array <integer>>

(arange [start] stop) returns an array of n consecutive integers from start (inclusive) up to stop (exclusive).

Deterministic

fill(<integer>, <number>)

Return type:<array <number>>

(fill n x) returns an array with the number x repeated n times

Deterministic

linspace(<number>, <number>, <count>)

Return type:<array <number>>

(linspace start stop n) returns an array of n evenly spaced numbers over the interval [start, stop].

Deterministic

id_matrix(<count>)

Return type:<matrix>

(id_matrix n) returns an identity matrix of dimension n.

Deterministic

diag_matrix(<array <number>>)

Return type:<matrix>

(diag_matrix v) returns a diagonal array whose diagonal is v.

Deterministic

ravel(<matrix>)

Return type:<array <number>>

(ravel m) returns a 1-D array containing the elements of the matrix m.

Deterministic

transpose(<matrix>)

Return type:<matrix>

(transpose m) returns the transpose of the matrix m.

Deterministic

vector_add(<array <number>>, <array <number>>)

Return type:<array <number>>

(vector_add x y) returns the sum of vectors x and y.

Deterministic

matrix_add(<matrix>, <matrix>)

Return type:<matrix>

(matrix_add x y) returns the sum of matrices x and y.

Deterministic

scale_vector(<number>, <array <number>>)

Return type:<array <number>>

(scale_vector x y) returns the product of scalar x and vector y.

Deterministic

scale_matrix(<number>, <matrix>)

Return type:<matrix>

(scale_matrix x y) returns the product of scalar x and matrix y.

Deterministic

vector_dot(<array <number>>, <array <number>>)

Return type:<number>

(vector_dot x y) returns the dot product of vectors x and y.

Deterministic

matrix_mul(<matrix>, <matrix>)

Return type:<matrix>

(matrix_mul x y) returns the product of matrices x and y.

Deterministic

matrix_times_vector(<matrix>, <array <number>>)

Return type:<array <number>>

(matrix_times_vector M v) returns the matrix-vector product Mv.

Deterministic

vector_times_matrix(<array <number>>, <matrix>)

Return type:<array <number>>

(vector_times_matrix v M) returns the vector-matrix product vM.

Deterministic

debug(<symbol>, k)

Return type:k

Print the given value, labeled by a Symbol. Return the value. Intended for debugging or for monitoring execution.

Deterministic

apply(proc(a, ...) -> b, <array a>)

Return type:b

(apply func vals) returns the result of applying a variadic function to an array of operands

Deterministic

fix(<array <symbol>>, <array <exp>>)

Return type:<environment>

fix

Used internally in the implementation of letrec.

Deterministic

mapv(proc(a) -> b, <array a>)

Return type:<array b>

(mapv func vals) returns the results of applying a function to each value in an array

Deterministic

imapv(proc(index, a) -> b, <array a>)

Return type:<array b>

(imapv func vals) returns the results of applying a function to each value in an array, together with its index

Deterministic

zip(<list>, ...)

Return type:<list <list>>

zip returns a list of lists, where the i-th nested list contains the i-th element from each of the input arguments

Deterministic

branch(<bool>, <exp>, <exp>)

Return type:<object>

branch evaluates either exp1 or exp2 in the current environment and returns the result. Is itself deterministic, but the chosen expression may involve a stochastic computation.

Deterministic

biplex(<bool>, <object>, <object>)

Return type:<object>

biplex returns either its second or third argument.

Deterministic

make_csp(<array <symbol>>, <exp>)

Return type:a compound SP

make_csp

Used internally in the implementation of compound procedures.

Deterministic

get_current_environment()

Return type:<environment>

get_current_environment returns the lexical environment of its invocation site

Deterministic

get_empty_environment()

Return type:<environment>

get_empty_environment returns the empty environment

Deterministic

is_environment(<object>)

Return type:<bool>

is_environment returns true iff its argument is a <environment>

Deterministic

extend_environment(<environment>, <symbol>, <object>)

Return type:<environment>

extend_environment returns an extension of the given environment where the given symbol is bound to the given object

Deterministic

eval(<exp>, <environment>)

Return type:<object>

eval evaluates the given expression in the given environment and returns the result. Is itself deterministic, but the given expression may involve a stochasitc computation.

Deterministic

mem(proc(a, ...) -> b)

Return type:proc(a, ...) -> b

mem returns the stochastically memoized version of the input SP.

Deterministic

tag(<scope>, <block>, <object>)

Return type:<object>

tag returns its third argument unchanged at runtime, but tags the subexpression creating the object as being within the given scope and block.

Deterministic

tag_exclude(<scope>, <object>)

Return type:<object>

tag_exclude returns its second argument unchanged at runtime, but tags the subexpression creating the object as being outside the given scope.

Deterministic

assess(<val>, proc(<args>, ...) -> <val>, <args>, ...)

Return type:<number>

(assess val func arg1 arg2 ...) returns the log probability (density) of simulating val from (func arg1 arg2 ...)

Deterministic

binomial(<count>, <probability>)

Return type:<count>

(binomial n p) simulates flipping n Bernoulli trials independently with probability p and returns the total number of successes.

Stochastic

flip([<probability>])

Return type:<bool>

(flip p) returns true with probability p and false otherwise. If omitted, p is taken to be 0.5.

Stochastic

bernoulli([<probability>])

Return type:<integer>

(bernoulli p) returns true with probability p and false otherwise. If omitted, p is taken to be 0.5.

Stochastic

log_flip(<number>)

Return type:<bool>

(log_flip p) returns true with probability exp(p) and false otherwise. This is useful for modeling very low probability events, because it does not suffer the underflow that (log_flip (exp p)) would.

Stochastic

log_bernoulli(<number>)

Return type:<bool>

(log_bernoulli p) returns true with probability exp(p) and false otherwise. This is useful for modeling very low probability events, because it does not suffer the underflow that (log_bernoulli (exp p)) would.

Stochastic

categorical(<simplex>[, <array>])

Return type:<object>

(categorical weights objects) samples a categorical with the given weights. In the one argument case, returns the index of the chosen option as an atom; in the two argument case returns the item at that index in the second argument. It is an error if the two arguments have different length.

Stochastic

uniform_discrete(<integer>, <integer>)

Return type:<integer>

(uniform_discrete start end) samples a uniform discrete on the (start, start + 1, ..., end - 1)

Stochastic

poisson(<positive>)

Return type:<count>

(poisson lambda) samples a poisson with rate lambda

Stochastic

normal(<number>, <number>)

Return type:<number>

(normal mu sigma) samples a normal distribution with mean mu and standard deviation sigma.

Stochastic, variationable

vonmises(<number>, <positive>)

Return type:<number>

(vonmises mu kappa) samples a von Mises distribution with mean mu and shape kappa. The output is normalized to the interval [-pi,pi].

Stochastic

uniform_continuous(<number>, <number>)

Return type:<number>

(uniform_continuous low high) -> samples a uniform real number between low and high.

Stochastic

beta(<positive>, <positive>)

Return type:<probability>

(beta alpha beta) returns a sample from a beta distribution with shape parameters alpha and beta.

Stochastic

expon(<positive>)

Return type:<positive>

(expon theta) returns a sample from an exponential distribution with rate (inverse scale) parameter theta.

Stochastic

gamma(<positive>, <positive>)

Return type:<positive>

(gamma alpha beta) returns a sample from a gamma distribution with shape parameter alpha and rate parameter beta.

Stochastic

student_t(<positive>[, <number>[, <number>]])

Return type:<number>

(student_t nu loc shape) returns a sample from Student’s t distribution with nu degrees of freedom, with optional location and scale parameters.

Stochastic

inv_gamma(<positive>, <positive>)

Return type:<positive>

(inv_gamma alpha beta) returns a sample from an inverse gamma distribution with shape parameter alpha and scale parameter beta

Stochastic

laplace(<number>, <positive>)

Return type:<number>

(laplace a b) returns a sample from a laplace (double exponential) distribution with shape parameter a and scale parameter b

Stochastic

multivariate_normal(<array <number>>, <symmetricmatrix>)

Return type:<array <number>>

(multivariate_normal mean covariance) samples a vector according to the given multivariate Gaussian distribution. It is an error if the dimensionalities of the arguments do not line up.

Stochastic

inv_wishart(<symmetricmatrix>, <positive>)

Return type:<symmetricmatrix>

(inv_wishart scale_matrix degree_of_freedeom) samples a positive definite matrix according to the given inverse wishart distribution

Stochastic

wishart(<symmetricmatrix>, <positive>)

Return type:<symmetricmatrix>

(wishart scale_matrix degree_of_freedeom) samples a positive definite matrix according to the given inverse wishart distribution

Stochastic

make_beta_bernoulli(<positive>, <positive>)

Return type:proc() -> <bool>

(make_beta_bernoulli alpha beta) returns a collapsed beta bernoulli sampler with pseudocounts alpha (for true) and beta (for false). While this procedure itself is deterministic, the returned sampler is stochastic.

Deterministic, children can absorb at applications

make_uc_beta_bernoulli(<positive>, <positive>)

Return type:proc() -> <bool>

(make_uc_beta_bernoulli alpha beta) returns an uncollapsed beta bernoulli sampler with pseudocounts alpha (for true) and beta (for false).

Stochastic, children can absorb at applications

make_suff_stat_bernoulli(<number>)

Return type:proc() -> <bool>

(make_suff_stat_bernoulli weight) returns a bernoulli sampler (weighted coin) with given weight. The latter maintains application statistics sufficient to absorb changes to the weight in O(1) time (without traversing all the applications).

Deterministic, children can absorb at applications

dirichlet(<array <positive>>)

Return type:<simplex>

(dirichlet alphas) samples a simplex point according to the given Dirichlet distribution.

Stochastic

symmetric_dirichlet(<positive>, <count>)

Return type:<simplex>

(symmetric_dirichlet alpha n) samples a simplex point according to the symmetric Dirichlet distribution on n dimensions with concentration parameter alpha.

Stochastic

make_dir_mult(<array <positive>>[, <array>])

Return type:proc() -> <object>

(make_dir_mult alphas objects) returns a sampler for a collapsed Dirichlet multinomial model. If the objects argument is given, the sampler will return one of those objects on each call; if not, it will return one of n <atom>s where n is the length of the list of alphas. It is an error if the list of objects is supplied and has different length from the list of alphas. While this procedure itself is deterministic, the returned sampler is stochastic.

Deterministic, children can absorb at applications

make_uc_dir_mult(<array <positive>>[, <array>])

Return type:proc() -> <object>

make_uc_dir_mult is an uncollapsed variant of make_dir_mult.

Stochastic, children can absorb at applications

make_sym_dir_mult(<positive>, <count>[, <array>])

Return type:proc() -> <object>

make_sym_dir_mult is a symmetric variant of make_dir_mult.

Deterministic, children can absorb at applications

make_uc_sym_dir_mult(<positive>, <count>[, <array>])

Return type:proc() -> <object>

make_uc_sym_dir_mult is an uncollapsed symmetric variant of make_dir_mult.

Stochastic, children can absorb at applications

make_crp(<number>[, <number>])

Return type:proc() -> <atom>

(make_crp alpha) -> <SP () <number>>

Chinese Restaurant Process with hyperparameter alpha. Returns a sampler for the table number.

Deterministic, children can absorb at applications

make_cmvn(<array <number>>, <number>, <number>, <matrix>)

Return type:proc() -> <array <number>>

(make_cmvn m0 k0 v0 S0) -> <SP () <float array>>

Collapsed multivariate normal with hyperparameters m0,k0,v0,S0, where parameters are named as in (Murphy, section 4.6.3.3, page 134).

Deterministic, children can absorb at applications

make_lazy_hmm(<simplex>, <matrix>, <matrix>)

Return type:proc(<count>) -> <atom>

Discrete-state HMM of unbounded length with discrete observations. The inputs are the probability distribution of the first state, the transition matrix, and the observation matrix. It is an error if the dimensionalities do not line up. Returns observations from the HMM encoded as a stochastic procedure that takes the time step and samples a new observation at that time step.

Deterministic

make_gp(mean function, covariance function)

Return type:proc(<array <number>>) -> <array <number>>

Constructs a Gaussian Process with the given mean and covariance functions. Wrap the gp in a mem if input points might be sampled multiple times. Global Logscore is broken with GPs, as it is with all SPs that have auxen.

Deterministic, children can absorb at applications

apply_function()

apply_function

Deterministic

exactly(<object>[, <number>])

Return type:<object>

Force a variable to be treated as random even though its value is known.

This deterministically returns the first argument when simulated, but is willing to pretend to be able to stochastically return any object. The second argument, if given, is the penalty (in log space) for a mismatch. If not given, taken to be -infinity.

Stochastic

value_error(<object>)

Return type:<object>

deterministic value_error

Deterministic

You can ask your Venture installation for a current version of this list by running the vendoc program (with no arguments).

Built-in Helpers

• true: The boolean True value.
• false: The boolean False value.