Andrey blog

Nonlinear dependence

2026-10-23T00:00:00+00:00

A constraint-based method learns a graph from independence tests. Its result depends on the test. The default test, partial correlation, detects only linear dependence. When an effect is nonlinear, it can miss an edge or add a false one. In 0.8.0, you can use PC, FCI, GFCI, and CD-NOD with four supported tests that detect nonlinear dependence: KCI, RCoT, CMIknn, and GPDC. Each runs faster than the package we measured it against at every size we timed, at the same level of accuracy: PC with RCoT runs more than 5x faster than causal-learn and more than 9x faster than pcalg.

TL;DR

Four supported nonlinear tests: indep_test="kci", "rcot", "cmiknn", and "gpdc", in pc, fci, gfci, and cdnod.
Faster than the reference package at every size we timed, at the same level of accuracy: PC with RCoT runs 5.9x to 36x faster than causal-learn and 9.5x to 29x faster than pcalg.
KCI and CMIknn also run on a CUDA GPU, with the same graphs as on the CPU.

What partial correlation misses

Partial correlation asks whether y rises or falls with x in a straight line. Many effects do not: a dose helps up to a point and then harms, a signal repeats, a cost grows with the square of a size. Each panel below has 400 points with the same noise.

	Partial correlation	KCI	RCoT	CMIknn	GPDC
y = x	✓p < 0.001	✓p < 0.001	✓p < 0.001	✓p = 0.002	✓p < 0.001
y = cos(x)	✗p = 0.17	✓p < 0.001	✓p < 0.001	✓p = 0.002	✓p < 0.001
y = x²	✗p = 0.23	✓p < 0.001	✓p < 0.001	✓p = 0.002	✓p < 0.001

Three ways y depends on x, each with the same noise; ✓ finds the dependence at alpha 0.05. Partial correlation measures only a straight-line trend, so it misses the cos and the square; KCI, RCoT, CMIknn, and GPDC find all three.

All the tests detect the linear dependence. For the cosine and the square, y depends on x, but the straight-line trend is flat, so partial correlation misses the dependence. KCI uses kernels to compare the two variables and detects all three relationships.

An example

We simulate 500 rows of 8 variables, each a weighted sum of the cosines of its causes plus noise. We fit PC with partial correlation and with each nonlinear test, then count the true edges each finds.

example.py

import andrey
from andrey.data import sample_scm

data = sample_scm(d=8, n=500, functional="nonmonotone", density=2.0, scale="standardize", seed=0)
true = data.graph.adjacency != 0
true |= true.T

for test in ("fisherz", "kci", "rcot", "cmiknn", "gpdc"):
    fit = andrey.pc(data.data, alpha=0.05, indep_test=test)
    found = fit.structure.adjacency != 0
    found |= found.T
    hits, extra = (found & true).sum() // 2, (found & ~true).sum() // 2
    print(f"{test:>7}: {hits} of {true.sum() // 2} true edges, {extra} extra")

example.py

fisherz: 3 of 8 true edges, 4 extra
    kci: 8 of 8 true edges, 0 extra
   rcot: 8 of 8 true edges, 0 extra
 cmiknn: 8 of 8 true edges, 0 extra
   gpdc: 7 of 8 true edges, 0 extra

True graph

8 links

Partial correlation

3 of 8 found, 4 extra

KCI

8 of 8 found, 0 extra

RCoT

8 of 8 found, 0 extra

CMIknn

8 of 8 found, 0 extra

GPDC

7 of 8 found, 0 extra

The example's true graph, and the graph PC finds on its 500 rows with each test.

Partial correlation finds 3 of the 8 edges and adds 4 false edges. KCI, RCoT, and CMIknn find all 8, and GPDC finds 7. None of the nonlinear tests adds a false edge.

Four tests

Each test asks whether x and y are independent given a set of variables z. They differ in how they measure dependence and how much computation they need.

`indep_test`	Test	How it decides	Cost
`"kci"`	Kernel conditional independence (Zhang et al., 2011)	Compares `x` and `y` in a Gaussian-kernel feature space after removing `z`	Grows with the square of the rows or faster; `rank=k` caps each kernel at `k` columns
`"rcot"`	Randomized conditional correlation (Strobl, Zhang, and Visweswaran, 2019)	Approximates the kernel test with quasi-Monte Carlo random Fourier features, sampled for each conditioning set	Linear in the rows; warns below 500 rows
`"cmiknn"`	Nearest-neighbor conditional mutual information (Runge, 2018)	Estimates conditional mutual information and builds its null by shuffling `x` among neighbors in `z`	500 shuffles per test by default
`"gpdc"`	Gaussian-process distance correlation (Runge et al., 2019)	Regresses `x` and `y` on `z` with Gaussian processes, then tests the residuals with distance correlation	Grows with the cube of the rows per regression

Your choice depends on the size of your data:

RCoT takes time linear in the number of rows. Every fit we ran finished, up to 50 variables and 5,000 rows. It warns below 500 rows.
KCI reached 20 variables at 2,000 rows in our runs. For more rows, KCI(rank=...) caps its cost, and a GPU runs it faster.
CMIknn is the slowest of the four: 10 variables at 500 rows takes minutes.
GPDC reached 20 variables at 1,000 rows in our runs. Its cost grows with the cube of the rows.

How fast

We compared PC and FCI with each test against the package that implements it: causal-learn for KCI and RCoT, pcalg with RCIT for RCoT, and tigramite for CMIknn and GPDC. We ran each on additive data and on nonmonotone data generated with cos, using 20 datasets per size, and timed 5 of them.

Each test against its reference package

		Faster by
PC and FCI	KCIvs causal-learn	2.7-5.6x
	RCoTvs causal-learn	5.9-36x
	RCoTvs pcalg	9.5-29x
	CMIknnvs tigramite	2.3-10x
	GPDCvs tigramite	1.3-1.9x

The range over sizes of the reference's median fit time over Andrey's.

Each test runs at the same level of accuracy as its reference package. The release card gives the errors at every size. On nonmonotone data, partial correlation makes more errors than the empty graph from 10 variables onward, while every nonlinear test makes fewer errors than the empty graph.

KCI and CMIknn also run on a CUDA GPU (ANDREY_BACKEND=cuda) and return the same graph as on the CPU; the 0.8.0 release card lists the speedups and the hardware.

Limits

Measured sizes. PC up to 20 variables at 2,000 rows with KCI, 50 variables at 5,000 rows with RCoT, 20 variables at 500 rows with CMIknn, and 20 variables at 1,000 rows with GPDC. FCI with KCI and RCoT at 5 and 10 variables. The release card lists every size and the hardware.
Cost. KCI and GPDC costs grow quickly with the number of rows; KCI(rank=...) caps KCI’s cost. CMIknn grows with the number of variables and rows.

0.8.0 also brings background knowledge for every search, score defaults that follow the data, and faster categorical tests. The 0.8.0 release card and the changelog give the details.

Try it

pip install -U andrey-core

Help us build it

Andrey is in alpha. The API may change between releases. When you try it on your own data, tell us what breaks or which method you need. We also welcome pull requests. The contributing guide explains how you can set up the development environment.

Acceleration

2026-10-23T00:00:00+00:00

Andrey was already the fastest causal discovery package. 0.9.0 is our biggest speed breakthrough yet, the fastest causal discovery we have ever shipped: BOSS runs up to 8.1x faster than before, exact search 5.2x, and FCI and GFCI 3.1x, and every graph is exactly the same. Every release so far added methods or data; this one is all speed. This post is the first of two. Here the rocket lifts off. The next release, 0.10.0, follows it up to the boundary: how far each method now goes before it stops finishing, or stops being accurate.

TL;DR

The fastest Andrey ever. Speedups over 0.8.0, at the best of the sizes we measured:
- Permutation-based: BOSS up to 8.1x, GRaSP 3.8x.
- Score-based: exact search 5.2x, GES and XGES 1.7x.
- Constraint-based: FCI and GFCI 3.1x, PC 1.8x, CD-NOD 1.6x.
- LiNGAM, pairwise, and temporal: LPCMCI 2.8x, PNL 2.2x, DirectLiNGAM and MultiGroupDirectLiNGAM 1.9x.
Exactly the same answers: in all 1,216 identity checks, 27 methods in five column orders with one worker and four, 0.9.0 returns exactly 0.8.0’s output.
PC, FCI, GFCI, and CD-NOD spread their largest skeleton passes over worker processes: with four workers, CD-NOD runs up to 4.6x faster than 0.8.0 and PC 2.6x. andrey calibrate measures when the workers pay off on your machine.

Where the time went

A causal discovery method spends its time on three jobs: tests or scores, the bookkeeping of the graph it searches, and the memory that holds them. The Why Andrey is fast post shows the ideas we started from. 0.9.0 applies them further, without changing a single result.

