Merge pull request #205 from baxtree/development-criterion

make MuRP a pointwise model and refactor

Author: louisccc

docs/source/api.rst

@@ -74,6 +74,18 @@ pykg2vec.models.projection
 .. automodule:: pykg2vec.models.projection
    :members:
 
+pykg2vec.models.Domain
+------------------------
+
+.. automodule:: pykg2vec.models.Domain
+   :members:
+
+pykg2vec.models.KGMeta
+------------------------
+
+.. automodule:: pykg2vec.models.KGMeta
+   :members:
+
 ====
 
 pykg2vec.utils
@@ -85,12 +97,30 @@ pykg2vec.utils.bayesian_optimizer
 .. automodule:: pykg2vec.utils.bayesian_optimizer
    :members:
 
+pykg2vec.utils.criterion
+---------------------------------
+
+.. automodule:: pykg2vec.utils.criterion
+   :members:
+
 pykg2vec.utils.evaluator
 ------------------------
 
 .. automodule:: pykg2vec.utils.evaluator
    :members:
 
+pykg2vec.utils.logger
+------------------------
+
+.. automodule:: pykg2vec.utils.logger
+   :members:
+
+pykg2vec.utils.riemannian_optimizer
+------------------------
+
+.. automodule:: pykg2vec.utils.riemannian_optimizer
+   :members:
+
 pykg2vec.utils.trainer
 ----------------------
 
@@ -118,19 +148,42 @@ pykg2vec.test.test_generator
 .. automodule:: pykg2vec.test.test_generator
    :members:
 
+pykg2vec.test.test_hp_loader
+----------------------------
+
+.. automodule:: pykg2vec.test.test_hp_loader
+   :members:
+
+pykg2vec.test.test_inference
+----------------------------
+
+.. automodule:: pykg2vec.test.test_inference
+   :members:
+
 pykg2vec.test.test_kg
 ---------------------
 
 .. automodule:: pykg2vec.test.test_kg
    :members:
 
+pykg2vec.test.test_logger
+---------------------
+
+.. automodule:: pykg2vec.test.test_logger
+   :members:
 
 pykg2vec.test.test_model
 ------------------------
 
 .. automodule:: pykg2vec.test.test_model
    :members:
 
+pykg2vec.test.test_trainer
+------------------------
+
+.. automodule:: pykg2vec.test.test_trainer
+   :members:
+
 pykg2vec.test.test_tune_model
 -----------------------------
 
@@ -140,5 +193,5 @@ pykg2vec.test.test_tune_model
 pykg2vec.test.test_inference
 ----------------------------
 
-.. automodule:: pykg2vec.test.test_inference
+.. automodule:: pykg2vec.test.test_visualization
    :members:

examples/README.txt

@@ -31,17 +31,18 @@ Please go through the examples for more advanced usages:
 - YAML formatting example (The file is also provided in /examples folder named custom_hp.yaml): ::
 
     model_name: "TransE"
-    dataset: "freebase15k"
-    parameters:
-        learning_rate: 0.01
-        l1_flag: True
-        hidden_size: 50
-        batch_size: 128
-        epochs: 1000
-        margin: 1.00
-        optimizer: "sgd"
-        sampling: "uniform"
-        neg_rate: 1
+    datasets:
+      - dataset: "freebase15k"
+        parameters:
+          learning_rate: 0.01
+          l1_flag: True
+          hidden_size: 50
+          batch_size: 128
+          epochs: 1000
+          margin: 1.00
+          optimizer: "sgd"
+          sampling: "bern"
+          neg_rate: 1
 
 - NB: To make sure the loaded hyperparameters will be actually used for training, you need to pass in the same model_name value via -mn and the same dataset value via -ds as already specified in the YAML file from where those hyperparameters are originated.
 
@@ -98,9 +99,26 @@ To create and use your own dataset, these steps are required:
     [name]-train.txt, [name]-valid.txt, [name]-test.txt
 
 3. For those three files, create a folder [path_storing_text_files] to include them.
-4. Once finished, you then can use your own dataset to train a KGE model using command:::
+4. Create a new custom hyperparameter YAML file (detailed in "Use Your Own Hyperparameters"). For example, ::
 
