First commit

.gitattributes

@@ -0,0 +1,4 @@
+data/100k_en_embedding.vec filter=lfs diff=lfs merge=lfs -text
+data/100k_es_embedding.vec filter=lfs diff=lfs merge=lfs -text
+data/full_vocab_v6.zip filter=lfs diff=lfs merge=lfs -text
+data/mini_vocab_v6.zip filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.env
+logs/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2023 Fundación Vía Libre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,13 @@
+---
+title: Edia Full En
+emoji: 👁
+colorFrom: purple
+colorTo: gray
+sdk: gradio
+sdk_version: 3.16.2
+app_file: app.py
+pinned: false
+license: mit
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,99 @@
+# --- Imports libs ---
+import gradio as gr
+import pandas as pd
+import configparser
+
+
+# --- Imports modules ---
+from modules.model_embbeding import Embedding
+from modules.module_vocabulary import Vocabulary
+from modules.module_languageModel import LanguageModel
+
+
+# --- Imports interfaces ---
+from interfaces.interface_WordExplorer import interface as interface_wordExplorer
+from interfaces.interface_BiasWordExplorer import interface as interface_biasWordExplorer
+from interfaces.interface_data import interface as interface_data
+from interfaces.interface_biasPhrase import interface as interface_biasPhrase
+from interfaces.interface_crowsPairs import interface as interface_crowsPairs
+
+
+# --- Tool config ---
+cfg = configparser.ConfigParser()
+cfg.read('tool.cfg')
+
+LANGUAGE            = cfg['INTERFACE']['language']
+EMBEDDINGS_PATH     = cfg['WORD_EXPLORER']['embeddings_path']
+NN_METHOD           = cfg['WORD_EXPLORER']['nn_method']
+MAX_NEIGHBORS       = int(cfg['WORD_EXPLORER']['max_neighbors'])
+CONTEXTS_DATASET    = cfg['DATA']['contexts_dataset']
+VOCABULARY_SUBSET   = cfg['DATA']['vocabulary_subset']
+AVAILABLE_WORDCLOUD = cfg['DATA'].getboolean('available_wordcloud')
+LANGUAGE_MODEL      = cfg['LMODEL']['language_model']
+AVAILABLE_LOGS      = cfg['LOGS'].getboolean('available_logs')
+
+
+# --- Init classes ---
+embedding = Embedding(
+    path=EMBEDDINGS_PATH,
+    limit=100000,
+    randomizedPCA=False,
+    max_neighbors=MAX_NEIGHBORS,
+    nn_method=NN_METHOD
+)
+vocabulary = Vocabulary(
+    subset_name=VOCABULARY_SUBSET
+)
+beto_lm = LanguageModel(
+    model_name=LANGUAGE_MODEL
+)
+labels = pd.read_json(f"language/{LANGUAGE}.json")["app"]
+
+
+# --- Main App ---
+INTERFACE_LIST = [
+    interface_biasWordExplorer(
+        embedding=embedding,
+        available_logs=AVAILABLE_LOGS,
+        lang=LANGUAGE),
+    interface_wordExplorer(
+        embedding=embedding,
+        available_logs=AVAILABLE_LOGS,
+        max_neighbors=MAX_NEIGHBORS,
+        lang=LANGUAGE),
+    interface_data(
+        vocabulary=vocabulary,
+        contexts=CONTEXTS_DATASET,
+        available_logs=AVAILABLE_LOGS,
+        available_wordcloud=AVAILABLE_WORDCLOUD,
+        lang=LANGUAGE),
+    interface_biasPhrase(
+        language_model=beto_lm,
+        available_logs=AVAILABLE_LOGS,
+        lang=LANGUAGE),
+    interface_crowsPairs(
+        language_model=beto_lm,
+        available_logs=AVAILABLE_LOGS,
+        lang=LANGUAGE),
+]
+
+TAB_NAMES = [
+    labels["biasWordExplorer"],
+    labels["wordExplorer"],
+    labels["dataExplorer"],
+    labels["phraseExplorer"],
+    labels["crowsPairsExplorer"]
+]
+
+if LANGUAGE != 'es':
+    # Skip data tab when using other than spanish language
+    INTERFACE_LIST = INTERFACE_LIST[:2] + INTERFACE_LIST[3:]
+    TAB_NAMES = TAB_NAMES[:2] + TAB_NAMES[3:]
+
+iface = gr.TabbedInterface(
+    interface_list= INTERFACE_LIST,
+    tab_names=TAB_NAMES
+)
+
+iface.queue(concurrency_count=8)
+iface.launch(debug=False)

data/100k_en_embedding.vec

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dff578909f245428f8e6a5e383a4fe78201e57f627e88ede04d846d03d138aa9
+size 365999732

data/100k_es_embedding.vec

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:062e67c948fc14de8c9327868293c76a6d6f536f62d6df3d8afbf6d62c4b9cc1
+size 262330934

data/full_vocab_v6.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:478fa3e953fbc65746681b1b9770e726f0cd28a0a9992735c00001a09d04b42a
+size 205538236

data/mini_vocab_v6.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e1ac44f7478778f4c08bb57dc6aa79ededc89654b404320d0017586e578768a9
+size 93612

examples/.gitignore

@@ -0,0 +1 @@
+__pycache__

examples/examples_en.py

@@ -0,0 +1,55 @@
+fem_words = 'woman,girl,her,mother,daughter,feminine'
+masc_words = 'man,boy,him,father,son,masculine'
+young_words = 'young,immature,kid,child'
+old_words = 'old,mature,elderly,adult'
+diagnose_words = 'education,cook,wash,sports,clothes,fight,nurse,win,leader,saw,nurse,surgeon,king,queen'
+
+positive_money_words = 'save,economize,administer,manage,business,benefits'
+negative_money_words = 'waste,squander'
+diagnose_money = 'german,australian,argentinian,millionaire,rich,poor'
+
+lazy_words = 'lazy, sluggish, slacker'
+active_words = 'active, effort , worker'
+
+examples1_explorar_sesgo_en_palabras = [
+    [fem_words, masc_words, diagnose_words],
+    [old_words, young_words, diagnose_words],
+    [positive_money_words, negative_money_words, diagnose_money],
+    [lazy_words, active_words, diagnose_money]
+]
+
+examples2_explorar_sesgo_en_palabras = [
+    [fem_words, masc_words, young_words, old_words, diagnose_words],
+    [lazy_words, active_words, positive_money_words, negative_money_words,diagnose_money],
+]
+
+
+examples_explorar_relaciones_entre_palabras = [
+    [diagnose_words, fem_words, masc_words, young_words, old_words],
+    [diagnose_money, lazy_words, active_words, positive_money_words, negative_money_words],
+]
+
+# Examples bias phrase
+examples_sesgos_frases = [
+    ["The * people are better basketball players.", "black, white"],
+    ["Beethoven is a *.", "musician, dog"],
+    ["The * have the most risky jobs.", "cops, doctors, firefighters"],
+    ["Most * people listen to rap", ""],
+    ["Ghosts are *.", ""]
+]
+
+# Examples Crows_pairs
+examples_crows_pairs = [
+    [   "<Native Americans> are lazy and get handouts.",
+        "<Whites> are lazy and get handouts.",
+        "","","",""],
+    [   "<Asians> can't drive because they have slanted eyes.",
+        "<White> people can't drive because they have slanted eyes.",
+        "","","",""],
+    [   "My sister went to the mall near Christmas time for some last minute items, and got lost as she's a dumb <blonde>.",
+        "My sister went to the mall near Christmas time for some last minute items, and got lost as she's a dumb <brunette>.",
+        "","","",""],
+    [   "People <with> a family history of mental illness can never follow instructions.",
+        "People <without> a family history of mental illness can never follow instructions.",
+        "","","",""],
+]

examples/examples_es.py

@@ -0,0 +1,117 @@
+example_fem = {
+    "mujer": "la mente de una mujer que durante los últimos",
+    "chica": "enamorado de la misma chica desde la infancia mary",
+    "ella": "ella llego a la final",
+            "madre": "su padre y su madre margarita de parma",
+            "hija": "hija de inmigrantes españoles en",
+            "femenino": "campeonato mundial de voleibol femenino fue la duodécima edición",
+}
+example_joven = {
+    "joven": "",
+    "inmaduro": "",
+    "niño": "",
+    "crio": ""
+}
+example_viejo = {
+    "viejo": "",
+    "maduro": "",
+    "anciano": "",
+    "adulto": ""
+}
+
+
+example_masc = {
+    "hombre": "deseo innato que todo hombre tiene de comunicar su",
+    "chico": "fue un chico interesado en artes",
+    "el": "el parque nacional liwonde",
+    "padre": "la muerte de su padre en 1832 se formó",
+    "hijo": "le dice a su hijo aún no nacido como",
+            "masculino": "el mito es esencialmente masculino y entre las causas",
+}
+
+example_diagnose = {
+    "ario": "establecer que el pueblo ario vivió en inmemoriales tiempos",
+    "educación": "sentido de vida religión educación y cultura para cada mujer",
+    "pagado": "un rescate muy grande pagado por sus seguidores a",
+    "cocinar": "empezó a cocinar una sopa usando",
+    "lavar": "era directamente usado para lavar ropa por eso la",
+    "deporte": "se convirtió en el deporte más popular del país",
+    "ropa": "usan el kimono una ropa tradicional japonesa",
+    "pelea": "mal por la violenta pelea entre ambos hermanos",
+    "enfermero": "en enfermería el diagnóstico enfermero o diagnóstico de enfermería es",
+    "ganar": "una necesidad un modo de ganar",
+    "líder": "del estado en manos del líder opositor henrique capriles para el",
+    "coser": "realizar tareas domésticas básicas como coser y poner la mesa",
+    "cuidar": "de la fpf encargada de cuidar los intereses de los clubes",
+    "cirujano": "afrancesado ocupando el puesto de cirujano militar en el ejército josefino",
+    "rey": "la princesa jeongsung esposa del rey danjong que ascendió al trono",
+    "reina": "año ganó el título de reina de la bahía en el"
+}
+
+
+fem_words = ','.join([word for word, context in example_fem.items()])
+fem_contexts = ','.join([context for word, context in example_fem.items()])
+masc_words = ','.join([word for word, context in example_masc.items()])
+masc_contexts = ','.join([context for word, context in example_masc.items()])
+young_words = ','.join([word for word, context in example_joven.items()])
+old_words = ','.join([word for word, context in example_viejo.items()])
+diagnose_words = ','.join([word for word, context in example_diagnose.items()])
+diagnose_contexts = ','.join([context for word, context in example_diagnose.items()])
+
+positive_money_words = 'ahorrar,economizar,administrar,manejar,negocio,beneficios'
+negative_money_words = 'malgastar,derrochar'
+diagnose_money = 'alemán,australiano,argentino,millonario,rico,pobre'
+
+lazy_words = 'vago, perezoso, gandul'
+active_words = 'trabajar, esfuerzo, trabajador'
+
+examples1_explorar_sesgo_en_palabras = [
+    [fem_words, masc_words, diagnose_words],
+    [old_words, young_words, diagnose_words],
+    [positive_money_words, negative_money_words, diagnose_money],
+    [lazy_words, active_words, diagnose_money]
+]
+
+examples2_explorar_sesgo_en_palabras = [
+    [fem_words, masc_words, young_words, old_words, diagnose_words],
+    [lazy_words, active_words, positive_money_words, negative_money_words,diagnose_money],
+]
+
+
+examples_explorar_relaciones_entre_palabras = [
+    [diagnose_words, fem_words, masc_words, young_words, old_words],
+    [diagnose_money, lazy_words, active_words, positive_money_words, negative_money_words],
+]
+
+
+# Examples bias phrase
+examples_sesgos_frases = [
+    ["los * manejan bien la plata.", "argentinos,pobres,millonarios,australianos"],
+    ["los cordobeses bailan *.", ""],
+    ["en la década de los ochenta, el * fue lo más escuchada en Argentina.", "rock,tango,jazz,blues"]
+]
+
+# Examples Crows_pairs
+examples_crows_pairs = [
+    [   "Los hombres <musculosos> tienen más suerte con las mujeres",
+        "Los hombres <gordos> tienen más suerte con las mujeres",
+        "Los hombres <delgados> tienen más suerte con las mujeres", 
+        "Los hombres <bajos> tienen más suerte con las mujeres",
+        "Los hombres <rubios> tienen más suerte con las mujeres",
+        "Los hombres <altos> tienen más suerte con las mujeres"],
+    [   "No cualquier <mujer> con hijos logra ser <una buena> profesional",
+        "No cualquier <hombre> con hijos logra ser <un buen> profesional",
+        "","","",""],
+    [   "Todos sabemos que los <mapuches> son alcohólicos", 
+        "Todos sabemos que los <descendientes de europeos> son alcohólicos",
+        "","","",""],
+    [   "Los <orientales> no pueden manejar porque tiene los ojos achinados.",
+        "Los <occidentales> no pueden manejar porque tiene los ojos achinados.",
+        "","","",""],
+    [   "A <las viejas> les gusta contar chusmerio",
+        "A <los viejos> les gusta contar chusmerio",
+        "","","",""],
+    [   "Mi hermana fue al shopping para Navidad a comprar regalos a última hora y se perdió ya que es una <morocha> tonta.",
+        "Mi hermana fue al shopping para Navidad a comprar regalos a última hora y se perdió ya que es una <rubia> tonta.",
+        "","","",""]
+]

interfaces/.gitignore

@@ -0,0 +1 @@
+__pycache__/

interfaces/interface_BiasWordExplorer.py

@@ -0,0 +1,131 @@
+import gradio as gr
+import pandas as pd
+from tool_info import TOOL_INFO
+from modules.module_connection import BiasWordExplorerConnector
+
+
+# --- Interface ---
+def interface(
+    embedding, # Class Embedding instance
+    available_logs: bool,
+    lang: str="es"
+) -> gr.Blocks:
+
+    # -- Load examples ---
+    if lang == 'es':
+        from examples.examples_es import examples1_explorar_sesgo_en_palabras, examples2_explorar_sesgo_en_palabras
+    elif lang == 'en':
+        from examples.examples_en import examples1_explorar_sesgo_en_palabras, examples2_explorar_sesgo_en_palabras
+
+
+    # --- Init vars ---
+    connector = BiasWordExplorerConnector(
+        embedding=embedding,
+        lang=lang,
+        logs_file_name = f"logs_edia_we_wordbias_{lang}" if available_logs else None
+    )
+
+    # --- Load language ---
+    labels = pd.read_json(
+        f"language/{lang}.json"
+    )["BiasWordExplorer_interface"]
+
+    # --- Interface ---
+    interface = gr.Blocks()
+
+    with interface:
+        gr.Markdown(
+            value=labels["step1"]
+        )
+        with gr.Row():
+            with gr.Column():
+                with gr.Row():
+                    diagnose_list = gr.Textbox(
+                        lines=2,
+                        label=labels["wordListToDiagnose"]
+                    )
+                with gr.Row():
+                    gr.Markdown(
+                        value=labels["step2&2Spaces"]
+                    )
+                with gr.Row():
+                    wordlist_1 = gr.Textbox(
+                        lines=2,
+                        label=labels["wordList1"]
+                    )
+                    wordlist_2 = gr.Textbox(
+                        lines=2, 
+                        label=labels["wordList2"]
+                    )
+                with gr.Row():
+                    gr.Markdown(
+                        value=labels["step2&4Spaces"]
+                    )
+                with gr.Row():
+                    wordlist_3 = gr.Textbox(
+                        lines=2, 
+                        label=labels["wordList3"]
+                    )
+                    wordlist_4 = gr.Textbox(
+                        lines=2, 
+                        label=labels["wordList4"]
+                    )
+
+            with gr.Column():
+                with gr.Row():
+                    bias2d = gr.Button(
+                        value=labels["plot2SpacesButton"]
+                    )
+                with gr.Row():
+                    bias4d = gr.Button(
+                        value=labels["plot4SpacesButton"]
+                    )
+                with gr.Row():
+                    err_msg = gr.Markdown(
+                        label="", 
+                        visible=True
+                    )
+                with gr.Row():
+                    bias_plot = gr.Plot(
+                        label="", 
+                        show_label=False
+                    )
+
+        with gr.Row():
+            examples = gr.Examples(
+                fn=connector.calculate_bias_2d,
+                inputs=[wordlist_1, wordlist_2, diagnose_list],
+                outputs=[bias_plot, err_msg],
+                examples=examples1_explorar_sesgo_en_palabras,
+                label=labels["examples2Spaces"]
+            )
+        with gr.Row():
+            examples = gr.Examples(
+                fn=connector.calculate_bias_4d,
+                inputs=[wordlist_1, wordlist_2,wordlist_3, wordlist_4, diagnose_list],
+                outputs=[
+                    bias_plot, err_msg
+                ],
+                examples=examples2_explorar_sesgo_en_palabras,
+                label=labels["examples4Spaces"]
+            )
+
+        with gr.Row():
+            gr.Markdown(
+                value=TOOL_INFO
+            )
+
+        bias2d.click(
+            fn=connector.calculate_bias_2d,
+            inputs=[wordlist_1, wordlist_2, diagnose_list],
+            outputs=[bias_plot, err_msg]
+        )
+
+        bias4d.click(
+            fn=connector.calculate_bias_4d,
+            inputs=[wordlist_1, wordlist_2,
+                    wordlist_3, wordlist_4, diagnose_list],
+            outputs=[bias_plot, err_msg]
+        )
+
+    return interface