Ask in stacks. PC, FCI, GFCI, and CD-NOD test whether two variables are independent given a set of others. 0.9.0 hands the test all of a pair’s conditioning sets at once, together with those of the pairs next to it, so one array operation answers what took many. Exact search does the same for its scores: it solves the equations of up to 4,096 parent sets in one call.

Use every core. With more than one worker, the largest passes of the PC, FCI, GFCI, and CD-NOD skeleton search run in worker processes. Small passes stay in one process, where starting workers would cost more than it saves. andrey calibrate measures that cutoff on your machine.

Copy less. A search tries many changes to its graph and keeps few. XGES now copies only the part of the graph a branch changes. After each move, GES updates only the edges the move can reach instead of rebuilding the whole graph, and keeps each reach set until a move can change it. BOSS and GRaSP keep one tuple of candidate parents, and the set of allowed parents, instead of building them again on every step.

Build once. FCI computes one reach set per variable for its possible-d-separation step, and builds its neighbor lists and reach sets once for each version of the graph; GFCI builds each node’s neighbor list once. LPCMCI keeps each node’s neighbors and paths for each version of the graph instead of building them for every query. Exact search looks up each variable’s best parent set in a table built once per fit. DirectLiNGAM and the methods built on it compute each pair’s residual entropy once per step instead of twice. PNL builds each variable’s kernel once and can run its independence tests on a CUDA GPU.

Hold less. The first pass of PC, FCI, GFCI, and CD-NOD builds its queries one stack at a time instead of listing every pair’s conditioning sets first, which on a complete graph of 1,000 variables held gigabytes. ANM and the KCI test build their kernels in blocks, in one reused matrix.

An example

The answer does not depend on how many workers you use. We fit GES on 200 variables with one worker and with four, and compare the graphs.

example.py

import numpy as np

import andrey
from andrey.data import sample_scm

if __name__ == "__main__":  # worker processes re-import this script
    data = sample_scm(d=200, n=2000, density=2.0, seed=0)

    # The same fit with one worker and with four.
    graphs = {}
    for workers in (1, 4):
        with andrey.config(num_workers=workers):
            graphs[workers] = andrey.ges(data.data).structure.adjacency

    print("same graph with 1 and 4 workers:", np.array_equal(graphs[1], graphs[4]))

example.py

same graph with 1 and 4 workers: True

How much faster

We timed each method in 0.9.0 against Andrey 0.8.0 on the same datasets, side by side on the same machine.

How much faster than Andrey 0.8.0

Each bar runs from a method's smallest to its largest speedup over the measured sizes, with one worker. 1x is as fast as 0.8.0.

The gains grow with the problem: BOSS is 2.9x faster at 200 variables and 8.1x at 400, and GFCI 2.2x at 200 and 3.1x at 400, because the work we removed, copies and repeated bookkeeping, grows faster than the tests and scores themselves. Every one of these fits returned exactly 0.8.0’s output.

GES now also runs 1.6x to 5.4x faster than pcalg’s, whose GES is written in C++, with the same or fewer errors at every size. The 0.9.0 release card gives every size, the conditions, and the comparison with pcalg.

Limits

Measured speedups. A speedup depends on the data, the settings, and the machine. Methods without speed work in 0.9.0 run as fast as in 0.8.0; the release card names them.
Same answers. In the identity checks, the LiNGAM methods return 0.8.0’s output exactly. Their internal scores can differ in the last bits, which could change a causal order only at an exact tie between two candidates. With one worker, PNL lets its linear algebra use every core, so on a machine with several cores its result can differ in the last digits from that with several workers.
Workers. Worker processes repay their start-up cost only on large passes. On a small problem, one worker is as fast.

Try it

pip install -U andrey-core

Help us build it

Permutation invariance

2026-10-19T00:00:00+00:00

Give two people the same table with its columns in different orders. Ask each to learn a causal graph. They should get the same graph. Column order carries no information: it comes from a database export, a DataFrame, or whoever wrote the CSV. A method whose graph does not depend on that order is permutation invariant.

Many causal-discovery methods are not invariant. When two steps look equally good, they take the first one they find, and “first” means the leftmost column. Colombo and Maathuis (2014) showed this for PC. It matters for three reasons:

Reproducibility. Two analysts with the same data get different graphs.
Trust. An edge that flips when you reorder the columns was never supported by the data.
Benchmarks. Data generators often write columns in an order tied to the graph, so a method that favors the first column gains or loses accuracy it did not earn.

We plan to make Andrey the first package in which every method is permutation invariant. As a first step, 0.7.0 makes nine methods invariant: their choices follow the data, not the column order. Our benchmark also shuffles the columns, so their order cannot skew the results.

Andrey 0.7.0 brings permutation invariance to PC, FCI, GFCI, CD-NOD, hill climbing, tabu search, BOSS, GRaSP, and GIN: reordering the columns in your dataset no longer changes the discovered causal graph.
It costs almost no speed: each fix reuses work the method already does.
By eliminating sensitivity to arbitrary column ordering, Andrey makes causal discovery more reproducible, reliable, and trustworthy.

Datasets where reordering the columns changed the graph (lower is better)

		Andrey 0.7.0	Andrey 0.6.0	causal-learn
Score-based	Hill climbing, BDeu	0%	97%	-
	Hill climbing, BIC	0%	98%	-
	Tabu search, BDeu	0%	75%	-
	Tabu search, BIC	0%	79%	-
Permutation	BOSS	0%	97%	91%
Permutation	GRaSP	0%	99%	100%
Hidden causes	GIN	0%	73%	-

How we found it

It started with hill climbing. On the 0.6.0 categorical benchmark, pgmpy’s hill climbing had fewer errors than Andrey’s on 17 datasets. We went looking for a bug and found a tie: adding x -> y and adding y -> x can score exactly the same, and Andrey gave the tie to whichever column came first. Reverse the columns, and Andrey had no more errors than pgmpy on 14 of the 17.

Then we checked our own data. Our generators wrote columns in an order tied to the graph: on a scale-free graph, the biggest hub came first. That order misled us. A better PC rule looked worse until we shuffled the columns.

Before 0.7.0: column 1 is the hub

0.7.0: columns shuffled

p-value rule minus column-order rule, endpoint errors

Columns as generated

+1.0

+4.8

Columns shuffled

-1.0

-3.1

fewer errorsmore errors

Each node is numbered by its column.

Why it happens

Column order enters when a method takes the first of two equally good steps. In PC, two colliders can disagree about one edge, and whichever PC orients first wins.

Below, A causes B, C, and D, and each of them causes E. A and E look independent given B, with a p-value of 0.052, just above the significance level of 0.05, so PC also proposes two false colliders, A -> C <- E and A -> D <- E. The column-order rule visits colliders by the column they point into, left to right: whenever C or D sits left of E, a false collider wins. The p-value rule starts with the most clearly separated pair, so the true colliders always win.

Click a column to move it first, or shuffle them all.

The data. A causes B, C, and D, and each of them causes E. PC proposes five colliders; two are false.

0.6.0: column-order rule

Visits the colliders column by column, left to right: each waits under the column it points into.

1. 1A->C<-Ep = 0.052orients
1. 2A->D<-Ep = 0.052orients
1. 3B->E<-Cp = 0.821skipped: C-E taken
2. 4B->E<-Dp = 0.631skipped: D-E taken
3. 5C->E<-Dp = 0.273skipped: C-E, D-E taken

C and D sit left of E, so their false colliders take C-E and D-E first.

This graph comes from 40 of 120 orders. Graphs seen: 1 of 4.

0.7.0: p-value rule

Visits the colliders by p-value, highest first: the most clearly separated pair goes first, wherever its columns sit.

1B->E<-Cp = 0.821orients
2B->E<-Dp = 0.631orients
3C->E<-Dp = 0.273orients
4A->C<-Ep = 0.052skipped: C-E taken
5A->D<-Ep = 0.052skipped: D-E taken
0.05p = 1

The true graph, from all 120 orders.

PC on the same 300 rows. A dashed card is a collider the true graph does not have.

The same thing happened in hill climbing and tabu search (score ties), BOSS and GRaSP (a starting order taken from the columns), GIN (a test built from each cluster’s first column), and FCI and GFCI (rules and a search step that visit the columns in order).

How we fixed it

Each fix replaces a column’s position with a value computed from its data, which moves with the column.

