The interfaces RealVar and IntVar are automatically imported.
As for most random variables, they can be either latent (unobserved, sampled), or fixed
(conditioned upon).
RealVar and IntVar are closely related to Java's Double
and Integer but
the former have implementations allowing mutability for the purpose of efficient sampling.
Java's Double and Integer are automatically converted back and forth
to RealVar and IntVar (some kind of generalization of
auto-boxing).
Blang's linear algebra is based on xlinear which is in turn based on a portfolio of established libraries.
The basic classes there are Matrix, DenseMatrix and SparseMatrix.
Blang/XBase allows operator overloading, so you write expressions likes matrix1 * matrix2,
2.0 * matrix, etc.
Vectors do not have a distinct type, they are just 1-by-n or n-by-1 matrix.
Standard operations are supported using unsurprising syntaxes, e.g.
identity(100_000), ones(3,3) matrix.norm, matrix.sum,
matrix.readOnlyView, matrix.slice(1, 3, 0, 2),
matrix.cholesky, etc.
See xlinear for more info.
xlinear is augmented in Blang with the following types:
DenseSimplex: Vector of entries summing to one.
void setPair(int index1, double value1, int index2, double value2): Set a pair of entries, checking their sum is the same before and after
DenseTransitionMatrix: Matrix where each row is a DenseSimplex.
DenseSimplex row(int i): Get a view into a row.
If a variable is only declared, as in random RealVar myVariable or
param RealVar myVariable, then it will be initialized using the command line
arguments with prefix model.myVariable.
Use --help to see the list of arguments. How to customize this
behaviour is describe here.
If a variable is provided with a default value, as in random RealVar myVariable ?: fixedReal(42.0)
or param RealVar myVariable ?: { /* init block */ }, then the initialization block will be used whenever
no command line arguments are provided for this variable. The following are useful for creating initialization blocks:
StaticUtils: Automatically statically imported in Blang meaning can call "StaticUtils::function(..)" as just "function(..)".
static IntScalar latentInt(): unobserved integer variable (initialized at zero).
static RealScalar latentReal(): unobserved real variable (represented in double precision, initialized at zero).
static SpikedRealVar latentSpikedReal(): unobserved real variable supporting a spike at zero (represented in double precision, initialized at zero).
static IntConstant fixedInt(int value): fixed (constant or conditioned upon) integer scalar.
static RealConstant fixedReal(double value): fixed real scalar.
static List<IntVar> latentIntList(int size): size specifies the length of the list.
static List<RealVar> latentRealList(int size): size specifies the length of the list.
static List<SpikedRealVar> latentSpikedRealList(int size): size specifies the length of the list.
static List<IntVar> fixedIntList(int ... entries): list where the integer valued entries are fixed to the provided values.
static DenseMatrix latentVector(int n): an n-by-1 latent dense vector (initialized at zero).
static DenseMatrix fixedVector(double ... entries): an n-by-1 fixed dense vector.
static DenseMatrix latentMatrix(int nRows, int nCols): an n-by-m latent dense matrix (initialized at zero).
static DenseMatrix fixedMatrix(double [][] entries): a constant dense matrix.
static DenseSimplex latentSimplex(int n): latent n-by-1 matrix with entries summing to one (initialized at uniform).
static DenseSimplex fixedSimplex(double ... probabilities): creates a constant simplex, also checks the provided list of number sums to one.
static DenseSimplex fixedSimplex(DenseMatrix probabilities): creates a constant simplex, also checks the provided vector sums to one.
static DenseTransitionMatrix latentTransitionMatrix(int nStates): latent n-by-n matrix with rows summing to one.
static DenseTransitionMatrix fixedTransitionMatrix(DenseMatrix probabilities): creates a constant transition matrix, also checks the provided rows all sum to one.
static DenseTransitionMatrix fixedTransitionMatrix(double [][] probabilities): creates a constant transition matrix, also checks the provided rows all sum to one.
ExtensionUtils: Automatically imported as extension methods, meaning functions f(a, b, ..) can be called as a.f(b, ...).
static RealVar getRealVar(Matrix m, int row, int col): View a single entry of a Matrix as a RealVar.
static RealVar getRealVar(Matrix m, int index): View a single entry of a 1-by-n or n-by-1 Matrix as a RealVar.
static Random generator(java.util.Random random): Upgrade a java.util.Random into to the type of Random we use, bayonet.distributions.Random.
static void setTo(Matrix one, Matrix another): Copy the contents of a matrix into another one.
static double sum(Iterable<? extends Number> numbers)
static <T> void increment(Map<T, Double> map, T key, double value): Increment an entry of a map to double, setting to the value if the key is missing.
static boolean isClose(double n1, double n2): Check if two numbers are within 1e-6 of each other.
As hinted in StaticUtils above, simple collections of random variables can be achieved using Java built-in
List objects. However in more complex scenarios we need random variables indexed by several plates.
Plate: in the following, K is the type indexing the replicates, typically an Integer or String. We assume these indices are not random variables.
ColumnName getName(): Human-readable name for the plate, typically automatically extracted from a DataSource column name.
Collection<Index<K>> indices(Query parentIndices): Get the indices available given the indices of the parent (enclosing) plates. The parents can be provided in any order.
static Plate<Integer> ofIntegers(ColumnName columnName, int size): a plate with indices 0, 1, 2, ..., size-1
static Plate<String> ofStrings(ColumnName columnName, int size): a plate with indices category_0, category_1, ...
static Plate<String> ofStrings(String columnName, int size): a plate with indices category_0, category_1, ...
Plated: a random variable or parameter of type T enclosed in one or more Plates.
T get(Index<?> ... indices): get the random variable or parameter indexed by the provided indices. The indices can be given in any order.
Collection<Entry<Query, T>> entries(): list all variables obtained through get(..) so far. Each returned entry contains the variable as well as the associated indices (Query).
Plated<T> slice(Index<?> ... indices): a view into a subset.
static <T> Plated<T> latent(ColumnName name, Supplier<T> supplier): use the provided lambda expression to initialize several latent variables.
For random generation, Blang uses bayonet.distributions.Random, a replacement for
java.util.Random which by default uses under the hood
the Math Commons implementation of MarsenneTwister and is compatible both with Java and Math Commons
random types.
To generate specific distributions, use blang.distributions.Generators, the methods of
which are automatically imported in Blang model as static extensions, meaning for example to generate
a gamma you can just write rand.gamma(shape, rate).
Generators: Various random number generators.
static int betaBinomial(Random random, double alpha, double beta, int numberOfTrials)
static int hyperGeometric(Random random, int numberOfDraws, int population, int populationConditioned)
static double gompertz(Random rand, double shape, double scale)
static double gumbel(Random rand, double location, double scale)
static double weibull(Random rand, double scale, double shape)
static double fDist(Random rand, double d1, double d2)
static double logisticDist(Random rand, double location, double scale)
static double logLogistic(Random rand, double scale, double shape)
static double halfstudentt(Random random, double nu, double sigma)
static double laplace(Random random, double location, double scale)
static int geometric(Random random, double prob)
static double chisquared(Random random, int nu)
static double studentt(Random random, double nu, double mu, double sigma)
static double gamma(Random random, double shape, double rate)
static double beta(Random random, double alpha, double beta)
static boolean bernoulli(Random random, double p)
static int categorical(Random random, double [] probabilities)
static int binomial(Random random, int numberOfTrials, double probabilityOfSuccess)
static int negativeBinomial(Random random, double r, double p)
static double unitRateExponential(Random random)
static double exponential(Random random, double rate)
static double uniform(Random random, double min, double max)
static int discreteUniform(Random rand, int minInclusive, int maxExclusive)
static DenseSimplex dirichlet(Random random, Matrix concentrations)
static Matrix multivariateNormal(Random rand, Matrix mean, CholeskyDecomposition precision)
static Matrix standardMultivariateNormal(Random rand, int dim)
static double normal(Random rand, double mean, double variance)
static double standardNormal(Random rand)
static int poisson(Random rand, double mean)