Skip to content
This repository has been archived by the owner on Jun 4, 2024. It is now read-only.

Tutorial Command Line Interface

Jump to bottom
mdpham edited this page May 5, 2016 · 15 revisions

#Command Line Interface

The C interface can be used to interact with the PGMLab application through a terminal on either Linux or Mac OSX operating systems.

##Three ways to use the command line interface:

  1. Use flags to configure and to run the program. In this way you will specify the files (pairwise interaction file, observations, etc...), the desired actions (learning, inference, generate factorgraph) and modify parameters (number of iterations, number of states, etc...). In order to learn more about the flags go to the bin folder and type pgmlab --help.

  2. Use the interactive interface by typing the command pgmlab --interactive. This will guide you through the analysis by prompting you for the relevant information. In interactive mode all information is entered in by the user and no information is taken from configuration files.

  3. Provide a directory with a specified folder structure and file naming. In this mode PGMLab will automatically determine what is needing to be done and is able to do this on multiple networks in one command. To do this you will need to specify the flag --data-dir=\<your-directory\>. For information on the folder structure see the instructions within the README file that comes with PGMLab.

*all commands will need to be run from the bin directory if the user has not run "make install" from the root directory

##Installation

In order to run the C interface you will first need to run the following commands:

make (from the project's root directory)

Once the PGMLab shared library has been created (net/lib/libpgmlab.so on linux or net/lib/libpgmlab.dynlib on OSX) the C interface should be made.

##Command line interface

###Flag based interface

pgmlab --help  (to get a list of all the parameters you can set)

The main flags to set are "file-paths", "generate-factorgraph", "inference" and "learning". The file-paths flag specifies a config file containing the file paths to both the input and output files. See the config/test-data1_0.5_0.7.ini file to see a configuration that has already been generated.

##Usage

pgmlab [-gliv] [--interactive] [--data-dir=<string>] [--pairwise-interaction-file=<file>] [--logical-factorgraph-file=<file>] [--estimated-parameters-file=<file>] [--learning-observed-data-file=<file>] [--inference-observed-data-file=<file>] [--inference-factorgraph-file=<file>] [--posterior-probability-file=<file>] [--number-of-states=<int>] [--em-max-iterations=<int>] [--log-likelihood-change-limit=<double>] [--parameters-change-limit=<double>] [--logging-on] [--maximum-a-posteriori-estimation] [--help] [--version] 

###Flag descriptions  
 -g, --generate-factorgraph              Generate factor graph from reaction logic [pairwise-interaction-file, logical-factorgraph-file]
 -l, --learning                          Run learning using training dataset [pairwise-interaction-file, logical-factorgraph-file, learning-observed-data-file, estimated-parameters-file]
 -i, --inference                         Run inference given the states of visible sets [pairwise-interaction-file, inference-factorgaph-file, inference-observed-data-file, posterior-probability-file]
 --interactive                           Interactive mode
 --data-dir=<string>                     Path to folder containing data in specified folder structure and naming conventions
 --pairwise-interaction-file=<file>      File path to pairwise interaction file
 --logical-factorgraph-file=<file>       File path to factorgraph file create from pairwise interaction file
 --estimated-parameters-file=<file>      File path to factorgraph file generated by learning
 --learning-observed-data-file=<file>    File path to oberserved data used during learning
 --inference-observed-data-file=<file>   File path to oberserved data used during inference
 --inference-factorgraph-file=<file>     File path to factorgraph used during inference
 --posterior-probability-file=<file>     File path to where you would like the posterior probabiliies to be written
 --number-of-states=<int>                Number of states for each node (default is 2)
 --em-max-iterations=<int>               Maximum number of iterations in the EM algorithm - used in learning (default is 4000)
 --log-likelihood-change-limit=<double>  Stopping criteria: change in the ML - used in learning (default 1e-5)
 --parameters-change-limit=<double>      Stopping criteria: change in the parameters - used in learning (default 1e-3)
 --logging-on                            Set this flag if you would like the learning step to print out the status into a log file (this file will have the same name as the estimate parameters file with .log appended to the end)
 --maximum-a-posteriori-estimation       Use this flag to set the MAP flag to 0 (default 1)
 -v, --verbose                           will provide verbose output when using data dir
 --help                                  Display help and exit
 --version                               Display version information and exit

###Example Commands

#####Generate Factor Graph pgmlab --pairwise-interaction-file=data/munin-dataset/munin4_pairwise.txt --logical-factorgraph-file=data/munin-dataset/logical_factorgraph.txt --generate-factorgraph ######Output

Generating factorgraph with:
		number of states	2
	Factorgragh has been printed out into the following file: data/munin-dataset/logical_factorgraph.txt
	Factorgraph generation completed

#####Learning pgmlab --pairwise-interaction-file=data/munin-dataset/munin4_pairwise.txt --logical-factorgraph-file=data/munin-dataset/logical_factorgraph.txt --learning-observed-data-file=data/munin-dataset/visibleSet_0.9.txt --estimated-parameters-file=data/munin-dataset/estimated_parameters_0.9.txt --learning ######Output

Running Learning with:
		Max iterations			4000
		number of states		2
		log likelilhood change limit	0.000010
		parameters change limit		0.001000
		logging				off
		MAP				on
	Estimated Parameters (learnt factorgraph) have been written to: data/munin-dataset/estimated_parameters_0.9.txt
	Learning completed

#####Inference pgmlab --pairwise-interaction-file=data/munin-dataset/munin4_pairwise.txt --inference-factorgraph-file=data/munin-dataset/estimated_parameters_0.9.txt --inference-observed-data-file=data/munin-dataset/visibleSet_0.9.txt --posterior-probability-file=data/munin-dataset/posterior_probabilities_0.9_0.9.txt --inference ######Output

Running Inference with:  
		number of states  2  
	Posterior probabilities have been written to the following file: data/munin-dataset/posterior_probabilities_0.9_0.9.txt  
	Inference completed

####Interactive mode To use the interactive interface use the following command

pgmlab --interactive

This command will perform all three major steps of the analysis with the files specified in the example.ini file.

###Interactive Interactive mode will guide you through the analysis. You will be prompted to input the paths to both input and output files.

####Example Session

Starting Interactive Mode
>>
Would you like to generate a factorgraph from pairwise interactions [Y/n] y

Gathering information required to generated the factorgraph file from pairwise interactions
	Enter pairwise interaction filepath (input):  data/munin-dataset/munin4_pairwise.txt
	Enter factorgraph filepath (output):  data/munin-dataset/logical_factorgraph.txt
	Enter number of states [default 2]: 

Generating a factorgraph from pairwise interactions: data/munin-dataset/logical_factorgraph.txt
	Factorgragh has been output into the following factorgraph file: data/munin-dataset/logical_factorgraph.txt
	Factorgraph generation completed

Would you like to perform learning [Y/n] 

Gathering information required to perform learning
	Enter observed data filepath (input):  data/munin-dataset/visibleSet_0.9.txt
	Enter estimated parameters filepath (output):  data/munin-dataset/estimated_parameters_0.9.txt
	Would you like to have a log be generated for monitoring progress. If yes a "file.log" will be generated. [Y/n]  
	Enter max number of iterations for EM [default 400]: 
	Enter the stop criterion log likelihood change limit [default 1e-5]: 
	Enter the stop criterion parameters change limit [default 1e-3]: 
	Enter map flag (1 or 0) [default 1]: 
Running Learning
	Estimated Parameters have been written to the following file: data/munin-dataset/estimated_parameters_0.9.txt
	Learning completed

Would you like to perform inference [Y/n] 

Select yes if you would like to use a learnt factorgraph (estimated parameters from learning) file vs a logical factorgraph file [Y/n] n

Gathering information required to perform inference
	Enter factorgraph filepath (input):  data/munin-dataset/logical_factorgraph.txt
	Enter observed data filepath (input):   data/munin-dataset/visibleSet_0.9.txt
	Enter posterior probabilities filepath (output):  data/munin-dataset/posterior_probabilities_0.9_0.9.txt
	Enter number of states [default 2]: 
Running Inference
	Posterior probabilities have been written to the following file: data/munin-dataset/posterior_probabilities_0.9_0.9.txt
	Inference completed

Analysis Complete
Clone this wiki locally