Package: ges
Greedy Equivalence Search (GES) Algorithm for Causal DiscoveryVisitgithub.com/juangamella/gesfor the full documentation and source code.This is a python implementation of the GES algorithm from the paper"Optimal Structure Identification With Greedy Search"by David Maxwell Chickering. It includes the additional turning phase described inHauser & Bühlmann (2012).InstallationYou can clone this repo or install the python package via pip:pipinstallgesTheonlydependency outside the Python Standard Library isnumpy>=1.15.0. Seerequirements.txtfor more details.When you should (and shouldn't) use this implementationTo the best of my knowledge, the only other public implementation of GES is in the R packagepcalg. It can be called from Python through an easy-to-use wrapper in theCausal Discovery Toolbox, but given its scope, this library contains many additional dependencies (including PyTorch) and still requires you to haveR.Thus,this implementation might be for you if:you want a dependency-light implementation (the only dependency outside the Python Standard Library is numpy), oryou want to rewrite parts of GES for your own research, but you'd rather do it in Python. The code has been written with an emphasis on readability, and everything is thoroughly documented and referenced back to theGES/GIESpapers.You should not use this implementation if:you have no interest in modifying GES itself,andyou care about speed, as thepcalgimplementation is highly optimized and isveryfast.Running the algorithmUsing the Gaussian BIC score:ges.fit_bicGES comes ready to use with theGaussian BIC score, i.e. the l0-penalized Gaussian likelihood score. This is the variant which is commonly found in the literature, and the one which was implemented in the original paper. It is made available under the functionges.fit_bic.ges.fit_bic(data,A0=None,phases=['forward','backward','turning'],debug=0)Parametersdata(np.array): the matrix containing the observations of each variable (each column corresponds to a variable).A0(np.array, optional): the initial CPDAG on which GES will run, where whereA0[i,j] != 0impliesi -> jandA[i,j] != 0 & A[j,i] != 0impliesi - j. Defaults to the empty graph.phases([{'forward', 'backward', 'turning'}*], optional): this controls which phases of the GES procedure are run, and in which order. Defaults to['forward', 'backward', 'turning']. The turning phase was found byHauser & Bühlmann (2012)to improve estimation performace, and is implemented here too.debug(int, optional): if larger than 0, debug are traces printed. Higher values correspond to increased verbosity.Returnsestimate(np.array): the adjacency matrix of the estimated CPDAG.total_score(float): the score of the estimate.ExampleHeresempleris used to generate an observational sample from a Gaussian SCM, but this is not a dependency.importgesimportsemplerimportnumpyasnp# Generate observational data from a Gaussian SCM using semplerA=np.array([[0,0,1,0,0],[0,0,1,0,0],[0,0,0,1,1],[0,0,0,0,1],[0,0,0,0,0]])W=A*np.random.uniform(1,2,A.shape)# sample weightsdata=sempler.LGANM(W,(1,2),(1,2)).sample(n=5000)# Run GES with the Gaussian BIC scoreestimate,score=ges.fit_bic(data)print(estimate,score)# Output# [[0 0 1 0 0]#  [0 0 1 0 0]#  [0 0 0 1 1]#  [0 0 0 0 1]#  [0 0 0 1 0]] 21511.315220683457Using a custom score:ges.fitWhileChickering (2002)chose the BIC score, any score-equivalent and locally decomposable function is adequate. To run with another score of your choice, you can useges.fit(score_class,completion_algorithm=None,A0=None,phases=['forward','backward','turning'],debug=0)wherescore_classis an instance of the class which implements your score. It should inherit fromges.scores.DecomposableScore, or define alocal_scorefunction and a few attributes (seedecomposable_score.pyfor more details).You may additionally also use a custom completion algorithm , i.e. the algorithm to go from PDAG to CPDAG after the application of each operator.Parametersscore_class(ges.scores.DecomposableScore): an instance of a class implementing a locally decomposable score, which inherits fromges.scores.DecomposableScore. Seedecomposable_score.pyfor more details.completion_algorithm(function, optional): the used to go from PDAG to CPDAG after the application of each operator. Must be a function which takes and returns a PDAG adjacency. IfNone, the algorithm used in the original GES paper is used.A0(np.array, optional): the initial CPDAG on which GES will run, where whereA0[i,j] != 0impliesi -> jandA[i,j] != 0 & A[j,i] != 0impliesi - j. Defaults to the empty graph.phases([{'forward', 'backward', 'turning'}*], optional): this controls which phases of the GES procedure are run, and in which order. Defaults to['forward', 'backward', 'turning']. The turning phase was found byHauser & Bühlmann (2012)to improve estimation performace, and is implemented here too.debug(int, optional): if larger than 0, debug are traces printed. Higher values correspond to increased verbosity.Returnsestimate(np.array): the adjacency matrix of the estimated CPDAG.total_score(float): the score of the estimate.ExampleRunning GES on a custom defined score (in this case the same Gaussian BIC score implemented inges.scores.GaussObsL0Pen).importgesimportges.scoresimportsemplerimportnumpyasnp# Generate observational data from a Gaussian SCM using semplerA=np.array([[0,0,1,0,0],[0,0,1,0,0],[0,0,0,1,1],[0,0,0,0,1],[0,0,0,0,0]])W=A*np.random.uniform(1,2,A.shape)# sample weightsdata=sempler.LGANM(W,(1,2),(1,2)).sample(n=5000)# Define the score classscore_class=ges.scores.GaussObsL0Pen(data)# Run GES with the Gaussian BIC scoreestimate,score=ges.fit(score_class)print(estimate,score)# Output# [[0 0 1 0 0]#  [0 0 1 0 0]#  [0 0 0 1 1]#  [0 0 0 0 1]#  [0 0 0 1 0]] 24002.112921580803Code StructureAll the modules can be found inside theges/directory. These include:ges.geswhich is the main module with the calls to start GES, and contains the implementation of the insert, delete and turn operators.ges.utilscontains auxiliary functions and the logic to transform a PDAG into a CPDAG, used after each application of an operator.ges.scorescontains the modules with the score classes:ges.scores.decomposable_scorecontains the base class for decomposable score classes (see that module for more details).ges.scores.gauss_obs_l0_pencontains an implementation of the cached Gaussian BIC score, as used in the original GES paper.ges.testcontains the modules with the unit tests and tests comparing against the algorithm's implementation in the 'pcalg' package.TestsAll components come with unit tests to match, and some property-based tests. The output of the overall procedure has been checked against that of thepcalgimplementation over tens of thousands of random graphs. Of course, this doesn't mean there are no bugs, but hopefully it meansthey are less likely:)The tests can be run withmake test. You can addSUITE=<module_name>to run a particular module only. There are, however, additional dependencies to run the tests. You can find these inrequirements_tests.txtandR_requirements_tests.txt.Test modulesThey are in the sub packageges.test, in the directoryges/test/:test_decomposable_score.py: tests for the decomposable score base class.test_gauss_bic.py: tests for the Gaussian bic score.test_operators.py: tests for the insert, delete and turn operators.test_pdag_to_cpdag.py: tests the conversion from PDAG to CPDAG, which is applied after each application of an operator.test_utils.py: tests the other auxiliary functions.ges.test.test_vs_pcalg: compares the output of the algorithm vs. that ofpcalgfor randomly generated graphs.FeedbackI hope you find this useful! Feedback and (constructive) criticism is always welcome, just shoot me anemail:)