causal-cmd v1.10.x
Introduction
Causal-cmd is a Java application that provides a Command-Line Interface (CLI) tool for causal discovery algorithms produced by the Center for Causal Discovery. The application currently includes the following algorithms:
boss, bpc, ccd, cpc, cstar, fas, fask, fask-pw, fci, fcimax, fges, fges-mb, fofc, ftfc, gfci, grasp, grasp-fci, ica-ling-d, ica-lingam, images, mgm, pag-sampling-rfci, pc, pc-mb, pcmax, r-skew, r3, rfci, skew, spfci, svar-fci, svar-gfci
Causal discovery algorithms are a class of search algorithms that explore a space of graphical causal models, i.e., graphical models where directed edges imply causation, for a model (or models) that are a good fit for a dataset. We suggest that newcomers to the field review Causation, Prediction and Search by Spirtes, Glymour and Scheines for a primer on the subject.
Causal discovery algorithms allow a user to uncover the causal relationships between variables in a dataset. These discovered causal relationships may be used further--understanding the underlying the processes of a system (e.g., the metabolic pathways of an organism), hypothesis generation (e.g., variables that best explain an outcome), guide experimentation (e.g., what gene knockout experiments should be performed) or prediction (e.g. parameterization of the causal graph using data and then using it as a classifier).
Command Line Usage
Java 8 or higher is the only prerequisite to run the software. Note that by default Java will allocate the smaller of 1/4 system memory or 1GB to the Java virtual machine (JVM). If you run out of memory (heap memory space) running your analyses you should increase the memory allocated to the JVM with the following switch '-XmxXXG' where XX is the number of gigabytes of ram you allow the JVM to utilize. For example to allocate 8 gigabytes of ram you would add -Xmx8G immediately after the java command.
In this example, we'll use download the Retention.txt Keep in mind that causal-cmd has different switches for different algorithms. To start, type the following command in your terminal:
java -jar causal-cmd-<version number>-jar-with-dependencies.jar
** Note: we are using causal-cmd-<version number>-jar-with-dependencies.jar to indicate the actual executable jar of specific version number that is being used. **
And you'll see the following instructions:
Missing required options: algorithm, data-type, dataset, delimiter
usage: java -jar Causal-cmd Project-1.10.0.jar --algorithm <string> [--comment-marker <string>] --data-type <string> --dataset <files> [--default] --delimiter <string> [--experimental] [--help] [--help-algo-desc] [--help-all] [--help-score-desc] [--help-test-desc] [--json-graph] [--metadata <file>] [--no-header] [--out <directory>] [--prefix <string>] [--quote-char <character>] [--skip-validation] [--version]
--algorithm <string> Algorithm: boss, bpc, ccd, cpc, cstar, dagma, direct-lingam, fas, fask, fask-pw, fci, fci-iod, fci-max, fges, fges-mb, fofc, ftfc, gfci, grasp, grasp-fci, ica-ling-d, ica-lingam, images, mgm, pag-sampling-rfci, pc, pc-mb, r-boss, r-skew, r3, rfci, skew, spfci, svar-fci, svar-gfci
--comment-marker <string> Comment marker.
--data-type <string> Data type: all, continuous, covariance, discrete, mixed
--dataset <files> Dataset. Multiple files are seperated by commas.
--default Use Tetrad default parameter values.
--delimiter <string> Delimiter: colon, comma, pipe, semicolon, space, tab, whitespace
--experimental Show experimental algorithms, tests, and scores.
--help Show help.
--help-algo-desc Show all the algorithms along with their descriptions.
--help-all Show all options and descriptions.
--help-score-desc Show all the scores along with their descriptions.
--help-test-desc Show all the independence tests along with their descriptions.
--json-graph Write out graph as json.
--metadata <file> Metadata file. Cannot apply to dataset without header.
--no-header Indicates tabular dataset has no header.
--out <directory> Output directory
--prefix <string> Replace the default output filename prefix in the format of <algorithm>_<numeric timestamp>.
--quote-char <character> Single character denotes quote.
--skip-validation Skip validation.
--version Show version.
Use --help for guidance list of options. Use --help-all to show all options.
By specifying an algorithm using the --algorithm switch the program will indicate the additional required switches. The program reminds the user of required switches to run. In general most algorithms also require data-type, dataset, delimiter and score. The switch --help-all displays and extended list of switches for the algorithm.
Example of listing all available options for an algorithm:
$ java -jar causal-cmd-1.9.0-jar-with-dependencies.jar --algorithm fges --data-type continuous --dataset Retention.txt --delimiter tab --score sem-bic-score --help
usage: java -jar Causal-cmd Project-1.10.0.jar --algorithm fges --data-type continuous --dataset Retention.txt --delimiter tab --score sem-bic-score [--addOriginalDataset] [--choose-dag-in-pattern] [--choose-mag-in-pag] [--comment-marker <string>] [--default] [--exclude-var <file>] [--experimental] [--external-graph <file>] [--extract-struct-model] [--faithfulnessAssumed] [--generate-complete-graph] [--genereate-pag-from-dag] [--genereate-pag-from-tsdag] [--genereate-pattern-from-dag] [--json-graph] [--knowledge <file>] [--make-all-edges-undirected] [--make-bidirected-undirected] [--make-undirected-bidirected] [--maxDegree <integer>] [--meekVerbose] [--metadata <file>] [--missing-marker <string>] [--no-header] [--numberResampling <integer>] [--out <directory>] [--parallelized] [--penaltyDiscount <double>] [--percentResampleSize <integer>] [--precomputeCovariances] [--prefix <string>] [--quote-char <character>] [--resamplingEnsemble <integer>] [--resamplingWithReplacement] [--saveBootstrapGraphs] [--seed <long>] [--semBicRule <integer>] [--semBicStructurePrior <double>] [--skip-validation] [--symmetricFirstStep] [--timeLag <integer>] [--verbose]
--addOriginalDataset Yes, if adding the original dataset as another bootstrapping
--choose-dag-in-pattern Choose DAG in Pattern graph.
--choose-mag-in-pag Choose MAG in PAG.
--comment-marker <string> Comment marker.
--default Use Tetrad default parameter values.
--exclude-var <file> Variables to be excluded from run.
--experimental Show experimental algorithms, tests, and scores.
--external-graph <file> External graph file.
--extract-struct-model Extract sturct model.
--faithfulnessAssumed Yes if (one edge) faithfulness should be assumed
--generate-complete-graph Generate complete graph.
--genereate-pag-from-dag Generate PAG from DAG.
--genereate-pag-from-tsdag Generate PAG from TsDAG.
--genereate-pattern-from-dag Generate pattern graph from PAG.
--json-graph Write out graph as json.
--knowledge <file> Prior knowledge file.
--make-all-edges-undirected Make all edges undirected.
--make-bidirected-undirected Make bidirected edges undirected.
--make-undirected-bidirected Make undirected edges bidirected.
--maxDegree <integer> The maximum degree of the graph (min = -1)
--meekVerbose Yes if verbose output for Meek rule applications should be printed or logged
--metadata <file> Metadata file. Cannot apply to dataset without header.
--missing-marker <string> Denotes missing value.
--no-header Indicates tabular dataset has no header.
--numberResampling <integer> The number of bootstraps/resampling iterations (min = 0)
--out <directory> Output directory
--parallelized Yes if the search should be parallelized
--penaltyDiscount <double> Penalty discount (min = 0.0)
--percentResampleSize <integer> The percentage of resample size (min = 10%)
--precomputeCovariances True if covariance matrix should be precomputed for tubular continuous data
--prefix <string> Replace the default output filename prefix in the format of <algorithm>_<numeric timestamp>.
--quote-char <character> Single character denotes quote.
--resamplingEnsemble <integer> Ensemble method: Preserved (1), Highest (2), Majority (3)
--resamplingWithReplacement Yes, if sampling with replacement (bootstrapping)
--saveBootstrapGraphs Yes if individual bootstrapping graphs should be saved
--seed <long> Seed for pseudorandom number generator (-1 = off)
--semBicRule <integer> Lambda: 1 = Chickering, 2 = Nandy
--semBicStructurePrior <double> Structure Prior for SEM BIC (default 0)
--skip-validation Skip validation.
--symmetricFirstStep Yes if the first step step for FGES should do scoring for both X->Y and Y->X
--timeLag <integer> A time lag for time series data, automatically applied (zero if none)
--verbose Yes if verbose output should be printed or logged
In this example, we'll be running the FGES algorithm on the dataset Retention.txt.
$ java -jar causal-cmd-1.10.0-jar-with-dependencies.jar --algorithm fges --data-type continuous --dataset Retention.txt --delimiter tab --score sem-bic-score
This command will output by default one file fges_<unix timestamp>.txt which is a log and result of the algorithm's activity.
'--json-graph' option will enable output fges_<unix timestamp>_graph.json which is a json graph from the algorithm, which is equivalent to the exported json file from tetrad-gui.
Example log output from causal-cmd:
================================================================================
FGES (Wed, October 04, 2023 01:42:43 PM)
================================================================================
Runtime Parameters
--------------------------------------------------------------------------------
number of threads: 7
Dataset
--------------------------------------------------------------------------------
file: Retention.txt
header: yes
delimiter: tab
quote char: none
missing marker: none
comment marker: none
Algorithm Run
--------------------------------------------------------------------------------
algorithm: FGES
score: Sem BIC Score
Algorithm Parameters
--------------------------------------------------------------------------------
addOriginalDataset: no
faithfulnessAssumed: no
maxDegree: 1000
meekVerbose: no
numberResampling: 0
parallelized: no
penaltyDiscount: 2.0
percentResampleSize: 100
precomputeCovariances: no
resamplingEnsemble: 1
resamplingWithReplacement: no
saveBootstrapGraphs: no
seed: -1
semBicRule: 1
semBicStructurePrior: 0.0
symmetricFirstStep: no
timeLag: 0
verbose: no
Wed, October 04, 2023 01:42:45 PM: Start data validation on file Retention.txt.
Wed, October 04, 2023 01:42:45 PM: End data validation on file Retention.txt.
There are 170 cases and 8 variables.
Wed, October 04, 2023 01:42:45 PM: Start reading in file Retention.txt.
Wed, October 04, 2023 01:42:45 PM: Finished reading in file Retention.txt.
Wed, October 04, 2023 01:42:45 PM: File Retention.txt contains 170 cases, 8 variables.
Start search: Wed, October 04, 2023 01:42:45 PM
End search: Wed, October 04, 2023 01:42:45 PM
================================================================================
Graph Nodes:
spending_per_stdt;grad_rate;stdt_clss_stndng;rjct_rate;tst_scores;stdt_accept_rate;stdt_tchr_ratio;fac_salary
Graph Edges:
1. spending_per_stdt --- fac_salary
2. spending_per_stdt --- rjct_rate
3. spending_per_stdt --- stdt_tchr_ratio
4. stdt_accept_rate --- fac_salary
5. stdt_clss_stndng --- rjct_rate
6. stdt_clss_stndng --- tst_scores
7. tst_scores --- fac_salary
8. tst_scores --- grad_rate
9. tst_scores --- rjct_rate
10. tst_scores --- spending_per_stdt
Graph Attributes:
Score: -5181.565079
Graph Node Attributes:
Score: [spending_per_stdt: -1408.4382541909688;grad_rate: -416.7933531919986;stdt_clss_stndng: -451.79480827547627;rjct_rate: -439.8087229322177;tst_scores: -330.2039598576225;stdt_accept_rate: -429.64771587695884;stdt_tchr_ratio: -208.85274641239832;fac_salary: -1496.025518245214]
Interpretation of graph output
The end of the file contains the causal graph edgesfrom the search procedure. Here is a key to the edge types:
- A --- B - There is causal relationship between variable A and B, but we cannot determine the direction of the relationship
- A --> B - There is a causal relationship from variable A to B
The GFCI algorithm has additional edge types:
- A <-> B - There is an unmeasured confounder of A and B
- A o-> B - Either A is a cause of B or there is an unmeasured confounder of A and B or both
-
A o-o B - Either (1) A is a cause of B or B is a cause of A, or (2) there is an unmeasured confounder of A and B, or both 1 and 2 hold.
-
A --> B dd nl - Definitely direct causal relationship and no latent confounder
- A --> B pd nl - Possibly direct and no latent confounder
- A --> B pd pl - Possibly direct and possibly latent confounder
NNote: the generated result file name is based on the system clock.
Sample Prior Knowledge File
From the above useage guide, we see the option of --knowledge <arg>, with which we can specify the prior knowledge file. Below is the content of a sample prior knowledge file:
/knowledge
addtemporal
1 spending_per_stdt fac_salary stdt_tchr_ratio
2 rjct_rate stdt_accept_rate
3 tst_scores stdt_clss_stndng
4* grad_rate
forbiddirect
x3 x4
requiredirect
x1 x2
The first line of the prior knowledge file must say /knowledge. And a prior knowledge file consists of three sections:
- addtemporal - tiers of variables where the first tier preceeds the last. Adding a asterisk next to the tier id prohibits edges between tier variables
- forbiddirect - forbidden directed edges indicated by a list of pairs of variables: from -> to direction
- requireddirect - required directed edges indicated by a list of pairs of variables: from -> to direction