{
    "info": {
        "author": "Facebook AI Research",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "Environment :: Console",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: BSD License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3 :: Only",
            "Topic :: Scientific/Engineering :: Artificial Intelligence"
        ],
        "description": "# ![PyTorch-BigGraph](docs/source/_static/logo_color.svg)\n\n[![CircleCI Status](https://circleci.com/gh/facebookresearch/PyTorch-BigGraph.svg?style=svg)](https://circleci.com/gh/facebookresearch/PyTorch-BigGraph) [![Documentation Status](https://readthedocs.org/projects/torchbiggraph/badge/?version=latest)](https://torchbiggraph.readthedocs.io/en/latest/?badge=latest)\n\nPyTorch-BigGraph (PBG) is a distributed system for learning graph embeddings for large graphs, particularly big web interaction graphs with up to billions of entities and trillions of edges.\n\nPBG was introduced in the [PyTorch-BigGraph: A Large-scale Graph Embedding Framework](https://www.sysml.cc/doc/2019/71.pdf) paper, presented at the [SysML conference](https://www.sysml.cc/) in 2019.\n\nPBG trains on an input graph by ingesting its list of edges, each identified by its source and target entities and, possibly, a relation type. It outputs a feature vector (embedding) for each entity, trying to place adjacent entities close to each other in the vector space, while pushing unconnected entities apart. Therefore, entities that have a similar distribution of neighbors will end up being nearby.\n\nIt is possible to configure each relation type to calculate this \"proximity score\" in a different way, with the parameters (if any) learned during training. This allows the same underlying entity embeddings to be shared among multiple relation types.\n\nThe generality and extensibility of its model allows PBG to train a number of models from the knowledge graph embedding literature, including [TransE](https://www.utc.fr/~bordesan/dokuwiki/_media/en/transe_nips13.pdf), [RESCAL](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.383.2015&rep=rep1&type=pdf), [DistMult](https://arxiv.org/abs/1412.6575) and [ComplEx](http://proceedings.mlr.press/v48/trouillon16.pdf).\n\nPBG is designed with scale in mind, and achieves it through:\n- *graph partitioning*, so that the model does not have to be fully loaded into memory\n- *multi-threaded computation* on each machine\n- *distributed execution* across multiple machines (optional), all simultaneously operating on disjoint parts of the graph\n- *batched negative sampling*, allowing for processing >1 million edges/sec/machine with 100 negatives per edge\n\nPBG is *not* for model exploration with exotic models on small graphs, e.g. graph convnets, deep networks, etc.\n\n## Requirements\n\nPBG is written in Python (version 3.6 or later) and relies on [PyTorch](https://pytorch.org/) (at least version 1.0) and a few other libraries.\n\nAll computations are performed on the CPU, therefore a large number of cores is advisable. No GPU is necessary.\n\nWhen running on multiple machines, they need to be able to communicate to each other at high bandwidth (10 Gbps or higher recommended) and have access to a shared filesystem (for checkpointing). PBG uses [torch.distributed](https://pytorch.org/docs/stable/distributed.html), which uses the Gloo package which runs on top of TCP or MPI.\n\n## Installation\n\nTo install the latest version of PBG run:\n```bash\npip install torchbiggraph\n```\n\nAs an alternative, one can instead install the *development* version from the repository. This may have newer features but could be more unstable. To do so, clone the repository (or download it as an archive) and, inside the top-level directory, run:\n```bash\npip install .\n```\n\n## Getting started\n\nThe results of [the paper](https://www.sysml.cc/doc/2019/71.pdf) can easily be reproduced by running the following command (which executes [this script](torchbiggraph/examples/fb15k.py)):\n```bash\ntorchbiggraph_example_fb15k\n```\nThis will download the Freebase 15k knowledge base dataset, put it into the right format, train on it using the ComplEx model and finally perform an evaluation of the learned embeddings that calculates the MRR and other metrics that should match the paper. Another command, `torchbiggraph_example_livejournal`, does the same for the LiveJournal interaction graph dataset.\n\nTo learn how to use PBG, let us walk through what the FB15k script does.\n\n### Downloading the data\n\nFirst, it [retrieves the dataset](https://dl.fbaipublicfiles.com/starspace/fb15k.tgz) and unpacks it, obtaining a directory with three edge sets as TSV files, for training, validation and testing.\n```bash\nwget https://dl.fbaipublicfiles.com/starspace/fb15k.tgz -P data\ntar xf data/fb15k.tgz -C data\n```\n\nEach line of these files contains information about one edge. Using tabs as separators, the lines are divided into columns which contain the identifiers of the source entities, the relation types and the target entities. For example:\n```\n/m/027rn\t/location/country/form_of_government\t/m/06cx9\n/m/017dcd\t/tv/tv_program/regular_cast./tv/regular_tv_appearance/actor\t/m/06v8s0\n/m/07s9rl0\t/media_common/netflix_genre/titles\t/m/0170z3\n/m/01sl1q\t/award/award_winner/awards_won./award/award_honor/award_winner\t/m/044mz_\n/m/0cnk2q\t/soccer/football_team/current_roster./sports/sports_team_roster/position\t/m/02nzb8\n```\n\n### Preparing the data\n\nThen, the script converts the edge lists to PBG's input format. This amounts to assigning a numerical identifier to all entities and relation types, shuffling and partitioning the entities and edges and writing all down in the right format.\n\nLuckily, there is a command that does all of this:\n```bash\ntorchbiggraph_import_from_tsv \\\n  --lhs-col=0 --rel-col=1 --rhs-col=2 \\\n  torchbiggraph/examples/configs/fb15k_config.py \\\n  data/FB15k/freebase_mtr100_mte100-train.txt \\\n  data/FB15k/freebase_mtr100_mte100-valid.txt \\\n  data/FB15k/freebase_mtr100_mte100-test.txt\n```\nThe outputs will be stored next to the inputs in the `data/FB15k` directory.\n\nThis simple utility is only suitable for small graphs that fit entirely in memory. To handle larger data one will have to implement their own custom preprocessor.\n\n### Training\n\nThe `torchbiggraph_train` command is used to launch training. The training parameters are tucked away in a configuration file, whose path is given to the command. They can however be overridden from the command line with the `--param` flag. The sample config is used for both training and evaluation, so we will have to use the override to specify the edge set to use.\n```bash\ntorchbiggraph_train \\\n  torchbiggraph/examples/configs/fb15k_config.py \\\n  -p edge_paths=data/FB15k/freebase_mtr100_mte100-train_partitioned\n```\n\nThis will read data from the `entity_path` directory specified in the configuration and the `edge_paths` directory given on the command line. It will write checkpoints (which also double as the output data) to the `checkpoint_path` directory also defined in the configuration, which in this case is `model/fb15k`.\n\nTraining will proceed for 50 epochs in total, with the progress and some statistics logged to the console, for example:\n```\nStarting epoch 1 / 50, edge path 1 / 1, edge chunk 1 / 1\nEdge path: data/FB15k/freebase_mtr100_mte100-train_partitioned\nstill in queue: 0\nSwapping partitioned embeddings None ( 0 , 0 )\n( 0 , 0 ): Loading entities\n( 0 , 0 ): bucket 1 / 1 : Processed 483142 edges in 17.36 s ( 0.028 M/sec ); io: 0.02 s ( 542.52 MB/sec )\n( 0 , 0 ): loss:  309.695 , violators_lhs:  171.846 , violators_rhs:  165.525 , count:  483142\nSwapping partitioned embeddings ( 0 , 0 ) None\nWriting partitioned embeddings\nFinished epoch 1 / 50, edge path 1 / 1, edge chunk 1 / 1\nWriting the metadata\nWriting the checkpoint\nSwitching to the new checkpoint version\n```\n\n### Evaluation\n\nOnce training is complete, the entity embeddings it produced can be evaluated against a held-out edge set. The `torchbiggraph_example_fb15k` command performs a *filtered* evaluation, which calculates the ranks of the edges in the evaluation set by comparing them against all other edges *except* the ones that are true positives in any of the training, validation or test set. Filtered evaluation is used in the literature for FB15k, but does not scale beyond small graphs.\n\nThe final results should match the values of `mrr` (Mean Reciprocal Rank, MRR) and `r10` (Hits@10) reported in [the paper](https://www.sysml.cc/doc/2019/71.pdf):\n```\nStats: pos_rank:  65.4821 , mrr:  0.789921 , r1:  0.738501 , r10:  0.876894 , r50:  0.92647 , auc:  0.989868 , count:  59071\n```\n\nEvaluation can also be run directly from the command line as follows:\n```bash\ntorchbiggraph_eval \\\n  torchbiggraph/examples/configs/fb15k_config.py \\\n  -p edge_paths=data/FB15k/freebase_mtr100_mte100-test_partitioned \\\n  -p relations.0.all_negs=true \\\n  -p num_uniform_negs=0\n```\n\nHowever, *filtered* evaluation *cannot* be performed on the command line, so the reported results will not match the paper. They will be something like:\n```\nStats: pos_rank:  234.136 , mrr:  0.239957 , r1:  0.131757 , r10:  0.485382 , r50:  0.712693 , auc:  0.989648 , count:  59071\n```\n\n### Converting the output\n\nDuring preprocessing, the entities and relation types had their identifiers converted from strings to ordinals. In order to map the output embeddings back onto the original names, one can do:\n```bash\ntorchbiggraph_export_to_tsv \\\n  torchbiggraph/examples/configs/fb15k_config.py \\\n  --entities-output entity_embeddings.tsv \\\n  --relation-types-output relation_types_parameters.tsv\n```\nThis will create the `entity_embeddings.tsv` file, which is a text file where each line contains the identifier of an entity followed respectively by the components of its embedding, each in a different column, all separated by tabs. For example, with each line shortened for brevity:\n```\n/m/0fphf3v\t-0.524391472\t-0.016430536\t-0.461346656\t-0.394277513\t0.125605106\t...\n/m/01bns_\t-0.122734159\t-0.091636233\t0.506501377\t-0.503864646\t0.215775326\t...\n/m/02ryvsw\t-0.107151665\t0.002058491\t-0.094485454\t-0.129078045\t-0.123694092\t...\n/m/04y6_qr\t-0.577532947\t-0.215747222\t-0.022358289\t-0.352154016\t-0.051905245\t...\n/m/02wrhj\t-0.593656778\t-0.557167351\t0.042525314\t-0.104738958\t-0.265990764\t...\n```\nIt will also create a `relation_types_parameters.tsv` file which contains the parameters of the operators for the relation types. The format is similar to the above, but each line starts with more key columns containing, respectively, the name of a relation type, a side (`lhs` or `rhs`), the name of the operator which is used by that relation type on that side, the name of a parameter of that operator and the shape of the parameter (integers separated by `x`). These columns are followed by the values of the flattened parameter. For example, for two relation types, `foo` and `bar`, respectively using operators `linear` and `complex_diagonal`, with an embedding dimension of 200 and dynamic relations enabled, this file could look like:\n```\nfoo\tlhs\tlinear\tlinear_transformation\t200x200\t-0.683401227\t0.209822774\t-0.047136042\t...\nfoo\trhs\tlinear\tlinear_transformation\t200x200\t-0.695254087\t0.502532542\t-0.131654695\t...\nbar\tlhs\tcomplex_diagonal\treal\t200\t0.263731539\t1.350529909\t1.217602968\t...\nbar\tlhs\tcomplex_diagonal\timag\t200\t-0.089371338\t-0.092713356\t0.025076168\t...\nbar\trhs\tcomplex_diagonal\treal\t200\t-2.350617170\t0.529571176\t0.521403074\t...\nbar\trhs\tcomplex_diagonal\timag\t200\t0.692483306\t0.446569800\t0.235914066\t...\n```\n\n## Documentation\n\nMore information can be found in [the full documentation](https://torchbiggraph.readthedocs.io/).\n\n## Pre-trained embeddings\n\nWe trained a PBG model on the full [Wikidata](https://www.wikidata.org/) graph, using a [translation operator](https://torchbiggraph.readthedocs.io/en/latest/scoring.html#operators) to represent relations. It can be downloaded [here](https://dl.fbaipublicfiles.com/torchbiggraph/wikidata_translation_v1.tsv.gz) (36GiB, gzip-compressed). We used the truthy version of data from [here](https://dumps.wikimedia.org/wikidatawiki/entities/) to train our model. The model file is in TSV format as described in the above section. Note that the first line of the file contains the number of entities, the number of relations and the dimension of the embeddings, separated by tabs. The model contains 78 million entities, 4,131 relations and the dimension of the embeddings is 200.\n\n## Citation\n\nTo cite this work please use:\n```tex\n@inproceedings{pbg,\n  title={{PyTorch-BigGraph: A Large-scale Graph Embedding System}},\n  author={Lerer, Adam and Wu, Ledell and Shen, Jiajun and Lacroix, Timothee and Wehrstedt, Luca and Bose, Abhijit and Peysakhovich, Alex},\n  booktitle={Proceedings of the 2nd SysML Conference},\n  year={2019},\n  address={Palo Alto, CA, USA}\n}\n```\n\n## License\n\nPyTorch-BigGraph is BSD licensed, as found in the [LICENSE.txt](LICENSE.txt) file.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/facebookresearch/PyTorch-BigGraph",
        "keywords": "machine-learning,knowledge-base,graph-embedding,link-prediction",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "torchbiggraph",
        "package_url": "https://pypi.org/project/torchbiggraph/",
        "platform": "",
        "project_url": "https://pypi.org/project/torchbiggraph/",
        "project_urls": {
            "Bug Reports": "https://github.com/facebookresearch/PyTorch-BigGraph/issues",
            "Documentation": "https://torchbiggraph.readthedocs.io/",
            "Homepage": "https://github.com/facebookresearch/PyTorch-BigGraph",
            "Source": "https://github.com/facebookresearch/PyTorch-BigGraph"
        },
        "release_url": "https://pypi.org/project/torchbiggraph/1.0.0/",
        "requires_dist": [
            "attrs (>=18.2)",
            "h5py (>=2.8)",
            "numpy",
            "setuptools",
            "torch (>=1)",
            "tqdm",
            "Sphinx ; extra == 'docs'"
        ],
        "requires_python": ">=3.6, <4",
        "summary": "A distributed system to learn embeddings of large graphs",
        "version": "1.0.0"
    },
    "last_serial": 5972332,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a97dc626f1c093959417160c17ad9b49",
                    "sha256": "14d8b7e89a76a62aacd94210bc937ea0c48711fe965419ca97d1aefe1fd3f3e4"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "a97dc626f1c093959417160c17ad9b49",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.6, <4",
                "size": 99142,
                "upload_time": "2019-10-14T16:44:41",
                "url": "https://files.pythonhosted.org/packages/c3/db/925f84ea4eccc12945749015d81b9f0cd9e09d2ed15ca2a91bef69509a4a/torchbiggraph-1.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2a48c4fcb24d18cd83a9d5ea7c908aec",
                    "sha256": "adbfe08723eda0ffdafbabf743267758191c46453e19b3422a225611973794be"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "2a48c4fcb24d18cd83a9d5ea7c908aec",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6, <4",
                "size": 141318,
                "upload_time": "2019-10-14T16:44:43",
                "url": "https://files.pythonhosted.org/packages/d8/21/c9212264cf29f3fbdddeb9efce545261ba58751c35d2d291d4b58efe9882/torchbiggraph-1.0.0.tar.gz"
            }
        ],
        "1.dev0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "6899da777f8cbbbe584cc2785550967a",
                    "sha256": "b6999b537d0f592b12d0b0ff068829442c0b140f2badf5d7c512a3d962376538"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.dev0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "6899da777f8cbbbe584cc2785550967a",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 77029,
                "upload_time": "2019-03-31T21:01:51",
                "url": "https://files.pythonhosted.org/packages/0b/cb/ab01ade66d99e3ccabea281386a77d1febccb74091ef7935e95d5fb7e108/torchbiggraph-1.dev0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "ffc899280553f630ca5688c4789c4f50",
                    "sha256": "5d64af58af651be025563710665496f92c93c7f732bf6dd242958d78ef0c8f96"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.dev0.tar.gz",
                "has_sig": false,
                "md5_digest": "ffc899280553f630ca5688c4789c4f50",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 67664,
                "upload_time": "2019-03-31T21:01:53",
                "url": "https://files.pythonhosted.org/packages/7a/a7/7fdf2b47bb7a03b63712bb36c29d9ef3b396e811fea6e667907f7871dd1d/torchbiggraph-1.dev0.tar.gz"
            }
        ],
        "1.dev1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4506640b393ce52bd7f5a3a7ca671d28",
                    "sha256": "b394fbe05d8e6afa5ed72a89fb2f391c21e7492bced7bf3000c40cfaa0822ad0"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.dev1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "4506640b393ce52bd7f5a3a7ca671d28",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 85215,
                "upload_time": "2019-05-01T21:31:13",
                "url": "https://files.pythonhosted.org/packages/4b/04/d75b8259751d8771e5ed355219cb41ba53593cf41347c60981a986dc25b0/torchbiggraph-1.dev1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "4a66d065b7405727b12bdb2e9b4d43a2",
                    "sha256": "968e4a0ff2e4a36fff41ed877c2610b89074b209a0988fb4f9ea411d40afd831"
                },
                "downloads": -1,
                "filename": "torchbiggraph-1.dev1.tar.gz",
                "has_sig": false,
                "md5_digest": "4a66d065b7405727b12bdb2e9b4d43a2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 100982,
                "upload_time": "2019-05-01T21:31:15",
                "url": "https://files.pythonhosted.org/packages/29/17/85f40b05f92fb94f4be60f93614defecfab4955466b1a07c2c06931f85e2/torchbiggraph-1.dev1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "a97dc626f1c093959417160c17ad9b49",
                "sha256": "14d8b7e89a76a62aacd94210bc937ea0c48711fe965419ca97d1aefe1fd3f3e4"
            },
            "downloads": -1,
            "filename": "torchbiggraph-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a97dc626f1c093959417160c17ad9b49",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6, <4",
            "size": 99142,
            "upload_time": "2019-10-14T16:44:41",
            "url": "https://files.pythonhosted.org/packages/c3/db/925f84ea4eccc12945749015d81b9f0cd9e09d2ed15ca2a91bef69509a4a/torchbiggraph-1.0.0-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "2a48c4fcb24d18cd83a9d5ea7c908aec",
                "sha256": "adbfe08723eda0ffdafbabf743267758191c46453e19b3422a225611973794be"
            },
            "downloads": -1,
            "filename": "torchbiggraph-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "2a48c4fcb24d18cd83a9d5ea7c908aec",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6, <4",
            "size": 141318,
            "upload_time": "2019-10-14T16:44:43",
            "url": "https://files.pythonhosted.org/packages/d8/21/c9212264cf29f3fbdddeb9efce545261ba58751c35d2d291d4b58efe9882/torchbiggraph-1.0.0.tar.gz"
        }
    ]
}