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

Tutorial Command Line Interface

Adam edited this page Dec 3, 2015 · 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. The first way is to use flags to configure and to run the program. In this way you will specify the files (pairwise interction 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. The second way is to 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 command 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 [-gli] [--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>] [--training-samples=<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 [logical-factorgraph-file, learning-observed-data-file, learnt-factorgraph-file]
 -i, --inference           Run inference given the states of visible sets [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)
 --training-samples=<int>  Number of training samples used in expectation mimization - used in learning step(default 400)
 --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)
 --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

#####Generate Factor Graph

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/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

#####Generate Factor Graph

pgmlab --pairwise-interaction-file=data/munin-dataset/munin4_pairwise.txt --logical-factorgraph-file=data/munin-dataset/logical_factorgraph.txt  --inference-observed-data-file=data/munin-dataset/estimated_parameters_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 criteriion log likelihood change limit [default 1e-5]: 
	Enter the stop criteriion 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