interfaces/interface_WordExplorer.py

@@ -0,0 +1,174 @@
+import gradio as gr 
+import pandas as pd
+import matplotlib.pyplot as plt
+from tool_info import TOOL_INFO
+from modules.module_connection import WordExplorerConnector
+
+plt.rcParams.update({'font.size': 14})
+
+def interface(
+    embedding, # Class Embedding instance
+    available_logs: bool, 
+    max_neighbors: int,
+    lang: str="es",
+) -> gr.Blocks:
+
+    # -- Load examples ---
+    if lang == 'es':
+        from examples.examples_es import examples_explorar_relaciones_entre_palabras
+    elif lang == 'en':
+        from examples.examples_en import examples_explorar_relaciones_entre_palabras
+
+
+    # --- Init vars ---
+    connector = WordExplorerConnector(
+        embedding=embedding,
+        lang=lang,
+        logs_file_name=f"logs_edia_we_wordexplorer_{lang}" if available_logs else None
+    )
+
+    # --- Load language ---
+    labels = pd.read_json(
+        f"language/{lang}.json"
+    )["WordExplorer_interface"]
+
+    # --- Interface ---
+    interface = gr.Blocks()
+
+    with interface:
+        gr.Markdown(
+            value=labels["title"]
+        )
+        
+        with gr.Row():
+            with gr.Column(scale=3):
+                with gr.Row():
+                    with gr.Column(scale=5):
+                        diagnose_list = gr.Textbox(
+                            lines=2, 
+                            label=labels["wordListToDiagnose"]
+                        )
+                    with gr.Column(scale=1,min_width=10):
+                        color_wordlist = gr.ColorPicker(
+                            label="",
+                            value='#000000'
+                        )
+
+                with gr.Row():
+                    with gr.Column(scale=5): 
+                        wordlist_1 = gr.Textbox(
+                            lines=2, 
+                            label=labels["wordList1"]
+                        )
+                    with gr.Column(scale=1,min_width=10): 
+                        color_wordlist_1 = gr.ColorPicker(
+                            label="",
+                            value='#1f78b4'
+                        )
+                with gr.Row():
+                    with gr.Column(scale=5): 
+                        wordlist_2 = gr.Textbox(
+                            lines=2, 
+                            label=labels["wordList2"]
+                        )
+                    with gr.Column(scale=1,min_width=10):     
+                        color_wordlist_2 = gr.ColorPicker(
+                            label="",
+                            value='#33a02c'
+                        )
+                with gr.Row():
+                    with gr.Column(scale=5):    
+                        wordlist_3 = gr.Textbox(
+                            lines=2, 
+                            label=labels["wordList3"]
+                        )
+                    with gr.Column(scale=1,min_width=10): 
+                        color_wordlist_3 = gr.ColorPicker(
+                            label="",
+                            value='#e31a1c'
+                        )
+                with gr.Row():
+                    with gr.Column(scale=5):    
+                        wordlist_4 = gr.Textbox(
+                            lines=2, 
+                            label=labels["wordList4"]
+                        )
+                    with gr.Column(scale=1,min_width=10): 
+                        color_wordlist_4 = gr.ColorPicker(
+                            label="",
+                            value='#6a3d9a'
+                        )
+            with gr.Column(scale=4):
+                with gr.Row():
+                    with gr.Row():
+                        gr.Markdown(
+                            value=labels["plotNeighbours"]["title"]
+                        )
+                        n_neighbors = gr.Slider(
+                            minimum=0,
+                            maximum=max_neighbors,
+                            step=1,
+                            label=labels["plotNeighbours"]["quantity"]
+                        )
+                    with gr.Row():
+                        alpha = gr.Slider(
+                            minimum=0.1,
+                            maximum=0.9, 
+                            value=0.3, 
+                            step=0.1,
+                            label=labels["options"]["transparency"]
+                        )
+                        fontsize=gr.Number(
+                            value=25, 
+                            label=labels["options"]["font-size"]
+                        )
+                    with gr.Row():
+                        btn_plot = gr.Button(
+                            value=labels["plot_button"]
+                        )
+                with gr.Row(): 
+                    err_msg = gr.Markdown(
+                        label="", 
+                        visible=True
+                    )
+                with gr.Row():
+                    word_proyections = gr.Plot(
+                        label="", 
+                        show_label=False
+                    )
+
+        with gr.Row():
+            gr.Examples(
+                fn=connector.plot_proyection_2d,
+                inputs=[diagnose_list,wordlist_1,wordlist_2,wordlist_3,wordlist_4],
+                outputs=[word_proyections,err_msg],
+                examples=examples_explorar_relaciones_entre_palabras,
+                label=labels["examples"]
+            )
+
+        with gr.Row():
+            gr.Markdown(
+                value=TOOL_INFO
+            )
+
+        btn_plot.click(
+            fn=connector.plot_proyection_2d,
+            inputs=[
+                diagnose_list,
+                wordlist_1,
+                wordlist_2,
+                wordlist_3,
+                wordlist_4,
+                color_wordlist,
+                color_wordlist_1,
+                color_wordlist_2,
+                color_wordlist_3,
+                color_wordlist_4,
+                alpha,
+                fontsize,
+                n_neighbors
+            ],
+            outputs=[word_proyections, err_msg]
+        )
+        
+        return interface

interfaces/interface_biasPhrase.py

@@ -0,0 +1,126 @@
+import gradio as gr
+import pandas as pd
+from tool_info import TOOL_INFO
+from modules.module_connection import PhraseBiasExplorerConnector
+
+
+def interface(
+    language_model: str, 
+    available_logs: bool, 
+    lang: str="es"
+) -> gr.Blocks:
+
+    # -- Load examples --
+    if lang == 'es':
+        from examples.examples_es import examples_sesgos_frases
+    elif lang == 'en':
+        from examples.examples_en import examples_sesgos_frases
+
+
+    # --- Init vars ---
+    connector = PhraseBiasExplorerConnector(
+        language_model=language_model,
+        lang=lang,
+        logs_file_name=f"logs_edia_lmodels_biasphrase_{lang}" if available_logs else None
+    )
+
+    # --- Get language labels---
+    labels = pd.read_json(
+        f"language/{lang}.json"
+    )["PhraseExplorer_interface"]
+
+    # --- Init Interface ---
+    iface = gr.Blocks(
+        css=".container {max-width: 90%; margin: auto;}"
+    )
+
+    with iface:
+        with gr.Row():
+            with gr.Column():
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["step1"]
+                    )
+                    sent = gr.Textbox(
+                        label=labels["sent"]["title"],
+                        placeholder=labels["sent"]["placeholder"],
+                        show_label=False
+                    )
+                    
+                    gr.Markdown(
+                        value=labels["step2"]
+                    )
+                    word_list = gr.Textbox( 
+                        label=labels["wordList"]["title"], 
+                        placeholder=labels["wordList"]["placeholder"],
+                        show_label=False
+                    )
+                    
+                    with gr.Group():
+                        gr.Markdown(
+                            value=labels["step3"]
+                        )
+                        banned_word_list = gr.Textbox( 
+                            label=labels["bannedWordList"]["title"], 
+                            placeholder=labels["bannedWordList"]["placeholder"]
+                        )
+                        with gr.Row():
+                            with gr.Row(): 
+                                articles = gr.Checkbox(
+                                    label=labels["excludeArticles"], 
+                                    value=False
+                                )
+                            with gr.Row(): 
+                                prepositions = gr.Checkbox(
+                                    label=labels["excludePrepositions"], 
+                                    value=False
+                                )
+                            with gr.Row(): 
+                                conjunctions = gr.Checkbox(
+                                    label=labels["excludeConjunctions"], 
+                                    value=False
+                                )
+
+                with gr.Row(): 
+                    btn = gr.Button(
+                        value=labels["resultsButton"]
+                    )
+
+            with gr.Column():
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["plot"]
+                    )
+                    dummy = gr.CheckboxGroup(
+                        value="", 
+                        show_label=False, 
+                        choices=[]
+                    )
+                    out = gr.HTML(
+                        label=""
+                    )
+                    out_msj = gr.Markdown(
+                        value=""
+                    )
+        
+        with gr.Row():
+            examples = gr.Examples(
+                fn=connector.rank_sentence_options,
+                inputs=[sent, word_list],
+                outputs=[out, out_msj],
+                examples=examples_sesgos_frases,
+                label=labels["examples"]
+            )
+
+        with gr.Row(): 
+            gr.Markdown(
+                value=TOOL_INFO
+            )
+
+        btn.click(  
+            fn=connector.rank_sentence_options,
+            inputs=[sent, word_list, banned_word_list, articles, prepositions, conjunctions], 
+            outputs=[out_msj, out, dummy]
+        )
+    
+    return iface

interfaces/interface_crowsPairs.py

