Triple Scoring

The c_clause.PredictionHandler can be used to calculate scores for triples of the form (head, relation, tail). We assume in the following a loader is created and data and rules are loaded:

from c_clause import PredictionHandler, Loader
from clause import Options

data = [
    ("anna", "livesIn", "london"),
    ("anna", "learns", "english"),
    ("bernd", "speaks", "french")
]
rules = [
    "speaks(X,Y) <= learns(X,Y)",
    "speaks(X,english) <= livesIn(X,london)",
    "speaks(X,english) <= speaks(X,A)"
]
stats = [
    [20, 10],
    [40, 35],
    [50, 5],
]
opts = Options()
loader = Loader(opts.get("loader"))
loader.load_data(data=data)
loader.load_rules(rules=rules, stats=stats)

Calculating Triple Scores

The handler is initialized with options and scores are calculated with PredictionHandler.calculate_scores(triples, loader). The calculated scores depend on the handler options and the selected aggregation function aggregation_function under the prediction handler options. If a triple is not predicted by any rule, the calculated score will be 0. The function takes as arguments the triples input and the loader.

scorer = PredictionHandler(options=opts.get("prediction_handler"))
triples = [("anna", "speaks", "french"), ("anna", "speaks", "english")]
scorer.calculate_scores(triples=triples, loader=loader)

Triple input types

  1. From Python as strings: triples can be a list of string triples (tuples or list). See above.

  2. From file as strings: triples can be a file path where every line contains a tab separated string triple, e.g., the standard KG input datasets:

anna    speaks  french
anna   speaks   english

3. From Python as idx’s: triples can be a list or 2d np.array of idx’s triples. This requires the user to know the relation and entity index. Either by retrieving them from the loader after data is loaded or by setting them before data is loaded. See also in the section Loading Data. The following example sets the entity and relation index before loading data and rules.

from c_clause import PredictionHandler, Loader
from clause import Options
import numpy as np

data = [
    ("anna", "livesIn", "london"),
    ("anna", "learns", "english"),
    ("bernd", "speaks", "french")
]
rules = [
    "speaks(X,Y) <= learns(X,Y)",
    "speaks(X,english) <= livesIn(X,london)",
    "speaks(X,english) <= speaks(X,A)"
]
stats = [
    [20, 10],
    [40, 35],
    [50, 5],
]

opts = Options()
loader = Loader(opts.get("loader"))

# 0:anna, 1:bernd 2:london ...
entity_index = ["anna", "bernd", "london", "english", "french"]
# 0: speaks, 1:livesIn ...
relation_index = ["speaks", "livesIn", "learns"]

# set index before loading data and rules
loader.set_entity_index(index=entity_index)
loader.set_relation_index(index=relation_index)

loader.load_data(data=data)
loader.load_rules(rules=rules, stats=stats)

triples = np.array([(0,0,3), (0,0,4)])
scorer = PredictionHandler(options=opts.get("prediction_handler"))
scorer.calculate_scores(triples=triples, loader=loader)

Retrieving Results

The handler caches the results until the calculate_scores(..) function is invoked again. Independent of how data was loaded and how triple inputs were defined (strs or idx’s), outputs can be written to a file or obtained in Python and they can be formatted as idx’s or as strings.

Outputting candidates and scores

...
scorer.calculate_scores(triples=triples, loader=loader)

# output strings
# returns a list of lists
# each list scores_str[i] contains 4 elements: head, relation, tail, score
scores_str = scorer.get_scores(as_string=True)
# output idx's; same as above only as idx's
scores_idx = scorer.get_scores(as_string=False)
# write to file as string
# writes TAB-separated lines: head relation tail score
scorer.write_scores(path="scores_str.tx", as_string=True)
# write to file as idx; as above only as idx's
scorer.write_scores(path="scores_idx.tx", as_string=False)

Triple Explanations

We loosely define an explanation for a target triple prediction (head, relation, tail) as

  • a rule that predicted the target triple

  • the triples/atoms that ground the body of the rule s.t. the target prediction is the resulting grounded head of the rule

How to retrieve explanations from the PredictionHandler is explained in section Triple Explanations.