Uncertain Data Types
Relevant source files
The following files were used as context for generating this wiki page:
- deep_causality_uncertain/src/types/uncertain/mod.rs
- deep_causality_uncertain/src/types/computation/mod.rs
- openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
- openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/spec.md
- openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/spec.md
- openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/plan.md
Uncertain Data Types within the deep_causality_uncertain crate provide a first-order type system for modeling and reasoning about probabilistic data. These types allow developers to explicitly represent values that are not fixed but instead described by probability distributions, enabling robust causal modeling in high-dimensional and sparse data environments.
The system primarily revolves around two types: Uncertain<T>, which represents a single value with inherent uncertainty, and MaybeUncertain<T>, which models the probabilistic presence or absence of data. These types leverage a symbolic computation graph to propagate uncertainty through complex operations, ensuring that the results of computations maintain their probabilistic context.
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/spec.md, openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/spec.md
Core Data Structures
The architecture of uncertain data types is built on symbolic representation and persistent data structures to facilitate functional transformations and efficient sampling.
Uncertain
The Uncertain<T> type models a value as a probability distribution. Internally, it is evolving from a specialized graph structure (ComputationNode) to a more generic and composable structure based on ConstTree from the deep_causality_ast crate. This shift allows for the implementation of Higher-Kinded Type (HKT) traits.
| Feature | Description |
|---|---|
| Type Representation | Models a single value T as a probability distribution. |
| Internal Storage | Utilizes ConstTree<UncertainNodeContent<T>> for symbolic computation graphs. |
| Type Constraints | Requires T to implement the ProbabilisticType trait. |
| Sampling | Provides a sample() method to retrieve a concrete value based on the underlying distribution. |
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/spec.md
MaybeUncertain
MaybeUncertain<T> acts as a "Probabilistic Maybe" type. Unlike a standard Option<T> which is binary (present or absent), MaybeUncertain<T> represents a distribution over Some(T) and None.
| Component | Description |
|---|---|
| Definition | A wrapper type: pub struct MaybeUncertain<T>(Uncertain<Option<T>>). |
| Presence Logic | Models the probability that a value exists at all. |
| Arithmetic Propagation | Propagates None values through operations (e.g., Some(A) + None = None). |
Sources: openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/plan.md, openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/spec.md
Architecture and Data Flow
The uncertain types utilize a symbolic graph to represent operations. When an operation is performed (like adding two uncertain values), the system does not immediately calculate a result. Instead, it builds a new node in the computation tree.
Computation Graph Structure
The internal representation uses UncertainNodeContent<T>, which defines various variants for the computation graph.
The diagram shows the different types of nodes that can exist within the UncertainNodeContent enum used to build the computation tree.
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Sampling Logic
To retrieve a value, the SequentialSampler traverses the ConstTree. The evaluate_node function interprets each node, applying transformations or sampling from leaf distributions to produce a SampledValue.
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Higher-Kinded Type (HKT) Integration
To enable functional programming patterns, the crate introduces Witness types and specialized traits that mirror standard functional abstractions.
HKT Witnesses
Because Rust has limitations regarding HKT, "Witness" types are used to implement traits like Functor, Applicative, and Monad.
- UncertainWitness: A zero-sized type used to map
Type<T>toUncertain<T>. - MaybeUncertainWitness: A zero-sized type used to map
Type<T>toMaybeUncertain<T>.
HKT Trait Implementation
The types implement a subset of functional traits specifically tailored for probabilistic types.
| Trait | Operation | Description |
|---|---|---|
| Functor | fmap | Transforms the inner value while preserving the probabilistic context. |
| Applicative | pure, apply | Lifts values into the context and combines independent computations. |
| Monad | bind | Sequences dependent computations where one result influences the next step. |
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/spec.md, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Type Conversion and Lifting
The system provides mechanisms to transition between certain, uncertain, and maybe-uncertain states.
Lifting MaybeUncertain to Uncertain
The lift_to_uncertain method allows converting a MaybeUncertain<T> into a definite Uncertain<T> if statistical evidence for its presence meets a defined threshold.
This flowchart illustrates the logic of the lift_to_uncertain method, which validates if a probabilistically present value can be treated as definitely present for further computation.
Sources: openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/spec.md, openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/plan.md
Summary of Constructors
| Constructor | Type | Use Case |
|---|---|---|
Uncertain::point(val) | Uncertain | Creates a constant point distribution. |
Uncertain::normal(mu, sigma) | Uncertain | Creates a normal (Gaussian) distribution. |
MaybeUncertain::from_value(val) | MaybeUncertain | A value that is certainly present. |
MaybeUncertain::always_none() | MaybeUncertain | A value that is certainly absent. |
MaybeUncertain::from_bernoulli_and_uncertain(p, dist) | MaybeUncertain | Models a value that is present with probability p. |
Sources: openspec/changes/archive/spec-kit-old/004-maybeuncertain-is-your/spec.md, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Conclusion
Uncertain Data Types provide the foundational layer for handling data ambiguity within the DeepCausality framework. By modeling both value uncertainty and presence uncertainty through Uncertain<T> and MaybeUncertain<T>, and providing monadic interfaces for their composition, the system enables complex causal reasoning that remains statistically sound even in the presence of sparse or noisy data.