Skip to content



Given a kgtk format file, this command will compute the the embeddings of this files' entities. We are using structure of nodes and their relations to compute embeddings of nodes. The set of metrics to compute are specified by the user.

Input format

The input is an kgtk format .tsv file where each line of these files contains information about nodes and relation. Each line is separated by tabs into columns which contains the node and relation data. For example:

id node1 relation node2 node1;label node2;label relation;label relation;dimension source sentence
/c/en/000-/r/RelatedTo-/c/en/112-0000 /c/en/000 /r/RelatedTo /c/en/112 000 112 related to CN ...

For further format details, please refer to the KGTK data specification.

Output format

There are three supported formats: glove, w2v, and kgtk.

glove format

When using this format, the output is a .tsv file where each line is the embedding for a node. Each line is represented by a single node followed respectively by the components of its embedding, each in a different column, all separated by tabs. For example:

"work" -0.014022544 -0.062030070 -0.012535412 -0.023111001 -0.038317516 ...

w2v format (default)

When using this format, the output is a .tsv file which it is almost the same as glove format, the only difference is that the word2vec format has a first line which indicates the shape of the embedding (e.g., "9 4" for 9 entities with 4 dimensions), each column of first line is separated by tabs. Here we use w2v as our default output format. For example:

16213 100
"work" -0.014022544 -0.062030070 -0.012535412 -0.023111001 -0.038317516 ...
"home" -0.014021411 -0.090830070 -0.012534120 -0.073111301 -0.068317516 ...

Here 16231 represents the number of nodes, 100 represents the dimension number of each node embedding.

kgtk format

When using this format, the output is a .tsv file where each line is the embedding for a node. Each line has 3 columns, first column represents entity node, second node represent its embedding type (here is graph_embeddings), third column represents the entity's embeddings. For example:

Q5 graph_embeddings
Q6 graph_embeddings


The algorithm is defined with the operator (-op) parameter. By default, it is ComplEx. It could be switched to: TransE, DistMult, or RESCAL. The operator is case insensitive, for example, users can input the string like complex to assign embedding method. For more details and pointers, see this documentation page.


You can call the functions directly with given args as

usage: kgtk graph-embeddings [-h] [-i INPUT_FILE] [-o OUTPUT_FILE] [-l] [-T]
                             [-ot] [-r True|False] [-d] [-s]
                             [-c dot|cos|l2|squared_l2]
                             [-op RESCAL|DistMult|ComplEx|TransE] [-e]
                             [-b True|False] [-w] [-bs]
                             [-lf ranking|logistic|softmax] [-lr] [-ef]
                             [-dr True|False] [-ge True|False]
                             [--no-output-header [True|False]]
                             [-v [optional True|False]]

Generate graph embedding in kgtk tsv format, here we use PytorchBigGraph as         low-level implementation 

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT_FILE, --input-file INPUT_FILE
                        The KGTK input file. (May be omitted or '-' for
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        The KGTK output file. (May be omitted or '-' for
  -l , --log            Setting the log path [Default: None]
  -T , --temporary_directory 
                        Sepecify the directory location to store temporary
  -ot , --output_format 
                        Outputformat for embeddings [Default: w2v] Choice:
                        kgtk | w2v | glove
  -r True|False, --retain_temporary_data True|False
                        When opearte graph, some tempory files will be
                        generated, set True to retain these files
  -d , --dimension      Dimension of the real space the embedding live in
                        [Default: 100]
  -s , --init_scale     Generating the initial embedding with this standard
                        deviation [Default: 0.001]If no initial embeddings are
                        provided, they are generated by sampling each
                        dimensionfrom a centered normal distribution having
                        this standard deviation.
  -c dot|cos|l2|squared_l2, --comparator dot|cos|l2|squared_l2
                        How the embeddings of the two sides of an edge (after
                        having already undergone some processing) are compared
                        to each other to produce a score[Default: dot],Choice:
  -op RESCAL|DistMult|ComplEx|TransE, --operator RESCAL|DistMult|ComplEx|TransE
                        The transformation to apply to the embedding of one of
                        the sides of the edge (typically the right-hand one)
                        before comparing it with the other one. It
                        reflectswhich model that embedding uses.
  -e , --num_epochs     The number of times the training loop iterates over
                        all the edges.[Default:100]
  -b True|False, --bias True|False
                        Whether use the bias choice [Default: False],If
                        enabled, withhold the first dimension of the
                        embeddings from the comparator and instead use it as a
                        bias, adding back to the score. Makes sense for
                        logistic and softmax loss functions.
  -w , --workers        The number of worker processes for training. If not
                        given, set to CPU count.
  -bs , --batch_size    The number of edges per batch.[Default:1000]
  -lf ranking|logistic|softmax, --loss_fn ranking|logistic|softmax
                        How the scores of positive edges and their
                        corresponding negatives are evaluated.[Default:
                        ranking], Choice: ranking|logistic|softmax
  -lr , --learning_rate 
                        The learning rate for the optimizer.[Default: 0.1]
  -ef , --eval_fraction 
                        The fraction of edges withheld from training and used
                        to track evaluation metrics during training.
                        [Defalut:0.0 training all edges ]
  -dr True|False, --dynamic_relations True|False
                        Whether use dynamic relations (when graphs with a
                        large number of relations) [Default: True]
  -ge True|False, --global_emb True|False
                        Whether use global embedding, if enabled, add to each
                        embedding a vector that is common to all the entities
                        of a certain type. This vector is learned during
                        training.[Default: False]
  --no-output-header [True|False]
                        When true, do not write a header to the output file

  -v [optional True|False], --verbose [optional True|False]
                        Print additional progress messages (default=False).


Example 1

For easiest running, just give the input file and let it write its output to output_embeddings.csv at current folder

kgtk graph-embeddings -i input_file.tsv  -o output_file.tsv

The output_file.tsv may look like:

172131 100
"work" -0.014022544 -0.062030070 -0.012535412 -0.023111001 -0.038317516 ...
"home" -0.014021411 -0.090830070 -0.012534120 -0.073111301 -0.068317516 ...

Example 2

Running with more specific parameters (TransE algorithm and 200-dimensional vectors):

kgtk graph-embeddings \
    --input-file input_file.tsv \
    --output-file output_file.tsv \
    --dimension 200 \
    --comparator dot \
    --operator translation \
    --loss_fn softmax \
    --learning_rate 0.1

The output_file.tsv may look like:

172131 100
"work" -0.014022544 -0.062030070 -0.012535412 -0.023111001 -0.038317516 ...
"home" -0.014021411 -0.090830070 -0.012534120 -0.073111301 -0.068317516 ...

Example 3

Using glove format to generate graph embeddings

kgtk graph-embeddings \
    --input-file input_file.tsv \
    --output-file output_file.tsv \
    --output_format glove

The output_file.tsv may look like:

"work" -0.014022544 -0.062030070 -0.012535412 -0.023111001 -0.038317516 ...
"home" -0.014021411 -0.090830070 -0.012534120 -0.073111301 -0.068317516 ...

Example 4

Using kgtk format to generate graph embeddings

kgtk graph-embeddings \
    --input-file input_file.tsv \
    --output-file output_file.tsv \
    --output_format kgtk --no-output-headers

The output_file.tsv may look like:

"work" graph_embeddings -0.014022544,-0.062030070,-0.012535412,-0.023111001,-0.038317516 ...
"home" graph_embeddings -0.014021411,-0.090830070,-0.012534120,-0.073111301,-0.068317516 ...