Bring Your Own Data

As an alternative to using a pre-packaged dataset, the training and testing can be set explicitly by file path or with instances of TriplesFactory. Throughout this tutorial, the paths to the training, testing, and validation sets for built-in Nations will be used as examples.

Pre-stratified Dataset

You’ve got a training and testing file as 3-column TSV files, all ready to go. You’re sure that there aren’t any entities or relations appearing in the testing set that don’t appear in the training set. Load them in the pipeline like this:

from pykeen.datasets.nations import NATIONS_TEST_PATH, NATIONS_TRAIN_PATH, NATIONS_VALIDATE_PATH
from pykeen.pipeline import pipeline
from pykeen.triples import TriplesFactory

result = pipeline(
    training=NATIONS_TRAIN_PATH,
    testing=NATIONS_TEST_PATH,
    model="TransE",
    epochs=5,  # short epochs for testing - you should go higher
)
result.save_to_directory("doctests/test_pre_stratified_transe")

PyKEEN will take care of making sure that the entities are mapped from their labels to appropriate integer (technically, 0-dimensional torch.LongTensor) indexes and that the different sets of triples share the same mapping.

This is equally applicable for the hpo_pipeline(), which has a similar interface to the pipeline() as in:

from pykeen.hpo import hpo_pipeline

hpo_pipeline_result = hpo_pipeline(
    n_trials=3,  # you probably want more than this
    training=NATIONS_TRAIN_PATH,
    testing=NATIONS_TEST_PATH,
    validation=NATIONS_VALIDATE_PATH,
    model="TransE",
    epochs=5,  # short epochs for testing - you should go higher
)
hpo_pipeline_result.save_to_directory("doctests/test_hpo_pre_stratified_transe")

The remainder of the examples will be for pipeline(), but all work exactly the same for hpo_pipeline().

If you want to pass additional arguments to the model, you can use the model_kwargs argument to the pipeline, e.g., to explicitly model inverse relations with use_inverse_triples=True.

result = pipeline(
    training=NATIONS_TRAIN_PATH,
    testing=NATIONS_TEST_PATH,
    model="TransE",
    model_kwargs={"use_inverse_triples": True},
    epochs=5,  # short epochs for testing - you should go higher
)
result.save_to_directory("doctests/test_pre_stratified_transe_inverse")

If you want finer control over how the triples are created, for example, if they are not all coming from TSV files, you can use the TriplesFactory interface.

training = TriplesFactory.from_path(NATIONS_TRAIN_PATH)
testing = TriplesFactory.from_path(
    NATIONS_TEST_PATH,
    entity_to_id=training.entity_to_id,
    relation_to_id=training.relation_to_id,
)
result = pipeline(
    training=training,
    testing=testing,
    model="TransE",
    epochs=5,  # short epochs for testing - you should go higher
)
result.save_to_directory("doctests/test_pre_stratified_transe_factory")

Warning

The instantiation of the testing factory, we used the entity_to_id and relation_to_id keyword arguments. This is because PyKEEN automatically assigns numeric identifiers to all entities and relations for each triples factory. However, we want the identifiers to be exactly the same for the testing set as the training set, so we just reuse it. If we didn’t have the same identifiers, then the testing set would get mixed up with the wrong identifiers in the training set during evaluation, and we’d get nonsense results.

Whether inverse relations are used is decided by the model, not by the TriplesFactory, so the same model_kwargs also work when passing your own triples factories:

training = TriplesFactory.from_path(NATIONS_TRAIN_PATH)
testing = TriplesFactory.from_path(
    NATIONS_TEST_PATH,
    entity_to_id=training.entity_to_id,
    relation_to_id=training.relation_to_id,
)
result = pipeline(
    training=training,
    testing=testing,
    model="TransE",
    model_kwargs={"use_inverse_triples": True},
    epochs=5,  # short epochs for testing - you should go higher
)
result.save_to_directory("doctests/test_pre_stratified_transe_factory_inverse")

Triples factories can also be instantiated using the triples keyword argument instead of the path argument if you already have triples loaded in a numpy.ndarray.

Unstratified Dataset

It’s more realistic your real-world dataset is not already stratified into training and testing sets. PyKEEN has you covered with split(), which will allow you to create a stratified dataset.

tf = TriplesFactory.from_path(NATIONS_TRAIN_PATH)
training, testing = tf.split()
result = pipeline(
    training=training,
    testing=testing,
    model="TransE",
    epochs=5,  # short epochs for testing - you should go higher
)
result.save_to_directory("doctests/test_unstratified_transe")

By default, this is an 80/20 split. If you want to use early stopping, you’ll also need a validation set, so you should specify the splits:

tf = TriplesFactory.from_path(NATIONS_TRAIN_PATH)
training, testing, validation = tf.split([0.8, 0.1, 0.1])
result = pipeline(
    training=training,
    testing=testing,
    validation=validation,
    model="TransE",
    stopper="early",
    epochs=5,  # short epochs for testing - you should go
    # higher, especially with early stopper enabled
)
result.save_to_directory("doctests/test_unstratified_stopped_transe")

Bring Your Own Data with Checkpoints

For a tutorial on how to use your own data together with checkpoints, see Checkpoints When Bringing Your Own Data and Loading Models Manually.