causal

Documentation

Overview

Experimental — this package is not yet wired into the main framework.

Package causal provides causal structure learning from observational data.

The primary entry point is DiscoverGraph, which implements the PC algorithm to recover a directed acyclic graph (DAG) from data. The algorithm proceeds in three phases:

1. Skeleton discovery — start with a fully connected undirected graph and remove edges between conditionally independent variables.
2. V-structure orientation — orient colliders (X -> Z <- Y) where X and Y are non-adjacent but both adjacent to Z.
3. Edge orientation — apply Meek's rules to orient remaining undirected edges without creating new v-structures or cycles.

Conditional independence is tested via partial correlation with a Fisher z-transform significance test.

(Stability: alpha)

Index

• type CausalGraph
  • func DiscoverGraph(data [][]float64, varNames []string, config DiscoverConfig) (*CausalGraph, error)
  • func (g *CausalGraph) AdjacencyMatrix() [][]bool
  • func (g *CausalGraph) Children(node int) []int
  • func (g *CausalGraph) IsDAG() bool
  • func (g *CausalGraph) Parents(node int) []int
• type DiscoverConfig
• type Edge
• type Effect
• type Intervention
• type Prediction
  • func Intervene(graph *CausalGraph, intervention Intervention) (*Prediction, error)

Types

type CausalGraph

type CausalGraph struct {
	Nodes []string
	Edges []Edge
}

CausalGraph holds the result of causal structure discovery.

func DiscoverGraph

func DiscoverGraph(data [][]float64, varNames []string, config DiscoverConfig) (*CausalGraph, error)

DiscoverGraph learns a causal DAG from observational data using the PC algorithm. data is shaped [n_samples][n_variables] and varNames provides a label for each variable column.

func (*CausalGraph) AdjacencyMatrix

func (g *CausalGraph) AdjacencyMatrix() [][]bool

AdjacencyMatrix returns a directed adjacency matrix where adj[i][j] is true when there is a directed edge from node i to node j.

func (*CausalGraph) Children

func (g *CausalGraph) Children(node int) []int

Children returns the indices of all child nodes of the given node.

func (*CausalGraph) IsDAG

func (g *CausalGraph) IsDAG() bool

IsDAG returns true if the graph is a valid directed acyclic graph.

func (*CausalGraph) Parents

func (g *CausalGraph) Parents(node int) []int

Parents returns the indices of all parent nodes of the given node.

type DiscoverConfig

type DiscoverConfig struct {
	// Alpha is the significance level for conditional independence tests.
	// Default: 0.05.
	Alpha float64

	// MaxConditioningSet is the maximum size of conditioning sets explored
	// during skeleton discovery. A value of 0 means no limit.
	MaxConditioningSet int
}

DiscoverConfig controls the behaviour of DiscoverGraph.

type Edge

type Edge struct {
	From int
	To   int
}

Edge represents a directed causal relationship where From causes To.

type Effect

type Effect struct {
	// Variable is the name of the affected variable.
	Variable string

	// Value is the predicted value under the intervention.
	Value float64
}

Effect holds the estimated causal effect on a single variable.

type Intervention

type Intervention struct {
	// Variable is the name of the variable to intervene on (must exist in the graph).
	Variable string

	// Value is the value to set the variable to under do(Variable = Value).
	Value float64

	// Data is the observational dataset used to estimate causal coefficients,
	// shaped [n_samples][n_variables] matching the graph's node ordering.
	Data [][]float64
}

Intervention specifies a do-calculus intervention: set a variable to a fixed value. Data is required to estimate the linear causal coefficients.

type Prediction

type Prediction struct {
	// IntervenedVariable is the variable that was set.
	IntervenedVariable string

	// IntervenedValue is the value it was set to.
	IntervenedValue float64

	// Effects contains the predicted values for all downstream variables.
	Effects []Effect
}

Prediction holds the result of a causal intervention.

func Intervene

func Intervene(graph *CausalGraph, intervention Intervention) (*Prediction, error)

Intervene performs a do-calculus intervention on a causal graph: do(Variable = Value). It estimates linear causal coefficients from the provided observational data, constructs the mutilated graph (removing incoming edges to the intervened variable), and propagates the intervention value through downstream variables in topological order.