Skip to content

README.md

Latest commit

 

History

History
162 lines (118 loc) · 7.3 KB

README.md

File metadata and controls

162 lines (118 loc) · 7.3 KB

Example: Decomposing Causal Structure with SURD-States

This example demonstrates the surd_states algorithm to analyze and decompose the causal relationships from raw data of dynamic systems. It showcases how to use the algorithm and, more importantly, how to interpret its rich, detailed output.

The core idea is to go beyond a simple "A causes B" statement. The SURD-states algorithm provides a deep, multi-faceted view of causality by answering four critical questions:

  1. What is the interaction type? Is the causal influence from a set of variables Redundant (overlapping), * Unique* (direct and independent), or Synergistic (emerging only from the combination)?
  2. How strong is the influence? How much information, measured in bits, does a source variable provide about the future of a target variable?
  3. What is the role of hidden factors? How much of the target's behavior is unexplained by the variables we can see? This is the Information Leak.
  4. How does causality change with the system's state? Does a variable become more or less influential depending on its current value or the value of other variables? This is revealed by the State-Dependent Maps.

How to Run This Example

To run the analysis, run:

cargo run --example example_surd

The example will run four different test cases, each with a different underlying causal structure, and print a detailed breakdown of the causal structure.

Understanding the Output

The example analyzes a simple system with two source variables, S1 and S2, and one target variable, T. The output for each test case is broken into two parts: the aggregate (average) causal effects and the detailed state-dependent maps.

Test Case 1: Original Example Data

This is a baseline case with a mix of different causal influences.

--- SURD Decomposition Result ---
Aggregate Redundant Info: {: 0.278...,: -6.66e-17}
Aggregate Synergistic Info: {: 0.121...}
Aggregate Mutual Info: {: 0.399...,: -6.66e-17,: 0.278...}
Information Leak: 0.599...

Interpretation:

  • Information Leak (~60%): This is the first and most important number. It tells us that 60% of the target's future behavior is unexplained by our source variables S1 and S2. This suggests a significant influence from unobserved factors (noise or hidden variables).
  • Aggregate Mutual Info: [2]: 0.278 shows that, on average, S2 provides a significant amount of information about T. [1]: ~0 shows that S1 provides almost no information on its own.
  • Decomposition: The total information from S2 (0.278 bits) is almost entirely Redundant. The Synergistic term (0.121 bits) represents the new information that emerges only when we consider S1 and S2 together.
  • Conclusion: S2 is the main driver. S1 is only useful when considered in combination with S2.

Test Case 2: Low Information Leak (Strong, Synergistic System)

This models a system where the target is almost perfectly determined by the sources.

--- SURD Decomposition Result ---
Aggregate Redundant Info: {: 0.0,: 0.0}
Aggregate Synergistic Info: {: 0.531...}
Information Leak: 0.468...

Interpretation:

  • Information Leak (47%): The unexplained part is now lower. The source variables explain more than half of the target's behavior.
  • Redundant & Unique Info are Zero: Looking at S1 alone or S2 alone tells us nothing. This is the classic signature of an XOR-like relationship.
  • Synergistic Info is High: All the causal influence (0.531 bits) comes from the synergy between S1 and S2. You must know both inputs to predict the output.
  • Conclusion: The algorithm has correctly identified a purely synergistic causal structure.

Test Case 3: Medium Information Leak (Mixed System)

This models a system where S2 is the primary driver, but S1 has a small, independent effect.

--- SURD Decomposition Result ---
Aggregate Redundant Info: {: 0.014...,: 0.122...}
Aggregate Synergistic Info: {: 0.005...}
Information Leak: 0.857...

Interpretation:

  • Information Leak (86%): The system is now much noisier. The majority of the target's behavior is unexplained.
  • Decomposition: The algorithm correctly identifies that S2 has the largest influence (0.122 bits of **Redundant ** info). S1 has a smaller, but non-zero, influence (0.014 bits). The synergy is very small.
  • State-Dependent Maps are Non-Empty: This is a key result. The output Causal Unique States: [[2]] tells us that the unique causal influence of S2 is strong enough to be identified in specific states of the system.
  • Conclusion: The algorithm has correctly identified a noisy system dominated by one variable, with minor influences from another.

Test Case 4: High Information Leak (Nearly Random System)

This models a system where the target is almost completely independent of the sources.

--- SURD Decomposition Result ---
Aggregate Synergistic Info: {: 0.00115...}
Information Leak: 0.998...

Interpretation:

  • Information Leak (99.9%): This is the immediate giveaway. The algorithm is telling you that the source variables you provided have almost no predictive power over the target.
  • Aggregate Info is Near Zero: The total mutual information is tiny (0.00115 bits), which is effectively statistical noise.
  • State-Dependent Maps are Empty: This is the most important result. Because there is no meaningful causal structure to be found, the algorithm correctly reports that there are no specific states where a significant causal interaction occurs.
  • Conclusion: This is a feature, not a bug. The SURD-states algorithm has correctly analyzed a random system and concluded that there is no causality to be found. It is a powerful demonstration of the algorithm's ability to distinguish a true signal from noise.

Example: Minimum Redundancy Maximum Relevance (mRMR) Feature Selection

This example demonstrates the mrmr_features_selector algorithm, which selects a subset of features maximally relevant to a target variable and minimally redundant among themselves. Crucially, it now returns normalized importance scores (between 0 and 1) for each selected feature.

How to Run This Example

To run the mRMR feature selection example, execute:

cargo run --example example_mrmr

Understanding the Output

The example will output a list of selected feature indices along with their normalized importance scores.

Selected features and their scores:
- Feature Index: 0, Importance Score: 1.0000
- Feature Index: 1, Importance Score: 0.0855

Interpretation:

  • Feature Index: The original column index of the selected feature in the input tensor.
  • Importance Score: A normalized value between 0.0 and 1.0, indicating the relative importance of the feature.
    • For the first selected feature, this score represents its relevance (F-statistic) to the target, normalized against the maximum score found.
    • For subsequent features, this score represents its mRMR value (Relevance / Redundancy), also normalized.
  • A score of 1.0 indicates the most important feature (or one of the most important if multiple features share the top score). Lower scores indicate less importance in the context of the selected feature set.