  PyKEEN

    PyKEEN (Python KnowlEdge EmbeddiNgs) is a Python package designed to
    train and evaluate knowledge graph embedding models (incorporating multi-modal information).

  Installation •
  Quickstart •
  Datasets (37) •
  Inductive Datasets (5) •
  Models (40) •
  Support •
  Citation

## Installation ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pykeen) ![PyPI](https://img.shields.io/pypi/v/pykeen)

The latest stable version of PyKEEN requires Python 3.8+. It can be downloaded
and installed from [PyPI](https://pypi.org/project/pykeen) with:

```shell
pip install pykeen
```

The latest version of PyKEEN can be installed directly from the
source code on [GitHub](https://github.com/pykeen/pykeen) with:

```shell
pip install git+https://github.com/pykeen/pykeen.git
```

More information about installation (e.g., development mode, Windows installation, Colab, Kaggle, extras)
can be found in the [installation documentation](https://pykeen.readthedocs.io/en/latest/installation.html).

## Quickstart [![Documentation Status](https://readthedocs.org/projects/pykeen/badge/?version=latest)](https://pykeen.readthedocs.io/en/latest/?badge=latest)

This example shows how to train a model on a dataset and test on another dataset.

The fastest way to get up and running is to use the pipeline function. It
provides a high-level entry into the extensible functionality of this package.
The following example shows how to train and evaluate the [TransE](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.TransE.html#pykeen.models.TransE)
model on the [Nations](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Nations.html#pykeen.datasets.Nations)
dataset. By default, the training loop uses the [stochastic local closed world assumption (sLCWA)](https://pykeen.readthedocs.io/en/latest/reference/training.html#pykeen.training.SLCWATrainingLoop)
training approach and evaluates with [rank-based evaluation](https://pykeen.readthedocs.io/en/latest/reference/evaluation/rank_based.html#pykeen.evaluation.RankBasedEvaluator).

```python
from pykeen.pipeline import pipeline

result = pipeline(
    model='TransE',
    dataset='nations',
)
```

The results are returned in an instance of the [PipelineResult](https://pykeen.readthedocs.io/en/latest/reference/pipeline.html#pykeen.pipeline.PipelineResult)
dataclass that has attributes for the trained model, the training loop, the evaluation, and more. See the tutorials
on [using your own dataset](https://pykeen.readthedocs.io/en/latest/byo/data.html),
[understanding the evaluation](https://pykeen.readthedocs.io/en/latest/tutorial/understanding_evaluation.html),
and [making novel link predictions](https://pykeen.readthedocs.io/en/latest/tutorial/making_predictions.html).

PyKEEN is extensible such that:

- Each model has the same API, so anything from ``pykeen.models`` can be dropped in
- Each training loop has the same API, so ``pykeen.training.LCWATrainingLoop`` can be dropped in
- Triples factories can be generated by the user with ``from pykeen.triples.TriplesFactory``

The full documentation can be found at https://pykeen.readthedocs.io.

## Implementation

Below are the models, datasets, training modes, evaluators, and metrics implemented
in ``pykeen``.

### Datasets

The following 37 datasets are built in to PyKEEN. The citation for each dataset corresponds to either the paper
describing the dataset, the first paper published using the dataset with knowledge graph embedding models,
or the URL for the dataset if neither of the first two are available. If you want to use a custom dataset,
see the [Bring Your Own Dataset](https://pykeen.readthedocs.io/en/latest/byo/data.html) tutorial. If you
have a suggestion for another dataset to include in PyKEEN, please let us know
[here](https://github.com/pykeen/pykeen/issues/new?assignees=cthoyt&labels=New+Dataset&template=dataset-request.md&title=Add+%5BDATASET+NAME%5D).

| Name                               | Documentation                                                                                | Citation                                                                                |   Entities |   Relations |   Triples |
|------------------------------------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------|-------------|-----------|
| Aristo-v4                          | [`pykeen.datasets.AristoV4`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.AristoV4.html)             | [Chen *et al*., 2021](https://openreview.net/pdf?id=Qa3uS3H7-Le)                                                        |      42016 |        1593 |    279425 |
| BioKG                              | [`pykeen.datasets.BioKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.BioKG.html)                   | [Walsh *et al*., 2019](https://doi.org/10.1145/3340531.3412776)                                                         |     105524 |          17 |   2067997 |
| Clinical Knowledge Graph           | [`pykeen.datasets.CKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CKG.html)                       | [Santos *et al*., 2020](https://doi.org/10.1101/2020.05.09.084897)                                                      |    7617419 |          11 |  26691525 |
| CN3l Family                        | [`pykeen.datasets.CN3l`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CN3l.html)                     | [Chen *et al*., 2017](https://www.ijcai.org/Proceedings/2017/0209.pdf)                                                  |       3206 |          42 |     21777 |
| CoDEx (large)                      | [`pykeen.datasets.CoDExLarge`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CoDExLarge.html)         | [Safavi *et al*., 2020](https://arxiv.org/abs/2009.07810)                                                               |      77951 |          69 |    612437 |
| CoDEx (medium)                     | [`pykeen.datasets.CoDExMedium`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CoDExMedium.html)       | [Safavi *et al*., 2020](https://arxiv.org/abs/2009.07810)                                                               |      17050 |          51 |    206205 |
| CoDEx (small)                      | [`pykeen.datasets.CoDExSmall`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CoDExSmall.html)         | [Safavi *et al*., 2020](https://arxiv.org/abs/2009.07810)                                                               |       2034 |          42 |     36543 |
| ConceptNet                         | [`pykeen.datasets.ConceptNet`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.ConceptNet.html)         | [Speer *et al*., 2017](https://arxiv.org/abs/1612.03975)                                                                |   28370083 |          50 |  34074917 |
| Countries                          | [`pykeen.datasets.Countries`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Countries.html)           | [Bouchard *et al*., 2015](https://www.aaai.org/ocs/index.php/SSS/SSS15/paper/view/10257/10026)                          |        271 |           2 |      1158 |
| Commonsense Knowledge Graph        | [`pykeen.datasets.CSKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.CSKG.html)                     | [Ilievski *et al*., 2020](http://arxiv.org/abs/2012.11490)                                                              |    2087833 |          58 |   4598728 |
| DB100K                             | [`pykeen.datasets.DB100K`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.DB100K.html)                 | [Ding *et al*., 2018](https://arxiv.org/abs/1805.02408)                                                                 |      99604 |         470 |    697479 |
| DBpedia50                          | [`pykeen.datasets.DBpedia50`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.DBpedia50.html)           | [Shi *et al*., 2017](https://arxiv.org/abs/1711.03438)                                                                  |      24624 |         351 |     34421 |
| Drug Repositioning Knowledge Graph | [`pykeen.datasets.DRKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.DRKG.html)                     | [`gnn4dr/DRKG`](https://github.com/gnn4dr/DRKG)                                                                         |      97238 |         107 |   5874257 |
| FB15k                              | [`pykeen.datasets.FB15k`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.FB15k.html)                   | [Bordes *et al*., 2013](http://papers.nips.cc/paper/5071-translating-embeddings-for-modeling-multi-relational-data.pdf) |      14951 |        1345 |    592213 |
| FB15k-237                          | [`pykeen.datasets.FB15k237`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.FB15k237.html)             | [Toutanova *et al*., 2015](https://www.aclweb.org/anthology/W15-4007/)                                                  |      14505 |         237 |    310079 |
| Global Biotic Interactions         | [`pykeen.datasets.Globi`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Globi.html)                   | [Poelen *et al*., 2014](https://doi.org/10.1016/j.ecoinf.2014.08.005)                                                   |     404207 |          39 |   1966385 |
| Hetionet                           | [`pykeen.datasets.Hetionet`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Hetionet.html)             | [Himmelstein *et al*., 2017](https://doi.org/10.7554/eLife.26726)                                                       |      45158 |          24 |   2250197 |
| Kinships                           | [`pykeen.datasets.Kinships`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Kinships.html)             | [Kemp *et al*., 2006](https://www.aaai.org/Papers/AAAI/2006/AAAI06-061.pdf)                                             |        104 |          25 |     10686 |
| Nations                            | [`pykeen.datasets.Nations`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Nations.html)               | [`ZhenfengLei/KGDatasets`](https://github.com/ZhenfengLei/KGDatasets)                                                   |         14 |          55 |      1992 |
| NationsL                           | [`pykeen.datasets.NationsLiteral`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.NationsLiteral.html) | [`pykeen/pykeen`](https://github.com/pykeen/pykeen)                                                                     |         14 |          55 |      1992 |
| OGB BioKG                          | [`pykeen.datasets.OGBBioKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.OGBBioKG.html)             | [Hu *et al*., 2020](https://arxiv.org/abs/2005.00687)                                                                   |      93773 |          51 |   5088434 |
| OGB WikiKG2                        | [`pykeen.datasets.OGBWikiKG2`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.OGBWikiKG2.html)         | [Hu *et al*., 2020](https://arxiv.org/abs/2005.00687)                                                                   |    2500604 |         535 |  17137181 |
| OpenBioLink                        | [`pykeen.datasets.OpenBioLink`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.OpenBioLink.html)       | [Breit *et al*., 2020](https://doi.org/10.1093/bioinformatics/btaa274)                                                  |     180992 |          28 |   4563407 |
| OpenBioLink LQ                     | [`pykeen.datasets.OpenBioLinkLQ`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.OpenBioLinkLQ.html)   | [Breit *et al*., 2020](https://doi.org/10.1093/bioinformatics/btaa274)                                                  |     480876 |          32 |  27320889 |
| OpenEA Family                      | [`pykeen.datasets.OpenEA`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.OpenEA.html)                 | [Sun *et al*., 2020](http://www.vldb.org/pvldb/vol13/p2326-sun.pdf)                                                     |      15000 |         248 |     38265 |
| PharMeBINet                        | [`pykeen.datasets.PharMeBINet`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.PharMeBINet.html)       | [Königs *et al*., 2022](https://www.nature.com/articles/s41597-022-01510-3)                                             |    2869407 |         208 |  15883653 |
| PharmKG                            | [`pykeen.datasets.PharmKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.PharmKG.html)               | [Zheng *et al*., 2020](https://doi.org/10.1093/bib/bbaa344)                                                             |     188296 |          39 |   1093236 |
| PharmKG8k                          | [`pykeen.datasets.PharmKG8k`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.PharmKG8k.html)           | [Zheng *et al*., 2020](https://doi.org/10.1093/bib/bbaa344)                                                             |       7247 |          28 |    485787 |
| PrimeKG                            | [`pykeen.datasets.PrimeKG`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.PrimeKG.html)               | [Chandak *et al*., 2022](https://doi.org/10.1101/2022.05.01.489928)                                                     |     129375 |          30 |   8100498 |
| Unified Medical Language System    | [`pykeen.datasets.UMLS`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.UMLS.html)                     | [`ZhenfengLei/KGDatasets`](https://github.com/ZhenfengLei/KGDatasets)                                                   |        135 |          46 |      6529 |
| WD50K (triples)                    | [`pykeen.datasets.WD50KT`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.WD50KT.html)                 | [Galkin *et al*., 2020](https://www.aclweb.org/anthology/2020.emnlp-main.596/)                                          |      40107 |         473 |    232344 |
| Wikidata5M                         | [`pykeen.datasets.Wikidata5M`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.Wikidata5M.html)         | [Wang *et al*., 2019](https://arxiv.org/abs/1911.06136)                                                                 |    4594149 |         822 |  20624239 |
| WK3l-120k Family                   | [`pykeen.datasets.WK3l120k`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.WK3l120k.html)             | [Chen *et al*., 2017](https://www.ijcai.org/Proceedings/2017/0209.pdf)                                                  |     119748 |        3109 |   1375406 |
| WK3l-15k Family                    | [`pykeen.datasets.WK3l15k`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.WK3l15k.html)               | [Chen *et al*., 2017](https://www.ijcai.org/Proceedings/2017/0209.pdf)                                                  |      15126 |        1841 |    209041 |
| WordNet-18                         | [`pykeen.datasets.WN18`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.WN18.html)                     | [Bordes *et al*., 2014](https://arxiv.org/abs/1301.3485)                                                                |      40943 |          18 |    151442 |
| WordNet-18 (RR)                    | [`pykeen.datasets.WN18RR`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.WN18RR.html)                 | [Toutanova *et al*., 2015](https://www.aclweb.org/anthology/W15-4007/)                                                  |      40559 |          11 |     92583 |
| YAGO3-10                           | [`pykeen.datasets.YAGO310`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.YAGO310.html)               | [Mahdisoltani *et al*., 2015](http://service.tsi.telecom-paristech.fr/cgi-bin//valipub_download.cgi?dId=284)            |     123143 |          37 |   1089000 |

### Inductive Datasets

The following 5 inductive datasets are built in to PyKEEN.

| Name            | Documentation                                                                                | Citation                                                  |
|-----------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| ILPC2022 Large  | [`pykeen.datasets.ILPC2022Large`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.ILPC2022Large.html)         | [Galkin *et al*., 2022](https://arxiv.org/abs/2203.01520) |
| ILPC2022 Small  | [`pykeen.datasets.ILPC2022Small`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.ILPC2022Small.html)         | [Galkin *et al*., 2022](https://arxiv.org/abs/2203.01520) |
| FB15k-237       | [`pykeen.datasets.InductiveFB15k237`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.InductiveFB15k237.html) | [Teru *et al*., 2020](https://arxiv.org/abs/1911.06962)   |
| NELL            | [`pykeen.datasets.InductiveNELL`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.InductiveNELL.html)         | [Teru *et al*., 2020](https://arxiv.org/abs/1911.06962)   |
| WordNet-18 (RR) | [`pykeen.datasets.InductiveWN18RR`](https://pykeen.readthedocs.io/en/latest/api/pykeen.datasets.InductiveWN18RR.html)     | [Teru *et al*., 2020](https://arxiv.org/abs/1911.06962)   |

### Representations

The following 20 representations are implemented by PyKEEN.

| Name                       | Reference                                                                                |
|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Backfill                   | [`pykeen.nn.BackfillRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.BackfillRepresentation.html)                      |
| Text Encoding              | [`pykeen.nn.BiomedicalCURIERepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.BiomedicalCURIERepresentation.html)        |
| Combined                   | [`pykeen.nn.CombinedRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.CombinedRepresentation.html)                      |
| Embedding                  | [`pykeen.nn.Embedding`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.Embedding.html)                                                |
| Featurized Message Passing | [`pykeen.nn.FeaturizedMessagePassingRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.pyg.FeaturizedMessagePassingRepresentation.html) |
| Low Rank Embedding         | [`pykeen.nn.LowRankRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.LowRankRepresentation.html)                        |
| NodePiece                  | [`pykeen.nn.NodePieceRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.node_piece.representation.NodePieceRepresentation.html)         |
| Partition                  | [`pykeen.nn.PartitionRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.PartitionRepresentation.html)                    |
| R-GCN                      | [`pykeen.nn.RGCNRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.message_passing.RGCNRepresentation.html)                             |
| Simple Message Passing     | [`pykeen.nn.SimpleMessagePassingRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.pyg.SimpleMessagePassingRepresentation.html)         |
| CompGCN                    | [`pykeen.nn.SingleCompGCNRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.SingleCompGCNRepresentation.html)            |
| Subset Representation      | [`pykeen.nn.SubsetRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.SubsetRepresentation.html)                          |
| Tensor-Train               | [`pykeen.nn.TensorTrainRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.TensorTrainRepresentation.html)                |
| Text Encoding              | [`pykeen.nn.TextRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.TextRepresentation.html)                              |
| Tokenization               | [`pykeen.nn.TokenizationRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.node_piece.representation.TokenizationRepresentation.html)   |
| Transformed                | [`pykeen.nn.TransformedRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.TransformedRepresentation.html)                |
| Typed Message Passing      | [`pykeen.nn.TypedMessagePassingRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.pyg.TypedMessagePassingRepresentation.html)           |
| Visual                     | [`pykeen.nn.VisualRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.vision.VisualRepresentation.html)                                  |
| Wikidata Text Encoding     | [`pykeen.nn.WikidataTextRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.representation.WikidataTextRepresentation.html)              |
| Wikidata Visual            | [`pykeen.nn.WikidataVisualRepresentation`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.vision.WikidataVisualRepresentation.html)                  |

### Interactions

The following 34 interactions are implemented by PyKEEN.

| Name                           | Reference                                                                                | Citation                                                                                |
|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| AutoSF                         | [`pykeen.nn.AutoSFInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.AutoSFInteraction.html)                       | [Zhang *et al.*, 2020](https://arxiv.org/abs/1904.11682)                                                                |
| BoxE                           | [`pykeen.nn.BoxEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.BoxEInteraction.html)                           | [Abboud *et al.*, 2020](https://arxiv.org/abs/2007.06267)                                                               |
| ComplEx                        | [`pykeen.nn.ComplExInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ComplExInteraction.html)                     | [Trouillon *et al.*, 2016](https://arxiv.org/abs/1606.06357)                                                            |
| ConvE                          | [`pykeen.nn.ConvEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ConvEInteraction.html)                         | [Dettmers *et al.*, 2018](https://www.aaai.org/ocs/index.php/AAAI/AAAI18/paper/view/17366)                              |
| ConvKB                         | [`pykeen.nn.ConvKBInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ConvKBInteraction.html)                       | [Nguyen *et al.*, 2018](https://www.aclweb.org/anthology/N18-2053)                                                      |
| Canonical Tensor Decomposition | [`pykeen.nn.CPInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.CPInteraction.html)                               | [Lacroix *et al.*, 2018](https://arxiv.org/abs/1806.07297)                                                              |
| CrossE                         | [`pykeen.nn.CrossEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.CrossEInteraction.html)                       | [Zhang *et al.*, 2019](https://arxiv.org/abs/1903.04750)                                                                |
| DistMA                         | [`pykeen.nn.DistMAInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.DistMAInteraction.html)                       | [Shi *et al.*, 2019](https://www.aclweb.org/anthology/D19-1075.pdf)                                                     |
| DistMult                       | [`pykeen.nn.DistMultInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.DistMultInteraction.html)                   | [Yang *et al.*, 2014](https://arxiv.org/abs/1412.6575)                                                                  |
| ER-MLP                         | [`pykeen.nn.ERMLPInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ERMLPInteraction.html)                         | [Dong *et al.*, 2014](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/45634.pdf)                   |
| ER-MLP (E)                     | [`pykeen.nn.ERMLPEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ERMLPEInteraction.html)                       | [Sharifzadeh *et al.*, 2019](https://github.com/pykeen/pykeen)                                                          |
| HolE                           | [`pykeen.nn.HolEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.HolEInteraction.html)                           | [Nickel *et al.*, 2016](https://www.aaai.org/ocs/index.php/AAAI/AAAI16/paper/viewFile/12484/11828)                      |
| KG2E                           | [`pykeen.nn.KG2EInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.KG2EInteraction.html)                           | [He *et al.*, 2015](https://dl.acm.org/doi/10.1145/2806416.2806502)                                                     |
| LineaRE                        | [`pykeen.nn.LineaREInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.LineaREInteraction.html)                     | [Peng *et al.*, 2020](https://arxiv.org/abs/2004.10037)                                                                 |
| MultiLinearTucker              | [`pykeen.nn.MultiLinearTuckerInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.MultiLinearTuckerInteraction.html) | [Tucker *et al.*, 1966](https://dx.doi.org/10.1007/BF02289464)                                                          |
| MuRE                           | [`pykeen.nn.MuREInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.MuREInteraction.html)                           | [Balažević *et al.*, 2019](https://arxiv.org/abs/1905.09791)                                                            |
| NTN                            | [`pykeen.nn.NTNInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.NTNInteraction.html)                             | [Socher *et al.*, 2013](https://proceedings.neurips.cc/paper/2013/file/b337e84de8752b27eda3a12363109e80-Paper.pdf)      |
| PairRE                         | [`pykeen.nn.PairREInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.PairREInteraction.html)                       | [Chao *et al.*, 2020](http://arxiv.org/abs/2011.03798)                                                                  |
| ProjE                          | [`pykeen.nn.ProjEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.ProjEInteraction.html)                         | [Shi *et al.*, 2017](https://www.aaai.org/ocs/index.php/AAAI/AAAI17/paper/view/14279)                                   |
| QuatE                          | [`pykeen.nn.QuatEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.QuatEInteraction.html)                         | [Zhang *et al.*, 2019](https://arxiv.org/abs/1904.10281)                                                                |
| RESCAL                         | [`pykeen.nn.RESCALInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.RESCALInteraction.html)                       | [Nickel *et al.*, 2011](https://icml.cc/2011/papers/438_icmlpaper.pdf)                                                  |
| RotatE                         | [`pykeen.nn.RotatEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.RotatEInteraction.html)                       | [Sun *et al.*, 2019](https://arxiv.org/abs/1902.10197)                                                                  |
| Structured Embedding           | [`pykeen.nn.SEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.SEInteraction.html)                               | [Bordes *et al.*, 2011](https://www.aaai.org/ocs/index.php/AAAI/AAAI11/paper/download/3659/3898)                        |
| SimplE                         | [`pykeen.nn.SimplEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.SimplEInteraction.html)                       | [Kazemi *et al.*, 2018](https://papers.nips.cc/paper/7682-simple-embedding-for-link-prediction-in-knowledge-graphs)     |
| TorusE                         | [`pykeen.nn.TorusEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TorusEInteraction.html)                       | [Ebisu *et al.*, 2018](https://www.aaai.org/ocs/index.php/AAAI/AAAI18/paper/view/16227)                                 |
| TransD                         | [`pykeen.nn.TransDInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransDInteraction.html)                       | [Ji *et al.*, 2015](http://www.aclweb.org/anthology/P15-1067)                                                           |
| TransE                         | [`pykeen.nn.TransEInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransEInteraction.html)                       | [Bordes *et al.*, 2013](http://papers.nips.cc/paper/5071-translating-embeddings-for-modeling-multi-relational-data.pdf) |
| TransF                         | [`pykeen.nn.TransFInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransFInteraction.html)                       | [Feng *et al.*, 2016](https://www.aaai.org/ocs/index.php/KR/KR16/paper/view/12887)                                      |
| Transformer                    | [`pykeen.nn.TransformerInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransformerInteraction.html)             | [Galkin *et al.*, 2020](https://doi.org/10.18653/v1/2020.emnlp-main.596)                                                |
| TransH                         | [`pykeen.nn.TransHInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransHInteraction.html)                       | [Wang *et al.*, 2014](https://www.aaai.org/ocs/index.php/AAAI/AAAI14/paper/viewFile/8531/8546)                          |
| TransR                         | [`pykeen.nn.TransRInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TransRInteraction.html)                       | [Lin *et al.*, 2015](http://www.aaai.org/ocs/index.php/AAAI/AAAI15/paper/download/9571/9523/)                           |
| TripleRE                       | [`pykeen.nn.TripleREInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TripleREInteraction.html)                   | [Yu *et al.*, 2021](https://vixra.org/abs/2112.0095)                                                                    |
| Tucker                         | [`pykeen.nn.TuckerInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.TuckerInteraction.html)                       | [Balažević *et al.*, 2019](https://arxiv.org/abs/1901.09590)                                                            |
| Unstructured Model             | [`pykeen.nn.UMInteraction`](https://pykeen.readthedocs.io/en/latest/api/pykeen.nn.modules.UMInteraction.html)                               | [Bordes *et al.*, 2014](https://link.springer.com/content/pdf/10.1007%2Fs10994-013-5363-6.pdf)                          |

### Models

The following 40 models are implemented by PyKEEN.

| Name                           | Model                                                                                | Citation                                                                                |
|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| AutoSF                         | [`pykeen.models.AutoSF`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.auto_sf.AutoSF.html)                                                | [Zhang *et al.*, 2020](https://arxiv.org/abs/1904.11682)                                                                |
| BoxE                           | [`pykeen.models.BoxE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.boxe.BoxE.html)                                                       | [Abboud *et al.*, 2020](https://arxiv.org/abs/2007.06267)                                                               |
| Canonical Tensor Decomposition | [`pykeen.models.CP`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.cp.CP.html)                                                             | [Lacroix *et al.*, 2018](https://arxiv.org/abs/1806.07297)                                                              |
| CompGCN                        | [`pykeen.models.CompGCN`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.compgcn.CompGCN.html)                                              | [Vashishth *et al.*, 2020](https://arxiv.org/pdf/1911.03082)                                                            |
| ComplEx                        | [`pykeen.models.ComplEx`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.complex.ComplEx.html)                                              | [Trouillon *et al.*, 2016](https://arxiv.org/abs/1606.06357)                                                            |
| ComplEx Literal                | [`pykeen.models.ComplExLiteral`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.multimodal.complex_literal.ComplExLiteral.html)                      | [Kristiadi *et al.*, 2018](https://arxiv.org/abs/1802.00934)                                                            |
| ConvE                          | [`pykeen.models.ConvE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.conv_e.ConvE.html)                                                   | [Dettmers *et al.*, 2018](https://www.aaai.org/ocs/index.php/AAAI/AAAI18/paper/view/17366)                              |
| ConvKB                         | [`pykeen.models.ConvKB`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.conv_kb.ConvKB.html)                                                | [Nguyen *et al.*, 2018](https://www.aclweb.org/anthology/N18-2053)                                                      |
| CooccurrenceFiltered           | [`pykeen.models.CooccurrenceFilteredModel`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.meta.filtered.CooccurrenceFilteredModel.html)             | [Berrendorf *et al.*, 2022](https://github.com/pykeen/pykeen/pull/943)                                                  |
| CrossE                         | [`pykeen.models.CrossE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.crosse.CrossE.html)                                                 | [Zhang *et al.*, 2019](https://arxiv.org/abs/1903.04750)                                                                |
| DistMA                         | [`pykeen.models.DistMA`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.distma.DistMA.html)                                                 | [Shi *et al.*, 2019](https://www.aclweb.org/anthology/D19-1075.pdf)                                                     |
| DistMult                       | [`pykeen.models.DistMult`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.distmult.DistMult.html)                                           | [Yang *et al.*, 2014](https://arxiv.org/abs/1412.6575)                                                                  |
| DistMult Literal               | [`pykeen.models.DistMultLiteral`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.multimodal.distmult_literal.DistMultLiteral.html)                   | [Kristiadi *et al.*, 2018](https://arxiv.org/abs/1802.00934)                                                            |
| DistMult Literal (Gated)       | [`pykeen.models.DistMultLiteralGated`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.multimodal.distmult_literal_gated.DistMultLiteralGated.html)   | [Kristiadi *et al.*, 2018](https://arxiv.org/abs/1802.00934)                                                            |
| ER-MLP                         | [`pykeen.models.ERMLP`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.ermlp.ERMLP.html)                                                    | [Dong *et al.*, 2014](https://dl.acm.org/citation.cfm?id=2623623)                                                       |
| ER-MLP (E)                     | [`pykeen.models.ERMLPE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.ermlpe.ERMLPE.html)                                                 | [Sharifzadeh *et al.*, 2019](https://github.com/pykeen/pykeen)                                                          |
| Fixed Model                    | [`pykeen.models.FixedModel`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.mocks.FixedModel.html)                                                   | [Berrendorf *et al.*, 2021](https://github.com/pykeen/pykeen/pull/691)                                                  |
| HolE                           | [`pykeen.models.HolE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.hole.HolE.html)                                                       | [Nickel *et al.*, 2016](https://www.aaai.org/ocs/index.php/AAAI/AAAI16/paper/viewFile/12484/11828)                      |
| InductiveNodePiece             | [`pykeen.models.InductiveNodePiece`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.inductive.inductive_nodepiece.InductiveNodePiece.html)           | [Galkin *et al.*, 2021](https://arxiv.org/abs/2106.12144)                                                               |
| InductiveNodePieceGNN          | [`pykeen.models.InductiveNodePieceGNN`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.inductive.inductive_nodepiece_gnn.InductiveNodePieceGNN.html) | [Galkin *et al.*, 2021](https://arxiv.org/abs/2106.12144)                                                               |
| KG2E                           | [`pykeen.models.KG2E`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.kg2e.KG2E.html)                                                       | [He *et al.*, 2015](https://dl.acm.org/doi/10.1145/2806416.2806502)                                                     |
| MuRE                           | [`pykeen.models.MuRE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.mure.MuRE.html)                                                       | [Balažević *et al.*, 2019](https://arxiv.org/abs/1905.09791)                                                            |
| NTN                            | [`pykeen.models.NTN`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.ntn.NTN.html)                                                          | [Socher *et al.*, 2013](https://dl.acm.org/doi/10.5555/2999611.2999715)                                                 |
| NodePiece                      | [`pykeen.models.NodePiece`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.node_piece.NodePiece.html)                                       | [Galkin *et al.*, 2021](https://arxiv.org/abs/2106.12144)                                                               |
| PairRE                         | [`pykeen.models.PairRE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.pair_re.PairRE.html)                                                | [Chao *et al.*, 2020](http://arxiv.org/abs/2011.03798)                                                                  |
| ProjE                          | [`pykeen.models.ProjE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.proj_e.ProjE.html)                                                   | [Shi *et al.*, 2017](https://www.aaai.org/ocs/index.php/AAAI/AAAI17/paper/view/14279)                                   |
| QuatE                          | [`pykeen.models.QuatE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.quate.QuatE.html)                                                    | [Zhang *et al.*, 2019](https://arxiv.org/abs/1904.10281)                                                                |
| R-GCN                          | [`pykeen.models.RGCN`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.rgcn.RGCN.html)                                                       | [Schlichtkrull *et al.*, 2018](https://arxiv.org/pdf/1703.06103)                                                        |
| RESCAL                         | [`pykeen.models.RESCAL`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.rescal.RESCAL.html)                                                 | [Nickel *et al.*, 2011](http://www.cip.ifi.lmu.de/~nickel/data/paper-icml2011.pdf)                                      |
| RotatE                         | [`pykeen.models.RotatE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.rotate.RotatE.html)                                                 | [Sun *et al.*, 2019](https://arxiv.org/abs/1902.10197v1)                                                                |
| SimplE                         | [`pykeen.models.SimplE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.simple.SimplE.html)                                                 | [Kazemi *et al.*, 2018](https://papers.nips.cc/paper/7682-simple-embedding-for-link-prediction-in-knowledge-graphs)     |
| Structured Embedding           | [`pykeen.models.SE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.structured_embedding.SE.html)                                           | [Bordes *et al.*, 2011](https://www.aaai.org/ocs/index.php/AAAI/AAAI11/paper/download/3659/3898)                        |
| TorusE                         | [`pykeen.models.TorusE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.toruse.TorusE.html)                                                 | [Ebisu *et al.*, 2018](https://www.aaai.org/ocs/index.php/AAAI/AAAI18/paper/view/16227)                                 |
| TransD                         | [`pykeen.models.TransD`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.trans_d.TransD.html)                                                | [Ji *et al.*, 2015](http://www.aclweb.org/anthology/P15-1067)                                                           |
| TransE                         | [`pykeen.models.TransE`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.trans_e.TransE.html)                                                | [Bordes *et al.*, 2013](http://papers.nips.cc/paper/5071-translating-embeddings-for-modeling-multi-relational-data.pdf) |
| TransF                         | [`pykeen.models.TransF`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.trans_f.TransF.html)                                                | [Feng *et al.*, 2016](https://www.aaai.org/ocs/index.php/KR/KR16/paper/view/12887)                                      |
| TransH                         | [`pykeen.models.TransH`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.trans_h.TransH.html)                                                | [Wang *et al.*, 2014](https://www.aaai.org/ocs/index.php/AAAI/AAAI14/paper/viewFile/8531/8546)                          |
| TransR                         | [`pykeen.models.TransR`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.trans_r.TransR.html)                                                | [Lin *et al.*, 2015](http://www.aaai.org/ocs/index.php/AAAI/AAAI15/paper/download/9571/9523/)                           |
| TuckER                         | [`pykeen.models.TuckER`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.tucker.TuckER.html)                                                 | [Balažević *et al.*, 2019](https://arxiv.org/abs/1901.09590)                                                            |
| Unstructured Model             | [`pykeen.models.UM`](https://pykeen.readthedocs.io/en/latest/api/pykeen.models.unimodal.unstructured_model.UM.html)                                             | [Bordes *et al.*, 2014](https://link.springer.com/content/pdf/10.1007%2Fs10994-013-5363-6.pdf)                          |

### Losses

The following 15 losses are implemented by PyKEEN.

| Name                                                      | Reference                                                                                | Description                                                                                |
|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| Adversarially weighted binary cross entropy (with logits) | [`pykeen.losses.AdversarialBCEWithLogitsLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.AdversarialBCEWithLogitsLoss.html) | An adversarially weighted BCE loss.                                                                   |
| Binary cross entropy (after sigmoid)                      | [`pykeen.losses.BCEAfterSigmoidLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.BCEAfterSigmoidLoss.html)                   | The numerically unstable version of explicit Sigmoid + BCE loss.                                      |
| Binary cross entropy (with logits)                        | [`pykeen.losses.BCEWithLogitsLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.BCEWithLogitsLoss.html)                       | The binary cross entropy loss.                                                                        |
| Cross entropy                                             | [`pykeen.losses.CrossEntropyLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.CrossEntropyLoss.html)                         | The cross entropy loss that evaluates the cross entropy after softmax output.                         |
| Double Margin                                             | [`pykeen.losses.DoubleMarginLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.DoubleMarginLoss.html)                         | A limit-based scoring loss, with separate margins for positive and negative elements from [sun2018]_. |
| Focal                                                     | [`pykeen.losses.FocalLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.FocalLoss.html)                                       | The focal loss proposed by [lin2018]_.                                                                |
| InfoNCE loss with additive margin                         | [`pykeen.losses.InfoNCELoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.InfoNCELoss.html)                                   | The InfoNCE loss with additive margin proposed by [wang2022]_.                                        |
| Margin ranking                                            | [`pykeen.losses.MarginRankingLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.MarginRankingLoss.html)                       | The pairwise hinge loss (i.e., margin ranking loss).                                                  |
| Mean squared error                                        | [`pykeen.losses.MSELoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.MSELoss.html)                                           | The mean squared error loss.                                                                          |
| Self-adversarial negative sampling                        | [`pykeen.losses.NSSALoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.NSSALoss.html)                                         | The self-adversarial negative sampling loss function proposed by [sun2019]_.                          |
| Pairwise logistic                                         | [`pykeen.losses.PairwiseLogisticLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.PairwiseLogisticLoss.html)                 | The pairwise logistic loss.                                                                           |
| Pointwise Hinge                                           | [`pykeen.losses.PointwiseHingeLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.PointwiseHingeLoss.html)                     | The pointwise hinge loss.                                                                             |
| Soft margin ranking                                       | [`pykeen.losses.SoftMarginRankingLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.SoftMarginRankingLoss.html)               | The soft pairwise hinge loss (i.e., soft margin ranking loss).                                        |
| Softplus                                                  | [`pykeen.losses.SoftplusLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.SoftplusLoss.html)                                 | The pointwise logistic loss (i.e., softplus loss).                                                    |
| Soft Pointwise Hinge                                      | [`pykeen.losses.SoftPointwiseHingeLoss`](https://pykeen.readthedocs.io/en/latest/api/pykeen.losses.SoftPointwiseHingeLoss.html)             | The soft pointwise hinge loss.                                                                        |

### Regularizers

The following 6 regularizers are implemented by PyKEEN.

| Name          | Reference                                                                                | Description                                                            |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| combined      | [`pykeen.regularizers.CombinedRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.CombinedRegularizer.html)           | A convex combination of regularizers.                                  |
| lp            | [`pykeen.regularizers.LpRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.LpRegularizer.html)                       | A simple L_p norm based regularizer.                                   |
| no            | [`pykeen.regularizers.NoRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.NoRegularizer.html)                       | A regularizer which does not perform any regularization.               |
| normlimit     | [`pykeen.regularizers.NormLimitRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.NormLimitRegularizer.html)         | A regularizer which formulates a soft constraint on a maximum norm.    |
| orthogonality | [`pykeen.regularizers.OrthogonalityRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.OrthogonalityRegularizer.html) | A regularizer for the soft orthogonality constraints from [wang2014]_. |
| powersum      | [`pykeen.regularizers.PowerSumRegularizer`](https://pykeen.readthedocs.io/en/latest/api/pykeen.regularizers.PowerSumRegularizer.html)           | A simple x^p based regularizer.                                        |

### Training Loops

The following 3 training loops are implemented in PyKEEN.

| Name          | Reference                                                                                | Description                                                                               |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| lcwa          | [`pykeen.training.LCWATrainingLoop`](https://pykeen.readthedocs.io/en/latest/reference/training.html#pykeen.training.LCWATrainingLoop)                   | A training loop that is based upon the local closed world assumption (LCWA).              |
| slcwa         | [`pykeen.training.SLCWATrainingLoop`](https://pykeen.readthedocs.io/en/latest/reference/training.html#pykeen.training.SLCWATrainingLoop)                 | A training loop that uses the stochastic local closed world assumption training approach. |
| symmetriclcwa | [`pykeen.training.SymmetricLCWATrainingLoop`](https://pykeen.readthedocs.io/en/latest/reference/training.html#pykeen.training.SymmetricLCWATrainingLoop) | A "symmetric" LCWA scoring heads *and* tails at once.                                     |

### Negative Samplers

The following 3 negative samplers are implemented in PyKEEN.

| Name        | Reference                                                                                | Description                                                                            |
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| basic       | [`pykeen.sampling.BasicNegativeSampler`](https://pykeen.readthedocs.io/en/latest/api/pykeen.sampling.BasicNegativeSampler.html)             | A basic negative sampler.                                                              |
| bernoulli   | [`pykeen.sampling.BernoulliNegativeSampler`](https://pykeen.readthedocs.io/en/latest/api/pykeen.sampling.BernoulliNegativeSampler.html)     | An implementation of the Bernoulli negative sampling approach proposed by [wang2014]_. |
| pseudotyped | [`pykeen.sampling.PseudoTypedNegativeSampler`](https://pykeen.readthedocs.io/en/latest/api/pykeen.sampling.PseudoTypedNegativeSampler.html) | A sampler that accounts for which entities co-occur with a relation.                   |

### Stoppers

The following 2 stoppers are implemented in PyKEEN.

| Name   | Reference                                                                                | Description                   |
|--------|--------------------------------------------------------------------------------------------------------------------------------|-------------------------------|
| early  | [`pykeen.stoppers.EarlyStopper`](https://pykeen.readthedocs.io/en/latest/reference/stoppers.html#pykeen.stoppers.EarlyStopper) | A harness for early stopping. |
| nop    | [`pykeen.stoppers.NopStopper`](https://pykeen.readthedocs.io/en/latest/reference/stoppers.html#pykeen.stoppers.NopStopper)     | A stopper that does nothing.  |

### Evaluators

The following 5 evaluators are implemented in PyKEEN.

| Name             | Reference                                                                                | Description                                                              |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| classification   | [`pykeen.evaluation.ClassificationEvaluator`](https://pykeen.readthedocs.io/en/latest/api/pykeen.evaluation.ClassificationEvaluator.html)     | An evaluator that uses a classification metrics.                         |
| macrorankbased   | [`pykeen.evaluation.MacroRankBasedEvaluator`](https://pykeen.readthedocs.io/en/latest/api/pykeen.evaluation.MacroRankBasedEvaluator.html)     | Macro-average rank-based evaluation.                                     |
| ogb              | [`pykeen.evaluation.OGBEvaluator`](https://pykeen.readthedocs.io/en/latest/api/pykeen.evaluation.OGBEvaluator.html)                           | A sampled, rank-based evaluator that applies a custom OGB evaluation.    |
| rankbased        | [`pykeen.evaluation.RankBasedEvaluator`](https://pykeen.readthedocs.io/en/latest/api/pykeen.evaluation.RankBasedEvaluator.html)               | A rank-based evaluator for KGE models.                                   |
| sampledrankbased | [`pykeen.evaluation.SampledRankBasedEvaluator`](https://pykeen.readthedocs.io/en/latest/api/pykeen.evaluation.SampledRankBasedEvaluator.html) | A rank-based evaluator using sampled negatives instead of all negatives. |

### Metrics

The following 44 metrics are implemented in PyKEEN.

| Name                                                                                | Interval                    | Direction   | Description                                                             | Type           |
|------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|-------------|-------------------------------------------------------------------------|----------------|
| [Accuracy](https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers#Single_metrics)                                                      | $[0, 1]$                    | 📈           | The ratio of the number of correct classifications to the total number. | Classification |
| [Area Under The Receiver Operating Characteristic Curve](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.roc_auc_score.html) | $[0, 1]$                    | 📈           | The area under the receiver operating characteristic curve.             | Classification |
| [Average Precision Score](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.average_precision_score.html)                      | $[0, 1]$                    | 📈           | The average precision across different thresholds.                      | Classification |
| [Balanced Accuracy Score](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.balanced_accuracy_score.html)                      | $[0, 1]$                    | 📈           | The average of recall obtained on each class.                           | Classification |
| [Diagnostic Odds Ratio](https://en.wikipedia.org/wiki/Diagnostic_odds_ratio)                                                                   | $[0, ∞)$                    | 📈           | The ratio of positive and negative likelihood ratio.                    | Classification |
| [F1 Score](https://en.wikipedia.org/wiki/F1_score)                                                                                | $[0, 1]$                    | 📈           | The harmonic mean of precision and recall.                              | Classification |
| [False Discovery Rate](https://en.wikipedia.org/wiki/False_discovery_rate)                                                                     | $[0, 1]$                    | 📉           | The proportion of predicted negatives which are true positive.          | Classification |
| [False Negative Rate](https://en.wikipedia.org/wiki/Type_I_and_type_II_errors#False_positive_and_false_negative_rates)                         | $[0, 1]$                    | 📉           | The probability that a truly positive triple is predicted negative.     | Classification |
| [False Omission Rate](https://en.wikipedia.org/wiki/Positive_and_negative_predictive_values)                                                   | $[0, 1]$                    | 📉           | The proportion of predicted positives which are true negative.          | Classification |
| [False Positive Rate](https://en.wikipedia.org/wiki/False_positive_rate)                                                                       | $[0, 1]$                    | 📉           | The probability that a truly negative triple is predicted positive.     | Classification |
| [Fowlkes Mallows Index](https://en.wikipedia.org/wiki/Fowlkes%E2%80%93Mallows_index)                                                           | $[0, 1]$                    | 📈           | The Fowlkes Mallows index.                                              | Classification |
| [Informedness](https://en.wikipedia.org/wiki/Informedness)                                                                                | $[-1, 1]$                   | 📈           | The informedness metric.                                                | Classification |
| [Matthews Correlation Coefficient](https://en.wikipedia.org/wiki/Phi_coefficient)                                                              | $[-1, 1]$                   | 📈           | The Matthews Correlation Coefficient (MCC).                             | Classification |
| [Negative Likelihood Ratio](https://en.wikipedia.org/wiki/Negative_likelihood_ratio)                                                           | $[0, ∞)$                    | 📉           | The ratio of false positive rate to true positive rate.                 | Classification |
| [Negative Predictive Value](https://en.wikipedia.org/wiki/Negative_predictive_value)                                                           | $[0, 1]$                    | 📈           | The proportion of predicted negatives which are true negatives.         | Classification |
| [Number of Scores](https://pykeen.readthedocs.io/en/stable/reference/evaluation.html)                                                          | $[0, ∞)$                    | 📈           | The number of scores.                                                   | Classification |
| [Positive Likelihood Ratio](https://en.wikipedia.org/wiki/Positive_likelihood_ratio)                                                           | $[0, ∞)$                    | 📈           | The ratio of true positive rate to false positive rate.                 | Classification |
| [Positive Predictive Value](https://en.wikipedia.org/wiki/Positive_predictive_value)                                                           | $[0, 1]$                    | 📈           | The proportion of predicted positives which are true positive.          | Classification |
| [Prevalence Threshold](https://en.wikipedia.org/wiki/Prevalence_threshold)                                                                     | $[0, ∞)$                    | 📉           | The prevalence threshold.                                               | Classification |
| [Threat Score](https://en.wikipedia.org/wiki/Sensitivity_and_specificity)                                                                      | $[0, 1]$                    | 📈           | The harmonic mean of precision and recall.                              | Classification |
| [True Negative Rate](https://en.wikipedia.org/wiki/Specificity_(tests))                                                                        | $[0, 1]$                    | 📈           | The probability that a truly false triple is predicted negative.        | Classification |
| [True Positive Rate](https://en.wikipedia.org/wiki/Sensitivity_(test))                                                                         | $[0, 1]$                    | 📈           | The probability that a truly positive triple is predicted positive.     | Classification |
| [Adjusted Arithmetic Mean Rank (AAMR)](https://arxiv.org/abs/2002.06914)                                                                       | $[0, 2)$                    | 📉           | The mean over all ranks divided by its expected value.                  | Ranking        |
| [Adjusted Arithmetic Mean Rank Index (AAMRI)](https://arxiv.org/abs/2002.06914)                                                                | $[-1, 1]$                   | 📈           | The re-indexed adjusted mean rank (AAMR)                                | Ranking        |
| [Adjusted Geometric Mean Rank Index (AGMRI)](https://arxiv.org/abs/2002.06914)                                                                 | $(\frac{-E[f]}{1-E[f]}, 1]$ | 📈           | The re-indexed adjusted geometric mean rank (AGMRI)                     | Ranking        |
| [Adjusted Hits at K](https://arxiv.org/abs/2203.07544)                                                                                | $(\frac{-E[f]}{1-E[f]}, 1]$ | 📈           | The re-indexed adjusted hits at K                                       | Ranking        |
| [Adjusted Inverse Harmonic Mean Rank](https://arxiv.org/abs/2203.07544)                                                                        | $(\frac{-E[f]}{1-E[f]}, 1]$ | 📈           | The re-indexed adjusted MRR                                             | Ranking        |
| [Geometric Mean Rank (GMR)](https://arxiv.org/abs/2203.07544)                                                                                | $[1, ∞)$                    | 📉           | The geometric mean over all ranks.                                      | Ranking        |
| [Harmonic Mean Rank (HMR)](https://arxiv.org/abs/2203.07544)                                                                                | $[1, ∞)$                    | 📉           | The harmonic mean over all ranks.                                       | Ranking        |
| [Hits @ K](https://pykeen.readthedocs.io/en/stable/tutorial/understanding_evaluation.html#hits-k)                                              | $[0, 1]$                    | 📈           | The relative frequency of ranks not larger than a given k.              | Ranking        |
| [Inverse Arithmetic Mean Rank (IAMR)](https://arxiv.org/abs/2203.07544)                                                                        | $(0, 1]$                    | 📈           | The inverse of the arithmetic mean over all ranks.                      | Ranking        |
| [Inverse Geometric Mean Rank (IGMR)](https://arxiv.org/abs/2203.07544)                                                                         | $(0, 1]$                    | 📈           | The inverse of the geometric mean over all ranks.                       | Ranking        |
| [Inverse Median Rank](https://arxiv.org/abs/2203.07544)                                                                                | $(0, 1]$                    | 📈           | The inverse of the median over all ranks.                               | Ranking        |
| [Mean Rank (MR)](https://pykeen.readthedocs.io/en/stable/tutorial/understanding_evaluation.html#mean-rank)                                     | $[1, ∞)$                    | 📉           | The arithmetic mean over all ranks.                                     | Ranking        |
| [Mean Reciprocal Rank (MRR)](https://en.wikipedia.org/wiki/Mean_reciprocal_rank)                                                               | $(0, 1]$                    | 📈           | The inverse of the harmonic mean over all ranks.                        | Ranking        |
| [Median Rank](https://arxiv.org/abs/2203.07544)                                                                                | $[1, ∞)$                    | 📉           | The median over all ranks.                                              | Ranking        |
| [z-Geometric Mean Rank (zGMR)](https://arxiv.org/abs/2203.07544)                                                                               | $(-∞, ∞)$                   | 📈           | The z-scored geometric mean rank                                        | Ranking        |
| [z-Hits at K](https://arxiv.org/abs/2203.07544)                                                                                | $(-∞, ∞)$                   | 📈           | The z-scored hits at K                                                  | Ranking        |
| [z-Mean Rank (zMR)](https://arxiv.org/abs/2203.07544)                                                                                | $(-∞, ∞)$                   | 📈           | The z-scored mean rank                                                  | Ranking        |
| [z-Mean Reciprocal Rank (zMRR)](https://arxiv.org/abs/2203.07544)                                                                              | $(-∞, ∞)$                   | 📈           | The z-scored mean reciprocal rank                                       | Ranking        |

### Trackers

The following 8 trackers are implemented in PyKEEN.

| Name        | Reference                                                                                | Description                                               |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| console     | [`pykeen.trackers.ConsoleResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.ConsoleResultTracker.html)         | A class that directly prints to console.                  |
| csv         | [`pykeen.trackers.CSVResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.CSVResultTracker.html)                 | Tracking results to a CSV file.                           |
| json        | [`pykeen.trackers.JSONResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.JSONResultTracker.html)               | Tracking results to a JSON lines file.                    |
| mlflow      | [`pykeen.trackers.MLFlowResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.MLFlowResultTracker.html)           | A tracker for MLflow.                                     |
| neptune     | [`pykeen.trackers.NeptuneResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.NeptuneResultTracker.html)         | A tracker for Neptune.ai.                                 |
| python      | [`pykeen.trackers.PythonResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.PythonResultTracker.html)           | A tracker which stores everything in Python dictionaries. |
| tensorboard | [`pykeen.trackers.TensorBoardResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.TensorBoardResultTracker.html) | A tracker for TensorBoard.                                |
| wandb       | [`pykeen.trackers.WANDBResultTracker`](https://pykeen.readthedocs.io/en/latest/api/pykeen.trackers.WANDBResultTracker.html)             | A tracker for Weights and Biases.                         |

## Experimentation

### Reproduction

PyKEEN includes a set of curated experimental settings for reproducing past landmark
experiments. They can be accessed and run like:

```shell
pykeen experiments reproduce tucker balazevic2019 fb15k
```

Where the three arguments are the model name, the reference, and the dataset.
The output directory can be optionally set with `-d`.

### Ablation

PyKEEN includes the ability to specify ablation studies using the
hyper-parameter optimization module. They can be run like:

```shell
pykeen experiments ablation ~/path/to/config.json
```

### Large-scale Reproducibility and Benchmarking Study

We used PyKEEN to perform a large-scale reproducibility and benchmarking study which are described in
[our article](https://doi.org/10.1109/TPAMI.2021.3124805):

```bibtex
@article{ali2020benchmarking,
  author={Ali, Mehdi and Berrendorf, Max and Hoyt, Charles Tapley and Vermue, Laurent and Galkin, Mikhail and Sharifzadeh, Sahand and Fischer, Asja and Tresp, Volker and Lehmann, Jens},
  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence},
  title={Bringing Light Into the Dark: A Large-scale Evaluation of Knowledge Graph Embedding Models under a Unified Framework},
  year={2021},
  pages={1-1},
  doi={10.1109/TPAMI.2021.3124805}}
}
```

We have made all code, experimental configurations, results, and analyses that lead to our interpretations available
at https://github.com/pykeen/benchmarking.

## Contributing

Contributions, whether filing an issue, making a pull request, or forking, are appreciated.
See [CONTRIBUTING.md](/CONTRIBUTING.md) for more information on getting involved.

If you have questions, please use the GitHub discussions feature at
https://github.com/pykeen/pykeen/discussions/new.

## Acknowledgements

### Supporters

This project has been supported by several organizations (in alphabetical order):

- [Bayer](https://www.bayer.com/)
- [CoronaWhy](https://www.coronawhy.org/)
- [Enveda Biosciences](https://www.envedabio.com/)
- [Fraunhofer Institute for Algorithms and Scientific Computing](https://www.scai.fraunhofer.de)
- [Fraunhofer Institute for Intelligent Analysis and Information Systems](https://www.iais.fraunhofer.de)
- [Fraunhofer Center for Machine Learning](https://www.cit.fraunhofer.de/de/zentren/maschinelles-lernen.html)
- [Harvard Program in Therapeutic Science - Laboratory of Systems Pharmacology](https://hits.harvard.edu/the-program/laboratory-of-systems-pharmacology/)
- [Ludwig-Maximilians-Universität München](https://www.en.uni-muenchen.de/index.html)
- [Munich Center for Machine Learning (MCML)](https://mcml.ai/)
- [Siemens](https://new.siemens.com/global/en.html)
- [Smart Data Analytics Research Group (University of Bonn & Fraunhofer IAIS)](https://sda.tech)
- [Technical University of Denmark - DTU Compute - Section for Cognitive Systems](https://www.compute.dtu.dk/english/research/research-sections/cogsys)
- [Technical University of Denmark - DTU Compute - Section for Statistics and Data Analysis](https://www.compute.dtu.dk/english/research/research-sections/stat)
- [University of Bonn](https://www.uni-bonn.de/)

### Funding

The development of PyKEEN has been funded by the following grants:

| Funding Body                                             | Program                                                                                | Grant           |
|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------|
| DARPA                                                    | [Young Faculty Award (PI: Benjamin Gyori)](https://indralab.github.io/#projects)                                              | W911NF2010255   |
| DARPA                                                    | [Automating Scientific Knowledge Extraction (ASKE)](https://www.darpa.mil/program/automating-scientific-knowledge-extraction) | HR00111990009   |
| German Federal Ministry of Education and Research (BMBF) | [Maschinelles Lernen mit Wissensgraphen (MLWin)](https://mlwin.de)                                                            | 01IS18050D      |
| German Federal Ministry of Education and Research (BMBF) | [Munich Center for Machine Learning (MCML)](https://mcml.ai)                                                                  | 01IS18036A      |
| Innovation Fund Denmark (Innovationsfonden)              | [Danish Center for Big Data Analytics driven Innovation (DABAI)](https://dabai.dk)                                            | Grand Solutions |

### Logo

The PyKEEN logo was designed by [Carina Steinborn](https://www.xing.com/profile/Carina_Steinborn2)

## Citation

If you have found PyKEEN useful in your work, please consider citing
[our article](http://jmlr.org/papers/v22/20-825.html):

```bibtex
@article{ali2021pykeen,
    author = {Ali, Mehdi and Berrendorf, Max and Hoyt, Charles Tapley and Vermue, Laurent and Sharifzadeh, Sahand and Tresp, Volker and Lehmann, Jens},
    journal = {Journal of Machine Learning Research},
    number = {82},
    pages = {1--6},
    title = {{PyKEEN 1.0: A Python Library for Training and Evaluating Knowledge Graph Embeddings}},
    url = {http://jmlr.org/papers/v22/20-825.html},
    volume = {22},
    year = {2021}
}
```


.. image:: https://img.shields.io/pypi/v/irc.svg
   :target: https://pypi.org/project/irc

.. image:: https://img.shields.io/pypi/pyversions/irc.svg

.. image:: https://github.com/jaraco/irc/actions/workflows/main.yml/badge.svg
   :target: https://github.com/jaraco/irc/actions?query=workflow%3A%22tests%22
   :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff

.. image:: https://readthedocs.org/projects/irc/badge/?version=latest
   :target: https://irc.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2024-informational
   :target: https://blog.jaraco.com/skeleton

.. image:: https://badges.gitter.im/jaraco/irc.svg
   :alt: Join the chat at https://gitter.im/jaraco/irc
   :target: https://gitter.im/jaraco/irc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

.. image:: https://tidelift.com/badges/github/jaraco/irc
   :target: https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=readme

Full-featured Python IRC library for Python.

- `Project home <https://github.com/jaraco/irc>`_
- `Docs <https://python-irc.readthedocs.io/>`_
- `History <https://python-irc.readthedocs.io/en/latest/history.html>`_

Overview
========

This library provides a low-level implementation of the IRC protocol for
Python.  It provides an event-driven IRC client framework.  It has
a fairly thorough support for the basic IRC protocol, CTCP, and DCC
connections.

In order to understand how to make an IRC client, it's best to read up first
on the `IRC specifications
<http://web.archive.org/web/20160628193730/http://www.irchelp.org/irchelp/rfc/>`_.

Client Features
===============

The main features of the IRC client framework are:

* Abstraction of the IRC protocol.
* Handles multiple simultaneous IRC server connections.
* Handles server PONGing transparently.
* Messages to the IRC server are done by calling methods on an IRC
  connection object.
* Messages from an IRC server triggers events, which can be caught
  by event handlers.
* Multiple options for reading from and writing to an IRC server:
  you can use sockets in an internal ``select()`` loop OR use
  Python3's asyncio event loop
* Functions can be registered to execute at specified times by the
  event-loop.
* Decodes CTCP tagging correctly (hopefully); I haven't seen any
  other IRC client implementation that handles the CTCP
  specification subtleties.
* A kind of simple, single-server, object-oriented IRC client class
  that dispatches events to instance methods is included.
* DCC connection support.

Current limitations:

* The IRC protocol shines through the abstraction a bit too much.
* Data is not written asynchronously to the server (and DCC peers),
  i.e. the ``write()`` may block if the TCP buffers are stuffed.
* Like most projects, documentation is lacking ...
* DCC is not currently implemented in the asyncio-based version

Unfortunately, this library isn't as well-documented as I would like
it to be.  I think the best way to get started is to read and
understand the example program ``irccat``, which is included in the
distribution.

The following modules might be of interest:

* ``irc.client``

  The library itself.  Read the code along with comments and
  docstrings to get a grip of what it does.  Use it at your own risk
  and read the source, Luke!

* ``irc.client_aio``

  All the functionality of the above library, but utilizing
  Python 3's native asyncio library for the core event loop.
  Interface/API is otherwise functionally identical to the classes
  in ``irc.client``

* ``irc.bot``

  An IRC bot implementation.

* ``irc.server``

  A basic IRC server implementation. Suitable for testing, but not
  intended as a production service.

  Invoke the server with ``python -m irc.server``.

Examples
========

Example scripts in the scripts directory:

* ``irccat``

  A simple example of how to use the IRC client.  ``irccat`` reads
  text from stdin and writes it to a specified user or channel on
  an IRC server.

* ``irccat2``

  The same as above, but using the ``SimpleIRCClient`` class.

* ``aio_irccat``

  Same as above, but uses the asyncio-based event loop in
  ``AioReactor`` instead of the ``select()`` based ``Reactor``.

* ``aio_irccat2``

  Same as above, but using the ``AioSimpleIRCClient`` class

* ``servermap``

  Another simple example.  ``servermap`` connects to an IRC server,
  finds out what other IRC servers there are in the net and prints
  a tree-like map of their interconnections.

* ``testbot``

  An example bot that uses the ``SingleServerIRCBot`` class from
  ``irc.bot``.  The bot enters a channel and listens for commands in
  private messages or channel traffic.  It also accepts DCC
  invitations and echos back sent DCC chat messages.

* ``dccreceive``

  Receives a file over DCC.

* ``dccsend``

  Sends a file over DCC.

NOTE: If you're running one of the examples on a unix command line, you need
to escape the ``#`` symbol in the channel. For example, use ``\\#test`` or
``"#test"`` instead of ``#test``.

Scheduling Events
=================

The library includes a default event Scheduler as
``irc.schedule.DefaultScheduler``,
but this scheduler can be replaced with any other scheduler. For example,
to use the `schedule <https://pypi.org/project/schedule>`_ package,
include it
in your dependencies and install it into the IRC library as so:

    class ScheduleScheduler(irc.schedule.IScheduler):
        def execute_every(self, period, func):
            schedule.every(period).do(func)

        def execute_at(self, when, func):
            schedule.at(when).do(func)

        def execute_after(self, delay, func):
            raise NotImplementedError("Not supported")

        def run_pending(self):
            schedule.run_pending()

    irc.client.Reactor.scheduler_class = ScheduleScheduler

Decoding Input
==============

By default, the IRC library attempts to decode all incoming streams as
UTF-8, even though the IRC spec stipulates that no specific encoding can be
expected. Since assuming UTF-8 is not reasonable in the general case, the IRC
library provides options to customize decoding of input by customizing the
``ServerConnection`` class. The ``buffer_class`` attribute on the
``ServerConnection`` determines which class is used for buffering lines from the
input stream, using the ``buffer`` module in `jaraco.stream
<https://pypi.python.org/pypi/jaraco.stream>`_. By default it is
``buffer.DecodingLineBuffer``, but may be
re-assigned with another class, following the interface of ``buffer.LineBuffer``.
The ``buffer_class`` attribute may be assigned for all instances of
``ServerConnection`` by overriding the class attribute.

For example:

.. code:: python

    from jaraco.stream import buffer

    irc.client.ServerConnection.buffer_class = buffer.LenientDecodingLineBuffer

The ``LenientDecodingLineBuffer`` attempts UTF-8 but falls back to latin-1, which
will avoid ``UnicodeDecodeError`` in all cases (but may produce unexpected
behavior if an IRC user is using another encoding).

The buffer may be overridden on a per-instance basis (as long as it's
overridden before the connection is established):

.. code:: python

    server = irc.client.Reactor().server()
    server.buffer_class = buffer.LenientDecodingLineBuffer
    server.connect()

Alternatively, some clients may still want to decode the input using a
different encoding. To decode all input as latin-1 (which decodes any input),
use the following:

.. code:: python

    irc.client.ServerConnection.buffer_class.encoding = "latin-1"

Or decode to UTF-8, but use a replacement character for unrecognized byte
sequences:

.. code:: python

    irc.client.ServerConnection.buffer_class.errors = "replace"

Or, to simply ignore all input that cannot be decoded:

.. code:: python

    class IgnoreErrorsBuffer(buffer.DecodingLineBuffer):
        def handle_exception(self):
            pass

    irc.client.ServerConnection.buffer_class = IgnoreErrorsBuffer

The library requires text for message
processing, so a decoding buffer must be used. Clients
must use one of the above techniques for decoding input to text.

Notes and Contact Info
======================

Enjoy.

Maintainer:
Jason R. Coombs <jaraco@jaraco.com>

Original Author:
Joel Rosdahl <joel@rosdahl.net>

Copyright © 1999-2002 Joel Rosdahl
Copyright © 2011-2016 Jason R. Coombs
Copyright © 2009 Ferry Boender

For Enterprise
==============

Available as part of the Tidelift Subscription.

This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.

`Learn more <https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=github>`_.