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
func distribution(
name: String,
parameters: [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
func randomVariable(
name: 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
func multivariateNormal(
mean: [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
func multinomialDistribution(
trialCount: UniffiExpression,
probabilities: [UniffiExpression],
) -> UniffiExpression
Construct a multinomial law from a nonnegative integer trial count and ordered
category probabilities summing exactly to one.
dirichlet#
Explicit context
func dirichlet(parameters: [UniffiExpression]) -> UniffiExpression
Construct a Dirichlet law. Its density is relative to intrinsic simplex measure,
not ambient Euclidean Lebesgue measure.
independent_product#
Explicit context
func independentProduct(factors: [UniffiExpression]) -> UniffiExpression
Construct the joint product law that explicitly certifies independence.
discrete_markov_chain#
Explicit context
func discreteMarkovChain(
name: String,
states: [UniffiExpression],
transitionMatrix: UniffiMatrix,
initialProbabilities: [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
func 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
func 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
func hittingProbability(
process: UniffiExpression,
startState: UniffiExpression,
targetStates: [UniffiExpression],
) -> UniffiExpression
Return the exact probability that the chain ever reaches one of the target
states from start_state.
expected_hitting_time#
Explicit context
func expectedHittingTime(
process: UniffiExpression,
startState: UniffiExpression,
targetStates: [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
func affineProcessTransformation(
name: 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
func independentGaussianProcessSum(
name: 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
func finiteDimensionalRandomVector(
process: UniffiExpression,
indices: [UniffiExpression],
coordinateNames: [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
func conditionalProcessSliceDistribution(
process: UniffiExpression,
selectedIndices: [UniffiExpression],
conditioningIndices: [UniffiExpression],
conditioningValues: [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
func independentProcessProduct(
firstProcess: UniffiExpression,
firstIndices: [UniffiExpression],
secondProcess: UniffiExpression,
secondIndices: [UniffiExpression],
) -> UniffiExpression
Construct the explicit block-independent joint law of two finite process slices.
product_copula#
Explicit context
func productCopula(marginals: [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
func gaussianCopula(
marginals: [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
func archimedeanCopula(
family: String,
marginals: [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
func estimateArchimedeanCopulaParameter(
family: 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
func estimateArchimedeanCopulaParameterNumeric(
family: 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
func 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
func 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
func minimum(
baseLaw: UniffiExpression,
sampleSize: UniffiExpression,
) -> UniffiExpression
Construct the smallest member of an i.i.d. sample from a scalar law.
maximum#
Explicit context
func maximum(
baseLaw: UniffiExpression,
sampleSize: UniffiExpression,
) -> UniffiExpression
Construct the largest member of an i.i.d. sample from a scalar law.
random_vector#
Explicit context
func randomVector(
coordinateNames: [String],
jointDistribution: UniffiExpression,
) -> UniffiExpression
Construct an ordered vector of fresh coordinate handles for a joint law.
joint_distribution#
Explicit context
func jointDistribution(randomVector: UniffiExpression) -> UniffiExpression
Return a random vector's joint law.
component#
Explicit context
func component(
randomVector: UniffiExpression,
position: UInt64,
) -> UniffiExpression
Select one coordinate by zero-based position.
marginal#
Explicit context
func marginal(
jointDistribution: UniffiExpression,
positions: [UInt64],
) -> UniffiExpression
Return the distinct ordered coordinate projection of a joint law.
permute#
Explicit context
func permute(
jointDistribution: UniffiExpression,
permutation: [UInt64],
) -> UniffiExpression
Reorder every coordinate by a permutation.
joint_density#
Explicit context
func jointDensity(
jointDistribution: UniffiExpression,
points: [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
func intrinsicSimplexDensity(
jointDistribution: UniffiExpression,
points: [UniffiExpression],
) -> UniffiExpression
Evaluate a Dirichlet density relative to its intrinsic simplex measure.
joint_probability_mass_function#
Explicit context
func jointProbabilityMassFunction(
jointDistribution: UniffiExpression,
points: [UniffiExpression],
) -> UniffiExpression
Evaluate a joint point mass at an ordered point.
joint_cumulative_distribution#
Explicit context
func jointCumulativeDistribution(
jointDistribution: UniffiExpression,
points: [UniffiExpression],
) -> UniffiExpression
Evaluate the lower-orthant cumulative distribution at an ordered point.
joint_rectangle_probability#
Explicit context
func jointRectangleProbability(
jointDistribution: UniffiExpression,
lowerBounds: [UniffiExpression],
upperBounds: [UniffiExpression],
) -> UniffiExpression
Evaluate the ordered rectangle probability (lower, upper].
joint_support#
Explicit context
func jointSupport(jointDistribution: UniffiExpression) -> UniffiExpression
Return the exact support of a joint law when available.
joint_raw_moment#
Explicit context
func jointRawMoment(
jointDistribution: UniffiExpression,
orders: [UniffiExpression],
) -> UniffiExpression
Return an exact multi-index raw moment when known.
joint_mean#
Explicit context
func jointMean(jointDistribution: UniffiExpression) -> [UniffiExpression]
Return the ordered exact mean entries of a joint law.
joint_covariance_matrix#
Explicit context
func jointCovarianceMatrix(jointDistribution: UniffiExpression) -> UniffiMatrix
Return the exact covariance matrix of a joint law.
joint_correlation_matrix#
Explicit context
func jointCorrelationMatrix(jointDistribution: UniffiExpression) -> UniffiMatrix
Return the correlation matrix when coordinate variances are proved positive.
density#
Explicit context
func 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
func cumulativeDistribution(
randomVariable: UniffiExpression,
point: UniffiExpression,
) -> UniffiExpression
Cumulative distribution function of random_variable evaluated at point.
expectation#
Explicit context
func expectation(
target: UniffiExpression,
randomVariables: [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
func variance(
target: UniffiExpression,
randomVariables: [UniffiExpression],
) -> UniffiExpression
Variance of target over the listed independent random variables.
covariance#
Explicit context
func covariance(
left: UniffiExpression,
right: UniffiExpression,
randomVariables: [UniffiExpression],
) -> UniffiExpression
Covariance of left and right over the listed independent random variables;
zero for independent operands.
probability#
Explicit context
func probability(
predicate: UniffiExpression,
randomVariables: [UniffiExpression],
) -> UniffiExpression
Probability that predicate (a tail comparison such as X > t) holds over the
listed independent random variables.
moment#
Explicit context
func moment(
randomVariable: UniffiExpression,
order: UniffiExpression,
) -> UniffiExpression
The order-th raw moment E[X^order] of random_variable.
cumulant#
Explicit context
func cumulant(
randomVariable: UniffiExpression,
order: UniffiExpression,
) -> UniffiExpression
The order-th cumulant of random_variable.
moment_generating_function#
Explicit context
func momentGeneratingFunction(
randomVariable: UniffiExpression,
auxiliaryVariable: 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
func characteristicFunction(
randomVariable: UniffiExpression,
auxiliaryVariable: String,
) -> UniffiExpression
Closed-form characteristic function φX(t) of random_variable in the named
auxiliary variable, when elementary; otherwise an unevaluated structural form.
Example#