PC. Conflicting colliders are oriented by the p-value that separated each pair, highest first, adapting Ramsey (2016). Meek’s rules then apply in rounds, so an edge they disagree about stays undirected. In 16 settings, no reordering changed PC’s graph, and PC made fewer errors in every one, for at most about 4% more time.
Hill climbing and tabu search. Exact score ties go to a rank computed from each column’s data. Accuracy is unchanged.
BOSS and GRaSP. Both search the columns sorted by that rank. Their accuracy matches causal-learn’s.
GIN. The test that orders the hidden causes uses every member of a cluster, not the first.
FCI and GFCI. Their rules apply in rounds, and the possible-d-separation step visits the columns by rank. possible_dsep="fast" keeps the column-order step.
Benchmark data. Our data generators and andrey.data.load_dataset shuffle the columns along with the true graph.

Simulated data can understate the problem, so we also ran FCI on six real tables, each under 200 random column orders (20 for the full superconductivity table). With the default, no order changed the result.

Column orders that changed FCI's result (lower is better)

		Default	possible_dsep="fast"
Real tables	Sachs protein signaling11 variables, 853 rows	0%	0%
	Wine13 variables, 178 rows	0%	0%
	Diabetes10 variables, 442 rows	0%	75%
	Breast cancer30 variables, 569 rows	0%	78%
	Superconductivity, 1,000-row sample81 variables, 1,000 rows	0%	64%
	Superconductivity81 variables, 21,263 rows	0%	100%

What it costs

Almost nothing. A fix that runs more tests or more score evaluations would trade speed for order independence, so each fix reuses work the method already does:

PC orients by the p-values of the tests that removed each edge, so it runs no new test. With Meek’s rules in rounds, a fit takes at most about 4% longer.
Hill climbing and tabu search rank each column once per fit, from its data, and add no score evaluations.
BOSS and GRaSP sort the columns once by that rank and run the same search, in 1.03x and 0.91x the time of 0.6.0.
GIN runs its root test once per member of a cluster, but builds each column’s kernel matrix once per fit instead of once per test, so it runs about 4x to 7x faster than before.
FCI and GFCI put the columns in rank order once and run the same search, in 0.99x to 1.05x the time at 20 to 200 variables.

One trade remains. On some graphs with 400 or more variables, FCI’s and GFCI’s order-free step can take longer: on one graph, 406 to 417 s against 120 to 336 s for the column-order step. possible_dsep="fast" keeps that step.

How Andrey compares

Permutation invariance is a yes-or-no property, so a few small examples answer it. We fit each package’s implementation at its defaults on three small datasets per method, each in nine column orders, and checked whether any reordering changed the graph.

Does reordering the columns change the graph?

		Andrey 0.7.0	causal-learn 0.1.4.8	pcalg 2.7-12	bnlearn 5.2.1	pgmpy 1.1.2	Tetrad 7.6.10
Constraint	PC	Same	Changed	Changed	Changed	By name	By name
Constraint	FCI	Same	Changed	Changed	-	-	By name
Score-based	Hill climbing	Same	-	-	Changed	By run	-
Score-based	Tabu search	Same	-	-	Changed	-	-
Permutation	BOSS	Same	Changed	-	-	-	Changed
Permutation	GRaSP	Same	Changed	-	-	-	Changed
Hidden causes	GIN	Same	Changed*	-	-	-	Changed

Each package at its defaults, on three small datasets per method, each in nine column orders; causal-learn's and Tetrad's BOSS and GRaSP ran without their own randomness. By name: the graph follows the variables' names, so it can change when the names follow the positions, as a bare array's do. By run: pgmpy's hill climbing breaks ties in Python's hash order, which changes between runs. * causal-learn's GIN also tests columns by position, a known bug (py-why/causal-learn#271).

For BOSS, GRaSP, GIN, and tabu search, every other implementation we checked changed its graph under some reordering. pcalg and causal-learn can make PC’s colliders order-independent, but only with options that are off by default; Andrey does it by default, with no extra tests.

Try it

pip install -U andrey-core

Fit PC on 10 random orders of the same columns, with the old rule and with 0.7.0’s default:

example.py

import numpy as np

import andrey
from andrey.data import sample_scm

data = sample_scm(d=50, n=500, density=4.0, scale="standardize", seed=0).data
rng = np.random.default_rng(0)
orders = [rng.permutation(data.shape[1]) for _ in range(10)]

for rule in ("column", "p_value"):
    graphs = set()
    for order in orders:
        fit = andrey.pc(data[:, order], alpha=0.05, collider_order=rule)
        back = np.argsort(order)  # put the columns back in their first order
        graphs.add(fit.structure.adjacency[np.ix_(back, back)].tobytes())
    count = len(graphs)
    print(f"collider_order={rule!r}: {count} graph{'s' if count > 1 else ''} from 10 column orders")

Output

collider_order='column': 10 graphs from 10 column orders
collider_order='p_value': 1 graph from 10 column orders

The 0.7.0 release card reports every measurement in this release, with each method’s limits, and the changelog lists every change.

Mixed and categorical data

2026-10-17T00:00:00+00:00

Your tables may contain more than numbers. A customer record holds a plan and a region alongside hours used and the amount billed. A patient record holds a diagnosis alongside blood pressure. With Andrey 0.6.0, you can learn causal graphs from categorical data and from tables that mix categorical and continuous columns.

TL;DR

GES on categorical data: more than 50x faster than causal-learn at every size, with the same graph on every dataset.
Hill climbing on categorical data: more than 20x faster than pgmpy at every size.
PC on mixed data: more than 10x faster than Tetrad at 10 and 20 variables.

We explain how Andrey reads each kind of column, run an example, and report benchmark results.

Tests and scores

A constraint-based method tests whether two variables are independent given others. A score-based method compares graphs by how well they explain the data. Each needs a test or score that fits your data. In Andrey 0.6.0 you can use both with categorical and mixed data.

Data	Tests	Scores
Categorical	`"chisq"` (chi-square), `"gsq"` (G-square)	`"local_score_BDeu"`, `"local_score_BIC_categorical"` (multinomial BIC)
Mixed	`"degen_gauss"` (degenerate Gaussian), `"cond_gauss"` (conditional Gaussian)	`"local_score_degen_gauss"`, `"local_score_cond_gauss"`

PC, FCI, GFCI, and CD-NOD take every test. GES, GFCI, hill climbing, and exact search take every score; Tabu search takes the categorical scores, and BOSS and GRaSP the mixed ones. GFCI, CD-NOD, exact search, and the mixed scores in BOSS and GRaSP are experimental.

The two mixed-data forms make different assumptions:

Degenerate Gaussian replaces a categorical column of k categories with k - 1 indicator columns and treats every column as Gaussian. It suits effects that add up across categories. It is the faster of the two, though only slightly in PC.
Conditional Gaussian fits a Gaussian with its own mean and covariance to the continuous variables within each combination of categories. A category can change the spread as well as the average. It needs several rows in each combination.

You do not need to encode a DataFrame’s text, bool, or category columns; Andrey reads them as categorical. With a mixed-data test or score, Andrey also reads a column with at most 10 distinct whole numbers as categorical and issues a warning. To be sure, name the categorical columns with categorical=[...], or change the limit with max_categories.

Example

We simulate 2,000 customers. Their plan and region each change how many hours they use the service. The hours set the monthly bill. Plan and region are text; hours and bill are numbers.

example.py

import numpy as np
import pandas as pd

import andrey

# Customers of a service. Their plan and their region each change how many hours they use it,
# and the hours set the monthly bill. Plan and region are text; hours and bill are numbers.
rng = np.random.default_rng(0)
n = 2000
plan = rng.choice(["basic", "pro"], size=n)
region = rng.choice(["north", "south", "west"], size=n)
shift = {"north": 0.0, "south": 3.0, "west": -3.0}
hours = 10 + 12 * (plan == "pro") + np.vectorize(shift.get)(region) + rng.normal(0, 3, n)
bill = 5 + 1.5 * hours + rng.normal(0, 5, n)
data = pd.DataFrame({"plan": plan, "region": region, "hours": hours, "bill": bill})

# The conditional Gaussian test and score handle both kinds of column.
categorical = ["plan", "region"]
print(andrey.pc(data, indep_test="cond_gauss", categorical=categorical), end="\n\n")
print(andrey.ges(data, score_func="local_score_cond_gauss", categorical=categorical))

PC with the conditional Gaussian test and GES with the conditional Gaussian score both find and orient all three links in the model. Plan and region are independent, but both change the hours. This lets the data show which way those two links run, then orient the link from hours to the bill.

example.py

PC  cpdag  |  4 nodes  |  3 edges (3 directed)

  plan -> hours
  region -> hours
  hours -> bill

  categorical: ['plan', 'region']

GES  cpdag  |  4 nodes  |  3 edges (3 directed)

  plan -> hours
  region -> hours
  hours -> bill

  score: 2.943e+04
  categorical: ['plan', 'region']

Benchmarks