-    $ python train.py -mn TransE -ds [name] -dsp [path_storing_text_files] 
+    model_name: "TransE"
+    datasets:
+      - dataset: "[name]"
+        parameters:
+          learning_rate: 0.01
+          l1_flag: True
+          hidden_size: 50
+          batch_size: 128
+          epochs: 1000
+          margin: 1.00
+          optimizer: "sgd"
+          sampling: "bern"
+          neg_rate: 1
+
+5. Once finished, you then can use your own dataset to train a KGE model or tune its hyperparameters using commands:::
+
+    $ python train.py -mn TransE -ds [name] -dsp [path_storing_text_files] -hpf [path_to_hyperparameter_yaml]
+    $ python tune_model.py -mn TransE -ds [name] -dsp [path_storing_text_files] -hpf [path_to_hyperparameter_yaml]
 
 
 .. _LinkToEx: https://github.com/Sujit-O/pykg2vec/tree/master/examples

examples/custom_hp.yaml

@@ -1,12 +1,13 @@
 model_name: "TransE"
-dataset: "freebase15k"
-parameters:
-  learning_rate: 0.01
-  l1_flag: True
-  hidden_size: 50
-  batch_size: 128
-  epochs: 1000
-  margin: 1.00
-  optimizer: "sgd"
-  sampling: "uniform"
-  neg_rate: 1
+datasets:
+  - dataset: "freebase15k"
+    parameters:
+      learning_rate: 0.01
+      l1_flag: True
+      hidden_size: 50
+      batch_size: 128
+      epochs: 1000
+      margin: 1.00
+      optimizer: "sgd"
+      sampling: "bern"
+      neg_rate: 1

pykg2vec/common.py

@@ -22,7 +22,6 @@ class TrainingStrategy(Enum):
     PROJECTION_BASED = "projection_based"               # matching models with neural network
     PAIRWISE_BASED = "pairwise_based"                   # translational distance models
     POINTWISE_BASED = "pointwise_based"                 # semantic matching models
-    HYPERBOLIC_SPACE_BASED = "hyperbolic_space_based"   # models of hyperbolic space
 
 
 class KGEArgParser:
@@ -272,7 +271,7 @@ def __init__(self):
                          "hyper": "projection.HypER",
                          "interacte": "projection.InteractE",
                          "kg2e": "pairwise.KG2E",
-                         "murp": "hyperbolic.MuRP",
+                         "murp": "pointwise.MuRP",
                          "ntn": "pairwise.NTN",
                          "octonione": "pointwise.OctonionE",
                          "proje_pointwise": "projection.ProjE_pointwise",

pykg2vec/data/generator.py

@@ -305,8 +305,6 @@ def create_train_processor_process(self):
                 process_worker = Process(target=process_function_pairwise, args=(self.raw_queue, self.processed_queue, self.config))
             elif self.training_strategy == TrainingStrategy.POINTWISE_BASED:
                 process_worker = Process(target=process_function_pointwise, args=(self.raw_queue, self.processed_queue, self.config))
-            elif self.training_strategy == TrainingStrategy.HYPERBOLIC_SPACE_BASED:
-                process_worker = Process(target=process_function_pairwise, args=(self.raw_queue, self.processed_queue, self.config))
             else:
                 raise NotImplementedError("This strategy is not supported.")
             self.process_list.append(process_worker)

pykg2vec/models/KGMeta.py

@@ -78,17 +78,3 @@ def __init__(self, model_name):
         self.model_name = model_name
         self.training_strategy = TrainingStrategy.PROJECTION_BASED
         self.database = {}  # dict to store model-specific hyperparameter
-
-
-class HyperbolicSpaceModel(nn.Module, Model):
-    """ Meta Class for KGE models of hyperbolic space"""
-
-    __metaclass__ = ABCMeta
-
-    def __init__(self, model_name):
-        """Initialize and create the model to be trained and inferred"""
-        super(HyperbolicSpaceModel, self).__init__()
-
-        self.model_name = model_name
-        self.training_strategy = TrainingStrategy.HYPERBOLIC_SPACE_BASED
-        self.database = {}  # dict to store model-specific hyperparameter