Add RLCD

[kunwuz]

Summary

This PR adds RLCD (Rank-based Latent Causal Discovery) to causal-learn under causallearn.search.HiddenCausal.RLCD.

The implementation integrates the structure-learning portion of RLCD from scm-identify and exposes it through a causal-learn style API:

from causallearn.search.HiddenCausal.RLCD import RLCD

cg = RLCD(data)

What Changed

• Added RLCD structure learning under causallearn/search/HiddenCausal/RLCD/.
• Added a public RLCD(data, ...) -> CausalGraph API, consistent with methods such as PC.
• Added Chi2RankTest for sample-based rank testing.
• Added package-local RLCD utilities required by the structure-learning implementation.
• Added RLCD documentation under docs/source/search_methods_index/Hidden causal representation learning/.
• Updated the hidden-causal docs index to include RLCD.
• Updated docs/source/getting_started.rst and setup.py with new dependencies:
  • communities
  • joblib
• Added tests/TestRLCD.py with a synthetic hidden-variable recovery test.

API

The main public entry point is:

cg = RLCD(data)

Optional parameters include:

cg = RLCD(
    data,
    ranktest_method=ranktest_method,
    stage1_method="ges",
    alpha_dict={0: 0.01, 1: 0.01, 2: 0.01, 3: 0.01},
    maxk=3,
    node_names=node_names,
)

The returned object is a CausalGraph, where cg.G.graph[j, i] = 1 and cg.G.graph[i, j] = -1 indicate i --> j; cg.G.graph[i, j] = cg.G.graph[j, i] = -1 indicates i --- j; and cg.G.graph[i, j] = cg.G.graph[j, i] = 1 indicates i <-> j.

Additional RLCD metadata is attached to the returned object:

• cg.stage1_cg
• cg.adjacency
• cg.all_vars

Documentation

The new RLCD docs include:

• Basic usage with default and customized parameters.
• Visualization examples consistent with PC:
  • cg.draw_pydot_graph()
  • GraphUtils.to_pydot(cg.G)
• Parameter descriptions for data, ranktest_method, stage1_method, alpha_dict, maxk, and node_names.
• Return-value documentation for CausalGraph.
• Conference-version citation for the RLCD paper.

Testing

Added a test that constructs a simple linear Gaussian model with hidden variables:

• Two causally related latent variables.
• Three observed indicators for each latent variable.
• RLCD is run with the real Chi2RankTest.
• The test checks that RLCD recovers the two latent clusters and a directed relation between the latent variables.
• The test also verifies compatibility with GraphUtils.to_pydot(cg.G).

Test Plan

python -m unittest "tests.TestRLCD"
python -m compileall -q "causallearn/search/HiddenCausal/RLCD"

Both checks pass locally.