

whatlies.embedding.Embedding

This object represents a word embedding. It contains a vector and a name.

Parameters

Name	Type	Description	Default
name		the name of this embedding, includes operations	required
vector		the numerical representation of the embedding	required
orig		original name of embedding, is left alone	None

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo | bar
foo - bar + bar

ndim: (property, readonly)

Return the dimension of embedding vector.

norm: (property, readonly)

Gives the norm of the vector of the embedding

__add__(self, other)

Show source code in whatlies/embedding.py

    def __add__(self, other) -> "Embedding":
        """
        Add two embeddings together.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo + bar
        ```
        """
        copied = deepcopy(self)
        copied.name = f"({self.name} + {other.name})"
        copied.vector = self.vector + other.vector
        return copied

Add two embeddings together.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo + bar

__gt__(self, other)

Show source code in whatlies/embedding.py

    def __gt__(self, other):
        """
        Measures the size of one embedding to another one.

        The `>` is meant to indicate the "unto" operation.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo > bar
        ```
        """
        return (self.vector.dot(other.vector)) / (other.vector.dot(other.vector))

Measures the size of one embedding to another one.

The > is meant to indicate the "unto" operation.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo > bar

__neg__(self)

Show source code in whatlies/embedding.py

    def __neg__(self):
        """
        Negate an embedding.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])

        assert (- foo).vector == - foo.vector
        ```
        """
        copied = deepcopy(self)
        copied.name = f"(-{self.name})"
        copied.vector = -self.vector
        return copied

Negate an embedding.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])

assert (- foo).vector == - foo.vector

__or__(self, other)

Show source code in whatlies/embedding.py

    def __or__(self, other):
        """
        Makes one embedding orthogonal to the other one.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo | bar
        ```
        """
        copied = deepcopy(self)
        copied.name = f"({self.name} | {other.name})"
        copied.vector = self.vector - (self >> other).vector
        return copied

Makes one embedding orthogonal to the other one.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo | bar

__rshift__(self, other)

Show source code in whatlies/embedding.py

    def __rshift__(self, other):
        """
        Maps an embedding unto another one.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo >> bar
        ```
        """
        copied = deepcopy(self)
        new_vec = (
            (self.vector.dot(other.vector))
            / (other.vector.dot(other.vector))
            * other.vector
        )
        copied.name = f"({self.name} >> {other.name})"
        copied.vector = new_vec
        return copied

Maps an embedding unto another one.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo >> bar

__sub__(self, other)

Show source code in whatlies/embedding.py

    def __sub__(self, other):
        """
        Subtract two embeddings.

        Usage:

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo - bar
        ```
        """
        copied = deepcopy(self)
        copied.name = f"({self.name} - {other.name})"
        copied.vector = self.vector - other.vector
        return copied

Subtract two embeddings.

Usage:

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo - bar

copy(self)

Show source code in whatlies/embedding.py

    def copy(self):
        """
        Returns a deepcopy of the embdding.
        """
        return deepcopy(self)

Returns a deepcopy of the embdding.

distance(self, other, metric='cosine')

Show source code in whatlies/embedding.py

    def distance(self, other, metric: str = "cosine"):
        """
        Calculates the vector distance between two embeddings.

        Arguments:
            other: the other embedding you're comparing against
            metric: the distance metric to use, the list of valid options can be found [here](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise_distances.html)

        **Usage**

        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [1.0, 0.0])
        bar = Embedding("bar", [0.0, 0.5])

        foo.distance(bar)
        foo.distance(bar, metric="euclidean")
        foo.distance(bar, metric="cosine")
        ```
        """
        return pairwise_distances([self.vector], [other.vector], metric=metric)[0][0]

Calculates the vector distance between two embeddings.

Parameters

Name	Type	Description	Default
other		the other embedding you're comparing against	required
metric	str	the distance metric to use, the list of valid options can be found here	'cosine'

Usage

from whatlies.embedding import Embedding

foo = Embedding("foo", [1.0, 0.0])
bar = Embedding("bar", [0.0, 0.5])

foo.distance(bar)
foo.distance(bar, metric="euclidean")
foo.distance(bar, metric="cosine")

plot(self, kind='arrow', x_axis=0, y_axis=1, axis_metric=None, x_label=None, y_label=None, title=None, color=None, show_ops=False, annot=True, axis_option=None)

Show source code in whatlies/embedding.py

    def plot(
        self,
        kind: str = "arrow",
        x_axis: Union[int, "Embedding"] = 0,
        y_axis: Union[int, "Embedding"] = 1,
        axis_metric: Optional[Union[str, Callable, Sequence]] = None,
        x_label: Optional[str] = None,
        y_label: Optional[str] = None,
        title: Optional[str] = None,
        color: str = None,
        show_ops: bool = False,
        annot: bool = True,
        axis_option: Optional[str] = None,
    ):
        """
        Handles the logic to perform a 2d plot in matplotlib.

        Arguments:
            kind: what kind of plot to make, can be `scatter`, `arrow` or `text`
            x_axis: the x-axis to be used, must be given when dim > 2; if an integer, the corresponding
                dimension of embedding is used.
            y_axis: the y-axis to be used, must be given when dim > 2; if an integer, the corresponding
                dimension of embedding is used.
            axis_metric: the metric used to project an embedding on the axes; only used when the corresponding
                axis (i.e. `x_axis` or `y_axis`) is an `Embedding` instance. It could be a string
                (`'cosine_similarity'`, `'cosine_distance'` or `'euclidean'`), or a callable that takes two vectors as input
                and returns a scalar value as output. To set different metrics for x- and y-axis, a list or a tuple of
                two elements could be given. By default (`None`), normalized scalar projection (i.e. `>` operator) is used.
            x_label: an optional label used for x-axis; if not given, it is set based on `x_axis` value.
            y_label: an optional label used for y-axis; if not given, it is set based on `y_axis` value.
            title: an optional title for the plot.
            color: the color of the dots
            show_ops: setting to also show the applied operations, only works for `text`
            annot: should the points be annotated
            axis_option: a string which is passed as `option` argument to `matplotlib.pyplot.axis` in order to control
                axis properties (e.g. using `'equal'` make circles shown circular in the plot). This might be useful
                for preserving geometric relationships (e.g. orthogonality) in the generated plot. See `matplotlib.pyplot.axis`
                [documentation](https://matplotlib.org/3.1.0/api/_as_gen/matplotlib.pyplot.axis.html#matplotlib-pyplot-axis)
                for possible values and their description.

        **Usage**
        ```python
        from whatlies.embedding import Embedding

        foo = Embedding("foo", [0.1, 0.3])
        bar = Embedding("bar", [0.7, 0.2])

        foo.plot(kind="arrow", annot=True)
        bar.plot(kind="arrow", annot=True)
        ```
        """
        if isinstance(axis_metric, (list, tuple)):
            x_axis_metric = axis_metric[0]
            y_axis_metric = axis_metric[1]
        else:
            x_axis_metric = axis_metric
            y_axis_metric = axis_metric
        x_val, x_lab = self._get_plot_axis_value_and_label(
            x_axis, x_axis_metric, dir="x"
        )
        y_val, y_lab = self._get_plot_axis_value_and_label(
            y_axis, y_axis_metric, dir="y"
        )
        x_label = x_lab if x_label is None else x_label
        y_label = y_lab if y_label is None else y_label
        emb_plot = Embedding(name=self.name, vector=[x_val, y_val], orig=self.orig)
        handle_2d_plot(
            emb_plot,
            kind=kind,
            color=color,
            xlabel=x_label,
            ylabel=y_label,
            title=title,
            show_operations=show_ops,
            annot=annot,
            axis_option=axis_option,
        )
        return self

Handles the logic to perform a 2d plot in matplotlib.

Parameters

Name	Type	Description	Default
kind	str	what kind of plot to make, can be scatter, arrow or text	'arrow'
x_axis	Union[int, ForwardRef('Embedding')]	the x-axis to be used, must be given when dim > 2; if an integer, the corresponding dimension of embedding is used.	0
y_axis	Union[int, ForwardRef('Embedding')]	the y-axis to be used, must be given when dim > 2; if an integer, the corresponding dimension of embedding is used.	1
axis_metric	Optional[Union[str, Callable, Sequence]]	the metric used to project an embedding on the axes; only used when the corresponding axis (i.e. x_axis or y_axis) is an Embedding instance. It could be a string ('cosine_similarity', 'cosine_distance' or 'euclidean'), or a callable that takes two vectors as input and returns a scalar value as output. To set different metrics for x- and y-axis, a list or a tuple of two elements could be given. By default (None), normalized scalar projection (i.e. > operator) is used.	None
x_label	Optional[str]	an optional label used for x-axis; if not given, it is set based on x_axis value.	None
y_label	Optional[str]	an optional label used for y-axis; if not given, it is set based on y_axis value.	None
title	Optional[str]	an optional title for the plot.	None
color	str	the color of the dots	None
show_ops	bool	setting to also show the applied operations, only works for text	False
annot	bool	should the points be annotated	True
axis_option	Optional[str]	a string which is passed as option argument to matplotlib.pyplot.axis in order to control axis properties (e.g. using 'equal' make circles shown circular in the plot). This might be useful for preserving geometric relationships (e.g. orthogonality) in the generated plot. See matplotlib.pyplot.axis documentation for possible values and their description.	None

Usage

from whatlies.embedding import Embedding

foo = Embedding("foo", [0.1, 0.3])
bar = Embedding("bar", [0.7, 0.2])

foo.plot(kind="arrow", annot=True)
bar.plot(kind="arrow", annot=True)