Statistics
Symbolic probability distributions, joint laws, and random-variable algebra. A
distribution node names a parametrised family; a random variable node names
a draw from a distribution. Distinct draws are not independent unless they share
an explicit independent-product law. The complete distribution registry
lists every accepted family, its ordered parameters, support, and closed-form
operations. The canonical names for the gamma and beta families are
gamma_distribution and beta_distribution.
distribution#
Explicit context
fun distribution(
name: kotlin.String,
parameters: List<UniffiExpression>,
): UniffiExpression
Build a distribution node from a family name and its ordered parameter list
(e.g. distribution("normal", [mean, standard_deviation])). An unknown name
raises an invalid-option error. A parameter count that does not match the
family's arity raises a collection-shape error; it does not create an
undefined mathematical value.
random_variable#
Explicit context
fun randomVariable(
name: kotlin.String,
distribution: UniffiExpression,
): UniffiExpression
Build a random variable named name drawn from distribution. Each call creates
a distinct coordinate identity, even when its display name is reused.
multivariate_normal#
Explicit context
fun multivariateNormal(
mean: List<UniffiExpression>,
covariance: UniffiMatrix,
): UniffiExpression
Construct an ordinary multivariate normal law from an ordered real mean vector
and a symmetric positive-definite covariance matrix.
multinomial_distribution#
Explicit context
fun multinomialDistribution(
trialCount: UniffiExpression,
probabilities: List<UniffiExpression>,
): UniffiExpression
Construct a multinomial law from a nonnegative integer trial count and ordered
category probabilities summing exactly to one.
dirichlet#
Explicit context
fun dirichlet(parameters: List<UniffiExpression>): UniffiExpression
Construct a Dirichlet law. Its density is relative to intrinsic simplex measure,
not ambient Euclidean Lebesgue measure.
independent_product#
Explicit context
fun independentProduct(factors: List<UniffiExpression>): UniffiExpression
Construct the joint product law that explicitly certifies independence.
discrete_markov_chain#
Explicit context
fun discreteMarkovChain(
name: kotlin.String,
states: List<UniffiExpression>,
transitionMatrix: UniffiMatrix,
initialProbabilities: List<UniffiExpression>,
): UniffiExpression
Construct a finite-state time-homogeneous Markov chain with ordered distinct
state labels, an exact row-stochastic transition matrix, and an exact initial
row law.
transition_probability#
Explicit context
fun transitionProbability(
process: UniffiExpression,
fromState: UniffiExpression,
toState: UniffiExpression,
startIndex: UniffiExpression,
endIndex: UniffiExpression,
): UniffiExpression
Return the exact finite-horizon transition probability for a finite Markov
chain. The horizon must be a proved nonnegative integer.
stationary_distributions#
Explicit context
fun stationaryDistributions(process: UniffiExpression): UniffiMatrix
Return one row for every extreme stationary law. All stationary laws are the
convex combinations of these rows in the process state order.
hitting_probability#
Explicit context
fun hittingProbability(
process: UniffiExpression,
startState: UniffiExpression,
targetStates: List<UniffiExpression>,
): UniffiExpression
Return the exact probability that the chain ever reaches one of the target
states from start_state.
expected_hitting_time#
Explicit context
fun expectedHittingTime(
process: UniffiExpression,
startState: UniffiExpression,
targetStates: List<UniffiExpression>,
): UniffiExpression
Return the exact expected time to reach a target state set. The result is
positive infinity when the target is not reached almost surely.
Explicit context
fun affineProcessTransformation(
name: kotlin.String,
source: UniffiExpression,
multiplier: UniffiExpression,
offset: UniffiExpression,
): UniffiExpression
Construct the pointwise affine image offset + multiplier * source of a certified Gaussian process.
independent_gaussian_process_sum#
Explicit context
fun independentGaussianProcessSum(
name: kotlin.String,
firstSource: UniffiExpression,
secondSource: UniffiExpression,
): UniffiExpression
Construct the pointwise sum of two explicitly independent Gaussian processes on the same index domain.
finite_dimensional_random_vector#
Explicit context
fun finiteDimensionalRandomVector(
process: UniffiExpression,
indices: List<UniffiExpression>,
coordinateNames: List<kotlin.String>,
): UniffiExpression
Construct the ordered random-vector handle for a finite process slice, using the shared joint-law and conditioning operations.
conditional_process_slice_distribution#
Explicit context
fun conditionalProcessSliceDistribution(
process: UniffiExpression,
selectedIndices: List<UniffiExpression>,
conditioningIndices: List<UniffiExpression>,
conditioningValues: List<UniffiExpression>,
): UniffiExpression
Condition an ordered finite process slice on another ordered slice at explicit values through the shared continuous conditional-law engine. The operation declines or remains unevaluated when the conditioning marginal has no certified density.
independent_process_product#
Explicit context
fun independentProcessProduct(
firstProcess: UniffiExpression,
firstIndices: List<UniffiExpression>,
secondProcess: UniffiExpression,
secondIndices: List<UniffiExpression>,
): UniffiExpression
Construct the explicit block-independent joint law of two finite process slices.
product_copula#
Explicit context
fun productCopula(marginals: List<UniffiExpression>): UniffiExpression
Construct the product copula of at least two continuous marginals with exact CDF
and density descriptors. The result is the certified independent product law.
gaussian_copula#
Explicit context
fun gaussianCopula(
marginals: List<UniffiExpression>,
correlation: UniffiMatrix,
): UniffiExpression
Construct a Gaussian copula from continuous marginals and a symmetric
positive-semidefinite unit-diagonal correlation matrix. Its density remains
unevaluated unless the system gains an exact normal-quantile representation.
archimedean_copula#
Explicit context
fun archimedeanCopula(
family: kotlin.String,
marginals: List<UniffiExpression>,
parameter: UniffiExpression,
): UniffiExpression
Construct a Clayton, Frank, or Gumbel copula from continuous marginals. The
parameter domain is checked exactly; arbitrary generator expressions are not
accepted as copulas.
estimate_archimedean_copula_parameter#
Explicit context
fun estimateArchimedeanCopulaParameter(
family: kotlin.String,
observations: UniffiMatrix,
): UniffiExpression
Estimate a Clayton or Gumbel parameter by exactly inverting bivariate
Kendall's tau. Observations must have exactly two columns and every pairwise
order must be exact and strict, so ties and undecidable comparisons decline.
estimate_archimedean_copula_parameter_numeric#
Explicit context
fun estimateArchimedeanCopulaParameterNumeric(
family: kotlin.String,
observations: UniffiMatrix,
parameter: UniffiExpression,
lower: UniffiExpression,
upper: UniffiExpression,
options: UniffiNumericOptions,
): UniffiNumericRootFindingResult
Explicitly request bracketed numerical Frank-parameter estimation. A result is
returned only when the requested bracket and every needed numerical kernel can
be certified; otherwise its typed decline explains why.
quantile_numeric#
Explicit context
fun quantileNumeric(
distribution: UniffiExpression,
probability: UniffiExpression,
quantileVariable: UniffiExpression,
lower: UniffiExpression,
upper: UniffiExpression,
options: UniffiNumericOptions,
): UniffiNumericRootFindingResult
Explicitly invert a scalar continuous CDF on an exact rational bracket. Symbolic
probability operations never invoke this numerical operation implicitly.
order_statistic#
Explicit context
fun orderStatistic(
baseLaw: UniffiExpression,
sampleSize: UniffiExpression,
rank: UniffiExpression,
): UniffiExpression
Construct the rank order statistic of an i.i.d. sample from a scalar law. Both
sample size and rank must be positive exact integers, and rank cannot exceed
sample size.
minimum#
Explicit context
fun minimum(
baseLaw: UniffiExpression,
sampleSize: UniffiExpression,
): UniffiExpression
Construct the smallest member of an i.i.d. sample from a scalar law.
maximum#
Explicit context
fun maximum(
baseLaw: UniffiExpression,
sampleSize: UniffiExpression,
): UniffiExpression
Construct the largest member of an i.i.d. sample from a scalar law.
random_vector#
Explicit context
fun randomVector(
coordinateNames: List<kotlin.String>,
jointDistribution: UniffiExpression,
): UniffiExpression
Construct an ordered vector of fresh coordinate handles for a joint law.
joint_distribution#
Explicit context
fun jointDistribution(randomVector: UniffiExpression): UniffiExpression
Return a random vector's joint law.
component#
Explicit context
fun component(
randomVector: UniffiExpression,
position: kotlin.ULong,
): UniffiExpression
Select one coordinate by zero-based position.
marginal#
Explicit context
fun marginal(
jointDistribution: UniffiExpression,
positions: List<kotlin.ULong>,
): UniffiExpression
Return the distinct ordered coordinate projection of a joint law.
permute#
Explicit context
fun permute(
jointDistribution: UniffiExpression,
permutation: List<kotlin.ULong>,
): UniffiExpression
Reorder every coordinate by a permutation.
joint_density#
Explicit context
fun jointDensity(
jointDistribution: UniffiExpression,
points: List<UniffiExpression>,
): UniffiExpression
Evaluate an ordinary joint density at an ordered point. Laws without an ordinary
density retain an unevaluated query.
intrinsic_simplex_density#
Explicit context
fun intrinsicSimplexDensity(
jointDistribution: UniffiExpression,
points: List<UniffiExpression>,
): UniffiExpression
Evaluate a Dirichlet density relative to its intrinsic simplex measure.
joint_probability_mass_function#
Explicit context
fun jointProbabilityMassFunction(
jointDistribution: UniffiExpression,
points: List<UniffiExpression>,
): UniffiExpression
Evaluate a joint point mass at an ordered point.
joint_cumulative_distribution#
Explicit context
fun jointCumulativeDistribution(
jointDistribution: UniffiExpression,
points: List<UniffiExpression>,
): UniffiExpression
Evaluate the lower-orthant cumulative distribution at an ordered point.
joint_rectangle_probability#
Explicit context
fun jointRectangleProbability(
jointDistribution: UniffiExpression,
lowerBounds: List<UniffiExpression>,
upperBounds: List<UniffiExpression>,
): UniffiExpression
Evaluate the ordered rectangle probability (lower, upper].
joint_support#
Explicit context
fun jointSupport(jointDistribution: UniffiExpression): UniffiExpression
Return the exact support of a joint law when available.
joint_raw_moment#
Explicit context
fun jointRawMoment(
jointDistribution: UniffiExpression,
orders: List<UniffiExpression>,
): UniffiExpression
Return an exact multi-index raw moment when known.
joint_mean#
Explicit context
fun jointMean(jointDistribution: UniffiExpression): List<UniffiExpression>
Return the ordered exact mean entries of a joint law.
joint_covariance_matrix#
Explicit context
fun jointCovarianceMatrix(jointDistribution: UniffiExpression): UniffiMatrix
Return the exact covariance matrix of a joint law.
joint_correlation_matrix#
Explicit context
fun jointCorrelationMatrix(jointDistribution: UniffiExpression): UniffiMatrix
Return the correlation matrix when coordinate variances are proved positive.
density#
Explicit context
fun density(
randomVariable: UniffiExpression,
point: UniffiExpression,
): UniffiExpression
Probability density (continuous families) or probability mass (discrete
families) of random_variable evaluated at point. Falls back to an
unevaluated structural form when no closed form exists.
cumulative_distribution#
Explicit context
fun cumulativeDistribution(
randomVariable: UniffiExpression,
point: UniffiExpression,
): UniffiExpression
Cumulative distribution function of random_variable evaluated at point.
expectation#
Explicit context
fun expectation(
target: UniffiExpression,
randomVariables: List<UniffiExpression>,
): UniffiExpression
Expectation of target over the listed independent random variables. Linearity
and the constant-factor lift are applied; bare and power-of-random-variable
leaves consume the distribution's mean and raw moments.
variance#
Explicit context
fun variance(
target: UniffiExpression,
randomVariables: List<UniffiExpression>,
): UniffiExpression
Variance of target over the listed independent random variables.
covariance#
Explicit context
fun covariance(
left: UniffiExpression,
right: UniffiExpression,
randomVariables: List<UniffiExpression>,
): UniffiExpression
Covariance of left and right over the listed independent random variables;
zero for independent operands.
probability#
Explicit context
fun probability(
predicate: UniffiExpression,
randomVariables: List<UniffiExpression>,
): UniffiExpression
Probability that predicate (a tail comparison such as X > t) holds over the
listed independent random variables.
moment#
Explicit context
fun moment(
randomVariable: UniffiExpression,
order: UniffiExpression,
): UniffiExpression
The order-th raw moment E[X^order] of random_variable.
cumulant#
Explicit context
fun cumulant(
randomVariable: UniffiExpression,
order: UniffiExpression,
): UniffiExpression
The order-th cumulant of random_variable.
moment_generating_function#
Explicit context
fun momentGeneratingFunction(
randomVariable: UniffiExpression,
auxiliaryVariable: kotlin.String,
): UniffiExpression
Closed-form moment generating function M_X(t) of random_variable in the
named auxiliary variable, when elementary; otherwise an unevaluated structural
form.
characteristic_function#
Explicit context
fun characteristicFunction(
randomVariable: UniffiExpression,
auxiliaryVariable: kotlin.String,
): UniffiExpression
Closed-form characteristic function φX(t) of random_variable in the named
auxiliary variable, when elementary; otherwise an unevaluated structural form.
Example#