We compare methods on simulated categorical and conditional linear Gaussian networks with 10, 20, and 40 variables and 2,000 rows. We use 5 categorical datasets and 10 mixed datasets at each size. We compare each method with packages that implement it: causal-learn and pgmpy in Python, bnlearn in R, and Tetrad in Java.

Method	Data	Compared with	Andrey’s speedup	Graph
GES, BDeu score	Categorical	causal-learn	more than 50x at every size	the same as causal-learn’s on every dataset
Hill climbing, BDeu and BIC scores	Categorical	pgmpy	more than 20x at every size	the same scores; the graphs differ on 28 of 30 datasets, with fewer errors on 9 and more on 17; on those 17 the two searches part at a tie between two equal moves, which they break differently
PC, conditional Gaussian test	Mixed	Tetrad	more than 10x at 10 and 20 variables	fewer errors on 12 of the 18 datasets Tetrad finished, more on 4
GES, conditional Gaussian score	Mixed	Tetrad (FGES)	more than 9x at every size	the same on 11 of 30 datasets; of the other 19, fewer errors on 11 and more on 7
PC, chi-square and G-square tests	Categorical	bnlearn	more than 3x at 20 and 40 variables	fewer errors on 24 of 30 datasets, more on 2
PC, chi-square and G-square tests	Categorical	causal-learn	more than 2x at 20 and 40 variables	the same as causal-learn’s on every dataset

Each speedup holds at every size it names. At 10 variables, PC on categorical data takes under 0.1 s in every package, too fast to time fairly. Its speedups therefore start at 20. Tetrad’s PC with the conditional Gaussian test stopped with an error on 12 of its 30 fits. The table counts only the datasets both packages finished.

You can find every measurement in the 0.6.0 release card, including comparisons with bnlearn’s hill climbing and the degenerate Gaussian forms. It also shows where Andrey is not faster and gives the machine, settings, and known limits.

More features

Simulated networks. andrey.data.sample_discrete and sample_mixed sample a categorical or a conditional linear Gaussian network along with its true graph.
Published networks as categorical data. load_dataset("alarm", discrete=True) samples ASIA, ALARM, HEPAR2, or ANDES from the network’s own probability tables.
Hill climbing respects the model. With a mixed-data score, hc never adds an edge from a continuous variable to a categorical one. A conditional linear Gaussian network cannot express that edge.

