Causal Discovery Language (CDL)
Relevant source files
The following files were used as context for generating this wiki page:
Causal Discovery Language (CDL) is a Domain Specific Language (DSL) within the deep_causality_discovery crate designed to streamline the transition from raw observational data to executable causal models. It provides a modular, type-safe pipeline that leverages monadic composition to orchestrate complex statistical algorithms. CDL acts as a bridge, enabling users to identify causal structures such as synergistic, unique, and redundant influences, which subsequently inform the construction of Causaloid Graphs and Context structures within the broader DeepCausality framework.
Sources: deep_causality_discovery/README.md:16-20, website/web/src/content/blog/en/announcement-causal-discovery.md:9-12
The language is built upon Rust's typestate pattern and functional programming paradigms, specifically the CdlEffect monad from the deep_causality_haft crate. This architecture ensures that pipeline stages—such as data loading, feature selection, and causal discovery—are executed in a valid sequence enforced at compile-time, while providing explicit channels for error propagation and warning accumulation.
Sources: deep_causality_discovery/README.md:22-26, openspec/changes/archive/cdl_hkt.md:38-43
Pipeline Architecture
The CDL pipeline is organized into sequential stages. Each stage transitions the pipeline from one state to another, ensuring data integrity and logical flow.
Workflow Stages
The core workflow follows a specific progression:
| Stage | State Transition | Description |
|---|---|---|
| Initialization | NoData | Pipeline starts via CdlBuilder::build() or CDL::new(). |
| Data Loading | NoData -> WithData | Ingests CSV or Parquet data into a CausalTensor<f64>. |
| Data Cleaning | WithData -> WithCleanedData | Converts NaN values to None to prevent bias during imputation. |
| Feature Selection | WithCleanedData -> WithFeatures | Identifies relevant variables using algorithms like mRMR. |
| Causal Discovery | WithFeatures -> WithCausalResults | Applies SURD to decompose influences into Synergistic, Unique, and Redundant. |
| Analysis | WithCausalResults -> WithAnalysis | Interprets raw bits against thresholds to generate recommendations. |
| Finalization | WithAnalysis -> Finalized | Formats the report for console output or model generation. |
Sources: deep_causality_discovery/README.md:28-66, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:158-175
Data Flow Diagram
The following diagram illustrates the linear progression of data through the CDL typestate transitions.
The workflow ensures that feature selection cannot occur until data is loaded and cleaned, and discovery cannot start until features are selected.
Sources: deep_causality_discovery/README.md:28-66, openspec/changes/archive/cdl_hkt.md:104-118
Monadic Effect System
CDL employs a specialized monad, CdlEffect, to manage side effects during the discovery process. Unlike a standard Result, the CdlEffect tracks both a fatal error channel and a persistent log of warnings.
CdlEffect Structure
The CdlEffect<T> structure encapsulates the state of the pipeline:
- inner: A
Result<T, CdlError>that enforces valid state and short-circuits on fatal errors. - warnings: A
CdlWarningLogthat accumulates non-fatal issues (e.g., "Minor data inconsistency") throughout the entire pipeline duration.
Sources: openspec/changes/archive/cdl_hkt.md:83-102, website/web/src/content/blog/en/announcement-causal-discovery.md:28-33
Monadic Binding
Composition is achieved through the .bind() operator. This allows for a clean functional flow where each closure receives the current CDL state and returns a CdlEffect wrapping the next state.
let result_effect = CdlBuilder::build()
.bind(|cdl| cdl.load_data(file_path, target_index, vec![]))
.bind(|cdl| cdl.clean_data(OptionNoneDataCleaner))
.bind(|cdl| {
cdl.feature_select(|tensor| {
mrmr_features_selector(tensor, 3, target_index)
})
})
.bind(|cdl| cdl.analyze())
.bind(|cdl| cdl.finalize());
Sources: deep_causality_discovery/README.md:84-106, openspec/changes/archive/cdl_hkt.md:230-245
Core Algorithms
CDL integrates specific statistical algorithms to perform feature selection and causal decomposition.
MRMR (Max-Relevance Min-Redundancy)
The Feature Selection stage uses the mRMR algorithm to rank features based on their relevance to a target variable while minimizing mutual information between selected features. This reduces noise and prevents the pipeline from processing redundant data.
Sources: openspec/changes/archive/spec-kit-old/001-mrmr-feature-selector/spec.md:58-62, website/web/src/content/blog/en/announcement-causal-discovery.md:41-43
SURD (Synergistic, Unique, Redundant Decomposition)
The core causal engine utilizes the SURD-states algorithm. It decomposes the total information between sources and a target into:
- Unique Influence: Information contributed by a single variable.
- Redundant Influence: Overlapping information shared between multiple variables.
- Synergistic Influence: Information that emerges only when variables interact together.
Sources: deep_causality_discovery/README.md:52-57, website/web/src/content/blog/en/announcement-causal-discovery.md:44-48
Translation Heuristics
The analyze stage applies heuristics to map numerical SURD results into executable causal structures in the DeepCausality library.
| Discovery Result | Recommendation | Causaloid Model |
|---|---|---|
| Strong Synergy | Join Required | Causaloid Collection with AggregateLogic::All (Conjunction). |
| Strong Unique | Direct Link | Direct edge in CausaloidGraph: Causaloid(Source) -> Causaloid(Target). |
| Strong Redundant | Alternative Link | Causaloid Collection with AggregateLogic::Any (Disjunction). |
| Mixed Influences | Threshold Link | Causaloid Collection with AggregateLogic::Some(k). |
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:182-205, deep_causality_discovery/README.md:126-140
Configuration and Entities
CDL uses several configuration entities to control the behavior of the pipeline stages.
| Entity | Description | Key Fields |
|---|---|---|
| CsvConfig | Configures CSV ingestion. | delimiter, has_headers, skip_rows. |
| MrmrConfig | Configures feature selection. | num_features, target_col. |
| SurdConfig | Configures discovery order. | max_order (interactions to compute). |
| AnalyzeConfig | Defines influence thresholds. | synergy_threshold, unique_threshold. |
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:139-152, deep_causality_discovery/README.md:30-34
Summary
The Causal Discovery Language (CDL) provides a formal, automated path from raw observational data to validated causal models. By combining the typestate pattern with a monadic effect system, it ensures that data science workflows are reproducible, type-safe, and diagnostically transparent. The integration of SURD and mRMR allows for high-precision structural identification, which serves as the foundational input for building complex, dynamic systems using the broader DeepCausality framework.