HyTE

HyTE: Hyperplane-based Temporally aware Knowledge Graph Embedding

Source code and dataset for EMNLP 2018 paper: HyTE: Hyperplane-based Temporally aware Knowledge Graph Embedding.

Overview of HyTE (proposed method). a temporally aware KG embedding method which explicitly incorporates time in the entity-relation space by stitching each timestamp with a corresponding hyperplane. HyTE not only performs KG inference using temporal guidance, but also predicts temporal scopes for relational facts with missing time annotations. Please refer paper for more details.

Dependencies

• Compatible with TensorFlow 1.x and Python 3.x.
• Dependencies can be installed using requirements.txt.

Dataset:

• Download the processed version of WikiData and YAGO datasets.
• Unzip the .zip file in data directory.
• Documents are originally taken from YAGO and Wikidata.

Usage:

• After installing python dependencies from requirements.txt.
• time_proj.py contains TensorFlow (1.x) based implementation of HyTE (proposed method).
• To start training:

  python time_proj.py -name yago_data_neg_sample_5_mar_10_l2_0.00 -margin 10 -l2 0.00 -neg_sample 5 -gpu 5 -epoch 2000 -data_type yago -version large -test_freq 5

• Some of the important Available options include:

  '-data_type' default ='yago', choices = ['yago','wiki_data'], help ='dataset to choose'
    '-version',  default = 'large', choices = ['large','small'], help = 'data version to choose'
    '-test_freq',    default = 25,      type=int,   help='testing frequency'
    '-neg_sample',   default = 5,       type=int,   help='negative samples for training'
    '-gpu',      dest="gpu",        default='1',            help='GPU to use'
    '-name',     dest="name",       help='Name of the run'
    '-lr',   dest="lr",         default=0.0001,  type=float,    help='Learning rate'
    '-margin',   dest="margin",     default=1,      type=float,     help='margin'
    '-batch',    dest="batch_size",     default= 50000,     type=int,   help='Batch size'
    '-epoch',    dest="max_epochs",     default= 5000,      type=int,   help='Max epochs'
    '-l2',   dest="l2",         default=0.0,    type=float,     help='L2 regularization'
    '-seed',     dest="seed",       default=1234,   type=int,   help='Seed for randomization'
    '-inp_dim',  dest="inp_dim",    default = 128,      type=int,   help='')
    '-L1_flag',  dest="L1_flag",    action='store_false',           help='Hidden state dimension of FC layer'

Evaluation:

• Validate after Training.
• Use the same model name and test frequency used at training as arguments for the following evalutation--
• For getting best validation MR and hit@10 for head and tail prediction:

    python result_eval.py -eval_mode valid -model yago_data_neg_sample_5_mar_10_l2_0.00 -test_freq 5

• For getting best validation MR and hit@10 for relation prediction:

   python result_eval_relation.py -eval_mode valid -model yago_data_neg_sample_5_mar_10_l2_0.00  -test_freq 5

  The Evaluation run will output the Best Validation Rank and the corresponding Best Validation Epoch when it was achieved. Note them down for obtaining results on test set.

Testing:

• Test after validation using the best validation weights.
• First run the time_proj.py script once to restore parameters and then dump the predictions corresponding the the test set.

  python time_proj.py -res_epoch `Best Validation Epoch` -onlyTest -restore -name yago_data_neg_sample_5_mar_10_l2_0.00 -margin 10 -l2 0.00 -neg_sample 5 -gpu 0 -data_type yago -version large

• Now evaluate the test predictions to obtain MR and hits@10 using

  python result_eval.py -eval_mode test -test_freq `Best Validation Epoch` -model yago_data_neg_sample_5_mar_10_l2_0.00

Citing:

InProceedings{D18-1225,
  author =  "Dasgupta, Shib Sankar
        and Ray, Swayambhu Nath
        and Talukdar, Partha",
  title =   "HyTE: Hyperplane-based Temporally aware Knowledge Graph Embedding",
  booktitle =   "Proceedings of the 2018 Conference on Empirical Methods in Natural Language Processing",
  year =    "2018",
  publisher =   "Association for Computational Linguistics",
  pages =   "2001--2011",
  location =    "Brussels, Belgium",
  url =     "http://aclweb.org/anthology/D18-1225"
}