diff --git a/docs/notebooks/Evaluation_of_word_embeddings.ipynb b/docs/notebooks/Evaluation_of_word_embeddings.ipynb
new file mode 100644
index 0000000000..0d9b323f7d
--- /dev/null
+++ b/docs/notebooks/Evaluation_of_word_embeddings.ipynb
@@ -0,0 +1,406 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "7da5ed4a",
+ "metadata": {},
+ "source": [
+ "# How to evaluate word embedding models\n",
+ "\n",
+ "The existing state-of-the-art approaches for word embedding evaluation can be divided into two major classes: _intrinsic_ vs _extrinsic_ evaluation.\n",
+ "\n",
+ "_Extrinsic metrics_ perform the evaluation by using embeddings as features for specific downstream tasks. For instance, question deduplication, Part-of-Speech (POS) Tagging, Language Modelling, and Named Entity Recognition (NER). As a drawback, extrinsic metrics are:\n",
+ "1. computationally heavy;\n",
+ "2. have high complexity of creating gold standard datasets for downstream tasks;\n",
+ "3. have a lack of performance consistency over different tasks.\n",
+ "\n",
+ "_Intrinsic metrics_ evaluate the quality of a vector model per se, independently from specific downstream tasks. They measure syntactic or semantic relationships between words directly, typically using a gold benchmark of semantic similarity between pair of words. \n",
+ "The gold benchmark can be obtained directly getting human judgements or using automated semantic similarity measures.\n",
+ "\n",
+ "Some of the limitations of human annotated benchmarks are:\n",
+ "1. suffering from word sense ambiguity(faced by a human tester) and subjectivity;\n",
+ "2. facing difficulties in finding significant differences between models due to the small size and low inter-annotator agreement of existing datasets;\n",
+ "3. need for constructing judgement datasets for each language and each domain, given that word meanings can change a lot across different domains.\n",
+ "Moreover, the update and the upscale of handcrafted resources like the similarity human scores are costly, time expensive, and error-prone. \n",
+ "\n",
+ "A well-known __intrinsic evaluation method__ is Semantic Relatedness (or Similarity) (see [Baroni et al.](https://aclanthology.org/P14-1023.pdf), [Schnabel et al.](https://aclanthology.org/D15-1036.pdf)\n",
+ "), which evaluates the performance of a vector model by the correlation between the cosine similarity between pairs of word vectors and the semantic relatedness (or similarity) between them in the gold benchmark.\n",
+ "\n",
+ "## Intrinsic evaluations\n",
+ "\n",
+ "Gensim provides the possibility to evaluate word embedding models through two of the most used intrinsic evaluation tasks: semantic similarity and word analogy.\n",
+ "\n",
+ "You can evaluate your models on those tasks using `evaluate_word_pairs(pairs)` and `evaluate_word_analogies(analogies)`, specifying the benchmark you want to use as the first argument of the function.\n",
+ "\n",
+ "### How to evaluate word embedding models with taxonomy‐based semantic similarity measures\n",
+ "\n",
+ "The evaluation based on taxonomy‐based semantic similarity measures is another type of intrinsic evaluation, and it exploit the information encoded in an existing taxonomy to build a benchmark for the evaluation of word embeddings.\n",
+ "\n",
+ "To perform this type of evaluation you can use the benchmark HSS4570.tsv (you can find it at test/test_data/HSS4570.tsv) through the Gensim function `evaluate_word_pairs()`, which returns:\n",
+ "\n",
+ "* the Pearson correlation coefficient with 2-tailed p-value;\n",
+ "\n",
+ "* the Spearman rank-order correlation coefficient between the similarities from the dataset and the similarities produced by the model itself, with 2-tailed p-value."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "b765dbcd",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from gensim.models import KeyedVectors\n",
+ "path_to_model = 'models/ft_vectors_0_10_50_5.txt'\n",
+ "model = KeyedVectors.load_word2vec_format(path_to_model, binary=False)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "8df874c1",
+ "metadata": {
+ "scrolled": true
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "((0.42422276164431727, 4.739561944305236e-193),\n",
+ " SpearmanrResult(correlation=0.4326345056769725, pvalue=1.508555569557493e-201),\n",
+ " 3.063457330415755)"
+ ]
+ },
+ "execution_count": 2,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import pkgutil\n",
+ "similarities = model.evaluate_word_pairs('benchmark/HSS4570.tsv', delimiter='\\t')\n",
+ "similarities"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "0ad743a6",
+ "metadata": {},
+ "source": [
+ "To perform this evaluation you can also use the library `TaxoSS` to create your benchmark using the taxonomy of your choice that better suits the topic of your work, to select the word embedding model that best encodes the taxonomic relationships between the concepts in the taxonomy.\n",
+ "\n",
+ "You can compute the semantic similarity in the following way:\n",
+ "\n",
+ "1. create a list of pairs of words for comparison, for example:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "1c7e24d4",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[['cat', 'dog'], ['bird', 'fish'], ['mammal', 'vertebrate']]"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "w1 = ['cat', 'bird', 'mammal']\n",
+ "w2 = ['dog', 'fish', 'vertebrate']\n",
+ "words = [[x, y] for x, y in zip(w1, w2)]\n",
+ "words"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c3ec3fd9",
+ "metadata": {},
+ "source": [
+ "2. for each pair compute the similarity between the words:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "23fd5026",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[2.5578320203297156, 1.4267224907237086, 1.4852139609136645]"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from TaxoSS.functions import semantic_similarity\n",
+ "hss = []\n",
+ "for w in words:\n",
+ " hss.append(semantic_similarity(w[0], w[1], 'hss'))\n",
+ "hss"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "372f68bf",
+ "metadata": {},
+ "source": [
+ "3. create your benchmark as a dataframe:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "b15c13f3",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " word1 | \n",
+ " word2 | \n",
+ " hss | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " cat | \n",
+ " dog | \n",
+ " 2.557832 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " bird | \n",
+ " fish | \n",
+ " 1.426722 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " mammal | \n",
+ " vertebrate | \n",
+ " 1.485214 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " word1 | \n",
+ " word2 | \n",
+ " hss | \n",
+ " cosine_similarity | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " cat | \n",
+ " dog | \n",
+ " 2.557832 | \n",
+ " 0.878396 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " bird | \n",
+ " fish | \n",
+ " 1.426722 | \n",
+ " 0.709674 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " mammal | \n",
+ " vertebrate | \n",
+ " 1.485214 | \n",
+ " 0.784841 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "