Forthcoming fixes - cmu-phil/tetrad GitHub Wiki

New fixes

Interim up-to-date beta versions of the Tetrad launch JAR with the updates listed below can be downloaded using this link in py-tetrad:

https://github.com/cmu-phil/py-tetrad/blob/main/pytetrad/resources/tetrad-current.jar

To download the beta version, click the link above and then click the button with the downward-pointing arrow in the upper-right corner of the page. This will save a file called tetrad-current.jar, which is a launchable Tetrad interface JAR. You may rename this file if you wish to distinguish versions.

This release substantially expands Tetrad's nonlinear and mixed-data workflow, introducing orthogonal polynomial (Legendre) and random Fourier feature (RFF) modeling frameworks with heavy-tailed likelihoods, alongside strengthened diagnostics, improved simulation tools, exact discrete inference improvements, and a new dark-mode--compatible interface.

New features

1. Added dark mode and theme-aware interface rendering.

Tetrad now includes a dark mode and broader theme-aware rendering across the interface. Session and graph workbenches, nodes, edges, plots, tables, and related UI components have been updated to respect the active Swing look-and-feel. This improves readability and visual consistency in both light and dark themes.

2. Renamed and unified FF tests and scores (formerly KFF).

The previously named KFF tests and scores have been renamed to FF (Fourier Features) tests and scores to better reflect their underlying methodology. Naming, defaults, and parameterization have been unified across tests and scores, improving clarity and consistency in hybrid workflows.

3. Added FFCI conditional independence test.

A new fast, general conditional independence test, FFCI, has been added. FFCI uses random Fourier feature approximations to perform nonlinear conditional independence testing efficiently and is designed to scale to moderate and large sample sizes.

4. Added FFML score.

A new nonlinear likelihood-based score, FFML (Fourier Features -- Maximum Likelihood), has been added. FFML approximates Gaussian-process marginal likelihood using random Fourier features and scales well to larger datasets. A slower full-Gram-matrix version remains available as KML (Kernel Maximum Likelihood). These scores are optimizations of the Gaussian-process score introduced in Huang, Zhang, Schölkopf, and Zhang (2018).

5. Added mixed versions of FFCI and FFML.

Mixed-data variants of both the FFCI test and the FFML score have been added to support datasets containing both continuous and discrete variables. Discrete variables are handled natively through appropriate feature encodings, allowing nonlinear causal discovery to be applied directly to mixed datasets.

6. Added general BIC scores for additive-noise DAG search.

The general BIC scores KCV-BIC (full Gram matrix, slower) and RFF-BIC (Fourier feature approximation, faster) remain available for users who wish to orient all edges in a DAG under additive noise assumptions. These scores are intended for DAG-search methods rather than FGES and are useful when full orientation is desired rather than a CPDAG.

7. Improved PC-Max performance and robustness.

PC-Max has been substantially improved when used with FF-CI, often matching or exceeding the performance of score-based methods in simulation for moderate-density nonlinear models while remaining computationally efficient.

8. Added cycle-prevention checks during collider orientation.

PC now explicitly forbids collider orientations that would introduce directed cycles, improving correctness and stability in finite-sample settings.

9. Expanded MAX-P collider orientation options.

MAX-P collider orientation now supports global and depth-stratified variants, improved tie handling, and optional logging for diagnostics.

10. Added a diagnostic tool for detecting nonlinear and additive structure.

A new analysis tool has been added to the Tools menu of the Data box, allowing users to detect nonlinear and additive relationships directly from data. This tool helps users choose appropriate causal discovery algorithms.

11. Added Vertex Checker and Markov diagnostics.

A new Vertex Checker tool has been added for diagnosing local violations of the Markov property in an estimated graph. For each vertex, the tool evaluates whether the conditional independencies implied by the graph (given its Markov blanket) are supported by the data using a selected conditional independence test.

The resulting p-values are aggregated into per-vertex diagnostics, allowing users to identify specific variables where the model appears mis-specified.

This tool extends the global Markov checking framework by localizing discrepancies to individual vertices. In addition to reporting vertex-level and model-wide uniformity statistics, the tool includes a model repair option, which explores nearby graphs (via single-edge edits) and ranks candidate modifications according to improvements in vertex-level and overall Markov fit.

This workflow transforms Markov checking from a global goodness-of-fit statistic into a localized model-debugging framework.

12. Added DAG Factorization Comparison tool.

A new visualization tool has been added for assessing how well a DAG-based factorized decoding recovers the marginal structure of a dataset.

The tool takes a dataset and a DAG as input and displays two synchronized plot matrices:

the original data on the left
an encoded--decoded reconstruction on the right, where the decode step is factorized according to the supplied DAG

A shared controller keeps the same variable pair and plot type in view across both panels, making it easy to visually compare recovered scatterplots and marginal histograms.

Internally, the reconstruction uses mechanisms learned from the dataset (similar to the previous Trained DAG Simulator). The resulting reconstructed data can also be exported and used downstream in other boxes in the interface.

13. Added DAG Model Scores panel.

A new model-scoring panel has been added for evaluating proposed DAGs against a dataset.

The panel takes a dataset and one or more DAGs as input and reports a table of metrics such as:

linear-Gaussian SEM fit measures (BIC, χ², CFI, model p-value, RMSEA)
nonlinear and mixed-data scores such as FF-ML, Legendre BIC, and Minimax t-RFF BIC

This provides a single location for comparing multiple notions of model fit.

14. Added Minimax t-RFF CI Test.

A new robust conditional independence test, Minimax t-RFF, has been added. The test models nonlinear relationships using random Fourier feature representations and evaluates conditional dependence via heavy-tailed regression residuals.

A minimax aggregation principle guards against heterogeneous effects and local violations of modeling assumptions.

15. Added Minimax Legendre BIC Score.

A new nonlinear BIC-style score, Minimax Legendre BIC, replaces the earlier BF Blocks and BF LRT BIC scores.

The score represents conditional response functions using an orthogonal Legendre polynomial basis, enabling stable estimation of nonlinear effects while preserving good numerical conditioning. Interaction terms between parents are optionally included.

Model fitting uses a robust heavy-tailed likelihood and a minimax aggregation principle to guard against heterogeneity and local misspecification.

16. Added Minimax t-RFF BIC Score.

A complementary nonlinear score, Minimax t-RFF BIC, represents conditional response functions using random Fourier feature expansions combined with a heavy-tailed likelihood and minimax aggregation.

It scales well to larger datasets and often performs competitively with FF-ML.

17. Added Minimax Legendre LR Test.

A likelihood-ratio conditional independence test corresponding to the Minimax Legendre BIC score has been added. The test models conditional relationships using orthogonal Legendre polynomial expansions and evaluates nested models under a robust heavy-tailed likelihood.

18. Added GCM CI Test.

The Generalized Covariance Measure (GCM) test fits regressions for X|Z and Y|Z, computes residuals, and tests independence between residuals. The method is computationally efficient because its runtime is dominated by the regression fits rather than kernel operations.

19. Added a new text-based Bayes Updater interface.

The previous interface has been replaced with a simpler text-based interface designed to be easier to use and more compatible with LLM-based workflows.

20. Added experimental doubly robust ATE tool.

An experimental tool for computing doubly robust average treatment effects (ATEs) has been added in the Regression box.

21. Unified mixed-data nonlinear causal discovery workflow.

Nonlinear tests, scores, simulation, and ATE estimation now consistently support mixed continuous and discrete datasets across the interface.

22. Experimental: causal-learn KCI integration via Python bridge.

Tetrad can optionally call the Kernel-based Conditional Independence (KCI) test from the Python causal-learn library via a lightweight subprocess bridge.

This allows users to run causal-learn's kernel-based CI implementation directly within Tetrad search algorithms such as PC and PC-Max.

Configuration uses a user-specified Python virtual environment containing causal-learn.

Setup instructions:
https://github.com/cmu-phil/tetrad/wiki/Setup-for-CL-KCI-in-Tetrad

This feature is currently experimental.

23. Added Trek-MIMIC latent structure discovery algorithm.

Trek-MIMIC has been added to the search interface as a new latent structure discovery algorithm targeting Multiple Indicators Multiple Causes (MIMIC) models. Trek-MIMIC assumes linearity and uses rank-based tests to identify clusters of indicators sharing a common latent cause, recover measured input variables that drive those latents, and orient and prune the latent-latent structure. Parameters controlling latent subset size, higher-rank expansion, and orient-and-prune behavior are configurable from the interface.

24. Added DM latent structure discovery algorithm.

DM has been added to the search interface as a second MIMIC- style latent structure discovery algorithm. Unlike Trek-MIMIC, DM-Merge does not assume linearity and accepts a user-supplied independence test, making it applicable to nonlinear and mixed-data settings.

25. Added Random MIMIC graph generator.

A new Random MIMIC graph generator has been added for simulation and benchmarking of MIMIC-style models. Each group in the generated graph has a single latent factor with private measured cause nodes (parents of the latent) and measured indicator nodes (children of the latent). A random meta-DAG is built over the latents, with optional shared measured parents wired across pairs of latents and optional impurities including cross-loadings, directed edges among measured nodes, and bidirected associations.

Bug fixes and technical improvements

Unified independence testing and p-value caching for vertex diagnostics.
Improved consistency of Markov and vertex-level diagnostics.
Locality-based speedups for Vertex Repair.
Improved ranking and filtering of Vertex Repair candidates.
FF-CI p-value approximation options fixed.
Improved defaults for FF-ML bandwidth estimation.
Fixed BOSS non-termination bug under background knowledge.
Fixed concurrency bug in RCIT p-value handling.
GridSearch reliability improvements.
Standardization added to additive noise simulator.
Required knowledge handling fixed for PC.
Junction Tree and Row Summing Exact updaters now produce identical results.
Improved numerical stability of BOSS under background knowledge.
Improved simulator consistency across nonlinear model families.

The general additive model, additive noise model, and generalized noise model simulators were updated to improve consistency of scaling, parameter interpretation, and benchmarking behavior across simulation regimes.

Improvements to the infrastructure of the Tetrad interface, addressing long-standing issues in session node lifecycle management, event dispatch, and UI state consistency.