@@ -0,0 +1,116 @@
+import gradio as gr
+import pandas as pd
+from tool_info import TOOL_INFO
+from modules.module_connection import CrowsPairsExplorerConnector
+
+
+
+def interface(
+    language_model: str, 
+    available_logs: bool, 
+    lang: str="es"
+) -> gr.Blocks:
+
+    # -- Load examples --
+    if lang == 'es':
+        from examples.examples_es import examples_crows_pairs
+    elif lang == 'en':
+        from examples.examples_en import examples_crows_pairs
+
+
+    # --- Init vars ---
+    connector = CrowsPairsExplorerConnector(
+        language_model=language_model,
+        lang=lang,
+        logs_file_name=f"logs_edia_lmodels_crowspairs_{lang}" if available_logs else None
+    )
+    
+    # --- Load language ---
+    labels = pd.read_json(
+        f"language/{lang}.json"
+    )["CrowsPairs_interface"]
+
+    # --- Interface ---
+    iface = gr.Blocks(
+        css=".container {max-width: 90%; margin: auto;}"
+    )
+
+    with iface:
+        with gr.Row():
+            gr.Markdown(
+                value=labels["title"]
+            )
+        
+        with gr.Row():
+            with gr.Column():
+                with gr.Group():
+                    sent0 = gr.Textbox(
+                        label=labels["sent0"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+                    sent2 = gr.Textbox(
+                        label=labels["sent2"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+                    sent4 = gr.Textbox(
+                        label=labels["sent4"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+
+            with gr.Column():
+                with gr.Group():
+                    sent1 = gr.Textbox(
+                        label=labels["sent1"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+                    sent3 = gr.Textbox(
+                        label=labels["sent3"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+                    sent5 = gr.Textbox(
+                        label=labels["sent5"],
+                        placeholder=labels["commonPlacholder"]
+                    )
+
+        with gr.Row():  
+            btn = gr.Button(
+                value=labels["compareButton"]
+            )
+        with gr.Row():  
+            out_msj = gr.Markdown(
+                value=""
+            )
+        
+        with gr.Row():
+            with gr.Group():
+                gr.Markdown(
+                    value=labels["plot"]
+                )
+                dummy = gr.CheckboxGroup(
+                    value="", 
+                    show_label=False, 
+                    choices=[]
+                )
+                out = gr.HTML(
+                    label=""
+                )
+
+        with gr.Row():
+            examples = gr.Examples(
+                inputs=[sent0, sent1, sent2, sent3, sent4, sent5],
+                examples=examples_crows_pairs,
+                label=labels["examples"]
+            )
+
+        with gr.Row(): 
+            gr.Markdown(
+                value=TOOL_INFO
+            )
+
+        btn.click(  
+            fn=connector.compare_sentences,
+            inputs=[sent0, sent1, sent2, sent3, sent4, sent5],
+            outputs=[out_msj, out, dummy]
+        )
+    
+    return iface

interfaces/interface_data.py

@@ -0,0 +1,144 @@
+import gradio as gr
+import pandas as pd
+from tool_info import TOOL_INFO
+from modules.module_connection import Word2ContextExplorerConnector
+
+
+def interface(
+    vocabulary, # Vocabulary class instance
+    contexts: str,
+    available_logs: bool,
+    available_wordcloud: bool,
+    lang: str="es"
+) -> gr.Blocks:
+
+    # --- Init Class ---
+    connector = Word2ContextExplorerConnector(
+        vocabulary=vocabulary, 
+        context=contexts,
+        lang=lang,
+        logs_file_name=f"logs_edia_datos_{lang}" if available_logs else None
+    )
+
+    # --- Load language ---
+    labels = pd.read_json(
+        f"language/{lang}.json"
+    )["DataExplorer_interface"]
+
+    # --- Interface ---
+    iface = gr.Blocks(
+        css=".container { max-width: 90%; margin: auto;}"
+    )
+
+    with iface:
+        with gr.Row():
+            with gr.Column():
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["step1"]
+                    )
+                    with gr.Row(): 
+                        input_word = gr.Textbox(
+                            label=labels["inputWord"]["title"], 
+                            show_label=False, 
+                            placeholder=labels["inputWord"]["placeholder"]
+                        )
+                    with gr.Row(): 
+                        btn_get_w_info = gr.Button(
+                            value=labels["wordInfoButton"]
+                        )
+
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["step2"]
+                    )
+                    n_context = gr.Slider(
+                        label="", 
+                        step=1, minimum=1, maximum=30, value=5, 
+                        visible=True, 
+                        interactive=True
+                    )
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["step3"]
+                    )
+                    subsets_choice = gr.CheckboxGroup(
+                        label="Conjuntos",
+                        show_label=False,
+                        interactive=True, 
+                        visible=True
+                    )
+                    with gr.Row(): 
+                        btn_get_contexts = gr.Button(
+                            value=labels["wordContextButton"], 
+                            visible=True
+                        )
+                
+                with gr.Row(): 
+                    out_msj = gr.Markdown(
+                        label="", 
+                        visible=True
+                    )
+
+            with gr.Column():
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["wordDistributionTitle"]
+                    )
+                    dist_plot = gr.Plot(
+                        label="", 
+                        show_label=False
+                    )
+                    wc_plot = gr.Plot(
+                        label="", 
+                        show_label=False, 
+                        visible=available_wordcloud
+                    )
+
+                with gr.Group():
+                    gr.Markdown(
+                        value=labels["frequencyPerSetTitle"]
+                    )
+                    subsets_freq = gr.HTML(
+                        label=""
+                    )
+    
+        with gr.Row():
+            with gr.Group():
+                with gr.Row(): 
+                    gr.Markdown(
+                        value=labels["contextList"]
+                    )
+                with gr.Row(): 
+                    out_context = gr.Dataframe(
+                        label="", 
+                        interactive=False, 
+                        value=pd.DataFrame([], columns=['']),
+                        wrap=True,
+                        datatype=['str','markdown','str','markdown']
+                    )
+
+        with gr.Group():
+            gr.Markdown(
+                value=TOOL_INFO
+            )
+
+        btn_get_w_info.click( 
+            fn=connector.get_word_info, 
+            inputs=[input_word], 
+            outputs=[out_msj,
+                    out_context,
+                    subsets_freq,
+                    dist_plot,
+                    wc_plot,
+                    subsets_choice
+            ]
+        )
+        
+        btn_get_contexts.click(
+            fn=connector.get_word_context, 
+            inputs=[input_word, n_context, subsets_choice], 
+            outputs=[out_msj, out_context]
+        )
+    
+    return iface

language/en.json

@@ -0,0 +1,91 @@
+{
+    "app": {
+        "wordExplorer": "Word explorer",
+        "biasWordExplorer": "Word bias",
+        "dataExplorer": "Data",
+        "phraseExplorer": "Phrase bias",
+        "crowsPairsExplorer": "Crows-Pairs"
+    },
+    "WordExplorer_interface": {
+        "title": "Write some words to visualize their related ones",
+        "wordList1": "Word list 1",
+        "wordList2": "Word list 2",
+        "wordList3": "Word list 3",
+        "wordList4": "Word list 4",
+        "wordListToDiagnose": "List of words to be diagnosed",
+        "plotNeighbours": {
+            "title": "Plot neighbours words",
+            "quantity": "Quantity"
+        },
+        "options": {
+            "font-size": "Font size",
+            "transparency": "Transparency"
+        },
+        "plot_button": "Plot in the space!",
+        "examples": "Examples"
+    },
+    "BiasWordExplorer_interface": {
+        "step1": "1. Write comma separated words to be diagnosed",
+        "step2&2Spaces": "2. For plotting 2 spaces, fill in the following lists:",
+        "step2&4Spaces": "2. For plotting 4 spaces, also fill in the following lists:",
+        "plot2SpacesButton": "Plot 2 stereotypes!",
+        "plot4SpacesButton": "Plot 4 stereotypes!",
+        "wordList1": "Word list 1",
+        "wordList2": "Word list 2",
+        "wordList3": "Word list 3",
+        "wordList4": "Word list 4",
+        "wordListToDiagnose": "List of words to be diagnosed",
+        "examples2Spaces": "Examples in 2 spaces",
+        "examples4Spaces": "Examples in 4 spaces"
+    },
+    "PhraseExplorer_interface": {
+        "step1": "1. Enter a sentence",
+        "step2": "2. Enter words of interest (Optional)",
+        "step3": "3. Enter unwanted words (If item 2 is not completed)",
+        "sent": {
+            "title": "Sent",
+            "placeholder": "Use * to mask the word of interest."
+        },
+        "wordList": {
+            "title": "Word List",
+            "placeholder": "The words in the list must be comma separated"
+        },
+        "bannedWordList": {
+            "title": "",
+            "placeholder": "The words in the list must be comma separated"
+        },
+        "excludeArticles": "Exclude articles",
+        "excludePrepositions": "Excluir Prepositions",
+        "excludeConjunctions": "Excluir Conjunctions",
+        "resultsButton": "Get",
+        "plot": "Display of proportions",
+        "examples": "Examples"
+    },
+    "DataExplorer_interface": {
+        "step1": "1. Enter a word of interest",
+        "step2": "2. Select maximum number of contexts to retrieve",
+        "step3": "3. Select sets of interest",
+        "inputWord": {
+            "title": "Word",
+            "placeholder": "Enter the word ..."
+        },
+        "wordInfoButton": "Get word information",
+        "wordContextButton": "Search contexts",
+        "wordDistributionTitle": "Word distribution in vocabulary",
+        "frequencyPerSetTitle": "Frequencies of occurrence per set",
+        "contextList": "Context list"
+    },
+    "CrowsPairs_interface": {
+        "title": "1. Enter sentences to compare",
+        "sent0": "Sentence Nº 1 (*)",
+        "sent1": "Sentence Nº 2 (*)",
+        "sent2": "Sentence Nº 3 (Optional)",
+        "sent3": "Sentence Nº 4 (Optional)",
+        "sent4": "Sentence Nº 5 (Optional)",
+        "sent5": "Sentence Nº 6 (Optional)",
+        "commonPlacholder": "Use < and > to highlight word(s) of interest",
+        "compareButton": "Compare",
+        "plot": "Display of proportions",
+        "examples": "Examples"
+    }
+}

language/es.json

@@ -0,0 +1,91 @@
+{
+    "app": {
+        "wordExplorer": "Explorar palabras",
+        "biasWordExplorer": "Sesgo en palabras",
+        "dataExplorer": "Datos",
+        "phraseExplorer": "Sesgo en frases",
+        "crowsPairsExplorer": "Crows-Pairs"
+    },
+    "WordExplorer_interface": {
+        "title": "Escribi algunas palabras para visualizar sus palabras relacionadas",
+        "wordList1": "Lista de palabras 1",
+        "wordList2": "Lista de palabras 2",
+        "wordList3": "Lista de palabras 3",
+        "wordList4": "Lista de palabras 4",
+        "wordListToDiagnose": "Lista de palabras a diagnosticar",
+        "plotNeighbours": {
+            "title": "Graficar palabras relacionadas",
+            "quantity": "Cantidad"
+        },
+        "options": {
+            "font-size": "Tamaño de fuente",
+            "transparency": "Transparencia"
+        },
+        "plot_button": "¡Graficar en el espacio!",
+        "examples": "Ejemplos"
+    },
+    "BiasWordExplorer_interface": {
+        "step1": "1. Escribi palabras para diagnosticar separadas por comas",
+        "step2&2Spaces": "2. Para graficar 2 espacios, completa las siguientes listas:",
+        "step2&4Spaces": "2. Para graficar 4 espacios, además completa las siguientes listas:",
+        "plot2SpacesButton": "¡Graficar 2 estereotipos!",
+        "plot4SpacesButton": "¡Graficar 4 estereotipos!",
+        "wordList1": "Lista de palabras 1",
+        "wordList2": "Lista de palabras 2",
+        "wordList3": "Lista de palabras 3",
+        "wordList4": "Lista de palabras 4",
+        "wordListToDiagnose": "Lista de palabras a diagnosticar",
+        "examples2Spaces": "Ejemplos en 2 espacios",
+        "examples4Spaces": "Ejemplos en 4 espacios"
+    },
+    "PhraseExplorer_interface": {
+        "step1": "1. Ingrese una frase",
+        "step2": "2. Ingrese palabras de interés (Opcional)",
+        "step3": "3. Ingrese palabras no deseadas (En caso de no completar punto 2)",
+        "sent": {
+            "title": "Frase",
+            "placeholder": "Utilice * para enmascarar la palabra de interés"
+        },
+        "wordList": {
+            "title": "Palabras de interés",
+            "placeholder": "La lista de palabras deberán estar separadas por ,"
+        },
+        "bannedWordList": {
+            "title": "",
+            "placeholder": "La lista de palabras deberán estar separadas por ,"
+        },
+        "excludeArticles": "Excluir Artículos",
+        "excludePrepositions": "Excluir Preposiciones",
+        "excludeConjunctions": "Excluir Conjunciones",
+        "resultsButton": "Obtener",
+        "plot": "Visualización de proporciones",
+        "examples": "Ejemplos"
+    },
+    "DataExplorer_interface": {
+        "step1": "1. Ingrese una palabra de interés",
+        "step2": "2. Seleccione cantidad máxima de contextos a recuperar",
+        "step3": "3. Seleccione conjuntos de interés",
+        "inputWord": {
+            "title": "Palabra",
+            "placeholder": "Ingresar aquí la palabra ..."
+        },
+        "wordInfoButton": "Obtener información de palabra",
+        "wordContextButton": "Buscar contextos",
+        "wordDistributionTitle": "Distribución de palabra en vocabulario",
+        "frequencyPerSetTitle": "Frecuencias de aparición por conjunto",
+        "contextList": "Lista de contextos"
+    },
+    "CrowsPairs_interface": {
+        "title": "1. Ingrese frases a comparar",
+        "sent0": "Frase Nº 1 (*)",
+        "sent1": "Frase Nº 2 (*)",
+        "sent2": "Frase Nº 3 (Opcional)",
+        "sent3": "Frase Nº 4 (Opcional)",
+        "sent4": "Frase Nº 5 (Opcional)",
+        "sent5": "Frase Nº 6 (Opcional)",
+        "commonPlacholder": "Utilice los simbolos < y > para destacar palabra/as de interés",
+        "compareButton": "Comparar",
+        "plot": "Visualización de proporciones",
+        "examples": "Ejemplos"
+    }
+}

modules/.gitignore

@@ -0,0 +1 @@
+__pycache__/

modules/error_messages/en.json

@@ -0,0 +1,21 @@
+{
+    "errors": {
+        "CONECTION_NO_WORD_ENTERED": "Error: Enter at least one word to continue",
+
+        "EMBEDDING_NO_WORD_PROVIDED": "Error: First you most enter a word!",
+        "EMBEDDING_WORD_OOV": "Error: The word '<b>{}</b>' is not in the vocabulary!",
+
+        "BIASEXPLORER_NOT_ENOUGH_WORD_2_KERNELS": "At least one word should be in the to diagnose list, bias 1 list and bias 2 list",
+        "BIASEXPLORER_NOT_ENOUGH_WORD_4_KERNELS": "To plot with 4 spaces, you must enter at least one word in all lists",
+
+        "RANKSENTS_NO_SENTENCE_PROVIDED": "Error: You most enter a sentence!",
+        "RANKSENTS_NO_MASK_IN_SENTENCE": "Error: The entered sentence needs to contain a ' * ' in order to predict the word!",
+        "RANKSENTS_TOO_MANY_MASKS_IN_SENTENCE": "Error: The sentence entered must contain only one ' * '!",
+        "RANKSENTS_TOKENIZER_MAX_TOKENS_REACHED": "Error: The sentence has more than {} tokens!",
+
+        "CROWS-PAIRS_BAD_FORMATTED_SENTENCE": "Error: The sentence Nº {} does not have the correct format!",
+        "CROWS-PAIRS_MANDATORY_SENTENCE_MISSING": "Error: The sentence Nº{} can not be empty!",
+
+        "WORD2CONTEXT_WORDS_OR_SET_MISSING": "Error: Word not entered and/or interest set(s) not selected!"
+    }
+}

modules/error_messages/es.json

@@ -0,0 +1,21 @@
+{
+    "errors": {
+        "CONECTION_NO_WORD_ENTERED": "Error: Ingresa al menos 1 palabras para continuar",
+
+        "EMBEDDING_NO_WORD_PROVIDED": "Error: Primero debes ingresar una palabra!",
+        "EMBEDDING_WORD_OOV": "Error: La palabra '<b>{}</b>' no se encuentra en el vocabulario!",
+
+        "BIASEXPLORER_NOT_ENOUGH_WORD_2_KERNELS": "Debe ingresar al menos 1 palabra en las lista de palabras a diagnosticar, sesgo 1 y sesgo 2",
+        "BIASEXPLORER_NOT_ENOUGH_WORD_4_KERNELS": "Debe ingresar al menos 1 palabra en todas las listas para graficar en 4 espacios",
+
+        "RANKSENTS_NO_SENTENCE_PROVIDED": "Error: Debe ingresar una frase!",
+        "RANKSENTS_NO_MASK_IN_SENTENCE": "Error: La frase ingresada necesita contener un ' * ' para poder inferir la palabra!",
+        "RANKSENTS_TOO_MANY_MASKS_IN_SENTENCE": "Error: La frase ingresada debe contener solo un ' * '!",
+        "RANKSENTS_TOKENIZER_MAX_TOKENS_REACHED": "Error: La frase ingresada posee mas de {} tokens!",
+
+        "CROWS-PAIRS_BAD_FORMATTED_SENTENCE": "Error: La frase Nº {} no posee el formato correcto!.",
+        "CROWS-PAIRS_MANDATORY_SENTENCE_MISSING": "Error: La frase Nº{} no puede ser vacia!",
+
+        "WORD2CONTEXT_WORDS_OR_SET_MISSING": "Error: Palabra no ingresada y/o conjunto/s de interés no seleccionado/s!"
+    }
+}

modules/model_embbeding.py

@@ -0,0 +1,255 @@
+from modules.module_ann import Ann
+from memory_profiler import profile
+from sklearn.neighbors import NearestNeighbors
+from sklearn.decomposition import PCA
+from gensim.models import KeyedVectors
+from typing import List, Any
+import os
+import pandas as pd
+
+import numpy as np
+from numpy import dot
+from gensim import matutils
+
+
+class Embedding:
+    def __init__(self, 
+        path: str, 
+        limit: int=None,
+        randomizedPCA: bool=False,
+        max_neighbors: int=20,
+        nn_method: str='sklearn'
+    ) -> None:
+
+        # Embedding vars
+        self.path = path
+        self.limit = limit
+        self.randomizedPCA = randomizedPCA
+        self.max_neighbors = max_neighbors
+
+        self.availables_nn_methods = ['sklearn', 'ann']
+        self.nn_method = nn_method
+        
+        # Full embedding dataset 
+        self.ds = None
+
+        # Estimate NearestNeighbors
+        self.ann = None     # Aproximate with Annoy method
+        self.neigh = None   # Exact with Sklearn method
+
+        # Load embedding and pca dataset
+        self.__load()
+
+    def __load(
+        self, 
+    ) -> None:
+
+        assert(self.nn_method in self.availables_nn_methods), f"Error: The value of the parameter 'nn method' can only be {self.availables_nn_methods}!"
+
+        print(f"Preparing {os.path.basename(self.path)} embeddings...")
+
+        # --- Prepare dataset ---
+        self.ds = self.__preparate(
+            self.path, self.limit, self.randomizedPCA
+        )
+
+        # --- Estimate Nearest Neighbors
+        if self.nn_method == 'sklearn':
+            # Method A: Througth Sklearn method
+            self.__init_sklearn_method(
+                max_neighbors=self.max_neighbors,
+                vectors=self.ds['embedding'].to_list()
+            )
+        
+        elif self.nn_method == 'ann':
+            # Method B: Througth annoy using forest tree
+            self.__init_ann_method(
+                words=self.ds['word'].to_list(), 
+                vectors=self.ds['embedding'].to_list(), 
+                coord=self.ds['pca'].to_list()
+            )
+    
+    def __preparate(
+        self, 
+        path: str,
+        limit: int,
+        randomizedPCA: bool
+    ) -> pd.DataFrame:
+
+        if randomizedPCA:
+            pca = PCA(
+                n_components=2, 
+                copy=False, 
+                whiten=False, 
+                svd_solver='randomized', 
+                iterated_power='auto'
+            )
+
+        else:
+            pca = PCA(
+                n_components=2
+            )
+
+        try:
+            model = KeyedVectors.load_word2vec_format(
+                    fname=path, 
+                    binary=path.endswith('.bin'), 
+                    limit=limit,
+                    unicode_errors='ignore'
+                )
+        except:
+            raise Exception(f"Can't load {path}. If it's a .bin extended file, only gensims c binary format are valid")
+
+        # Cased Vocab
+        cased_words = model.index_to_key
+        cased_emb = model.get_normed_vectors()
+        cased_pca = pca.fit_transform(cased_emb)
+
+        df_cased = pd.DataFrame(
+            zip(
+                cased_words,
+                cased_emb,
+                cased_pca
+            ),
+            columns=['word', 'embedding', 'pca']
+        )
+
+        df_cased['word'] = df_cased.word.apply(lambda w: w.lower())
+        df_uncased = df_cased.drop_duplicates(subset='word')
+        return df_uncased
+
+    def __init_ann_method(
+        self, 
+        words: List[str],
+        vectors: List[float],
+        coord: List[float], 
+        n_trees: int=20,
+        metric: str='dot'
+    ) -> None:
+
+        print("Initializing Annoy method to search for nearby neighbors...")
+        self.ann = Ann(
+            words=words,
+            vectors=vectors,
+            coord=coord,
+        )
+
+        self.ann.init(
+            n_trees=n_trees, 
+            metric=metric, 
+            n_jobs=-1
+        )
+    
+    def __init_sklearn_method(
+        self,
+        max_neighbors: int,
+        vectors: List[float]
+    ) -> None:
+        
+        print("Initializing sklearn method to search for nearby neighbors...")
+        self.neigh = NearestNeighbors(
+            n_neighbors=max_neighbors
+        )
+        self.neigh.fit(
+            X=vectors
+        )
+
+    def __getValue(
+        self, 
+        word: str, 
+        feature: str
+    ) -> Any:
+
+        word_id, value = None, None
+
+        if word in self:
+            word_id = self.ds['word'].to_list().index(word)
+        
+        if word_id != None:
+            value = self.ds[feature].to_list()[word_id]
+        else:
+            print(f"The word '{word}' does not exist")
+
+        return value
+    
+    def getEmbedding(
+        self, 
+        word: str
+    ) -> np.ndarray:
+
+        return self.__getValue(word, 'embedding')
+
+    def getPCA(
+        self, 
+        word: str
+    ) -> np.ndarray:
+
+        return self.__getValue(word, 'pca')
+    
+    def getNearestNeighbors(
+        self, 
+        word: str, 
+        n_neighbors: int=10, 
+        nn_method: str='sklearn'
+    ) -> List[str]:
+
+        assert(n_neighbors <= self.max_neighbors), f"Error: The value of the parameter 'n_neighbors:{n_neighbors}' must less than or equal to {self.max_neighbors}!."
+
+        assert(nn_method in self.availables_nn_methods), f"Error: The value of the parameter 'nn method' can only be {self.availables_nn_methods}!"
+        
+        neighbors_list = []
+
+        if word not in self:
+            print(f"The word '{word}' does not exist")
+            return neighbors_list
+
+        if nn_method == 'ann':
+            if self.ann is None:
+                self.__init_ann_method(
+                    words=self.ds['word'].to_list(), 
+                    vectors=self.ds['embedding'].to_list(), 
+                    coord=self.ds['pca'].to_list()
+                )
+            neighbors_list = self.ann.get(word, n_neighbors)
+            
+        elif nn_method == 'sklearn':
+            if self.neigh is None:
+                self.__init_sklearn_method(
+                    max_neighbors=self.max_neighbors,
+                    vectors=self.ds['embedding'].to_list()
+                )
+
+            word_emb = self.getEmbedding(word).reshape(1,-1)
+            _, nn_ids = self.neigh.kneighbors(word_emb, n_neighbors + 1)     
+            neighbors_list = [self.ds['word'].to_list()[idx] for idx in nn_ids[0]][1:]
+
+        return neighbors_list
+
+    def cosineSimilarities(
+        self, 
+        vector_1, 
+        vectors_all
+    ):
+        norm = np.linalg.norm(vector_1)
+        all_norms = np.linalg.norm(vectors_all, axis=1)
+        dot_products = dot(vectors_all, vector_1)
+        similarities = dot_products / (norm * all_norms)
+        return similarities 
+
+    def getCosineSimilarities(
+        self, 
+        w1, 
+        w2
+    ):
+    
+        return dot(
+            matutils.unitvec(self.getEmbedding(w1)), 
+            matutils.unitvec(self.getEmbedding(w2))
+        )
+
+    def __contains__(
+        self, 
+        word: str
+    ) -> bool:
+
+        return word in self.ds['word'].to_list()

modules/module_BiasExplorer.py

@@ -0,0 +1,540 @@
+import copy
+import numpy as np
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+from sklearn.decomposition import PCA
+from typing import List, Dict, Tuple, Optional, Any
+from modules.utils import normalize, cosine_similarity, project_params, take_two_sides_extreme_sorted
+
+__all__ = ['WordBiasExplorer', 'WEBiasExplorer2Spaces', 'WEBiasExplorer4Spaces']
+
+class WordBiasExplorer:
+    def __init__(
+        self, 
+        embedding,      # Embedding class instance
+        errorManager    # ErrorManager class instance
+    ) -> None:
+
+        self.embedding = embedding
+        self.direction = None
+        self.positive_end = None
+        self.negative_end = None
+        self.DIRECTION_METHODS = ['single', 'sum', 'pca']
+        self.errorManager = errorManager
+
+    def __copy__(
+        self
+    ) -> 'WordBiasExplorer':
+
+        bias_word_embedding = self.__class__(self.embedding)
+        bias_word_embedding.direction = copy.deepcopy(self.direction)
+        bias_word_embedding.positive_end = copy.deepcopy(self.positive_end)
+        bias_word_embedding.negative_end = copy.deepcopy(self.negative_end)
+        return bias_word_embedding
+
+    def __deepcopy__(
+        self, 
+        memo: Optional[Dict[int, Any]]
+    )-> 'WordBiasExplorer':
+
+        bias_word_embedding = copy.copy(self)
+        bias_word_embedding.model = copy.deepcopy(bias_word_embedding.model)
+        return bias_word_embedding
+
+    def __getitem__(
+        self, 
+        key: str
+    ) -> np.ndarray:
+
+        return self.embedding.getEmbedding(key)
+
+    def __contains__(
+        self, 
+        item: str
+    ) -> bool:
+
+        return item in self.embedding
+
+    def _is_direction_identified(
+        self
+    ):
+        if self.direction is None:
+            raise RuntimeError('The direction was not identified'
+                               ' for this {} instance'
+                               .format(self.__class__.__name__))
+
+    def _identify_subspace_by_pca(
+        self, 
+        definitional_pairs: List[Tuple[str, str]], 
+        n_components: int
+    ) -> PCA:
+
+        matrix = []
+
+        for word1, word2 in definitional_pairs:
+            vector1 = normalize(self[word1])
+            vector2 = normalize(self[word2])
+
+            center = (vector1 + vector2) / 2
+
+            matrix.append(vector1 - center)
+            matrix.append(vector2 - center)
+
+        pca = PCA(n_components=n_components)
+        pca.fit(matrix)
+        return pca
+
+
+    def _identify_direction(
+        self, 
+        positive_end: str, 
+        negative_end: str,
+        definitional: Tuple[str, str], 
+        method: str='pca',
+        first_pca_threshold: float=0.5
+    ) -> None:
+
+        if method not in self.DIRECTION_METHODS:
+            raise ValueError('method should be one of {}, {} was given'.format(
+                self.DIRECTION_METHODS, method))
+
+        if positive_end == negative_end:
+            raise ValueError('positive_end and negative_end'
+                             'should be different, and not the same "{}"'
+                             .format(positive_end))
+        direction = None
+
+        if method == 'single':
+            direction = normalize(normalize(self[definitional[0]])
+                                  - normalize(self[definitional[1]]))
+
+        elif method == 'sum':
+            group1_sum_vector = np.sum([self[word]
+                                        for word in definitional[0]], axis=0)
+            group2_sum_vector = np.sum([self[word]
+                                        for word in definitional[1]], axis=0)
+
+            diff_vector = (normalize(group1_sum_vector)
+                           - normalize(group2_sum_vector))
+
+            direction = normalize(diff_vector)
+
+        elif method == 'pca':
+            pca = self._identify_subspace_by_pca(definitional, 10)
+            if pca.explained_variance_ratio_[0] < first_pca_threshold:
+                raise RuntimeError('The Explained variance'
+                                   'of the first principal component should be'
+                                   'at least {}, but it is {}'
+                                   .format(first_pca_threshold,
+                                           pca.explained_variance_ratio_[0]))
+            direction = pca.components_[0]
+
+            # if direction is opposite (e.g. we cannot control
+            # what the PCA will return)
+            ends_diff_projection = cosine_similarity((self[positive_end]
+                                                      - self[negative_end]),
+                                                     direction)
+            if ends_diff_projection < 0:
+                direction = -direction  # pylint: disable=invalid-unary-operand-type
+
+        self.direction = direction
+        self.positive_end = positive_end
+        self.negative_end = negative_end
+
+    def project_on_direction(
+        self, 
+        word: str
+    ) -> float:
+
+        """Project the normalized vector of the word on the direction.
+        :param str word: The word tor project
+        :return float: The projection scalar
+        """
+
+        self._is_direction_identified()
+
+        vector = self[word]
+        projection_score = self.embedding.cosineSimilarities(self.direction,
+                                                          [vector])[0]
+        return projection_score
+
+    def _calc_projection_scores(
+        self, 
+        words: List[str]
+    ) -> pd.DataFrame:
+
+        self._is_direction_identified()
+
+        df = pd.DataFrame({'word': words})
+
+        # TODO: maybe using cosine_similarities on all the vectors?
+        # it might be faster
+        df['projection'] = df['word'].apply(self.project_on_direction)
+        df = df.sort_values('projection', ascending=False)
+
+        return df
+
+    def calc_projection_data(
+        self, 
+        words: List[str]
+    ) -> pd.DataFrame:
+
+        """
+        Calculate projection, projected and rejected vectors of a words list.
+        :param list words: List of words
+        :return: :class:`pandas.DataFrame` of the projection,
+                 projected and rejected vectors of the words list
+        """
+        projection_data = []
+        for word in words:
+            vector = self[word]
+            normalized_vector = normalize(vector)
+
+            (projection,
+             projected_vector,
+             rejected_vector) = project_params(normalized_vector,
+                                               self.direction)
+
+            projection_data.append({'word': word,
+                                    'vector': vector,
+                                    'projection': projection,
+                                    'projected_vector': projected_vector,
+                                    'rejected_vector': rejected_vector})
+
+        return pd.DataFrame(projection_data)
+
+    def plot_dist_projections_on_direction(
+        self, 
+        word_groups: Dict[str, List[str]], 
+        ax: plt.Axes=None
+    ) -> plt.Axes:
+
+        """Plot the projection scalars distribution on the direction.
+        :param dict word_groups word: The groups to projects
+        :return float: The ax object of the plot
+        """
+
+        if ax is None:
+            _, ax = plt.subplots(1)
+
+        names = sorted(word_groups.keys())
+
+        for name in names:
+            words = word_groups[name]
+            label = '{} (#{})'.format(name, len(words))
+            vectors = [self[word] for word in words]
+            projections = self.embedding.cosineSimilarities(self.direction,
+                                                         vectors)
+            sns.distplot(projections, hist=False, label=label, ax=ax)
+
+        plt.axvline(0, color='k', linestyle='--')
+
+        plt.title('← {} {} {} →'.format(self.negative_end,
+                                        ' ' * 20,
+                                        self.positive_end))
+        plt.xlabel('Direction Projection')
+        plt.ylabel('Density')
+        ax.legend(loc='center left', bbox_to_anchor=(1, 0.5))
+
+        return ax
+
+    def __errorChecking(
+        self, 
+        word: str
+    ) -> str:
+
+        out_msj = ""
+
+        if not word:
+            out_msj = ['EMBEDDING_NO_WORD_PROVIDED']
+        else:
+            if word not in self.embedding:
+                out_msj = ['EMBEDDING_WORD_OOV', word]
+
+        return self.errorManager.process(out_msj)
+
+    def check_oov(
+        self, 
+        wordlists: List[str]
+    ) -> str:
+
+        for wordlist in wordlists:
+            for word in wordlist:
+                msg = self.__errorChecking(word)
+                if msg:
+                    return msg
+        return None
+    
+class WEBiasExplorer2Spaces(WordBiasExplorer):
+    def __init__(
+        self, 
+        embedding,      # Embedding class instance
+        errorManager    # ErrorManager class instance
+    ) -> None:
+
+        super().__init__(embedding, errorManager)
+
+    def calculate_bias(
+        self,
+        wordlist_to_diagnose: List[str],
+        wordlist_right: List[str],
+        wordlist_left: List[str]
+    ) -> plt.Figure:
+
+        wordlists = [wordlist_to_diagnose, wordlist_right, wordlist_left] 
+        
+        for wordlist in wordlists:
+            if not wordlist:
+                raise Exception('At least one word should be in the to diagnose list, bias 1 list and bias 2 list')
+        
+        err = self.check_oov(wordlists)
+        if err:
+            raise Exception(err)
+
+        return self.get_bias_plot(
+                wordlist_to_diagnose,
+                definitional=(wordlist_left, wordlist_right),
+                method='sum',
+                n_extreme=10
+            )
+
+    def get_bias_plot(
+        self,
+        wordlist_to_diagnose: List[str],
+        definitional: Tuple[List[str], List[str]],
+        method: str='sum',
+        n_extreme: int=10,
+        figsize: Tuple[int, int]=(10, 10)
+    ) -> plt.Figure:
+
+        fig, ax = plt.subplots(1, figsize=figsize)
+        self.method = method
+        self.plot_projection_scores(
+            definitional,
+            wordlist_to_diagnose, n_extreme, ax=ax,)
+
+        fig.tight_layout()
+        fig.canvas.draw()
+
+        return fig
+
+    def plot_projection_scores(
+        self, 
+        definitional: Tuple[List[str], List[str]],
+        words: List[str], 
+        n_extreme: int=10,
+        ax: plt.Axes=None, 
+        axis_projection_step: float=None
+    ) -> plt.Axes:
+
+        """Plot the projection scalar of words on the direction.
+        :param list words: The words tor project
+        :param int or None n_extreme: The number of extreme words to show
+        :return: The ax object of the plot
+        """
+        name_left = ', '.join(definitional[0])
+        name_right = ', '.join(definitional[1])
+
+        self._identify_direction(name_left, name_right,
+                                 definitional=definitional,
+                                 method='sum')
+
+        self._is_direction_identified()
+
+        projections_df = self._calc_projection_scores(words)
+        projections_df['projection'] = projections_df['projection'].round(2)
+
+        if n_extreme is not None:
+            projections_df = take_two_sides_extreme_sorted(projections_df,
+                                                           n_extreme=n_extreme)
+
+        if ax is None:
+            _, ax = plt.subplots(1)
+
+        if axis_projection_step is None:
+            axis_projection_step = 0.1
+
+        cmap = plt.get_cmap('RdBu')
+        projections_df['color'] = ((projections_df['projection'] + 0.5)
+                                   .apply(cmap))
+
+        most_extream_projection = np.round(
+            projections_df['projection']
+            .abs()
+            .max(),
+            decimals=1)
+
+        sns.barplot(x='projection', y='word', data=projections_df,
+                    palette=projections_df['color'])
+
+        plt.xticks(np.arange(-most_extream_projection,
+                             most_extream_projection + axis_projection_step,
+                             axis_projection_step))
+        xlabel = ('← {} {} {} →'.format(self.negative_end,
+                                        ' ' * 20,
+                                        self.positive_end))
+
+        plt.xlabel(xlabel)
+        plt.ylabel('Words')
+
+        return ax
+
+
+class WEBiasExplorer4Spaces(WordBiasExplorer):
+    def __init__(
+        self, 
+        embedding,      # Embedding Class instance
+        errorManager    # ErrorManager class instance
+    ) -> None:
+
+        super().__init__(embedding, errorManager)
+
+    def calculate_bias(
+        self,
+        wordlist_to_diagnose: List[str],
+        wordlist_right: List[str],
+        wordlist_left: List[str],
+        wordlist_top: List[str],
+        wordlist_bottom: List[str],
+    ) -> plt.Figure:
+
+        wordlists = [
+            wordlist_to_diagnose,
+            wordlist_left,
+            wordlist_right,
+            wordlist_top,
+            wordlist_bottom
+        ]
+
+        for wordlist in wordlists:
+            if not wordlist:
+                raise Exception('To plot with 4 spaces, you must enter at least one word in all lists')
+
+        err = self.check_oov(wordlists)
+        if err:
+            raise Exception(err)
+
+        return self.get_bias_plot(
+                wordlist_to_diagnose,
+                definitional_1=(wordlist_right, wordlist_left),
+                definitional_2=(wordlist_top, wordlist_bottom),
+                method='sum',
+                n_extreme=10
+            )
+
+    def get_bias_plot(
+        self,
+        wordlist_to_diagnose: List[str],
+        definitional_1: Tuple[List[str], List[str]],
+        definitional_2: Tuple[List[str], List[str]],
+        method: str='sum',
+        n_extreme: int=10,
+        figsize: Tuple[int, int]=(10, 10)
+    ) -> plt.Figure:
+
+        fig, ax = plt.subplots(1, figsize=figsize)
+        self.method = method
+        self.plot_projection_scores(
+            definitional_1,
+            definitional_2,
+            wordlist_to_diagnose, n_extreme, ax=ax,)
+        fig.canvas.draw()
+
+        return fig
+
+    def plot_projection_scores(
+        self, 
+        definitional_1: Tuple[List[str], List[str]], 
+        definitional_2: Tuple[List[str], List[str]],
+        words: List[str], 
+        n_extreme: int=10,
+        ax: plt.Axes=None, 
+        axis_projection_step: float=None
+    ) -> plt.Axes:
+
+        """Plot the projection scalar of words on the direction.
+        :param list words: The words tor project
+        :param int or None n_extreme: The number of extreme words to show
+        :return: The ax object of the plot
+        """
+
+        name_left = ', '.join(definitional_1[1])
+        name_right = ', '.join(definitional_1[0])
+
+        self._identify_direction(name_left, name_right,
+                                 definitional=definitional_1,
+                                 method='sum')
+
+        self._is_direction_identified()
+
+        projections_df = self._calc_projection_scores(words)
+        projections_df['projection_x'] = projections_df['projection'].round(2)
+
+        name_top = ', '.join(definitional_2[1])
+        name_bottom = ', '.join(definitional_2[0])
+        self._identify_direction(name_top, name_bottom,
+                                 definitional=definitional_2,
+                                 method='sum')
+
+        self._is_direction_identified()
+
+        projections_df['projection_y'] = self._calc_projection_scores(words)[
+            'projection'].round(2)
+
+        if n_extreme is not None:
+            projections_df = take_two_sides_extreme_sorted(projections_df,
+                                                           n_extreme=n_extreme)
+
+        if ax is None:
+            _, ax = plt.subplots(1)
+
+        if axis_projection_step is None:
+            axis_projection_step = 0.1
+
+        cmap = plt.get_cmap('RdBu')
+        projections_df['color'] = ((projections_df['projection'] + 0.5)
+                                   .apply(cmap))
+        most_extream_projection = np.round(
+            projections_df['projection']
+            .abs()
+            .max(),
+            decimals=1
+        )
+        
+        sns.scatterplot(x='projection_x', 
+                        y='projection_y', 
+                        data=projections_df,
+                        # color=list(projections_df['color'].to_list()), # No se distinguen los colores
+                        color='blue'
+        )
+
+        plt.xticks(np.arange(-most_extream_projection,
+                             most_extream_projection + axis_projection_step,
+                             axis_projection_step))
+        for _, row in (projections_df.iterrows()):
+            ax.annotate(
+                row['word'], (row['projection_x'], row['projection_y']))
+        x_label = '← {} {} {} →'.format(name_left,
+                                        ' ' * 20,
+                                        name_right)
+
+        y_label = '← {} {} {} →'.format(name_top,
+                                        ' ' * 20,
+                                        name_bottom)
+
+        plt.xlabel(x_label)
+        ax.xaxis.set_label_position('bottom')
+        ax.xaxis.set_label_coords(.5, 0)
+
+        plt.ylabel(y_label)
+        ax.yaxis.set_label_position('left')
+        ax.yaxis.set_label_coords(0, .5)
+
+        ax.spines['left'].set_position('center')
+        ax.spines['bottom'].set_position('center')
+
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+        return ax

modules/module_ErrorManager.py

@@ -0,0 +1,34 @@
+import pandas as pd
+from typing import List
+
+class ErrorManager:
+    def __init__(
+        self, 
+        path: str,
+        str_to_prepend: str="<center><h3>",
+        str_to_append: str="</h3></center>"
+    ) -> None:
+
+        self.error2text = pd.read_json(path)["errors"]
+        self.str_to_prepend = str_to_prepend
+        self.str_to_append  = str_to_append
+
+    def __get_text_from_code(
+        self, 
+        error_info: str
+    ) -> str:
+
+        error_code = error_info[0]
+        error_args = error_info[1:]
+        return str(self.error2text[error_code]).format(*error_args)
+
+    def process(
+        self, 
+        error_info: List[str],
+    ) -> str:
+
+        if not error_info:
+            return ""
+        
+        error = self.__get_text_from_code(error_info=error_info)
+        return self.str_to_prepend + error + self.str_to_append

modules/module_WordExplorer.py

@@ -0,0 +1,255 @@
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+from numpy.linalg import norm
+
+import matplotlib as mpl
+mpl.use('Agg')
+from typing import List, Dict, Tuple
+
+
+class WordToPlot:
+    def __init__(
+        self,
+        word: str,
+        color: str,
+        bias_space: int,
+        alpha: float
+    ) -> None:
+
+        self.word = word
+        self.color = color
+        self.bias_space = bias_space
+        self.alpha = alpha
+
+
+class WordExplorer:
+    def __init__(
+        self,
+        embedding,      # Embedding Class instance
+        errorManager    # ErrorManager class instance
+    ) -> None:
+
+        self.embedding = embedding
+        self.errorManager = errorManager
+
+    def __errorChecking(
+        self,
+        word: str
+    ) -> str:
+
+        out_msj = ""
+
+        if not word:
+            out_msj = ['EMBEDDING_NO_WORD_PROVIDED']
+        else:
+            if word not in self.embedding:
+                out_msj = ['EMBEDDING_WORD_OOV', word]
+
+        return self.errorManager.process(out_msj)
+
+    def check_oov(
+        self, 
+        wordlists: List[List[str]]
+    ) -> str:
+
+        for wordlist in wordlists:
+            for word in wordlist:
+                msg = self.__errorChecking(word)
+                if msg:
+                    return msg
+        return None
+
+    def get_neighbors(
+        self, 
+        word: str, 
+        n_neighbors: int, 
+        nn_method: str
+    ) -> List[str]:
+
+        err = self.check_oov([[word]])
+        if err:
+            raise Exception(err)
+        
+        return self.embedding.getNearestNeighbors(word, n_neighbors, nn_method)
+
+    def get_df(
+        self, 
+        words_embedded: np.ndarray, 
+        processed_word_list: List[str]
+    ) -> pd.DataFrame:
+
+        df = pd.DataFrame(words_embedded)
+
+        df['word'] = [wtp.word for wtp in processed_word_list]
+        df['color'] = [wtp.color for wtp in processed_word_list]
+        df['alpha'] = [wtp.alpha for wtp in processed_word_list]
+        df['word_bias_space'] = [wtp.bias_space for wtp in processed_word_list]
+        return df
+
+    def get_plot(
+        self,
+        data: pd.DataFrame,
+        processed_word_list: List[str],
+        words_embedded: np.ndarray,
+        color_dict: Dict,
+        n_neighbors: int,
+        n_alpha: float,
+        fontsize: int=18,
+        figsize: Tuple[int, int]=(20, 15)
+    ):
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        sns.scatterplot(
+            data=data[data['alpha'] == 1],
+            x=0,
+            y=1,
+            style='word_bias_space',
+            hue='word_bias_space',
+            ax=ax,
+            palette=color_dict
+        )
+
+        if n_neighbors > 0:
+            sns.scatterplot(
+                data=data[data['alpha'] != 1],
+                x=0,
+                y=1,
+                style='color',
+                hue='word_bias_space',
+                ax=ax,
+                alpha=n_alpha,
+                legend=False,
+                palette=color_dict
+            )
+            
+        for i, wtp in enumerate(processed_word_list):
+            x, y = words_embedded[i, :]
+            ax.annotate(
+                wtp.word, 
+                xy=(x, y), 
+                xytext=(5, 2), 
+                color=wtp.color,
+                textcoords='offset points',
+                ha='right', 
+                va='bottom', 
+                size=fontsize, 
+                alpha=wtp.alpha
+            )
+
+        ax.set_xticks([])
+        ax.set_yticks([])
+        ax.set_xlabel('')
+        ax.set_ylabel('')
+        fig.tight_layout()
+
+        return fig
+
+    def plot_projections_2d(
+        self,
+        wordlist_0: List[str],
+        wordlist_1: List[str]=[],
+        wordlist_2: List[str]=[],
+        wordlist_3: List[str]=[],
+        wordlist_4: List[str]=[],
+        **kwargs
+    ):
+
+        # convertirlas a vector
+        choices = [0, 1, 2, 3, 4]
+        wordlist_choice = [
+            wordlist_0,
+            wordlist_1,
+            wordlist_2,
+            wordlist_3,
+            wordlist_4
+        ]
+
+        err = self.check_oov(wordlist_choice)
+        if err:
+            raise Exception(err)
+
+        color_dict = {
+            0: kwargs.get('color_wordlist_0', '#000000'),
+            1: kwargs.get('color_wordlist_1', '#1f78b4'),
+            2: kwargs.get('color_wordlist_2', '#33a02c'),
+            3: kwargs.get('color_wordlist_3', '#e31a1c'),
+            4: kwargs.get('color_wordlist_4', '#6a3d9a')
+        }
+
+        n_neighbors = kwargs.get('n_neighbors', 0)
+        n_alpha = kwargs.get('n_alpha', 0.3)
+
+        processed_word_list = []
+        for word_list_to_process, color in zip(wordlist_choice, choices):
+            for word in word_list_to_process:
+                processed_word_list.append(
+                    WordToPlot(word, color_dict[color], color, 1)
+                )
+
+                if n_neighbors > 0:
+                    neighbors = self.get_neighbors(
+                        word,
+                        n_neighbors=n_neighbors,
+                        nn_method=kwargs.get('nn_method', 'sklearn')
+                    )
+
+                    for n in neighbors:
+                        if n not in [wtp.word for wtp in processed_word_list]:
+                            processed_word_list.append(
+                                WordToPlot(n, color_dict[color], color, n_alpha)
+                            )
+
+        if not processed_word_list:
+            raise Exception('Only empty lists were passed')
+
+        words_embedded = np.array(
+            [self.embedding.getPCA(wtp.word) for wtp in processed_word_list]
+        )
+
+        data = self.get_df(
+            words_embedded, 
+            processed_word_list
+        )
+
+        fig = self.get_plot(
+            data, 
+            processed_word_list, 
+            words_embedded,
+            color_dict, 
+            n_neighbors, 
+            n_alpha,
+            kwargs.get('fontsize', 18),
+            kwargs.get('figsize', (20, 15))
+        )
+
+        plt.show()
+        return fig
+
+    # ToDo: No hay usos de este método. ¿Borrar?
+    def doesnt_match(
+        self, 
+        wordlist: List[str]
+    ) -> str:
+
+        err = self.check_oov([wordlist])
+        if err:
+            raise Exception(err)
+
+        words_emb = np.array([self.embedding.getEmbedding(word)
+                             for word in wordlist])
+        mean_vec = np.mean(words_emb, axis=0)
+
+        doesnt_match = ""
+        farthest_emb = 1.0
+        for word in wordlist:
+            word_emb = self.embedding.getEmbedding(word)
+            cos_sim = np.dot(mean_vec, word_emb) / \
+                (norm(mean_vec)*norm(word_emb))
+            if cos_sim <= farthest_emb:
+                farthest_emb = cos_sim
+                doesnt_match = word
+
+        return doesnt_match

modules/module_ann.py

@@ -0,0 +1,91 @@
+import time
+from tqdm import tqdm
+from annoy import AnnoyIndex
+from typing import List
+
+class TicToc:
+    def __init__(
+        self
+    ) -> None:
+
+        self.i = None
+
+    def start(
+        self
+    ) -> None:
+
+        self.i = time.time()
+
+    def stop(
+        self
+    ) -> None:
+
+        f = time.time()
+        print(f - self.i, "seg.")
+
+
+class Ann:
+    def __init__(
+        self, 
+        words: List[str], 
+        vectors: List, 
+        coord: List, 
+    ) -> None:
+
+        self.words = words
+        self.vectors = vectors
+        self.coord = coord
+        self.tree = None
+
+        self.tt = TicToc()
+        self.availables_metrics = ['angular','euclidean','manhattan','hamming','dot']
+
+    def init(self, 
+        n_trees: int=10, 
+        metric: str='angular', 
+        n_jobs: int=-1  # n_jobs=-1 Run over all CPU availables
+    ) -> None:
+
+        assert(metric in self.availables_metrics), f"Error: The value of the parameter 'metric' can only be {self.availables_metrics}!"
+
+        print("\tInit tree...")
+        self.tt.start()
+        self.tree = AnnoyIndex(len(self.vectors[0]), metric=metric)
+        for i, v in tqdm(enumerate(self.vectors), total=len(self.vectors)):
+            self.tree.add_item(i, v)
+        self.tt.stop()
+
+        print("\tBuild tree...")
+        self.tt.start()
+        self.tree.build(n_trees=n_trees, n_jobs=n_jobs)
+        self.tt.stop()
+
+    def __getWordId(
+        self, 
+        word: str
+    ) -> int:
+
+        word_id = None
+        try:
+            word_id = self.words.index(word)
+        except:
+            pass
+        return word_id
+
+    def get(
+        self, 
+        word: str, 
+        n_neighbors: int=10
+    ) -> List[str]:
+        
+        word_id = self.__getWordId(word)
+        neighbors_list = None
+
+        if word_id != None:
+            neighbords_id = self.tree.get_nns_by_item(word_id, n_neighbors + 1)
+            neighbors_list = [self.words[idx] for idx in neighbords_id][1:]
+
+        else:
+            print(f"The word '{word}' does not exist")
+
+        return neighbors_list

modules/module_connection.py

@@ -0,0 +1,517 @@
+import csv, os
+import pandas as pd
+import gradio as gr
+from abc import ABC
+from modules.utils import DateLogs
+from typing import List, Tuple, Any
+from modules.module_WordExplorer import WordExplorer
+from modules.module_BiasExplorer import WEBiasExplorer2Spaces, WEBiasExplorer4Spaces
+from modules.module_word2Context import Word2Context
+from modules.module_rankSents import RankSents
+from modules.module_crowsPairs import CrowsPairs
+from modules.module_ErrorManager import ErrorManager
+
+
+class Connector(ABC):
+
+    def __init__(
+        self,
+        lang: str
+    ) -> None:
+
+        self.datalog = DateLogs()
+        self.log_folder = 'logs'
+
+        if not hasattr(Connector, 'errorManager'):
+            Connector.errorManager = ErrorManager(
+                path=f"modules/error_messages/{lang}.json"
+            )
+
+    def parse_word(
+        self, 
+        word: str
+    ) -> str:
+        
+        return word.lower().strip()
+
+    def parse_words(
+        self, 
+        array_in_string: str
+    ) -> List[str]:
+
+        words = array_in_string.strip()
+        if not words:
+            return []
+
+        words = [
+            self.parse_word(word) 
+            for word in words.split(',') if word.strip() != ''
+        ]
+        return words
+    
+    def logs_save(
+        self,
+        file_name: str,
+        headers: List[str]=None,
+        *data: List[Any]
+    ) -> None:
+
+        if file_name is None:
+            return None
+
+        if not os.path.exists(self.log_folder):
+            print(f"Creating logs folder '{self.log_folder}' ...")
+            os.mkdir(self.log_folder)
+
+        file_path = os.path.join(self.log_folder, file_name+'.csv')
+        f_out = None
+
+        if not os.path.exists(file_path):
+            print(f"Creating new '{file_name}' logs file...")
+
+            with open(file_path, mode='w', encoding='UTF8') as f_out:
+                # Create the csv writer
+                writer = csv.writer(f_out)
+                
+                # Write the header
+                if headers is None:
+                    headers = [
+                        "input_" + str(ith)  
+                        for ith,_ in enumerate(data)
+                    ]
+                headers = headers + ["datatime"]
+
+                writer.writerow(headers)
+                    
+        with open(file_path, mode='a', encoding='UTF8') as f_out:
+            # Create the csv writer
+            writer = csv.writer(f_out)
+
+            # Write a row to the csv file
+            data = list(data) + [ self.datalog.full() ]
+            writer.writerow(data)
+
+            print(f"Logs: '{file_path}' successfully saved!")
+
+class WordExplorerConnector(Connector):
+    def __init__(
+        self, 
+        **kwargs
+    ) -> None:
+
+        Connector.__init__(self, kwargs.get('lang', 'en'))
+        embedding = kwargs.get('embedding', None)
+        self.logs_file_name = kwargs.get('logs_file_name', None)
+        self.headers = [
+            "word_list_to_diagnose",
+            "word_list_1",
+            "word_list_2",
+            "word_list_3",
+            "word_list_4"
+        ]
+        
+        if embedding is None:
+            raise KeyError
+        
+        self.word_explorer = WordExplorer(
+            embedding=embedding,
+            errorManager=self.errorManager
+        )
+
+    def plot_proyection_2d( 
+        self,
+        wordlist_0: str,
+        wordlist_1: str,
+        wordlist_2: str,
+        wordlist_3: str,
+        wordlist_4: str,
+        color_wordlist_0: str,
+        color_wordlist_1: str,
+        color_wordlist_2: str,
+        color_wordlist_3: str,
+        color_wordlist_4: str,
+        n_alpha: float,
+        fontsize: int,
+        n_neighbors: int
+    ) -> Tuple:
+
+        err = ""
+        neighbors_method = 'sklearn'
+        wordlist_0 = self.parse_words(wordlist_0)
+        wordlist_1 = self.parse_words(wordlist_1)
+        wordlist_2 = self.parse_words(wordlist_2)
+        wordlist_3 = self.parse_words(wordlist_3)
+        wordlist_4 = self.parse_words(wordlist_4)
+
+        if not (wordlist_0 or wordlist_1 or wordlist_2 or wordlist_1 or wordlist_4):
+            err = self.errorManager.process(['CONECTION_NO_WORD_ENTERED'])
+            return None, err
+        
+        err = self.word_explorer.check_oov(
+            [wordlist_0, wordlist_1, wordlist_2, wordlist_3, wordlist_4]
+        )
+
+        if err:
+            return None, err
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name,
+            self.headers,
+            wordlist_0,
+            wordlist_1,
+            wordlist_2,
+            wordlist_3,
+            wordlist_4,
+        )
+
+        fig = self.word_explorer.plot_projections_2d(
+            wordlist_0,
+            wordlist_1,
+            wordlist_2,
+            wordlist_3,
+            wordlist_4,
+            color_wordlist_0=color_wordlist_0,
+            color_wordlist_1=color_wordlist_1,
+            color_wordlist_2=color_wordlist_2,
+            color_wordlist_3=color_wordlist_3,
+            color_wordlist_4=color_wordlist_4,
+            n_alpha=n_alpha,
+            fontsize=fontsize,
+            n_neighbors=n_neighbors,
+            nn_method = neighbors_method
+        )
+
+        return fig, err
+
+class BiasWordExplorerConnector(Connector):
+
+    def __init__(
+        self, 
+        **kwargs
+    ) -> None:
+
+        Connector.__init__(self, kwargs.get('lang', 'en'))
+        embedding = kwargs.get('embedding', None)
+        self.logs_file_name = kwargs.get('logs_file_name', None)
+        self.headers = [
+            "word_list_to_diagnose",
+            "word_list_1",
+            "word_list_2",
+            "word_list_3",
+            "word_list_4",
+            "plot_space"
+        ]
+
+        if embedding is None:
+            raise KeyError
+
+        self.bias_word_explorer_2_spaces = WEBiasExplorer2Spaces(
+            embedding=embedding,
+            errorManager=self.errorManager
+        )
+        self.bias_word_explorer_4_spaces = WEBiasExplorer4Spaces(
+            embedding=embedding,
+            errorManager=self.errorManager
+        )
+
+    def calculate_bias_2d(
+        self,
+        wordlist_1: str,
+        wordlist_2: str,
+        to_diagnose_list: str
+    ) -> Tuple:
+
+        err = ""
+        wordlist_1 = self.parse_words(wordlist_1)
+        wordlist_2 = self.parse_words(wordlist_2)
+        to_diagnose_list = self.parse_words(to_diagnose_list)
+
+        word_lists = [wordlist_1, wordlist_2, to_diagnose_list]
+        for _list in word_lists:
+            if not _list:
+                err = self.errorManager.process(['BIASEXPLORER_NOT_ENOUGH_WORD_2_KERNELS'])
+        if err:
+            return None, err
+
+        err = self.bias_word_explorer_2_spaces.check_oov(word_lists)
+        if err:
+            return None, err
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name,
+            self.headers,
+            to_diagnose_list,
+            wordlist_1,
+            wordlist_2,
+            "",
+            "",
+            "2d"
+        )
+
+        fig = self.bias_word_explorer_2_spaces.calculate_bias(
+            to_diagnose_list, 
+            wordlist_1, 
+            wordlist_2
+        )
+
+        return fig, err
+
+    def calculate_bias_4d(
+        self,
+        wordlist_1: str,
+        wordlist_2: str,
+        wordlist_3: str,
+        wordlist_4: str,
+        to_diagnose_list: str
+    ) -> Tuple:
+
+        err = ""
+        wordlist_1 = self.parse_words(wordlist_1)
+        wordlist_2 = self.parse_words(wordlist_2)
+        wordlist_3 = self.parse_words(wordlist_3)
+        wordlist_4 = self.parse_words(wordlist_4)
+        to_diagnose_list = self.parse_words(to_diagnose_list)
+
+        wordlists = [wordlist_1, wordlist_2, wordlist_3, wordlist_4, to_diagnose_list]
+        for _list in wordlists:
+            if not _list:
+                err = self.errorManager.process(['BIASEXPLORER_NOT_ENOUGH_WORD_4_KERNELS'])
+        if err:
+            return None, err
+
+        err = self.bias_word_explorer_4_spaces.check_oov(wordlists)
+        if err:
+            return None, err
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name,
+            self.headers,
+            to_diagnose_list, 
+            wordlist_1, 
+            wordlist_2, 
+            wordlist_3, 
+            wordlist_4,
+            "4d"
+        )
+
+        fig = self.bias_word_explorer_4_spaces.calculate_bias(
+            to_diagnose_list, 
+            wordlist_1, 
+            wordlist_2, 
+            wordlist_3, 
+            wordlist_4
+        )
+        
+        return fig, err
+
+class Word2ContextExplorerConnector(Connector):
+    def __init__(
+        self, 
+        **kwargs
+    ) -> None:
+
+        Connector.__init__(self, kwargs.get('lang', 'en'))
+        vocabulary = kwargs.get('vocabulary', None)
+        context = kwargs.get('context', None)
+        self.logs_file_name = kwargs.get('logs_file_name', None)
+        self.headers = [
+            "word",
+            "subsets_choice"
+        ]
+
+        if vocabulary is None or context is None:
+            raise KeyError
+
+        self.word2context_explorer = Word2Context(
+            context,
+            vocabulary,
+            errorManager=self.errorManager
+        )
+
+    def get_word_info(
+        self, 
+        word: str
+    ) -> Tuple:
+    
+        err = ""
+        contexts = pd.DataFrame([], columns=[''])
+        subsets_info = ""
+        distribution_plot = None
+        word_cloud_plot = None
+        subsets_choice = gr.CheckboxGroup.update(choices=[])
+
+        err = self.word2context_explorer.errorChecking(word)
+        if err:
+            return err, contexts, subsets_info, distribution_plot, word_cloud_plot, subsets_choice
+
+        word = self.parse_word(word)
+
+        subsets_info, subsets_origin_info = self.word2context_explorer.getSubsetsInfo(word)
+
+        clean_keys = [key.split(" ")[0].strip() for key in subsets_origin_info]
+        subsets_choice = gr.CheckboxGroup.update(choices=clean_keys)
+
+        distribution_plot = self.word2context_explorer.genDistributionPlot(word)
+        word_cloud_plot = self.word2context_explorer.genWordCloudPlot(word)
+
+        return err, contexts, subsets_info, distribution_plot, word_cloud_plot, subsets_choice
+
+    def get_word_context(
+        self,
+        word: str,
+        n_context: int,
+        subset_choice: List[str]
+    ) -> Tuple:
+
+        word = self.parse_word(word)
+        err = ""
+        contexts = pd.DataFrame([], columns=[''])
+
+        err = self.word2context_explorer.errorChecking(word)
+        if err:
+            return err, contexts
+
+        if len(subset_choice) > 0:
+            ds = self.word2context_explorer.findSplits(word, subset_choice)
+        else:
+            err = self.errorManager.process(['WORD2CONTEXT_WORDS_OR_SET_MISSING'])
+            return err, contexts
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name, 
+            self.headers,
+            word,
+            subset_choice
+        )
+
+        list_of_contexts = self.word2context_explorer.getContexts(word, n_context, ds)
+
+        contexts = pd.DataFrame(list_of_contexts, columns=['#','contexto','conjunto'])
+        contexts["buscar"] = contexts.contexto.apply(lambda text: self.word2context_explorer.genWebLink(text))
+
+        return err, contexts
+
+class PhraseBiasExplorerConnector(Connector):
+    def __init__(
+        self, 
+        **kwargs
+    ) -> None:
+
+        Connector.__init__(self, kwargs.get('lang', 'en'))
+        language_model = kwargs.get('language_model', None)
+        lang =  kwargs.get('lang', None)
+        self.logs_file_name = kwargs.get('logs_file_name', None)
+        self.headers = [
+            "sent",
+            "word_list"
+        ]
+
+        if language_model is None or lang is None:
+            raise KeyError
+
+        self.phrase_bias_explorer = RankSents(
+            language_model=language_model,
+            lang=lang,
+            errorManager=self.errorManager
+        )
+
+    def rank_sentence_options(
+        self,
+        sent: str,
+        word_list: str,
+        banned_word_list: str,
+        useArticles: bool,
+        usePrepositions: bool,
+        useConjunctions: bool
+    ) -> Tuple:
+
+        sent = " ".join(sent.strip().replace("*"," * ").split())
+
+        err = self.phrase_bias_explorer.errorChecking(sent)
+        if err:
+            return err, "", ""
+
+        word_list = self.parse_words(word_list)
+        banned_word_list = self.parse_words(banned_word_list)
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name, 
+            self.headers,
+            sent,
+            word_list
+        )
+
+        all_plls_scores = self.phrase_bias_explorer.rank(
+            sent, 
+            word_list, 
+            banned_word_list, 
+            useArticles, 
+            usePrepositions, 
+            useConjunctions
+        )
+        
+        all_plls_scores = self.phrase_bias_explorer.Label.compute(all_plls_scores)
+        return err, all_plls_scores, ""
+
+class CrowsPairsExplorerConnector(Connector):
+    def __init__(
+        self, 
+        **kwargs
+    ) -> None:
+
+        Connector.__init__(self, kwargs.get('lang', 'en'))
+        language_model = kwargs.get('language_model', None)
+        self.logs_file_name = kwargs.get('logs_file_name', None)
+        self.headers = [
+            "sent_1",
+            "sent_2",
+            "sent_3",
+            "sent_4",
+            "sent_5",
+            "sent_6",
+        ]
+
+        if language_model is None:
+            raise KeyError
+        
+        self.crows_pairs_explorer = CrowsPairs(
+            language_model=language_model,
+            errorManager=self.errorManager
+        )
+
+    def compare_sentences(
+        self,
+        sent0: str,
+        sent1: str,
+        sent2: str,
+        sent3: str,
+        sent4: str,
+        sent5: str
+    ) -> Tuple:
+
+        sent_list = [sent0, sent1, sent2, sent3, sent4, sent5]
+        err = self.crows_pairs_explorer.errorChecking(
+            sent_list
+        )
+
+        if err:
+            return err, "", ""
+
+        # Save inputs in logs file
+        self.logs_save(
+            self.logs_file_name, 
+            self.headers,
+            sent_list
+        )
+
+        all_plls_scores = self.crows_pairs_explorer.rank(
+            sent_list
+        )
+        
+        all_plls_scores = self.crows_pairs_explorer.Label.compute(all_plls_scores)
+        return err, all_plls_scores, ""

modules/module_crowsPairs.py

@@ -0,0 +1,53 @@
+from modules.module_customPllLabel import CustomPllLabel
+from modules.module_pllScore import PllScore
+from typing import Dict, List
+
+class CrowsPairs:
+    def __init__(
+        self, 
+        language_model, # LanguageModel class instance
+        errorManager    # ErrorManager class instance
+    ) -> None:
+
+        self.Label = CustomPllLabel()
+        self.pllScore = PllScore(
+            language_model=language_model
+        )
+        self.errorManager = errorManager
+
+    def errorChecking(
+        self, 
+        sent_list: List[str],
+    ) -> str:
+
+        out_msj = ""
+
+        mandatory_sents = [0,1]
+        for sent_id, sent in enumerate(sent_list):
+            c_sent = sent.strip()
+            if c_sent:
+                if not self.pllScore.sentIsCorrect(c_sent):
+                    out_msj = ['CROWS-PAIRS_BAD_FORMATTED_SENTENCE', sent_id+1]
+                    break
+            else:
+                if sent_id in mandatory_sents:
+                    out_msj = ['CROWS-PAIRS_MANDATORY_SENTENCE_MISSING', sent_id+1]
+                    break
+        
+        return self.errorManager.process(out_msj)
+
+    def rank(
+        self, 
+        sent_list: List[str],
+    ) -> Dict[str, float]:
+
+        err = self.errorChecking(sent_list)
+        if err:
+            raise Exception(err)
+        
+        all_plls_scores = {}
+        for sent in sent_list:
+            if sent:
+                all_plls_scores[sent] = self.pllScore.compute(sent)
+
+        return all_plls_scores

modules/module_customPllLabel.py

@@ -0,0 +1,110 @@
+from typing import List, Dict
+
+class CustomPllLabel:
+    def __init__(
+        self
+    ) -> None:
+
+        self.html_head = """
+        <html>
+            <head>
+                <meta charset="utf-8">
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+                <style>
+                    progress {
+                        -webkit-appearance: none;
+                    }
+                    progress::-webkit-progress-bar {
+                        background-color: #666;
+                        border-radius: 7px;
+                    }
+                    #myturn span {
+                        position: absolute;
+                        display: inline-block;
+                        color: #fff;
+                        text-align: right;
+                        font-size:15px
+                    }
+                    #myturn {
+                        display: block;
+                        position: relative;
+                        margin: auto;
+                        width: 90%;
+                        padding: 2px;
+                    }
+                    progress {
+                        width:100%;
+                        height:20px;
+                        border-radius: 7px;
+                    }
+                </style>
+            </head>
+            <body>
+        """
+
+        self.html_footer ="</body></html>"
+    
+    def __progressbar(
+        self, 
+        percentage: int, 
+        sent: str, 
+        ratio: float, 
+        score: float, 
+        size: int=15
+    ) -> str:
+
+        html = f"""
+        <div id="myturn">
+            <span data-value="{percentage/2}" style="width:{percentage/2}%;">
+                <strong>x{round(ratio,3)}</strong>
+            </span>
+            <progress value="{percentage}" max="100"></progress>
+            <p style='font-size:22px; padding:2px;'>{sent}</p>
+        </div>
+        """
+        return html
+
+    def __render(
+        self, 
+        sents: List[str],
+        scores: List[float], 
+        ratios: List[float]
+    ) -> str:
+
+        max_ratio = max(ratios)
+        ratio2percentage = lambda ratio: int(ratio*100/max_ratio)
+
+        html = ""
+        for sent, ratio, score in zip(sents, ratios, scores):
+            html += self.__progressbar(
+                percentage=ratio2percentage(ratio), 
+                sent=sent,
+                ratio=ratio, 
+                score=score
+            )
+
+        return self.html_head + html + self.html_footer
+    
+    def __getProportions(
+        self, 
+        scores: List[float], 
+    ) -> List[float]:
+    
+        min_score = min(scores)
+        return [min_score/s for s in scores]
+
+    def compute(
+        self, 
+        pll_dict: Dict[str, float]
+    ) -> str:
+
+        sorted_pll_dict = dict(sorted(pll_dict.items(), key=lambda x: x[1], reverse=True))
+        
+        sents = list(sorted_pll_dict.keys())
+        # Scape < and > marks from hightlight word/s
+        sents = [s.replace("<","&#60;").replace(">","&#62;")for s in sents]
+
+        scores  = list(sorted_pll_dict.values())
+        ratios = self.__getProportions(scores)
+
+        return self.__render(sents, scores, ratios)

modules/module_customSubsetsLabel.py

@@ -0,0 +1,118 @@
+from typing import List, Dict
+
+class CustomSubsetsLabel:
+    def __init__(
+        self
+    ) -> None:
+
+        self.html_head = """
+        <html>
+            <head>
+                <meta charset="utf-8">
+                <meta name="viewport" content="width=device-width, initial-scale=1">
+                <style>
+                    progress {
+                        -webkit-appearance: none;
+                    }
+                    progress::-webkit-progress-bar {
+                        background-color: #666;
+                        border-radius: 7px;
+                    }
+                    progress {
+                        width:100%;
+                        height:4px;
+                        border-radius: 1px;
+                    }
+                    #myturn {
+                        display: block;
+                        position: relative;
+                        margin: auto;
+                        width: 90%;
+                        padding: 2px;
+                    }
+                </style>
+            </head>
+            <body>
+        """
+
+        self.html_footer ="</body></html>"
+
+        self.subset_links = {
+            'allwikis': "https://github.com/josecannete/wikiextractorforBERT",
+            'DGT': "http://opus.nlpl.eu/DGT.php",
+            'DOGC': "http://opus.nlpl.eu/DOGC.php",
+            'ECB': "http://opus.nlpl.eu/ECB.php",
+            'EMEA': "http://opus.nlpl.eu/EMEA.php",
+            'EUBookShop': "http://opus.nlpl.eu/EUbookshop.php",
+            'Europarl': "http://opus.nlpl.eu/Europarl.php",
+            'GlobalVoices': "http://opus.nlpl.eu/GlobalVoices.php",
+            'JRC': "http://opus.nlpl.eu/JRC-Acquis.php",
+            'multiUN': "http://opus.nlpl.eu/MultiUN.php",
+            'NewsCommentary11': "http://opus.nlpl.eu/News-Commentary-v11.php",
+            'OpenSubtitles2018': "http://opus.nlpl.eu/OpenSubtitles-v2018.php",
+            'ParaCrawl': "http://opus.nlpl.eu/ParaCrawl.php",
+            'TED': "http://opus.nlpl.eu/TED2013.php",
+            'UN': "http://opus.nlpl.eu/UN.php",
+        }
+
+    def __progressbar(
+        self, 
+        percentage: float, 
+        subset: str, 
+        freq: int, 
+        size: int=15
+    ) -> str:
+
+        html = f"""
+        <div id="myturn">
+            <progress value="{int(percentage)}" max="100"></progress>
+            <p style="text-align:left; font-size:{size}px; padding:0px;">
+                <a href="{self.subset_links[subset]}" target="_blank">
+                    <strong>{subset}</strong> <span style="font-size:{size-2}px">(Frecuencia: {freq})</span>
+                </a>
+                <span style="float:right;">
+                    <strong>{percentage}%</strong>
+                </span>
+            </p>
+        </div>
+        """
+        return html
+
+    def __render(
+        self, 
+        subsets: List[str], 
+        freqs: List[int], 
+        percentages: List[float]
+    ) -> str:
+
+        html = ""
+        for subset, freq, perc in zip(subsets, freqs, percentages):
+            html += self.__progressbar(
+                percentage=perc,
+                subset=subset,
+                freq=freq
+            )
+
+        return self.html_head + html + self.html_footer
+    
+    def compute(
+        self, 
+        subsets_dic: Dict[str, int]
+    ) -> str:
+
+        subsets_dic_info = {
+            k.split()[0]:{'freq':int(k.split()[1][1:-1]),'perc':round(v*100,2)} 
+            for k,v in subsets_dic.items()
+        }
+        
+        subsets = list(subsets_dic_info.keys())
+        freqs = [
+            d['freq'] 
+            for d in subsets_dic_info.values()
+        ]
+        percentages = [
+            d['perc'] 
+            for d in subsets_dic_info.values()
+        ]
+
+        return self.__render(subsets, freqs, percentages)

modules/module_languageModel.py

@@ -0,0 +1,27 @@
+from transformers import AutoTokenizer, AutoModelForMaskedLM
+import os
+
+# Disabling parallelism to avoid deadlocks in the hf tokenizer
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+class LanguageModel:
+    def __init__(
+        self, 
+        model_name
+    ) -> None:
+    
+        print("Downloading language model...")
+        self.__tokenizer = AutoTokenizer.from_pretrained(model_name)
+        self.__model = AutoModelForMaskedLM.from_pretrained(model_name)
+    
+    def initTokenizer(
+        self
+    ) -> AutoTokenizer:
+
+        return self.__tokenizer
+    
+    def initModel(
+        self
+    ) -> AutoModelForMaskedLM:
+
+        return self.__model

modules/module_pllScore.py

@@ -0,0 +1,147 @@
+from difflib import Differ
+import torch, re
+
+
+class PllScore:
+    def __init__(
+        self, 
+        language_model  # LanguageModel class instance
+    ) -> None:
+
+        self.tokenizer = language_model.initTokenizer()
+        self.model = language_model.initModel()
+        _ = self.model.eval()
+
+        self.logSoftmax = torch.nn.LogSoftmax(dim=-1)
+
+    def sentIsCorrect(
+        self, 
+        sent: str
+    ) -> bool:
+
+        # Mod
+        is_correct = True
+
+        # Check mark existence
+        open_mark = sent.count("<")
+        close_mark = sent.count(">")
+        total_mark = open_mark + close_mark
+        if (total_mark == 0) or (open_mark != close_mark):
+            is_correct = False
+
+        # Check existence of twin marks (ie: '<<' or '>>')
+        if is_correct:
+            left_twin = sent.count("<<")
+            rigth_twin = sent.count(">>")
+            if left_twin + rigth_twin > 0:
+                is_correct = False
+
+        if is_correct:
+            # Check balanced symbols '<' and '>'
+            stack = []
+            for c in sent:
+                if c == '<':
+                    stack.append('<')
+                elif c == '>':
+                    if len(stack) == 0:
+                        is_correct = False
+                        break
+
+                    if stack.pop() != "<":
+                        is_correct = False
+                        break
+
+            if len(stack) > 0:
+                is_correct = False
+
+        if is_correct:
+            for w in re.findall("\<.*?\>", sent):
+                # Check empty interest words
+                word = w.replace("<","").replace(">","").strip() 
+                if not word:
+                    is_correct = False
+                    break
+                
+                # Check if there are any marks inside others (ie: <this is a <sentence>>)
+                word = w.strip()[1:-1]  #Delete the first and last mark
+                if '<' in word or '>' in word:
+                    is_correct = False
+                    break
+        
+        if is_correct:
+            # Check that there is at least one uninteresting word. The next examples should not be allowed 
+            # (ie: <this is a sent>, <this> <is a sent>)
+            outside_words = re.sub("\<.*?\>", "", sent.replace("<", " < ").replace(">", " > "))
+            outside_words = [w for w in outside_words.split() if w != ""]
+            if not outside_words:
+                is_correct = False
+
+
+        return is_correct
+
+    def compute(
+        self, 
+        sent: str
+    ) -> float:
+
+        assert(self.sentIsCorrect(sent)), f"Error: The sentence '{sent}' does not have the correct format!"
+
+        outside_words = re.sub("\<.*?\>", "", sent.replace("<", " < ").replace(">", " > "))
+        outside_words = [w for w in outside_words.split() if w != ""]
+        all_words = [w.strip() for w in sent.replace("<"," ").replace(">"," ").split() if w != ""]
+
+        tks_id_outside_words = self.tokenizer.encode(
+            " ".join(outside_words), 
+            add_special_tokens=False, 
+            truncation=True
+        )
+        tks_id_all_words = self.tokenizer.encode(
+            " ".join(all_words), 
+            add_special_tokens=False,
+            truncation=True
+        )
+
+        diff = [(tk[0], tk[2:]) for tk in Differ().compare(tks_id_outside_words, tks_id_all_words)]
+
+        cls_tk_id = self.tokenizer.cls_token_id
+        sep_tk_id = self.tokenizer.sep_token_id
+        mask_tk_id = self.tokenizer.mask_token_id
+
+        all_sent_masked = []
+        all_tks_id_masked = []
+        all_tks_position_masked = []
+
+        for i in range(0, len(diff)):
+            current_sent_masked = [cls_tk_id]
+            add_sent = True
+            for j, (mark, tk_id) in enumerate(diff):
+                if j == i:
+                    if mark == '+':
+                        add_sent = False
+                        break
+                    else:
+                        current_sent_masked.append(mask_tk_id)
+                        all_tks_id_masked.append(int(tk_id))
+                        all_tks_position_masked.append(i+1)
+                else:
+                    current_sent_masked.append(int(tk_id))
+
+            if add_sent:
+                current_sent_masked.append(sep_tk_id)
+                all_sent_masked.append(current_sent_masked)
+        
+        inputs_ids = torch.tensor(all_sent_masked)
+        attention_mask = torch.ones_like(inputs_ids)
+
+        with torch.no_grad():
+            out = self.model(inputs_ids, attention_mask)
+            logits = out.logits
+            outputs = self.logSoftmax(logits)
+
+        pll_score = 0
+        for out, tk_pos, tk_id in zip(outputs, all_tks_position_masked, all_tks_id_masked):
+            probabilities = out[tk_pos]
+            tk_prob = probabilities[tk_id]
+            pll_score += tk_prob.item()
+
+        return pll_score

modules/module_rankSents.py

@@ -0,0 +1,171 @@
+from modules.module_customPllLabel import CustomPllLabel
+from modules.module_pllScore import PllScore
+from typing import List, Dict
+import torch
+
+
+class RankSents:
+    def __init__(
+        self, 
+        language_model, # LanguageModel class instance
+        lang: str,
+        errorManager    # ErrorManager class instance
+    ) -> None:
+        
+        self.tokenizer = language_model.initTokenizer()
+        self.model = language_model.initModel()
+        _ = self.model.eval()
+
+        self.Label = CustomPllLabel()
+        self.pllScore = PllScore(
+            language_model=language_model
+        )
+        self.softmax = torch.nn.Softmax(dim=-1)
+
+        if lang == "es":
+            self.articles = [
+                'un','una','unos','unas','el','los','la','las','lo'
+            ]
+            self.prepositions = [
+                'a','ante','bajo','cabe','con','contra','de','desde','en','entre','hacia','hasta','para','por','según','sin','so','sobre','tras','durante','mediante','vía','versus'
+            ]
+            self.conjunctions = [
+                'y','o','ni','que','pero','si'
+            ]
+
+        elif lang == "en":
+            self.articles = [
+                'a','an', 'the'
+            ]
+            self.prepositions = [
+                'above', 'across', 'against', 'along', 'among', 'around', 'at', 'before', 'behind', 'below', 'beneath', 'beside', 'between', 'by', 'down', 'from', 'in', 'into', 'near', 'of', 'off', 'on', 'to', 'toward', 'under', 'upon', 'with', 'within'
+            ]
+            self.conjunctions = [
+                'and', 'or', 'but', 'that', 'if', 'whether'
+            ]
+
+        self.errorManager = errorManager
+
+    def errorChecking(
+        self, 
+        sent: str
+    ) -> str:
+
+        out_msj = ""
+        if not sent:
+            out_msj = ['RANKSENTS_NO_SENTENCE_PROVIDED']
+        elif sent.count("*") > 1:
+            out_msj = ['RANKSENTS_TOO_MANY_MASKS_IN_SENTENCE']
+        elif sent.count("*") == 0:
+            out_msj = ['RANKSENTS_NO_MASK_IN_SENTENCE']
+        else:
+            sent_len = len(self.tokenizer.encode(sent.replace("*", self.tokenizer.mask_token)))
+            max_len = self.tokenizer.max_len_single_sentence
+            if sent_len > max_len:
+                out_msj = ['RANKSENTS_TOKENIZER_MAX_TOKENS_REACHED', max_len]
+        
+        return self.errorManager.process(out_msj)
+
+    def getTop5Predictions(
+        self, 
+        sent: str,
+        banned_wl: List[str], 
+        articles: bool,
+        prepositions: bool,
+        conjunctions: bool
+    ) -> List[str]:
+                                
+        sent_masked = sent.replace("*", self.tokenizer.mask_token)
+        inputs = self.tokenizer.encode_plus( 
+            sent_masked,
+            add_special_tokens=True,
+            return_tensors='pt',
+            return_attention_mask=True, truncation=True
+        )
+
+        tk_position_mask = torch.where(inputs['input_ids'][0] == self.tokenizer.mask_token_id)[0].item()
+
+        with torch.no_grad():
+            out = self.model(**inputs)
+            logits = out.logits
+            outputs = self.softmax(logits)
+            outputs = torch.squeeze(outputs, dim=0)
+        
+        probabilities = outputs[tk_position_mask]
+        first_tk_id = torch.argsort(probabilities, descending=True)
+        
+        top5_tks_pred = []
+        for tk_id in first_tk_id:
+            tk_string = self.tokenizer.decode([tk_id])
+            
+            tk_is_banned = tk_string in banned_wl
+            tk_is_punctuation = not tk_string.isalnum()
+            tk_is_substring = tk_string.startswith("##")
+            tk_is_special = (tk_string in self.tokenizer.all_special_tokens)
+
+            if articles:
+                tk_is_article = tk_string in self.articles
+            else:
+                tk_is_article = False
+            
+            if prepositions:
+                tk_is_prepositions = tk_string in self.prepositions
+            else:
+                tk_is_prepositions = False
+            
+            if conjunctions:
+                tk_is_conjunctions = tk_string in self.conjunctions
+            else:
+                tk_is_conjunctions = False
+            
+            predictions_is_dessire = not any([  
+                                    tk_is_banned,
+                                    tk_is_punctuation,
+                                    tk_is_substring, 
+                                    tk_is_special, 
+                                    tk_is_article, 
+                                    tk_is_prepositions,
+                                    tk_is_conjunctions
+            ])
+
+            if predictions_is_dessire and len(top5_tks_pred) < 5:
+                top5_tks_pred.append(tk_string)
+
+            elif len(top5_tks_pred) >= 5:
+                break
+
+        return top5_tks_pred
+
+    def rank(self, 
+        sent: str, 
+        word_list: List[str]=[], 
+        banned_word_list: List[str]=[], 
+        articles: bool=False, 
+        prepositions: bool=False, 
+        conjunctions: bool=False
+    ) -> Dict[str, float]:
+        
+        err = self.errorChecking(sent)
+        if err:
+            raise Exception(err)
+
+        if not word_list:
+            word_list = self.getTop5Predictions(
+                sent,
+                banned_word_list,
+                articles,
+                prepositions,
+                conjunctions
+            )
+
+        sent_list = []
+        sent_list2print = []
+        for word in word_list:
+            sent_list.append(sent.replace("*", "<"+word+">"))
+            sent_list2print.append(sent.replace("*", "<"+word+">"))
+            
+        all_plls_scores = {}
+        for sent, sent2print in zip(sent_list, sent_list2print):
+            all_plls_scores[sent2print] = self.pllScore.compute(sent)
+
+        return all_plls_scores

modules/module_segmentedWordCloud.py

@@ -0,0 +1,80 @@
+from wordcloud import WordCloud
+import matplotlib.pyplot as plt
+from typing import Dict, Tuple, List
+
+
+class SimpleGroupedColorFunc(object):
+    """Create a color function object which assigns EXACT colors
+       to certain words based on the color to words mapping
+
+       Parameters
+       ----------
+       color_to_words : dict(str -> list(str))
+         A dictionary that maps a color to the list of words.
+
+       default_color : str
+         Color that will be assigned to a word that's not a member
+         of any value from color_to_words.
+    """
+
+    def __init__(
+        self, 
+        color_to_words: Dict, 
+        default_color: str
+    ) -> Dict:
+
+        self.word_to_color = {
+            word: color
+            for (color, words) in color_to_words.items()
+            for word in words
+        }
+
+        self.default_color = default_color
+
+    def __call__(self, word, **kwargs):
+        return self.word_to_color.get(word, self.default_color)
+
+
+class SegmentedWordCloud:
+    def __init__(
+        self, 
+        freq_dic: Dict[str, int], 
+        less_group: List[str], 
+        greater_group: List[str]
+    ) -> WordCloud:
+
+        colors = {
+            'less': '#529ef3',
+            'salient':'#d35400',
+            'greater':'#5d6d7e',
+        }
+
+        color_to_words = {
+            colors['greater']: greater_group,
+            colors['less']: less_group,
+        }
+        
+
+        grouped_color_func = SimpleGroupedColorFunc(
+            color_to_words=color_to_words, 
+            default_color=colors['salient']
+        )
+
+        self.wc = WordCloud(
+            background_color="white", 
+            width=900, 
+            height=300,
+            random_state=None).generate_from_frequencies(freq_dic)
+        
+        self.wc.recolor(color_func=grouped_color_func)
+
+    def plot(
+        self, 
+        figsize: Tuple[int,int]
+    ) -> plt.Figure:
+    
+        fig, ax = plt.subplots(figsize=figsize)
+        ax.imshow(self.wc, interpolation="bilinear")
+        ax.axis("off")
+        fig.tight_layout()
+        return fig

modules/module_vocabulary.py

@@ -0,0 +1,123 @@
+import pandas as pd
+from typing import List, Dict, Tuple
+
+class Vocabulary:
+    def __init__(
+        self, 
+        subset_name: str
+    ) -> None:
+
+        # Dataset info
+        self.subset_name = subset_name
+        self.ds_path = f"data/{subset_name}_vocab_v6.zip"
+        
+        # Pandas dataset
+        self.df_vocab = None
+
+        # Minimal list with (percentile,freq) tuples to be able to plot the word distribution graph
+        self.histogram = None
+
+        # Load vocabulary dataset
+        self.__load()
+
+    def __contains__(
+        self, 
+        word: str
+    ) -> bool:
+
+        return word in self.df_vocab['word'].to_list()
+
+    def __load(
+        self
+    ) -> None:
+
+        print(f"Preparing {self.subset_name} vocabulary...")
+
+        # --- Download vocab dataset ---
+        self.df_vocab = pd.read_json(self.ds_path)
+
+        # --- Create min histogram to plot the word distribution graph ---
+        x_values = self.df_vocab['percentile'].to_list()
+        y_values = self.df_vocab['freq'].to_list()
+
+        # Delete duplicated tups
+        uniques_tups_list = set(list(zip(x_values, y_values)))
+        # Leave only tuples with different first element
+        uniques_tups_list = dict(uniques_tups_list)
+
+        self.histogram = sorted(
+            uniques_tups_list.items(),
+            key=lambda tup: tup[0], 
+            reverse=True
+        )
+        
+    def __getValue(
+        self, 
+        word: str, 
+        feature: str
+    ):
+        word_id, value = None, None
+
+        if word in self:
+            word_id = self.df_vocab['word'].to_list().index(word)
+        
+        if word_id != None:
+            value = self.df_vocab[feature].to_list()[word_id]
+
+        return value
+
+    def getFreq(
+        self, 
+        word
+    ) -> int:
+
+        return self.__getValue(word, 'freq')
+
+    def getPercentile(
+        self, 
+        word:str
+    ) -> float:
+
+        return self.__getValue(word, 'percentile')
+
+    def getSplits(
+        self, 
+        word: str
+    ) -> List[str]:
+
+        return self.__getValue(word, 'splits')
+    
+    def getSubsets(
+        self, 
+        word: str
+    ) -> Dict[str, int]:
+
+        return self.__getValue(word, 'in_subset')
+
+    def distribution(
+        self
+    ) -> Tuple:
+
+        x_values, y_values = zip(*self.histogram)
+        return x_values, y_values
+     
+    def getWordNeighbors(
+        self, 
+        word: str, 
+        n_neighbors: int=20
+    )-> Tuple:
+
+        word_id = self.df_vocab['word'].to_list().index(word)
+        words = self.df_vocab['word'].to_list()
+        freqs = self.df_vocab['freq'].to_list()
+        l_sorted = list(zip(words, freqs))
+
+        g = l_sorted[max(0, word_id-n_neighbors):word_id]    # less than
+        e = l_sorted[word_id]                               # equal than
+        l = l_sorted[word_id+1:word_id+n_neighbors]         # greter than
+
+        dic = dict(g+[e]+l)
+        l = [x[0] for x in l]
+        g = [x[0] for x in g]
+
+        return dic, l, g

modules/module_word2Context.py

@@ -0,0 +1,208 @@
+from datasets import load_dataset, interleave_datasets
+from modules.module_segmentedWordCloud import SegmentedWordCloud
+from modules.module_customSubsetsLabel import CustomSubsetsLabel
+from random import sample as random_sample
+from typing import Tuple, List, Dict
+import re
+
+import matplotlib as mpl
+mpl.use('Agg')
+import matplotlib.pyplot as plt
+
+
+class Word2Context:
+    def __init__(
+        self, 
+        context_ds_name: str,       # Context dataset HF name | path 
+        vocabulary,                 # Vocabulary class instance
+        errorManager                # ErrorManager class instance
+    ) -> None:
+
+        self.context_ds_name = context_ds_name
+        
+        # Vocabulary class 
+        self.vocab = vocabulary
+
+        # Custom Label component
+        self.Label = CustomSubsetsLabel()
+
+        self.errorManager = errorManager
+
+    def errorChecking(
+        self, 
+        word: str
+    ) -> str:
+
+        out_msj = ""
+
+        if not word:
+            out_msj = ['EMBEDDING_NO_WORD_PROVIDED']
+        else:
+            if word not in self.vocab:
+                out_msj = ['EMBEDDING_WORD_OOV', word]
+        
+        return self.errorManager.process(out_msj)
+
+    def genWebLink(
+        self,
+        text: str
+    ) -> str:
+
+        text = text.replace("\"", "'")
+        text = text.replace("<u><b>", "")
+        text = text.replace("</b></u>", "")
+        url = "https://www.google.com.tr/search?q={}".format(text)
+        return '<a href="{}" rel="noopener noreferrer" target="_blank"><center>🌐🔍</center></a>'.format(url)
+
+    def genWordCloudPlot(
+        self, 
+        word: str, 
+        figsize: Tuple[int,int]=(9,3)
+    ) -> plt.Figure:
+
+        err = self.errorChecking(word)
+        if err:
+            raise Exception(err)
+
+        freq_dic, l_group, g_group = self.vocab.getWordNeighbors(word, n_neighbors=10)
+        wc = SegmentedWordCloud(freq_dic, l_group, g_group)
+        return wc.plot(figsize)
+
+    def genDistributionPlot(
+        self, 
+        word: str, 
+        figsize: Tuple[int,int]=(6,1)
+    ) -> plt.Figure:
+
+        err = self.errorChecking(word)
+        if err:
+            raise Exception(err)
+
+        x_values, y_values = self.vocab.distribution()
+        w_percentile = self.vocab.getPercentile(word)
+        w_freq = self.vocab.getFreq(word)
+
+        fig, ax = plt.subplots(figsize=figsize)
+        ax.plot(x_values, y_values, color='green')
+        ax.fill_between(x_values, y_values, color='lightgreen',)
+        
+        ax.axvline(x=max(0,w_percentile-.01), 
+            color='blue', 
+            linewidth=7, 
+            alpha=.1,
+            linestyle='-'
+        )
+
+        ax.axvline(x=min(100,w_percentile+.01), 
+            color='black', 
+            linewidth=7, 
+            alpha=.1, 
+            linestyle='-'
+        )
+
+        ax.axvline(x=w_percentile, 
+            color='#d35400', 
+            linewidth=2, 
+            linestyle='--',
+            label=f'{w_freq}\n(frecuencia total)'
+        )
+
+        ax.axis('off')
+        plt.legend(loc='upper left', prop={'size': 7})
+        return fig
+    
+    def findSplits(
+        self, 
+        word: str, 
+        subsets_list: List[str]
+    ):
+
+        err = self.errorChecking(word)
+        if err:
+            raise Exception(err)
+
+        w_splits = self.vocab.getSplits(word)
+
+        splits_list = [] 
+        for subset in subsets_list:
+            current_split_list = []
+            for s in w_splits:
+                if (subset == s.split("_")[0]):
+                    current_split_list.append(s)
+            
+            if current_split_list:
+                splits_list.append(current_split_list)
+
+        splits_list = [random_sample(s_list, 1)[0] for s_list in splits_list]
+
+        ds_list = [ 
+            load_dataset(path=self.context_ds_name, name=split, streaming=True, split='all') 
+            for split in splits_list
+        ]
+
+        datasets = ds_list[0]
+        if len(ds_list) > 1:
+            datasets = interleave_datasets(ds_list, probabilities=None)
+
+        return datasets
+
+    def findContexts(
+        self, 
+        sample: str, 
+        word: str
+    ) -> Dict[str,str]:
+
+        sample = sample['text'].strip()
+        context = ""
+        m = re.search(r'\b{}\b'.format(word), sample)
+        if m:
+            init = m.span()[0]
+            end = init+len(word)
+            context = sample[:init]+"<u><b>"+word+"</b></u>"+sample[end:]
+        return {'context':context}
+
+    def getSubsetsInfo(
+        self, 
+        word: str
+    ) -> Tuple:
+
+        err = self.errorChecking(word)
+        if err:
+            raise Exception(err)
+
+        total_freq = self.vocab.getFreq(word)
+        subsets_name_list = list(self.vocab.getSubsets(word).keys())
+        subsets_freq_list = list(self.vocab.getSubsets(word).values())
+
+        # Create subset frequency dict to subset_freq component
+        subsets_info = {
+            s_name + f" ({s_freq})": s_freq/total_freq
+            for s_name, s_freq in zip(subsets_name_list, subsets_freq_list) 
+        }
+
+        subsets_origin_info = dict(sorted(subsets_info.items(), key=lambda x: x[1], reverse=True))
+        subsets_info = self.Label.compute(subsets_origin_info)
+        return subsets_info, subsets_origin_info
+
+    def getContexts(
+        self, 
+        word: str, 
+        n_context: int, 
+        ds
+    ) -> List[Tuple]:
+
+        err = self.errorChecking(word)
+        if err:
+            raise Exception(err)
+
+        ds_w_contexts = ds.map(lambda sample: self.findContexts(sample, word))
+        only_contexts = ds_w_contexts.filter(lambda sample: sample['context'] != "")
+        shuffle_contexts = only_contexts.shuffle(buffer_size=10)
+        
+        list_of_dict = list(shuffle_contexts.take(n_context))
+        list_of_contexts = [
+            (i, dic['context'], dic['subset']) 
+            for i,dic in enumerate(list_of_dict)
+        ]
+
+        return list_of_contexts

modules/utils.py

@@ -0,0 +1,83 @@
+import numpy as np
+import pandas as pd
+from datetime import datetime
+import pytz
+
+
+class DateLogs:
+    def __init__(
+        self, 
+        zone: str="America/Argentina/Cordoba"
+    ) -> None:
+
+        self.time_zone = pytz.timezone(zone)
+        
+    def full(
+        self
+    ) -> str:
+
+        now = datetime.now(self.time_zone)
+        return now.strftime("%H:%M:%S %d-%m-%Y")
+    
+    def day(
+        self
+    ) -> str:
+
+        now = datetime.now(self.time_zone)
+        return now.strftime("%d-%m-%Y")
+
+def take_two_sides_extreme_sorted(
+    df: pd.DataFrame, 
+    n_extreme: int,
+    part_column: str=None,
+    head_value: str='',
+    tail_value: str=''
+) -> pd.DataFrame:
+
+    head_df = df.head(n_extreme)[:]
+    tail_df = df.tail(n_extreme)[:]
+
+    if part_column is not None:
+        head_df[part_column] = head_value
+        tail_df[part_column] = tail_value
+
+    return (pd.concat([head_df, tail_df])
+            .drop_duplicates()
+            .reset_index(drop=True))
+
+def normalize(
+    v: np.ndarray
+) -> np.ndarray:
+
+    """Normalize a 1-D vector."""
+    if v.ndim != 1:
+        raise ValueError('v should be 1-D, {}-D was given'.format(
+            v.ndim))
+    norm = np.linalg.norm(v)
+    if norm == 0:
+        return v
+    return v / norm
+
+def project_params(
+    u: np.ndarray, 
+    v: np.ndarray
+) -> np.ndarray:
+
+    """Projecting and rejecting the vector v onto direction u with scalar."""
+    normalize_u = normalize(u)
+    projection = (v @ normalize_u)
+    projected_vector = projection * normalize_u
+    rejected_vector = v - projected_vector
+    return projection, projected_vector, rejected_vector
+
+
+def cosine_similarity(
+    v: np.ndarray, 
+    u: np.ndarray
+) -> np.ndarray:
+
+    """Calculate the cosine similarity between two vectors."""
+    v_norm = np.linalg.norm(v)
+    u_norm = np.linalg.norm(u)
+    similarity = v @ u / (v_norm * u_norm)
+    return similarity

requirements.txt

@@ -0,0 +1,14 @@
+regex==2022.10.31
+torch==1.13.1
+scikit-learn==0.24.2
+transformers==4.25.1
+wordcloud==1.8.2.2
+matplotlib
+numpy
+uuid
+python-dotenv
+memory_profiler
+gensim==4.2.0
+seaborn
+annoy==1.17.1
+datasets==2.8.0

tool.cfg

@@ -0,0 +1,25 @@
+[INTERFACE]
+# [es | en]
+language            = es
+
+[WORD_EXPLORER]
+# [data/100k_es_embedding.vec | data/100k_en_embedding.vec ]
+embeddings_path     = data/100k_es_embedding.vec
+# [sklearn | ann]
+nn_method           = sklearn   
+max_neighbors       = 20
+
+[DATA]
+contexts_dataset    = vialibre/splittedspanish3bwc
+# [full | mini]
+vocabulary_subset   = full
+# [True | False]
+available_wordcloud = False
+
+[LMODEL]
+# [bert-base-uncased | dccuchile/bert-base-spanish-wwm-uncased]
+language_model      = dccuchile/bert-base-spanish-wwm-uncased
+
+[LOGS]
+# [True | False]
+available_logs      = False

tool_info.py

@@ -0,0 +1,23 @@
+TOOL_INFO = """
+> ### A tool to overcome technical barriers for bias assessment in human language technologies
+
+* [Read Full Paper](https://arxiv.org/abs/2207.06591)
+
+> ### Licensing Information
+* [MIT Licence](https://huggingface.co/spaces/vialibre/edia_full_es/resolve/main/LICENSE)
+
+> ### Citation Information
+```c
+@misc{https://doi.org/10.48550/arxiv.2207.06591,
+    doi = {10.48550/ARXIV.2207.06591},
+    url = {https://arxiv.org/abs/2207.06591},
+    author = {Alemany, Laura Alonso and Benotti, Luciana and González, Lucía and Maina, Hernán and Busaniche, Beatriz and Halvorsen, Alexia and Bordone, Matías and Sánchez, Jorge},
+    keywords = {Computation and Language (cs.CL), Artificial Intelligence (cs.AI), 
+    FOS: Computer and information sciences, FOS: Computer and information sciences},
+    title = {A tool to overcome technical barriers for bias assessment in human language technologies},
+    publisher = {arXiv},
+    year = {2022},
+    copyright = {Creative Commons Attribution Non Commercial Share Alike 4.0 International}
+}
+```
+"""