Skip to content

sfu-cl-lab/FactorBase

Repository files navigation

FactorBase: Learning Graphical Models from multi-relational data

Build Status

The source code repository for the FactorBase system. The code in this repository implements the learn-and-join algorithm (see algorithm paper on ''Learning Graphical Models for Relational Data via Lattice Search'').

  • Input: A relational schema hosted on a MySQL server.

  • Output: A Bayesian network that shows probabilistic dependencies between the relationships and attributes represented in the database. Both network structure and parameters are computed by the system.

Contingency Table Generator

One of the key computational problems in relational learning and inference is to compute how many times a conjunctive condition is instantiated in a relational structure. FactorBase computes relational contingency tables, which store for a given set of first-order terms/predicates how many times different value combinations of the terms are instantiated in the input database. Given the general importance of this problem in pretty much any relational data problem, we provide stand-alone code for computing contingency tables that can be used independently of our Bayesian network learning system.

Further Information

  • Our project website contains various helpful information such as pointers to datasets, a gallery of learned models, and system tips.
  • The tutorial explains the concepts underlying the algorithm and our other tools
  • Our system paper titled '' FactorBase: Multi-Relational Model Learning with SQL All The Way'' explains the system components.

How to Use - Overview

  1. Import data into a Mysql server

    We provide example datasets in the examples folder. For debugging and testing, we recommend starting with the Unielwin dataset. This is a small today dataset.

    • Unielwin schema University Schema

We recommend using the MariaDB MySQL server. We have tested Factorbase on MariaDB version 10.4.28.

  1. Install the program

    First clone the project by running a command similar to the following:

    git clone https://github.com/sfu-cl-lab/FactorBase.git
    1. Simple approach: use the compiled .jar file at the root directory factorbase-1.0.jar
    2. More complex approach: build from scratch. FactorBase and other tools in the project can all be built using the following command (make sure to have Maven installed):
    cd FactorBase/code
    mvn install

    After the above commands are successfully run, an executable JAR file for FactorBase can be found at:

    factorbase/target/factorbase-<version>-SNAPSHOT.jar

    Where the <version> field is the version of FactorBase that you have generated.

    Note: The Maven build will run some tests that expect a test database to be setup. The required the setup file could be found at here. If you just want to create the JAR file for FactorBase, then you can run the following command instead:

    cd FactorBase/code
    mvn clean install -DskipTests
  2. Update config.cfg with your own analysis according to format explained here By default the executable JAR file will look for the configuration file in the current directory (i.e. where you are running the command), if you would like to specify a different configuration file to use when running FactorBase you can use the parameter -Dconfig=<config-file>. For example:

    java -Dconfig=../config.cfg -jar factorbase/target/factorbase-<version>-SNAPSHOT.jar
  3. Point to the database that you want to analyse

    Modify the configuration file with your own connection parameters according to the sample format explained in the image.

    Sample Configuration.

    See our project website for an explanation of the options.

    For the last row, you can set the global logger to this threee levels:

    • debug: show all log messages;
    • info: only show info, warning and error messages(no debug message), which is the default;
    • off: show no log message;
  4. Learn a Bayesian Network Structure

    In the FactorBase folder, run

    java -jar factorbase/target/factorbase-<version>-SNAPSHOT.jar

    Where the <version> field is the version of FactorBase that you have generated.

    Note: For big databases, you may need to specify larger java heap size by

    java -jar -Xmx8G factorbase/target/factorbase-<version>-SNAPSHOT.jar
  5. Inspect the Bayesian Network (BN)

    We follow the BayesStore design philosphy where statistical objects are treated as managed within the database.

    1. The network structure is stored in the table Final_Path_BayesNets of the <db>_BN database where <db> is the model database specified in your configuration file. For nodes with no parents, see the view View_Final_Path_BayesNets.
    2. The conditional probability tables are stored in tables named <nodename>_CP of the <db>_BN database where <db> is the model database specified in your configuration file and <nodename> is the name of the child node.
    3. The file Bif_<db>.xml contains a Bayes net specification that can be loaded into a Bayes net tool (see next Section). This file is written to the directory that contains your config.cfg file.

===============

Other Output Formats: BIF, MLN, ETL

The learned BN structure can be exported from the database to support a number of other applications.


Other Applications (May Be Under Construction)

After running the learn-and-join algorithm, the learned Bayesian network can be leveraged for various applications.