Update docs

[dobraczka]

• Explain the new possibilities enabled by class-resolver
• Incorporate architecture picture with explanation
• link to readthedocs in readme
• Give new examples (including for single-source)

[cthoyt]

It would be great to make an example where Kiez is applied to the embeddings coming from PyKEEN. This tutorial shows how to get embeddings out after training. The following example shows it for TransE:

from pykeen.pipeline import pipeline

results = pipeline(
    model='TransE',
    dataset='Nations',
    epochs=1,  # change this to ~25 for real usage on Nations
)

entity_embeddings   = results.model.entity_representations[0]()    # is torch.Size([14, 50])
relation_embeddings = results.model.relation_representations[0]()  # is torch.Size([55, 50])

These are torch tensors, which can be converted to numpy ndarrays of the same dimensions with

entity_embeddings   = results.model.entity_representations[0]().detach().numpy()
relation_embeddings = results.model.relation_representations[0]().detach().numpy()

A kiez API function could probably do some logic to accept either a pipeline result, model, or pykeen embedding, like:

from pykeen.models import Model
from pykeen.pipeline import PipelineResult
from pykeen.nn import Embedding
from typing import Union

def from_pykeen(model: Union[Model, PipelineResult, Embedding]):
    if isinstance(model, Embedding):
        representation = model
    elif isinstance(model, Model):
        representation = model.entity_representations[0]
    elif isinstance(model, PipelineResult):
        representation = model.model.entity_representations[0]
    else:
        raise TypeError
    arr = representation().detach().numpy()
    ...

[dobraczka]

The main purpose of Kiez (for now) is to use it for entity resolution, i.e. I have entity embeddings of two datasources (source & target) and want to find the nearest neighbors of source entities in the target space.
However using it to find nearest neighbors within a single source is technically already possible, e.g.

from kiez import Kiez
source = ... # get embeddings from somewhere
k_inst = Kiez()
k_inst.fit(source, source)
k_inst.kneighbors()

I want to adapt the API to make this use-case more intuitively available. In the course of that I would add your mentioned example in the doc and implement the convenience function for pykeen.

[cthoyt]

Oh I see. There are a few pykeen datasets that are constructed such that they contain 2 knowledge graphs with support edges linking the same entity in each (like a english and german version of the same graph, with different completeness) but none of them are directly accessible to give a really good example at the moment

[dobraczka]

I will close this and we can continue to talk about use cases in #11

[cthoyt]

@dobraczka great! Looking forward to it.