The categorical tests and scores build on work by Rui Zhu (#94). Thank you, Rui.

For details, read the changelog.

Try it

pip install -U andrey-core

Pass a DataFrame with text or category columns to andrey.pc(data, indep_test="cond_gauss") or andrey.ges(data, score_func="local_score_cond_gauss"), or use "chisq" and "local_score_BDeu" when every column is categorical.

Contribute

Andrey is in alpha. The API may change between releases. When you try it on your own data, tell us what breaks or which method you need. We also welcome pull requests. You can find setup instructions in the contributing guide.

Temporal causal discovery

2026-10-16T00:00:00+00:00

Causes take time. Rain today slows today’s traffic, and today’s traffic shapes tomorrow’s sales. When you measure the same variables day after day, the order of the days tells you which way a link can run: the future cannot cause the past. As of 0.5.0, we support six methods that use this order: PCMCI, PCMCI+, LPCMCI, lasso Granger causality, VARMA-LiNGAM, and LongitudinalLiNGAM.

We explain what a time-series method finds, run two on a small example, and report benchmark results.

Links across time

A time-series method returns one graph per lag. The lag-1 graph holds the links from yesterday to today. The lag-0 graph holds the links within one day. Most variables also depend on their own past, so each graph can hold a variable’s link to itself.

The methods look for different links and make different assumptions:

PCMCI uses conditional independence tests for each lagged link. It first selects each variable’s likely causes from the past, then tests every link given the causes of both ends.
PCMCI+ adds the links within a time step and orients them where the data allow.
LPCMCI allows for series you did not measure. It returns a time-series PAG, whose circles mark the ends the data cannot orient.
Granger regresses each variable on the past of every variable with a cross-validated lasso and keeps the lagged links with nonzero coefficients.
VARMA-LiNGAM uses non-Gaussian noise to order the variables within a time step and estimates the weight of every link, lagged and within a step.
LongitudinalLiNGAM takes a panel instead of one long series: many units, each measured at a few time points.

Supported methods

Before each release, we benchmark each supported method against another package and check its results on known data. PCMCI, PCMCI+, LPCMCI, and Granger are new in this release. VARMA-LiNGAM and LongitudinalLiNGAM were experimental until now.

Method	Finds	Returns
PCMCI	Lagged links	One directed graph per lag
PCMCI+	Lagged links and links within a step	A CPDAG within a step and a directed graph per lag
LPCMCI	The same, with unmeasured series	A time-series PAG
Granger	Lagged links	One directed graph per lag, with the coefficients as weights
VARMA-LiNGAM	Weighted links within a step and from the step before	Weighted graphs for each lag and the moving average
LongitudinalLiNGAM	Weighted links in a panel	Weighted graphs at every time point but the first

Choose a method for your data:

PCMCI+ when links can act within one time step, as they do when you measure once a day.
PCMCI or Granger when every effect takes at least one step.
LPCMCI when a variable you did not measure may drive several that you did.
VARMA-LiNGAM when you need the size of each effect and the noise is non-Gaussian.
LongitudinalLiNGAM when you follow many units over a few time points.

An example

We simulate three daily series. Rain slows traffic the same day, traffic drives the next day’s sales, and each series carries over from the day before.

example.py

import numpy as np
import pandas as pd

import andrey

# Three daily series. Rain slows traffic the same day; traffic drives the next day's sales; each
# series also carries over from the day before.
rng = np.random.default_rng(0)
days = 1000
e = rng.uniform(-1, 1, size=(days, 3))
x = np.zeros((days, 3))
for t in range(1, days):
    rain = 0.6 * x[t - 1, 0] + e[t, 0]
    traffic = 0.5 * x[t - 1, 1] - 0.6 * rain + e[t, 1]
    sales = 0.4 * x[t - 1, 2] + 0.7 * x[t - 1, 1] + e[t, 2]
    x[t] = rain, traffic, sales
data = pd.DataFrame(x, columns=["rain", "traffic", "sales"])

# Links from the past only, then links within a day as well.
print(andrey.pcmci(data, tau_max=1), end="\n\n")
print(andrey.pcmciplus(data, tau_max=1))

The links each method finds in the example

PCMCILinks from the past only; 2 links not in the model

PCMCI+Links within a day as well; the model's links exactly

in the model, from yesterday
in the model, within the day
not in the model

PCMCI+ finds exactly the five links in the model, including the same-day link from rain to traffic.

PCMCI tests only lagged links, so it cannot find the same-day effect. It also finds two links absent from the model. Yesterday’s rain predicts today’s traffic because rain persists and today’s rain slows today’s traffic. Yesterday’s sales also predict today’s traffic. When your measurements are coarser than the effects, use a method that tests links within a step.

The script prints both results:

example.py

pcmci  temporal  |  3 nodes  |  1 lags

  lag 1  |  6 edges (6 directed)
    rain -> rain
    rain -> traffic
    traffic -> traffic
    traffic -> sales
    sales -> traffic
    sales -> sales

  p_values: a list of 1, too long to print; read metadata['p_values']
  statistics: a list of 1, too long to print; read metadata['statistics']
  parents: [[[0, 1]], [[1, 1], [0, 1]], [[1, 1], [2, 1], [0, 1]]]

pcmciplus  temporal  |  3 nodes  |  2 lags

  lag 0  |  1 edges (1 directed)
    rain -> traffic

  lag 1  |  4 edges (4 directed)
    rain -> rain
    traffic -> traffic
    traffic -> sales
    sales -> sales

  p_values: a list of 2, too long to print; read metadata['p_values']
  statistics: a list of 2, too long to print; read metadata['statistics']
  parents: [[[0, 1]], [[1, 1], [0, 1]], [[1, 1], [2, 1]]]
  conflicts: []
  ambiguous_triples: []

Benchmark results

We compared each method with a package that implements it, using the simulations in the method’s paper: PCMCI, PCMCI+, and LPCMCI with tigramite, and the two LiNGAM methods with lingam.

Method	Compared with	Andrey’s speedup	Graph
PCMCI+	tigramite	more than 50x at every size; more than 100x at 80 variables and 2,000 steps	the same as tigramite’s on every dataset
PCMCI	tigramite	more than 20x at 10 variables	the same as tigramite’s on every dataset
LPCMCI	tigramite	more than 8x at every size	the same on 73 of 90 datasets; of the other 17, fewer errors on 12 and more on 5
LongitudinalLiNGAM	lingam	more than 1.3x at every timed size	the same on 231 of 240 datasets; of the other 9, fewer errors on 8 and more on 1

Each speedup holds at every size it names, where Andrey’s graphs have fewer errors than an empty graph.

The 0.5.0 release card reports every measurement for all six methods, including Granger and VARMA-LiNGAM. It also gives the sizes, machine, settings, and known limits.

Speedup over each method's other package

d=10, n=50023.2x

d=10, n=1,00024.0x

d=10, n=2,00027.4x

d=20, n=50051.4x

d=20, n=1,00058.8x

d=20, n=2,00069.5x

d=40, n=50086.6x

d=40, n=1,000104x

d=40, n=2,000125x

d=80, n=50088.6x

d=80, n=1,000132x

d=80, n=2,000166x

d=160, n=1,00091.6x

d=10, n=50052.0x

d=10, n=1,00054.8x

d=10, n=2,00067.8x

d=20, n=50072.9x

d=20, n=1,00082.9x

d=20, n=2,00096.6x

d=40, n=50064.7x

d=40, n=1,00069.4x

d=40, n=2,00084.3x

d=80, n=1,00096.4x

d=80, n=2,000116x

d=5 (4 observed), n=5008.56x

d=5 (4 observed), n=1,00012.0x

d=5 (4 observed), n=2,00015.9x

d=10 (7 observed), n=50010.4x

d=10 (7 observed), n=1,00012.6x

d=10 (7 observed), n=2,00018.7x

d=20 (14 observed), n=50010.8x

d=20 (14 observed), n=1,00012.2x

d=20 (14 observed), n=2,00016.5x

d=10, n=1,0003.34x

d=20, n=1,0003.09x

d=40, n=1,0002.83x

d=80, n=1,0002.15x

d=160, n=1,0001.59x

d=3, n=1001.05x

d=3, n=3001.00x

d=3, n=1,0001.02x

d=5, n=1001.06x

d=5, n=3000.962x

d=5, n=1,0001.03x

d=10, n=1001.03x

d=10, n=3001.01x

d=10, n=1,0001.04x

d=20, n=1001.11x

d=20, n=3001.13x

d=20, n=1,0001.12x

d=2, n=20, M=1,0001.37x

d=2, n=50, M=1001.60x

d=2, n=50, M=2001.42x

d=2, n=50, M=5001.34x

d=2, n=50, M=1,0001.33x

d=3, n=20, M=1001.55x

d=3, n=20, M=2001.47x

d=3, n=20, M=5001.52x

d=3, n=20, M=1,0001.66x

d=3, n=50, M=1001.52x

d=3, n=50, M=2001.54x

d=3, n=50, M=5001.59x

d=3, n=50, M=1,0001.55x

d=5, n=20, M=1001.90x

d=5, n=20, M=2002.02x

d=5, n=20, M=5002.24x

d=5, n=20, M=1,0001.77x

d=5, n=50, M=1001.87x

d=5, n=50, M=2001.95x

d=5, n=50, M=5001.96x

d=5, n=50, M=1,0001.84x

Each bar is the median, over the datasets of that size, of the other package's time divided by Andrey's on the same dataset. Each method's bars share its own scale.

Speed is not accuracy. On the larger simulated graphs, PCMCI’s graphs have more errors than an empty graph in both packages, and so do Granger’s. A fast answer still needs enough data for the question; the release card lists where these methods fall short.

Other highlights

A Student-t test for PC and FCI. pc, fci, gfci, and cdnod take indep_test="student_t", the partial-correlation test that the time-series methods use.
VARMA-LiNGAM weights. With prune=True, VARMA-LiNGAM refits the weights it keeps by least squares. These weights are no longer shrunk toward zero. max_iter sets the iteration limit of its likelihood fit.
Granger in any units. Granger standardizes each series, so its answer does not depend on the units of any variable.

For details, read the changelog.

Try it

pip install -U andrey-core

The time-series notebook runs all six methods on a simulated series. You can open it in Colab, then pass your own table, one row per time step, to any of them.

Help us build it

Pairwise direction

2026-10-15T00:00:00+00:00

Does x cause y, or does y cause x? With only two variables, independence tests cannot tell: both directions fit the data equally well. ANM and PNL instead use the shape of the relationship to infer direction. This release adds ANM. As of 0.4.0, we support both methods.

We explain how two variables can reveal their direction, run both tests on two pairs, and report benchmark results.

Direction from two variables

PC and GES can orient an edge only through a third variable, such as a common effect. A pair has no third variable, so x -> y and y -> x explain the data equally well. These methods leave the edge undirected.

A model of the mechanism can break the tie. Suppose y = f(x) + e, where the noise e is independent of x. Regress y on x, and the residual looks independent of x. Regress x on y, and in general no residual is independent of y, unless f is linear and the noise is Gaussian.

Each test fits both directions and checks whether the residual is independent of the proposed cause. It uses HSIC, a kernel test that detects nonlinear dependence as well as correlation. The direction whose residual looks independent is the causal one.

The methods fit different models:

ANM (additive noise model) fits y = f(x) + e by Gaussian-process regression. The direction is generally identifiable when f is nonlinear or the noise is non-Gaussian.
PNL (post-nonlinear model) fits y = f2(f1(x) + e), where f2 is invertible. This is an additive noise model observed through a distortion, such as a sensor that saturates. ANM is the case where f2 changes nothing. PNL fits each transform as a sum of smooth basis functions.

Supported methods

Before each release, we benchmark each supported method against another package and check its results on known data. ANM is new in this release. PNL was experimental until now.

Method	Model	Returns
ANM	`y = f(x) + e`	A two-node DAG, both p-values, and both test statistics
PNL	`y = f2(f1(x) + e)`	A two-node DAG, both p-values, and both test statistics

Choose a method for your data:

ANM when the effect is a smooth function of the cause plus independent noise. Its regression time grows with the cube of the number of rows, so it suits up to a few thousand rows.
PNL when the effect may pass through a distortion or you have more rows. In our benchmarks, its median fit took under 2 s at 5,000 rows.

Both assume that no hidden common cause links the pair. When one is plausible, use the methods in the 0.2.0 post.

Reading the result

Each test returns a two-node DAG and four values in metadata:

pval_forward and pval_backward: the p-values of the independence tests for x -> y and y -> x. A large p-value means the residual looks independent of the proposed cause, so that direction fits.
stat_forward and stat_backward: the two HSIC statistics, each divided by its mean under independence. Smaller values mean weaker dependence.

By default, the edge points in the direction with the larger p-value. On a large sample, both p-values can round to zero. The smaller statistic then decides. This rule always selects a direction, even for unrelated variables.

With a significance level such as alpha=0.05, a direction fits when its p-value exceeds the level. The test draws an edge only when exactly one direction fits.

Example pairs

In both pairs, x causes y, and e is Laplace noise:

Additive: y = x + 0.3 * x**3 + 0.5 * e. The noise adds to a function of x, so both models hold.
Saturating: a sensor reads y = tanh(x + 0.5 * e). The noise passes through the saturation, so only the post-nonlinear model holds.

example.py

import numpy as np
import pandas as pd

import andrey

# x causes y in both pairs; e is noise.
rng = np.random.default_rng(0)
x = rng.laplace(size=500)
e = rng.laplace(size=500)

# The additive pair: y = x + 0.3 * x**3 + 0.5 * e.
additive = pd.DataFrame({"x": x, "y": x + 0.3 * x**3 + 0.5 * e})
# The saturating pair, which a sensor reads: y = tanh(x + 0.5 * e).
saturating = pd.DataFrame({"x": x, "y": np.tanh(x + 0.5 * e)})

print("Additive pair\n")
print(andrey.anm(additive), andrey.pnl(additive), sep="\n\n")
print("\nSaturating pair\n")
print(andrey.anm(saturating), andrey.pnl(saturating), sep="\n\n")

# For comparison: ANM on the saturating pair with a significance level.
print()
print(andrey.anm(saturating, alpha=0.05))

Two pairs, two models

The additive pair500 rows of y = x + 0.3 * x**3 + 0.5 * e

ANMnames x -> y, the true direction

PNLnames x -> y, the true direction

The saturating pair500 rows of y = tanh(x + 0.5 * e)

ANMnames y -> x, reversed

PNLnames x -> y, the true direction

Each bar is one direction's p-value, on a scale from 0 to 1; the cobalt bar is the direction the test names, and the dashed line marks 0.05. On the additive pair, both tests name x -> y and reject y -> x. On the saturating pair, ANM rejects both directions, since the saturation is not additive noise, and names the one with the larger p-value; PNL keeps only x -> y.

On the additive pair, ANM and PNL both select the true direction, x -> y, and reject y -> x.

On the saturating pair, the distortion breaks ANM, and PNL models it:

ANM rejects both directions. Both p-values are near zero because the saturation is not additive noise. Its default rule still selects a direction, here the reversed one, y -> x. With alpha=0.05, ANM draws no edge (the last result below).
PNL models the saturation as its outer transform. Its p-value for x -> y is large. Its p-value for y -> x is near zero, so it selects the true direction.

The script prints each result in full:

example.py

Additive pair

ANM  dag  |  2 nodes  |  1 edges (1 directed)

  x -> y

  pval_forward: 0.02928
  pval_backward: 0
  stat_forward: 1.725
  stat_backward: 11.33

PNL  dag  |  2 nodes  |  1 edges (1 directed)

  x -> y

  pval_forward: 0.07243
  pval_backward: 2.379e-09
  stat_forward: 1.525
  stat_backward: 4.287

Saturating pair

ANM  dag  |  2 nodes  |  1 edges (1 directed)

  y -> x

  pval_forward: 0
  pval_backward: 1.695e-07
  stat_forward: 21.66
  stat_backward: 4.322

PNL  dag  |  2 nodes  |  1 edges (1 directed)

  x -> y

  pval_forward: 0.5863
  pval_backward: 2.091e-06
  stat_forward: 0.8921
  stat_backward: 3.344

ANM  dag  |  2 nodes  |  0 edges (no edges)

  pval_forward: 0
  pval_backward: 1.695e-07
  stat_forward: 21.66
  stat_backward: 4.322

Benchmark results

We compared both methods with causal-learn, a Python package that implements them, on simulated cause-effect pairs. We tested ANM on additive-noise pairs and PNL on post-nonlinear pairs.

Method	Compared with	Andrey’s speedup	Direction
ANM	causal-learn	about 2x	the same as causal-learn’s on every pair
PNL	causal-learn	up to 1,470x	true on more pairs than causal-learn’s

The 0.4.0 release card reports every measurement, including the sizes, machine, and settings.

Speedup over causal-learnRelease card

ANMPNL

200 rows2.08x

500 rows1.88x

1,000 rows2.05x

2,000 rows2.38x

4,000 rows2.47x

8,000 rows2.39x

200 rows1,470x

500 rows1,310x

1,000 rows993x

2,000 rows696x

5,000 rows275x

Each bar is causal-learn's time divided by Andrey's on the same pair, the median over the pairs of that size, on 4 cores per fit. The bars are on a log scale, so equal steps are equal factors; each method's bars share its own scale.

Our ANM implementation fits the same Gaussian process and uses the same independence test as causal-learn, so both return the same graph on every pair.

The PNL implementations differ more in how they fit and test each direction. Ours selects the true direction on 94% of pairs; causal-learn’s selects it on 45%.

Pairs with the true direction

ANMThe same direction as causal-learn on every pair

Andrey and causal-learn

PNLAndrey: every pair from 1,000 rows

Andreycausal-learn

The share of pairs, per size, on which each package names the true direction; higher is better. Each size has 20 pairs, except 10 at 4,000 rows and 5 at 8,000 rows for ANM. The empty graph names no direction, so its share is 0 at every size.

At 200 rows, both methods select the reversed direction on a quarter of the pairs. A direction test selects a direction on every pair, right or wrong. Check both p-values before you trust it.

Other highlights

Statistics break ties. On a large sample, both p-values can round to zero. PNL now selects the direction with the smaller HSIC statistic, relative to its mean under independence, instead of drawing no edge. ANM uses the same rule. Both statistics are in metadata.
ANM in any units. ANM standardizes each column first, so its answer does not depend on either variable’s units.

For details, read the changelog.

Try it

pip install -U andrey-core

The pairwise notebook runs both tests on simulated pairs. You can open it in Colab, then pass your own two-column table to andrey.anm or andrey.pnl.

Help us build it

Score-based search

2026-10-12T00:00:00+00:00

A score-based method searches for the graph that best explains the data according to a score. This release adds Tabu search and XGES. From 0.3.0, both are supported, as is hill climbing. Hill climbing also returns the same graphs in less time.

Below, we explain why a search can stop at the wrong graph. We run GES, hill climbing, Tabu search, and XGES on one small dataset, then report benchmark results.

Searching by a score

Andrey’s score-based methods rate a graph by its BIC (Bayesian information criterion). For each variable, the BIC measures how much variance its parents in the graph leave unexplained. It adds a penalty for each parent. A lower score is better. This BIC assumes linear relations with Gaussian noise. The methods also assume no hidden common causes.

The number of graphs grows faster than exponentially with the number of variables, so a search cannot score them all. A greedy search starts from the empty graph. It takes the move that improves the score most, such as adding, removing, or reversing one edge. It stops when no move improves the score. That graph is a local optimum: no single move improves it. A better graph can lie a few moves away, past graphs that score worse. A search that stops there can miss edges or point them the wrong way.

The four methods handle local optima differently:

Hill climbing searches over DAGs (directed acyclic graphs) and stops at the first local optimum.
Tabu search takes the same moves. At a local optimum, it takes the best move even when the score gets worse, and keeps going. It never returns to a recently visited graph, so it cannot step straight back. It returns the best graph it visited, so with the same settings its score is never worse than hill climbing’s.
GES (greedy equivalence search) searches over equivalence classes: sets of graphs that fit any data equally well. It adds edges while the score improves, then removes edges while the score improves.
XGES (extremely greedy equivalence search) searches the same classes with GES’s moves and edge reversals, in a different order. Each step deletes an edge if that improves the score. Otherwise, it tries reversing an edge, then adding one. Its extended search then deletes each edge of the result in turn, forbids adding it back, and searches again. It keeps any result with a better score, which lets it leave a local optimum.

Methods

Before each release, we benchmark each supported method against another package and check its results on known graphs. Tabu search and XGES are new in this release.

Method	Status	Searches over	Returns
GES	Supported	Equivalence classes	A CPDAG and its BIC score
XGES	Supported	Equivalence classes	A CPDAG and its BIC score
Hill climbing	Supported	DAGs	The CPDAG of the final DAG, and its score
Tabu search	Supported	DAGs	The CPDAG of the best DAG visited, and its score
GIES	Experimental	Equivalence classes	A CPDAG and its BIC score; without interventions, the same search as GES
Exact search	Experimental	Every DAG, so only a few variables	One DAG with the best BIC score
CALM	Experimental	A penalized likelihood, by continuous optimization	A weighted DAG, without a score

Choose a method for your data:

XGES for continuous data that roughly fit the BIC’s assumptions. In our benchmarks, its graphs scored better and had fewer errors than GES’s (see Benchmarks). Set extended_search=False for a faster fit that can stop at a local optimum.
GES for the same data, as a well-studied reference.
Hill climbing as a fast baseline over DAGs, and Tabu search when hill climbing may stop early. Both take max_iter, a move limit.
Exact search to find the best-scoring graph on a few variables.
CALM to try continuous optimization that returns edge weights. You need the torch extra.

BOSS and GRaSP also minimize the BIC but search over orders of the variables. These are Andrey’s permutation-based methods. When hidden common causes are plausible, use the methods in the 0.2.0 post.

Reading a CPDAG

GES, XGES, hill climbing, Tabu search, and GIES all return a CPDAG (completed partially directed acyclic graph). You can find its BIC score in metadata["score"]. A CPDAG represents an equivalence class:

x -> y: every graph in the class has x causing y.
x -- y: the class has graphs with x -> y and graphs with x <- y. These fit the data equally well, so the data cannot orient this edge.

See Graph types for details.

Example

Here x0 causes x1, and x0, x1, and x2 cause x3. The relations are linear. The noise is Gaussian. We chose this model because GES and hill climbing stop early on it.

example.py

import numpy as np
import pandas as pd

import andrey

# x0 causes x1, and x0, x1, and x2 cause x3.
rng = np.random.default_rng(0)
e0, e1, e2, e3 = rng.standard_normal((4, 500))
x0, x2 = e0, e2
x1 = -0.8 * x0 + e1
x3 = 0.8 * x0 - x1 + x2 + e3
df = pd.DataFrame({"x0": x0, "x1": x1, "x2": x2, "x3": x3})

methods = (andrey.ges, andrey.hc, andrey.tabu, andrey.xges)
print(*(method(df) for method in methods), sep="\n\n")

# For comparison: XGES without its extended search.
print()
print(andrey.xges(df, extended_search=False))

What each search returns

True graphthe model behind the data

GESscore 18.22, a local optimum

Hill climbingscore 18.22, a local optimum

Tabu searchscore 15.11, the true graph

XGESscore 15.11, the true graph

Every node in the same place; lower scores are better. GES and hill climbing stop at the same graph: x2 -> x0 (cobalt) is not in the true graph, x3 -> x0 (cobalt) points the wrong way, and x0 -- x1 is missing. Tabu search and XGES return the true graph's equivalence class, which leaves x0 -- x1 (amber) undirected.

GES and hill climbing stop at the same graph, with a score of 18.22. It has x2 -> x0, an edge absent from the true graph. It also has x3 -> x0, which points the wrong way. It misses x0 -- x1.
Tabu search and XGES return the true graph’s equivalence class, with a lower score of 15.11. The edge x0 -- x1 stays undirected. The true graph and the same graph with x1 -> x0 are equivalent, so they fit any data equally well.
XGES without its extended search returns GES’s graph (the last result below). Here, the extended search finds the better graph.

The script prints each result in full:

example.py

GES  cpdag  |  4 nodes  |  4 edges (4 directed)

  x2 -> x0
  x3 -> x0
  x1 -> x3
  x2 -> x3

  score: 18.22

HC  cpdag  |  4 nodes  |  4 edges (4 directed)

  x2 -> x0
  x3 -> x0
  x1 -> x3
  x2 -> x3

  score: 18.22

Tabu  cpdag  |  4 nodes  |  4 edges (1 undirected, 3 directed)

  x0 -- x1
  x0 -> x3
  x1 -> x3
  x2 -> x3

  score: 15.11

XGES  cpdag  |  4 nodes  |  4 edges (1 undirected, 3 directed)

  x0 -- x1
  x0 -> x3
  x1 -> x3
  x2 -> x3

  score: 15.11

XGES  cpdag  |  4 nodes  |  4 edges (4 directed)

  x2 -> x0
  x3 -> x0
  x1 -> x3
  x2 -> x3

  score: 18.22

Benchmarks

We compared XGES with xges, a Python package that implements it, and Tabu search and hill climbing with bnlearn, an R package. The data are linear-Gaussian, simulated from random graphs with ten rows per variable.

Method	Compared with	Andrey’s speedup	Same graph
XGES	xges	up to 140x	on every dataset
Tabu search	bnlearn	up to 561x	on most datasets
Hill climbing	bnlearn	up to 906x	on most datasets

The 0.3.0 release card reports every measurement, with the sizes, machines, and settings. Hill climbing ran to a local optimum and Tabu search until it stopped on its own, both with no move limit. Without the extended search, XGES still returns the same graph as xges on every dataset, and runs faster at every size.

Speedup over xges and bnlearnRelease card

XGESTabu searchHill climbing

25 variables3.95x

50 variables10.9x

100 variables43.2x

200 variables140x

10 variables2.54x

20 variables2.38x

50 variables5.63x

100 variables16.6x

200 variables55.3x

400 variables176x

800 variables561x

10 variables5.27x

20 variables3.60x

50 variables6.13x

100 variables19.3x

200 variables70.6x

400 variables231x

800 variables906x

Each bar is the other package's time divided by Andrey's on the same dataset, the median over five datasets: xges for XGES, on 1 core per fit, and bnlearn for Tabu search and hill climbing, on 4 cores. Every graph has a mean degree of 2. The bars are on a log scale, so equal steps are equal factors; each method's bars share its own scale.

On these data, XGES’s graphs scored better than GES’s and had fewer errors, at every size. On the denser graphs, the extended search cut XGES’s errors at every size, nearly by half at 50 variables.

Agreement between packages does not establish accuracy. From 50 variables on, Tabu search’s and hill climbing’s graphs have more errors than the empty graph, in both packages. Tabu search finds better-scoring graphs than hill climbing at every size, yet at 400 variables its graphs have more errors. A better score is not always a better graph.

On the sparser graphs, XGES’s graphs score better than the true graph at every size. With ten rows per variable, the best-scoring graph is not the true one. A larger lambda_value penalizes each parent more and favors sparser graphs.

Errors against the true graph

XGESMean degree 4: the fewest errors at every size

XGESWithout extended searchGESEmpty graph

Tabu search and hill climbingMean degree 2: more errors than the empty graph from 50 variables

Tabu searchHill climbingEmpty graphMore errors than the empty graph

The median over five datasets per size of the structural Hamming distance (SHD) to the true graph's equivalence class: the edges added, missed, or misoriented. Lower is better. XGES returns the same graphs as xges, with and without the extended search, so each shares one line. Tabu search and hill climbing are Andrey's; bnlearn's medians are within one error of them at every size.

Andrey alone also ran XGES at up to 1,000 variables, and Tabu search and hill climbing at up to 3,200. On the sparser graphs, their graphs at these sizes have more errors than the empty graph.

Speed and accuracy depend on your data, settings, and hardware.

Other highlights

Faster hill climbing. Hill climbing caches the score change for each candidate move between steps. It recomputes only the moves a step changes. It returns the same graphs as before in less time.
Hill climbing runs in one process. Its worker processes were slower at every measured size. We removed them, along with ANDREY_HC_PARALLEL_MIN_WORK and andrey calibrate --method hc. This change breaks scripts that set either one. ANDREY_NUM_WORKERS still sets the workers for GES, GIES, and GFCI.
XGES without the extended search. andrey.xges(data, extended_search=False) returns the graph where the first search stops. On the sparser graphs at 200 variables, it took a tenth of the time of the full search.
Shorter summaries. Since 0.2.1, a result’s summary shows the length of a long metadata list instead of printing it in full.

For more details, read the changelog.

Try it

pip install -U andrey-core

The GES quickstart notebook fits GES on a small chain. You can open it in Colab and replace andrey.ges with andrey.xges, andrey.tabu, or andrey.hc. Then try the methods on your own data.

Help us build it

Andrey is in alpha, and the API may change between releases. When you try it on your own data, tell us what breaks or which method you need. We also welcome pull requests. The contributing guide explains how you can set up.

Hidden common causes

2026-10-12T00:00:00+00:00

A hidden common cause, or latent confounder, is an unmeasured variable that affects two measured variables. This release adds RCD and BottomUpParceLiNGAM as supported methods. With FCI, they cover data with hidden common causes. Below, we run all three on one small dataset and report benchmark results. Other updates make small fits several times faster.

Why hidden causes matter

Many causal discovery methods, including PC, GES, and DirectLiNGAM, assume causal sufficiency: every common cause of two measured variables is measured too. Real data often violate this assumption. A hidden common cause can make two variables dependent even without an edge between them. A method that assumes causal sufficiency can then draw an edge that is not there. Methods that allow hidden common causes can mark the pair or leave the edge’s ends unresolved.

Methods

We benchmark each supported method against another package and check its results on known graphs before each release. RCD and BottomUpParceLiNGAM are new in this release.

Method	Assumes
FCI	Linear relations with roughly Gaussian noise, through its Fisher-z test
RCD	Linear relations with non-Gaussian noise
BottomUpParceLiNGAM	Linear relations with non-Gaussian noise

Reading a PAG

All three return a partial ancestral graph (PAG) over the variables you measured. Each end of an edge carries a tail, an arrowhead, or a circle. A circle means that end is unresolved.

x -> y: x causes y.
x <-> y: a hidden variable links x and y, such as a common cause.
x o-> y: y does not cause x; whether x causes y is unresolved.
x o-o y: both ends are unresolved.

FCI marks an end with a tail or an arrowhead only when every graph consistent with the data’s conditional independences agrees on that mark. RCD and BottomUpParceLiNGAM use the same marks for their findings: -> for a direct cause and <-> for a pair linked by a hidden variable. BottomUpParceLiNGAM also uses o-o between variables it cannot order. See Graph types for details.

Example

Here h causes x0 and x1 but is not in the data. Also, x0 causes x3, and x1 causes x2. The noise is uniform, so it is not Gaussian.

example.py

import numpy as np
import pandas as pd

import andrey

# h is a common cause of x0 and x1, and it is not in the data.
rng = np.random.default_rng(0)
h, e0, e1, e2, e3 = rng.uniform(-1, 1, (5, 2000))
x0, x1 = 1.5 * h + e0, 1.5 * h + e1
df = pd.DataFrame({"x0": x0, "x1": x1, "x2": 0.6 * x1 + e2, "x3": 0.6 * x0 + e3})

methods = (andrey.fci, andrey.rcd, andrey.bottom_up_parce_lingam)
print(*(method(df) for method in methods), sep="\n\n")

# For comparison: DirectLiNGAM assumes every common cause is in the data.
print()
print(andrey.direct_lingam(df))

What each method returns

True graphh is hidden, not in the data

FCIevery end unresolved

RCDmatches the true graph

BottomUpParceLiNGAMx0 and x1 left unordered

DirectLiNGAMa wrong edge, x0 -> x1

Every node in the same place: h is hidden (dashed), and DirectLiNGAM's x0 -> x1 (amber) is not in the true graph.

RCD returns the true graph: x0 <-> x1 for the pair linked by h, and both direct edges.
BottomUpParceLiNGAM finds both direct edges. It cannot order x0 and x1, which share h, so it groups them in one block joined by o-o. In causal_order, this block appears as the nested list [0, 1].
FCI finds the three edges but leaves every end a circle. Its orientations rely on conditional independences. These four variables have the same independences as a graph with no hidden cause and no collider (a variable that two arrows point into), such as x3 <- x0 -> x1 -> x2, so the independences cannot settle any mark. Given an observed cause of x0 and another of x1, FCI can mark the pair x0 <-> x1.

RCD and BottomUpParceLiNGAM also test whether regression residuals are independent. With non-Gaussian noise, this test settles the directions in this example. RCD and BottomUpParceLiNGAM also estimate the edge weights: 0.598 and 0.61, compared with the true 0.6. DirectLiNGAM assumes causal sufficiency. On the same data, it returns x0 -> x1 (the last graph above), an edge absent from the true graph.

The script prints each result in full:

example.py

FCI  pag  |  4 nodes  |  3 edges (3 circle)

  x0 o-o x1
  x0 o-o x3
  x1 o-o x2

RCD  pag  |  4 nodes  |  3 edges (1 bidirected, 2 directed)

  x0 <-> x1
  x0 -> x3  (+0.598)
  x1 -> x2  (+0.61)

  confounded_pairs: [[0, 1]]

BottomUpParceLiNGAM  pag  |  4 nodes  |  3 edges (1 circle, 2 directed)

  x0 o-o x1
  x0 -> x3  (+0.598)
  x1 -> x2  (+0.61)

  causal_order: [[0, 1], 3, 2]

DirectLiNGAM  dag  |  4 nodes  |  3 edges (3 directed)

  x0 -> x1  (+0.686)
  x0 -> x3  (+0.598)
  x1 -> x2  (+0.61)

  order: x0 -> x1 -> x2 -> x3

Benchmarks

We compared the three supported methods with packages that implement them.

Method	Compared with	Variables	Andrey’s speedup	Same graph
RCD	lingam	4-24 observed	1.7-2.9x	25 of 25 datasets
BottomUpParceLiNGAM	lingam	4-24 observed	2.5-10.8x	25 of 25 datasets
FCI	causal-learn	20-800, hidden ones included	3.4-16.5x at 50 to 800; 0.62x at 20	13 of 18 datasets

The 0.2.0 release card reports measurements for RCD and BottomUpParceLiNGAM on linear data with uniform noise, one node in five hidden, and 2,000 rows, on 2 cores.

Speedup over lingamRelease card

RCDBottomUpParceLiNGAM

4 observed variables1.66x

8 observed variables2.35x

12 observed variables2.17x

16 observed variables2.88x

24 observed variables2.55x

4 observed variables2.48x

8 observed variables5.08x

12 observed variables5.68x

16 observed variables6.61x

24 observed variables10.8x

Each bar is lingam's time divided by Andrey's on the same dataset, the median over five datasets, on 2 cores. Each method's bars share its own scale.

Agreement between packages does not establish accuracy: from 8 observed variables, BottomUpParceLiNGAM’s directed edges have more errors than the empty graph’s, in both packages.

Directed-edge errors

Andrey and lingamEmpty graphMore errors than the empty graph

RCDAt or below the empty graph's errors at every size

BottomUpParceLiNGAMMore errors than the empty graph from 8 observed variables

The median over five datasets per size; Andrey and lingam return the same graphs, so they share one line. Lower is better.

FCI’s numbers come from the 0.1.0 release card: linear-Gaussian data with one variable in ten hidden and ten rows per variable, on 16 cores. At 20 variables, Andrey is slower, but both packages take under 0.1 s. Their median endpoint errors are within two of each other. At 800 variables, both have more endpoint errors than the empty graph.

Speed and accuracy depend on your data, settings, and hardware.

Other highlights

Faster small fits. PC, FCI, GES, and hill climbing now find the Basic Linear Algebra Subprograms (BLAS) libraries once per process instead of on every fit. At 10 variables, PC and FCI take about a twelfth of the time they took before, hill climbing an eighth, and GES two fifths. Larger fits are no slower, and the graphs are unchanged.
Release cards. The Release cards page has one card per release: its benchmarks, the methods it adds or promotes, their known limits, and how to rerun the benchmarks.
Limitations. Every method’s docstring has a Limitations paragraph stating where the method was measured to work or that it is not benchmarked yet.
Checks before the fit. Every method checks your data and settings before fitting. Data with NaN or infinity, a constant column, or fewer than 2 rows raises a ValueError that names the argument. An out-of-range setting raises the same error.

For more details, read the changelog.

Try it

pip install -U andrey-core

Two new notebooks fit RCD and BottomUpParceLiNGAM on the example’s model, read the edge weights, and check the result over ten datasets. You can open each notebook in Colab, then try the methods on your own data.

Help us build it

Why Andrey is fast

2026-10-08T00:00:00+00:00

Most of the time in causal discovery goes to two jobs: testing whether variables are independent (PC and FCI) and scoring candidate graphs (GES and BOSS). We speed up both with four ideas, easiest first. Each animation runs the same work in two lanes: Andrey’s, and one labeled Others that does it one step at a time. They are illustrations of the ideas, not measurements; the benchmarks have the measurements.

1. Do many things at once

Batch and parallelize. Within one round of PC, each independence test stands alone, and within one pass of GES, so does each candidate move. Andrey runs them as one batched array operation, thousands at a time, with the same results as one at a time.

Andrey: 1 call, one call for the batch. Others: 8 calls, one call per test.

2. Never compute twice

Cache and update incrementally. Andrey computes the correlation matrix once, up front, and caches it. Each test reads the few entries it needs instead of recomputing them, and GES memoizes its local scores the same way.

Andrey: 1 computation, computed once, then read. Others: 6 computations, recomputed for each test.

3. Skip what can’t matter

Prune the search early. Tests given zero or one other variable have a closed form, so a quick pass settles most edges before any matrix is inverted. GES rules out invalid candidates with bit masks before scoring them.

Andrey: 3 inversions, a quick check first. Others: 10 inversions, every test inverts a matrix.

4. Use the hardware you have

Hardware-aware acceleration. With the optional extras, Numba JIT-compiles GES’s path checks, and a CUDA GPU computes large entropy tables many cells at a time, once they are large enough to repay the transfer. Correlation matrices move to the GPU too when you set ANDREY_BACKEND=cuda.

Andrey: 3 steps, a GPU, many cells per step. Others: 48 steps, one core, one cell per step.

Introducing Andrey

2026-10-08T00:00:00+00:00

We’re happy to introduce Andrey, a very fast causal discovery package for Python.

Andrey is named after Andrey Markov and Andrey Kolmogorov, whose ideas causal discovery still runs on (where the name comes from).

Most data analysis tells you which variables move together. Causal discovery learns from data which ones drive which, and draws them as a graph of causes. As AI systems take on more analysis and make decisions of their own, they need to know what causes what.

For a long time, scale has held causal discovery back. The methods are well understood, but popular Python packages run them slowly. PC on 400 variables took 617 s in causal-learn. At that speed, trying a new idea takes time, and data with thousands of variables is out of reach.

We built Andrey to make causal discovery fast and easy to use. It runs the same methods faster (over 100x on PC).

Fast: Over 100x faster on PC, and faster on most other supported methods.
Just as accurate: the same errors or fewer in 38 of 42 comparisons with other packages.
One API: 18 methods, each one function call.
Agent-ready: a command line that answers in JSON, and a skill for coding agents.

Speedup 400 variables800 variables150 variables800 variables400 variables200 variablesBenchmark report

Andrey941x

gCastle3.7x

causal-learn1x

Andrey8.7x

causal-learn1x

Andrey4.3x

causal-learn1x

Andrey3.4x

causal-learn1x

Andrey1.4x

causal-learn1x

Andrey3.3x

causal-learn1x

Why Andrey is fast explains the four ideas behind the speed. Andrey is free and open source, and so are its benchmarks, which you can rerun yourself.

What’s next

We plan to add more methods, including more for time series. We also plan to add local causal discovery, which finds the structure around one variable, such as its direct causes and effects or its Markov blanket, without learning the whole graph. And we want to use sparsity to scale causal discovery to millions of variables.

Try Andrey

uv add andrey-core

Then run PC on a real dataset:

example.py

import andrey
from andrey.data import load_dataset

df = load_dataset("sachs").data
out = andrey.pc(df)
print(out)

example.py

PC  cpdag  |  11 nodes  |  8 edges (6 undirected, 2 directed)

  raf -- mek
  plc -- pip3
  pip2 -- pip3
  erk -- akt
  erk -- pka
  akt -- pka
  p38 -> pkc
  jnk -> pkc

Help us build it

Andrey 0.1.0 is in alpha, the API may change between releases.

When you try it on your own data, tell us what breaks or which method you need. We’d welcome a pull request too. The contributing guide explains how to set up.