High-level usage - Code Overview#

On a high level the usage of Halerium involves the creation, training and evaluation of causal structures.

Causal Structures#

A CausalStructure is a collection of dependencies between parameters, with each parameter being defined by a string. The most convenient way to use a causal structure in conjunction with a pandas DataFrame, where the parameter names of the causal structure match the column names of the DataFrame.

For example:

>>> data = pandas.DataFrame(columns=["a", "b", "c", "d"])
>>> CausalStructure([[{"a", "b"}, {"c", "d"}]])
CausalStructure([[{'a', 'b'}, 'c'],
                 [{'a', 'b'}, 'd']])

Here the causal structure defines that c and d each depend on a and b.

Internally causal structures contains a Dependencies instance. The causal converts its Dependencies instance to the necessary core-objects (namely the Graph) to evaluate various objectives.


Internally causal structures utilize instances of Dependency and Dependencies. These classes manage the dependencies that make up the causal structure and are in charge of checking that the dependency tree is acyclic, i.e. that following a chain of dependencies cannot lead back to the first parameter in the chain.

>>> Dependency(feature: "a", target="a")
CyclicDependencyError: Cyclic dependency detected for 'a'.

>>> Dependencies([["a", "b"],
                  ["b", "c"],
                  ["c", "a"]])
CyclicDependencyError: Cyclic dependency detected for {'b'}.

The user does not have to create dependencies explicitly. The dependencies argument to the __init__ of the CausalStructure class is used to create the Dependencies instance automatically. The user can however also create the Dependencies instance themselves

>>> dependencies = Dependencies([[{"a", "b"}, {"c", "d"}]])
>>> causal_structure = CausalStructure(dependencies)
>>> causal_structure
CausalStructure([[{'a', 'b'}, 'c'],
                 [{'a', 'b'}, 'd']])

Basic Methods#

The most important method of the CausalStructure class are the following

train(): This method trains the causal structure (or rather its internal Graph) with a training data set. After training the causal structure can be used to make predictions or to evaluate objectives.

>>> data = pandas.DataFrame(columns=["a", "b", "c", "d"],
>>>                         data=[[0, 0,  0, 0],
>>>                               [1, 0,  1, 2],
>>>                               [0, 1, -2, 1],
>>>                               [1, 1, -1, 3]])
>>> causal_structure.train(data)

predict(): This method makes a prediction using the internal trained graph and an input data set.

>>> data_in = pandas.DataFrame(columns=["a", "b"],
>>>                            data=[[ -1,  -1],
>>>                                  [0.5, 0.5]])
>>> causal_structure.predict(data_in)
     a    b         c         d
0 -1.0 -1.0  0.976529 -2.953433
1  0.5  0.5 -0.476481  1.490052

evaluate_objective(): This method evaluates an objective class using the internal trained graph and additional arguments to the objective class. See the Objectives section.

Advanced Methods#

The CausalStructure class offers a number of advanced methods that allow the user to influence how the internal graph is build or to modify and/or utilize the graph with the core package The most important of these methods are the following

build_graph(): This method converts the dependencies into a Graph instance (see the core-package for details). The method is automatically called when the get_graph() or train() methods are called. With the explicit call the user can modify the build arguments.

get_graph(): This method returns the Graph instance that was created from the dependencies. If no graph was built yet, the build_graph() is triggered first. The user can modify the returned graph in-place using the core-package. Alternatively, a modified graph be used to replace the graph attribute.

get_trained_graph(): This method returns the Graph instance that was created by the train() method. If no training has taken place yet an Exception is raised. The user can modify the returned graph in-place using the core-package. Alternatively, a modified graph be used to replace the trained_graph attribute.

get_data_linker(): This method creates a DataLinker instance (see the core-package documentation for details) compatible with the internal graph from a provided data set.


The CausalStructure, Dependency and Dependencies classes are further explained in the following examples:

Real data applications of the CausalStructure are in the following examples:


Objectives are special classes that answer specific questions. The answer is based on the trained graph and the additional arguments to the objective (e.g. data). After the causal structure has been trained with the train() method objectives can be evaluated by calling the evaluate_objective() method. The first argument to the evaluate_objective() method is the objective class. The available classes are

Predictor: The predictor answers the question what the values of all parameters could be given the values of a subset of the parameters as data.

>>> causal_structure.evaluate_objective(Predictor, data=data_in, measure="mean")
     a    b         c         d
0 -1.0 -1.0  0.976529 -2.953433
1  0.5  0.5 -0.476481  1.490052

>>> causal_structure.evaluate_objective(Predictor, data=data_in, measure="std")
     a    b         c          d
0  0.0  0.0  9.443231  10.300908
1  0.0  0.0  0.875485   0.982973

Evaluator: The evaluator answers the question how well the predictions perform on a test data set.

>>> data_test = pandas.DataFrame(columns=["a", "b", "c", "d"],
>>>                              data=[[-1, -1,  1, -3],
>>>                                    [ 0, -1,  2, -1],
>>>                                    [-1,  0, -1, -2],
>>>                                    [ 2,  1,  0,  5],
>>>                                    [ 1,  2, -3,  4]])
>>> causal_structure.evaluate_objective(Evaluator, data=data_test,
>>>                                     inputs=["a", "b"], metric="r2")
{'a': None, 'b': None, 'c': 0.9997590212263663, 'd':  0.9998194827898427}

InfluenceEstimator: The influence estimator answers the question how much a certain target is influenced by the other parameters.

>>> causal_structure.evaluate_objective(InfluenceEstimator, target="d")
{'a': 0.7127661538640915, 'b': 0.4127766942443396, 'c': 0.0, 'd': 1.0}

OutlierDetector: The outlier detector answers the question which data points in a given data set are outliers (i.e. are very incompatible with the trained graph).

>>> data_test = pandas.DataFrame(columns=["a", "b", "c", "d"],
>>>                              data=[[1.5, 1.0, -0.5,  4.0],
>>>                                    [1.5, 1.0, -0.5, 40.0]])
>>> causal_structure.evaluate_objective(OutlierDetector, data=data_test)
     a    b    c    d  graph
0  1.0  0.0  0.0  0.0    0.0
1  1.0  0.0  1.0  1.0    1.0

RankEstimator: The rank estimator is the continuous analogon to the outlier detector. It answers the question of how many comparison data points would be more likely than the data point in question.

>>> causal_structure.evaluate_objective(RankEstimator, data=data_test)
      a     b     c     d  graph
0  0.04  0.31  0.60  0.52   0.22
1  0.04  0.31  0.00  0.00   0.00

ProbabilityEstimator: The probability estimator answers the question of what is the logarithmic probability density of the data point in question.

>>> causal_structure.evaluate_objective(ProbabilityEstimator, data=data_test)
          a         b         c           d        graph
0 -2.225791 -0.725791 -2.117248   -2.287631    -7.388386
1 -2.225791 -0.725791 -2.117248 -997.881033 -1222.759525

To answer questions which are not covered by these objective classes the user will have to utilize the low-level functionalities of the core package.


The objectives are used with the CausalStructure class in the following examples: