wordviz 0.1.1__tar.gz

wordviz-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Elena Zen
+
+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.

wordviz-0.1.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: wordviz
+Version: 0.1.1
+Summary: A lightweight Python package for loading, analyzing, and visualizing word embeddings.
+License: MIT
+Author: Elena Zen
+Author-email: elenazen563@gmail.com
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: adjusttext (>=1.3.0,<2.0.0)
+Requires-Dist: gensim (>=4.3.3,<5.0.0)
+Requires-Dist: ipykernel (>=6.29.5,<7.0.0)
+Requires-Dist: jupyter (>=1.1.1,<2.0.0)
+Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
+Requires-Dist: numpy (>=1.18.5,<2.0)
+Requires-Dist: plotly (>=6.0.1,<7.0.0)
+Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
+Requires-Dist: scipy (>=1.7.0,<1.14.0)
+Requires-Dist: seaborn (>=0.13.2,<0.14.0)
+Requires-Dist: umap-learn (>=0.5.7,<0.6.0)
+Description-Content-Type: text/markdown
+
+# WordViz
+
+**WordViz** is a Python visualization library designed for exploring and visualizing word embeddings. Built on top of popular libraries such as `matplotlib`, `plotly`, and `gensim`, WordViz provides intuitive tools for analyzing embeddings through clustering, similarity exploration, and dimensionality reduction, all wrapped in interactive and customizable plots.
+With WordViz, users can gain insights into the structure of their word embeddings, making it a valuable tool for researchers and practitioners in natural language processing.
+
+## Main Features
+
+- Load and explore pretrained embeddings (e.g., GloVe, FastText)
+- Select from a variety of available embeddings
+- Visualize embeddings in 2D with flexible dimensionality reduction options
+- Identify and plot the most similar words to a given token
+- Visualize clusters of related words
+- Interactive plots powered by `plotly`
+- Support for both light and dark themes
+
+
+## Installation
+
+Install the latest version from PyPI:
+
+```bash
+pip install wordviz
+```
+
+
+## Usage
+
+You can load and manage embeddings though the `EmbeddingLoader` class, and then visualize them with the `Visualizer` class.
+
+```python
+from wordviz.loading import EmbeddingLoader
+from wordviz.plotting import Visualizer
+
+loader = EmbeddingLoader()
+loader.load_from_file('path/to/your/embedding/file', 'word2vec')
+
+vis = Visualizer(loader)
+vis.plot_embeddings()
+```
+
+You can explore all functionalities through the example notebook provided in the `docs/` folder:
+
+👉 [View example notebook](docs/example.ipynb)
+
+
+## Contributing
+
+This project was created as part of my Bachelor's Degree thesis. For now, it remains a personal project and is not yet open to public collaboration.  
+However, it will be further developed and eventually opened to contributions.
+
+In the meantime, if you want to suggest features or report bugs, feel free to contact me directly.
+
+
+## License
+
+This project is licensed under the MIT License.

wordviz-0.1.1/README.md

@@ -0,0 +1,56 @@
+# WordViz
+
+**WordViz** is a Python visualization library designed for exploring and visualizing word embeddings. Built on top of popular libraries such as `matplotlib`, `plotly`, and `gensim`, WordViz provides intuitive tools for analyzing embeddings through clustering, similarity exploration, and dimensionality reduction, all wrapped in interactive and customizable plots.
+With WordViz, users can gain insights into the structure of their word embeddings, making it a valuable tool for researchers and practitioners in natural language processing.
+
+## Main Features
+
+- Load and explore pretrained embeddings (e.g., GloVe, FastText)
+- Select from a variety of available embeddings
+- Visualize embeddings in 2D with flexible dimensionality reduction options
+- Identify and plot the most similar words to a given token
+- Visualize clusters of related words
+- Interactive plots powered by `plotly`
+- Support for both light and dark themes
+
+
+## Installation
+
+Install the latest version from PyPI:
+
+```bash
+pip install wordviz
+```
+
+
+## Usage
+
+You can load and manage embeddings though the `EmbeddingLoader` class, and then visualize them with the `Visualizer` class.
+
+```python
+from wordviz.loading import EmbeddingLoader
+from wordviz.plotting import Visualizer
+
+loader = EmbeddingLoader()
+loader.load_from_file('path/to/your/embedding/file', 'word2vec')
+
+vis = Visualizer(loader)
+vis.plot_embeddings()
+```
+
+You can explore all functionalities through the example notebook provided in the `docs/` folder:
+
+👉 [View example notebook](docs/example.ipynb)
+
+
+## Contributing
+
+This project was created as part of my Bachelor's Degree thesis. For now, it remains a personal project and is not yet open to public collaboration.  
+However, it will be further developed and eventually opened to contributions.
+
+In the meantime, if you want to suggest features or report bugs, feel free to contact me directly.
+
+
+## License
+
+This project is licensed under the MIT License.

wordviz-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "wordviz"
+version = "0.1.1"
+description = "A lightweight Python package for loading, analyzing, and visualizing word embeddings."
+authors = ["Elena Zen <elenazen563@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+matplotlib = ">=3.10.1,<4.0.0"
+numpy = ">=1.18.5,<2.0"
+gensim = ">=4.3.3,<5.0.0"
+scipy = ">=1.7.0,<1.14.0"
+scikit-learn = ">=1.6.1,<2.0.0"
+plotly = ">=6.0.1,<7.0.0"
+seaborn = ">=0.13.2,<0.14.0"
+adjusttext = "^1.3.0"
+umap-learn = ">=0.5.7,<0.6.0"
+ipykernel = ">=6.29.5,<7.0.0"
+jupyter = ">=1.1.1,<2.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+black = "^25.1.0"
+isort = "^6.0.1"
+sphinx = "^8.2.3"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

wordviz-0.1.1/src/wordviz/clustering.py

@@ -0,0 +1,44 @@
+import numpy as np
+from sklearn.cluster import KMeans, DBSCAN
+from typing import Tuple, Optional
+from .dim_reduction import reduce_dim
+
+
+def create_clusters(vectors: np.ndarray, n_clusters: int = 5, method: str = 'kmeans') -> Tuple[np.ndarray, Optional[np.ndarray], np.ndarray]:
+    '''
+    Performs clustering on embeddings for visualization purposes.
+    If the input vectors have more than 2 dimensions, dimensionality reduction is applied first.
+
+    Parameters:
+    -----------
+    vectors : np.ndarray
+        Array of embeddings to cluster.
+    n_clusters : int, default=5
+        Number of clusters to generate (used only for k-means).
+    method : str, default='kmeans'
+        Clustering method to use ('kmeans' or 'dbscan').
+
+    Returns:
+    --------
+    labels : np.ndarray
+        Cluster labels assigned to each vector.
+    centers : np.ndarray or None
+        Coordinates of cluster centers (only for k-means; None for dbscan).
+    reduced_emb : np.ndarray
+        2D reduced embeddings used for clustering and plotting.
+    '''
+
+    if vectors.shape[1] > 2:
+        reduced_emb = reduce_dim(vectors)  
+    else:
+        reduced_emb = vectors  
+
+    match method:
+        case 'kmeans':
+            clustering = KMeans(n_clusters=n_clusters, random_state=0, n_init="auto").fit(reduced_emb)
+            centers = clustering.cluster_centers_
+        case 'dbscan':
+            clustering = DBSCAN(eps=0.5, min_samples=n_clusters).fit(reduced_emb)
+            centers = None
+
+    return clustering.labels_, centers, reduced_emb

wordviz-0.1.1/src/wordviz/dim_reduction.py

@@ -0,0 +1,76 @@
+import umap
+import numpy as np
+from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+from sklearn.manifold import Isomap
+from sklearn.manifold import MDS
+import warnings
+
+def reduce_dim(vectors: np.ndarray, method: str = 'pca', n_dimensions: int = 2, dist: str = 'euclidean', **kwargs) -> np.ndarray:
+    ''' 
+    Applies dimensionality reduction for visualization to input vectors using a specified method.
+
+    Parameters:
+    -----------
+    vectors: array
+        Input high-dimensional data to reduce.
+    method: str, default:'pca'
+        Dimensionality reduction algorithm to apply. Options are:
+        - 'pca': Principal Component Analysis
+        - 'tsne': t-Distributed Stochastic Neighbor Embedding
+        - 'umap': Uniformed Manifold Approximation and Projection
+        - 'isomap': Isometric Mapping
+        - 'mds': Multidimensional Scaling
+    n_dimensions: int, default:2
+        Number of dimensions for output. Must be 2 or 3
+     dist : str, default='euclidean'
+        Distance metric for methods that require a distance matrix (MDS). Ignored for other methods.
+    **kwargs : dict
+        Additional parameters passed to the selected dimensionality reduction algorithm.
+
+    Returns:
+    --------
+    np.ndarray
+        Embedding reduced at specified dimensions.
+    '''
+    
+    if n_dimensions not in [2, 3]:
+        raise ValueError('n_dimensions has to be 2 or 3')
+    
+    if (method in ['isomap', 'tsne', 'mds']) and vectors.shape[0] > 5000:
+        warnings.warn(f"Warning: {method} is a computational heavy method, loading very large embeddings without subsetting may result in execution times so long that the process may never complete.")
+
+    default_params = {
+        'pca': {},
+        'tsne': {'random_state': 42, 'perplexity': 30},
+        'umap': {'n_neighbors': 15, 'min_dist': 0.1, 'random_state': 42},
+        'isomap': {'n_neighbors': 5},
+        'mds': {'metric':True, 'n_init':3, 'max_iter':300, 'random_state':42, 'dissimilarity': 'euclidean'}
+    }
+
+    if method in default_params:
+        params = {**default_params[method.lower()], **kwargs}
+    else:
+        raise ValueError(f"Method {method} not supported. Choose between 'pca', 'tsne', 'umap' or 'isomap'")
+
+    match method.lower():
+        case 'pca':
+            reducer = PCA(n_components=n_dimensions, **params)
+        case 'tsne':    
+            reducer = TSNE(n_components=n_dimensions, **params)
+        case 'umap':
+            reducer = umap.UMAP(n_components=n_dimensions, **params)
+        case 'isomap': 
+            reducer = Isomap(n_components=n_dimensions, **params)
+        case 'mds':
+            reducer = MDS(n_components=n_dimensions,
+                        dissimilarity='euclidean' if dist == 'euclidean' else 'precomputed', **params)
+            if dist != 'precomputed' and dist != 'euclidean':
+                from sklearn.metrics import pairwise_distances
+                vectors = pairwise_distances(vectors, metric=dist)
+
+    reduced_emb = reducer.fit_transform(vectors)
+    
+    return reduced_emb
+        
+    

wordviz-0.1.1/src/wordviz/loading.py

@@ -0,0 +1,269 @@
+import os
+import shutil
+from gensim.models import KeyedVectors
+from gensim.scripts.glove2word2vec import glove2word2vec
+from  gensim.models.fasttext import load_facebook_model
+import numpy as np
+import zipfile
+from pathlib import Path
+import urllib.request
+
+
+class EmbeddingLoader:
+    def __init__(self):
+        self.embeddings_raw = None 
+        self.embeddings = None      
+        self.tokens = None         
+        self.dimension = None
+        self.embeddings_subset = None
+        self.tokens_subset = None
+
+        self.available_pretrained = {     
+        'glove': {
+            'en': {
+                'wiki': {
+                    '100d': {
+                    'url': 'https://nlp.stanford.edu/data/glove.6B.zip',
+                    'filename': 'glove.6B.100d.txt'
+                    }
+                },
+                'cc': {
+                    '300d': {
+                        'url': 'https://nlp.stanford.edu/data/glove.42B.300d.zip',
+                        'filename': 'glove.42B.300d.txt'
+                    }
+                },
+                'twitter': {
+                    '100d': {
+                    'url': 'https://nlp.stanford.edu/data/glove.twitter.27B.zip',
+                    'filename': 'glove.twitter.27B.100d.txt'
+                    }
+                }
+            }
+        },
+        'fasttext': {
+            'it': {
+                'cc': {
+                    '300d': {
+                        'url': 'https://dl.fbaipublicfiles.com/fasttext/vectors-crawl/cc.it.300.bin.gz'
+                    }
+                }
+            }
+        }
+    }
+
+    def get_cache_dir(self):
+        cache_dir = Path.home() / ".wordviz_cache"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        return cache_dir   
+
+
+    def _validate_file(self, path):
+        '''checks if path argument leads to a valid file name and returns if it is binary'''
+        valid_ext = ['.bin', '.txt', '.vec']
+
+        if not isinstance(path, str):
+            path = str(path)    
+        _, ext = os.path.splitext(path.lower())
+
+        if path is None:
+            raise ValueError('File path is required')
+        
+        if not isinstance(path, str):
+            raise TypeError('The file path must be a string')
+        
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Invalid file path {path}: the file does not exist")
+    
+        if ext not in valid_ext:
+            raise ValueError(f'Invalid file extension {ext}. Valid extensions are: {','.join(valid_ext)}')
+
+        binary = True if ext == '.bin' else False
+
+        return binary
+
+
+    def load_from_file(self, path: str, format: str) -> np.ndarray:
+        '''
+        Loads word embeddings from a file in .txt, .vec, or .bin format.
+
+        Parameters
+        -----------
+        path : str
+            Path to the embedding file.
+        format : str
+            Format of the embedding model: 'word2vec', 'fasttext', or 'glove'.
+
+        Returns
+        --------
+        np.ndarray
+            Loaded embedding matrix.
+
+        Notes:
+        ------
+        - For GloVe files, they are first converted to word2vec format.
+        - FastText binary files are supported via Facebook's native loader.
+        - Loaded tokens are stored in self.tokens.
+        - Embedding matrix is stored in self.embeddings.
+        '''
+
+        binary = self._validate_file(path)
+
+        match format:
+            case 'word2vec':
+                    self.embeddings_raw = KeyedVectors.load_word2vec_format(path, binary=binary)
+            case 'fasttext':
+                if binary:
+                    self.embeddings_raw = load_facebook_model(path)
+                else:
+                    self.embeddings_raw = KeyedVectors.load_word2vec_format(path, binary=False)
+            case 'glove':
+                glove2word2vec(path, "glove_w2v.txt")
+                if not os.path.exists("glove_w2v.txt"):
+                    raise RuntimeError("GloVe to Word2Vec conversion failed.")
+                
+                self.embeddings_raw = KeyedVectors.load_word2vec_format("glove_w2v.txt")
+
+        self.tokens = list(self.embeddings_raw.index_to_key)
+        self.dimension = self.embeddings_raw.vector_size
+
+        words = self.embeddings_raw.index_to_key
+        self.embeddings = np.array([self.embeddings_raw.get_vector(word) for word in words])
+        print("Embedding loaded from file")
+
+        return self.embeddings
+    
+
+    def download_zip(self, url, filename):
+        '''downloads zip file from url'''
+        zip_path = self.get_cache_dir() / filename
+        if not zip_path.exists():
+            print(f"Downloading {filename}...")
+            urllib.request.urlretrieve(url, zip_path)
+        else:
+            print(f"{filename} already exists in cache.")
+        return zip_path
+    
+
+    def export_embedding(self, source_path, dest_folder):
+        '''saves locally pretrained embeddings file'''
+        os.makedirs(dest_folder, exist_ok=True)
+        filename = os.path.basename(source_path)
+        dest_path = os.path.join(dest_folder, filename)
+        shutil.copy(source_path, dest_path)
+        print(f"File saved in {dest_path}.")
+
+
+    def load_pretrained(self, model: str, lang: str, source: str, dimension: str, save_file: bool = False, export_dir: str = None) -> np.ndarray:
+        '''
+        Downloads and loads a pretrained embedding model from an online source.
+
+        Parameters
+        -----------
+        model : str
+            Name of the embedding model ('word2vec', 'fasttext', etc.).
+        lang : str
+            Language code of the embedding ('en', 'it').
+        source : str
+            Data source ('wiki', 'cc').
+        dimension : str or int
+            Embedding dimensionality (e.g., '300').
+        save_file : bool, default=False
+            If True, saves the embedding to the specified export directory.
+        export_dir : str, optional
+            Path to the directory where the file will be exported (used if save_file=True).
+
+        Returns
+        --------
+        np.ndarray
+            Loaded embedding matrix (n_words x dimension).
+        '''
+
+        option = self.available_pretrained[model][lang][source][dimension]
+        url = option['url']
+        filename = option['filename']
+        zip_filename = url.split("/")[-1]
+
+        zip_path = self.download_zip(url, zip_filename)
+
+        dest_dir = self.get_cache_dir() / model / lang / source / dimension
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        file_path = dest_dir / filename
+
+        if not file_path.exists():
+            with zipfile.ZipFile(zip_path, 'r') as z:
+                print(f"Extracting {filename}...")
+                z.extract(filename, path=dest_dir)
+
+        self.embeddings = self.load_from_file(file_path, model)
+
+        if save_file:
+                if export_dir is None:
+                    raise ValueError("Must specify export_dir to save file.")
+                self.export_embedding(file_path, export_dir)
+
+        return self.embeddings
+    
+
+    def list_available_pretrained(self):
+        '''prints a list of pretrained embeddings provided by the package'''
+        print('model | lang | source | dim')
+        for model, langs in self.available_pretrained.items():
+            for lang, sources in langs.items():
+                for source, dims in sources.items():
+                    for dim in dims:
+                        print(f"{model} | {lang} | {source} | {dim}") 
+
+    
+    def get_embedding(self, word):
+        '''returns corresponding embeddings using KeyedVectors object for a string given by the user'''
+        if isinstance(word, str):
+            if word in self.embeddings_raw:
+                return self.embeddings_raw[word]
+            
+
+    def subset(self, n: int = 1000, strategy: str = 'first', random_seed: int = None):
+        '''
+        Create a subset of the current embeddings and tokens. Useful for speeding up visualizations or 
+        managing memory with large embedding spaces.
+
+        Parameters
+        -----------
+        n : int, default=1000
+            Number of embeddings to retain. If n exceeds the total number of available embeddings, all are retained.
+        strategy : str, default='first'
+            Selection strategy:
+                - 'first': select the first n embeddings in original order.
+                - 'random': select n random embeddings.
+        random_seed : int, optional
+            Seed for reproducible random sampling (only used if strategy is 'random').
+
+        Updates
+        --------
+        self.tokens_subset : list of str
+            List of selected token strings.
+        self.embeddings_subset : np.ndarray
+            Corresponding selected embedding vectors.
+    '''
+        if n > len(self.tokens):
+            print('n is larger than the embedding size, the subset size will be equal to the full size')
+
+        if strategy == 'first':
+            indices = list(range(min(n, len(self.tokens))))
+        elif strategy == 'random':
+            rng = np.random.default_rng(random_seed)
+            indices = rng.choice(len(self.tokens), size=min(n, len(self.tokens)), replace=False).tolist()
+        else:
+            raise ValueError("strategy has to be 'first' o 'random'")
+        
+        self.tokens_subset    = [self.tokens[i] for i in indices]
+        self.embeddings_subset = self.embeddings[indices]
+
+
+    def use_subset(self, n: int = 1000):
+        '''returns embedding subset. If None, creates 1000 words subset and returns it.'''
+
+        if self.embeddings_subset is None:
+            self.subset(n)
+        
+        return self.embeddings_subset, self.tokens_subset

wordviz-0.1.1/src/wordviz/plotting.py

@@ -0,0 +1,488 @@
+from adjustText import adjust_text
+import matplotlib.pyplot as plt
+import numpy as np
+import plotly.express as px
+import plotly.graph_objects as go
+import seaborn as sns
+from sklearn.cluster import KMeans
+from sklearn.metrics import pairwise_distances
+from scipy.stats import gaussian_kde
+import warnings
+from .clustering import create_clusters
+from .dim_reduction import reduce_dim
+from .similarity import n_most_similar
+
+
+class Visualizer:
+    def __init__(self, loader):
+        self.loader = loader
+        self.tokens = loader.tokens
+        self.embeddings = loader.embeddings
+
+
+    def get_theme(self, theme='light1'):
+        themes = { 
+            'light1': {
+                    'bg' : '#f5f5fa',
+                    'points' : '#66c2a5',
+                    'target' : '#e78ac3',
+                    'grid' : '#cccccc',
+                    'text' : '#1a1a1a',
+                    'scale': 'Viridis'
+                },
+            'dark1': {
+                    'bg' : '#1a1a1a',
+                    'points' : '#fc8d62',
+                    'target' : '#a6d854',
+                    'grid' : '#444444',
+                    'text' : '#f0f0f0',
+                    'scale': 'Plasma'
+                }
+        }
+        return themes.get(theme, themes['light1'])
+    
+
+    def _setup_plot(self, theme, grid, title):
+        '''base private function to config matplotlib plot'''
+        colors = self.get_theme(theme)
+
+        fig, ax = plt.subplots(figsize=(10, 8))
+
+        fig.patch.set_facecolor(colors['bg'])
+        ax.set_facecolor(colors['bg'])
+
+        if grid:  
+            ax.grid(True, linestyle='--', color=colors['grid'], alpha=0.6)
+            ax.set_axisbelow(True) 
+            ax.tick_params(left=True, bottom=True, labelleft=False, labelbottom=False, color=(0.5, 0.5, 0.5, 0.4))
+        else:
+            plt.xticks([])
+            plt.yticks([])
+
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+
+        if title is not None:
+            plt.title(title, fontsize=12, fontweight='bold', color=colors['text'])
+
+        return fig, ax, colors
+    
+
+    def map_colors(self, labels):
+        '''automatizes color and legend label mapping for clustering applied to embeddings'''
+        unique_classes = list(set(labels))
+        palette = sns.color_palette("Set2", n_colors=len(unique_classes))
+        class_to_color = dict(zip(unique_classes, palette))
+        colors = [class_to_color[label] for label in labels]
+        legend_labels = {label: (class_to_color[label], f'Cluster {label+1}') for label in unique_classes}
+
+        return colors, legend_labels
+
+
+    def select_sparse_labels(self, embeddings, n):
+        '''uses clustering to select n distributed labels to visualize'''
+        kmeans = KMeans(n_clusters=n, random_state=0).fit(embeddings)
+        centers = kmeans.cluster_centers_
+        indices = []
+
+        for center in centers:
+            idx = np.argmin(np.linalg.norm(embeddings - center, axis=1))
+            indices.append(idx)
+
+        return indices
+
+
+    def plot_embeddings(self, red_method: str = 'pca', grid: bool = True, theme: str = 'light1', title: str = None, nlabels: int = 0, use_subset: bool = False):   
+        '''
+        Creates a simple static 2D scatterplot of the embeddings.
+
+        Parameters
+        -----------
+        red_method : str, default='pca'
+            Dimensionality reduction method to apply ('pca', 'tsne', 'umap', etc.).
+        grid : bool, default=True
+            If True, displays a background grid on the plot.
+        theme : str, default='light1'
+            Color theme to apply.
+        title : str, optional
+            Title to display on the plot.
+        nlabels : int, default=0
+            Number of word labels to display. If 0, no labels are shown.
+        use_subset : bool, default=False
+            If True, uses the embedding subset instead of the full embeddings.
+
+        Returns
+        --------
+        fig : matplotlib.figure.Figure
+        ax : matplotlib.axes.Axes
+        '''
+
+        if use_subset:
+            emb, tokens = self.loader.use_subset()
+        else:
+            emb = self.embeddings
+            tokens = self.tokens
+
+        reduced_emb = reduce_dim(emb, method=red_method)
+
+        fig, ax, colors = self._setup_plot(theme, grid, title)
+        ax.scatter(reduced_emb[:, 0], reduced_emb[:, 1], c=colors['points'], alpha=0.5, s=14, marker='o')
+
+        texts = []
+        if nlabels > 0:
+            sparse_indices = self.select_sparse_labels(reduced_emb, nlabels)
+            for i in sparse_indices:
+                texts.append(ax.text(reduced_emb[i, 0], reduced_emb[i, 1], tokens[i],
+                color=colors['text'], fontsize=9, alpha=1, ha='center', va='bottom'))
+
+        adjust_text(texts, ax=ax, expand=(1.2, 2), arrowprops=dict(arrowstyle='-', color='k'))
+        plt.rcParams['figure.dpi'] = 600
+        plt.show()
+        return fig, ax
+    
+    
+    def plot_similarity(self, target_word: str, dist: str = 'cosine', n: int = 10, red_method: str = 'umap', grid: bool = True, theme: str = 'light1', title: str = None):
+        '''
+        Creates a scatterplot showing the most similar words to a target word.
+
+        Parameters
+        -----------
+        target_word : str
+            The word for which to find and plot the most similar words.
+        dist : str, default='cosine'
+            Distance metric to use when computing word similarity.
+        n : int, default=10
+            Number of similar words to display.
+        red_method : str, default='umap'
+            Dimensionality reduction method to apply ('pca', 'tsne', 'umap', etc.).
+        grid : bool, default=True
+            If True, displays a background grid on the plot.
+        theme : str, default='light1'
+            Color theme to apply to the plot.
+        title : str, optional
+            Title to display. If None, a default title will be generated.
+
+        Returns
+        --------
+        fig : matplotlib.figure.Figure
+        ax : matplotlib.axes.Axes
+        '''
+        similar_words, similar_vecs, _ = n_most_similar(self.loader, target_word, dist, n)
+        target_vec = self.loader.get_embedding(target_word)
+        vectors = np.vstack([target_vec.reshape(1, -1), similar_vecs])
+        words = [target_word] + similar_words
+
+        reduced_emb = reduce_dim(vectors, method=red_method)
+
+        if title is None:
+            title = f"Top {n} words similar to '{target_word}'"
+
+        fig, ax, colors = self._setup_plot(theme, grid, title)
+        
+        texts = []
+        ax.scatter(reduced_emb[0, 0], reduced_emb[0, 1], c=colors['target'], alpha=0.5, s=20, marker='o')
+        texts.append(ax.text(reduced_emb[0, 0], reduced_emb[0, 1], target_word,
+                color=colors['text'], fontsize=9, fontweight='bold', alpha=1, ha='center', va='bottom'))
+        
+        ax.scatter(reduced_emb[1:, 0], reduced_emb[1:, 1], c=colors['points'], alpha=0.5, s=20, marker='o')
+        for i, word in enumerate(similar_words):
+            texts.append(ax.text(reduced_emb[i+1, 0], reduced_emb[i+1, 1], word,
+                    color=colors['text'], fontsize=9, alpha=1, ha='center', va='bottom'))
+        
+       
+        plt.rcParams['figure.dpi'] = 600
+        plt.show()  
+
+        return fig, ax
+
+
+    def plot_topography(self, dist: str = 'cosine', red_method: str = 'isomap', use_subset: bool = True, grid: bool = True, theme: str = 'light1', title: str = None):       
+        '''
+        Plots word embeddings in a topographical map using dimensionality reduction to maintain word distances in the representation. Allows to visualize word density in the space.
+
+        Parameters
+        -----------
+        dist : str, default='cosine'
+            The distance metric to use for word similarity. Options include 'cosine', 'euclidean', etc.
+        red_method : str, default='isomap'
+            The dimensionality reduction method to use for visualizing the word embeddings, maintaining word distances. Options include 'umap', 'isomap', and 'mds'.
+        use_subset : bool, default=True
+            If True, uses a subset of the embeddings for visualization. This is recommended in this plot for larger embeddings.
+        grid : bool, default=True
+            If True, shows grid lines on the plot.
+        theme : str, default='light1'
+            The plot theme to use, which controls the colors of the plot.
+        title : str, optional
+            Title of the plot. If not provided, a default title is used.
+
+        Returns
+        --------
+        fig : plotly.graph_objs.Figure
+        '''
+
+        if use_subset:
+            emb, tokens = self.loader.use_subset()
+        else:
+            emb = self.embeddings
+            tokens = self.tokens
+
+        reduced_emb = reduce_dim(emb, red_method, dist=dist)
+
+        x = reduced_emb[:, 0]
+        y = reduced_emb[:, 1]
+        fig = go.Figure()
+
+        colors = self.get_theme(theme)
+
+        # calculate coordinates for contour plot
+        x_grid, y_grid = np.meshgrid(np.linspace(x.min() - 0.5, x.max() + 0.5, 100),
+                                np.linspace(y.min() - 0.5, y.max() + 0.5, 100))
+    
+        kde = gaussian_kde([x, y], bw_method=0.2) 
+        z_grid = kde([x_grid.flatten(), y_grid.flatten()]).reshape(x_grid.shape)
+        z_grid = np.log1p(z_grid)
+
+        # add contour
+        fig.add_trace(go.Contour(
+        z=z_grid,
+        x=x_grid[0],
+        y=y_grid[:, 0],
+        colorscale=colors['scale'],
+        opacity=0.8,
+        contours=dict(
+            showlabels=False,
+            start=z_grid.min(),
+            end=z_grid.max(),
+            size=(z_grid.max() - z_grid.min()) / 15),
+        colorbar=dict(title="Density"),
+        hoverinfo='skip'
+        ))
+
+        # add points
+        fig.add_trace(go.Scatter(
+            x=x, y=y,
+            mode='markers',
+            marker=dict(
+                size=5,
+                color='rgba(255, 255, 255, 0.5)',
+                line=dict(width=1, color='rgba(0, 0, 0, 0.8)')
+            ),
+            text=tokens,  
+            hovertemplate='%{text}<extra></extra>',  
+            showlegend=False
+        ))
+
+        fig.update_traces(
+            hoverlabel=dict(
+                bgcolor=colors['bg'], 
+                font=dict(color=colors['text']) 
+            )
+        )
+
+        fig.update_layout(
+            width=900,
+            height=700,
+            title=title if title else "Word Embedding Topography",
+            title_x=0.5,
+            title_xanchor='center',
+            plot_bgcolor=colors['bg'],
+            paper_bgcolor=colors['bg'],
+            font=dict(color=colors['text']),
+            xaxis=dict(showgrid=grid, zeroline=False, showticklabels=False, title=""),
+            yaxis=dict(showgrid=grid, zeroline=False, showticklabels=False, title="")
+        )
+
+        return fig
+    
+
+    def similarity_heatmap(self, dist: str = 'cosine', use_subset: bool = True, n: int = 500, theme: str = 'light1', title: bool = None):
+        ''' 
+        Creates a heatmap showing pairwise distances between word embeddings.
+
+        Parameters
+        -----------
+        dist : str, default='cosine'
+            Distance metric to use for computing similarity between embeddings.
+        use_subset : bool, default=True
+            If True, uses a subset of the embeddings. Otherwise, uses the full set.
+        n : int, optional
+            Number of embeddings to subset. Ignored if a subset already exists and use_subset is True.
+        theme : str, default='light1'
+            Plot color theme to use.
+        title : str, optional
+            Title for the heatmap. If None, a default title is assigned.
+
+        Returns
+        --------
+        fig : plotly.graph_objects.Figure
+        '''
+
+        if use_subset:
+            if n:
+                self.loader.subset(n)
+                emb = self.loader.embeddings_subset 
+                tokens = self.loader.tokens_subset
+            else:
+                emb, tokens = self.loader.use_subset()
+        else:
+            emb = self.embeddings
+            tokens = self.tokens
+
+        if emb.shape[0] > 500:
+            warnings.warn(f"Warning: loading more than 500 embeddings without subsetting will generate more than one heatmap and may result in longer execution times. Consider subsetting before or setting n < 500.")
+        
+        distances = pairwise_distances(emb, metric=dist)
+
+        colors = self.get_theme(theme)
+
+        fig = px.imshow(distances, x=tokens, y=tokens, text_auto=True, color_continuous_scale=colors['scale'])
+        fig.update_layout(
+            width=800, height=800,
+            title=title if title else "Word Embedding Similarity Heatmap",
+            title_x=0.5,
+            title_xanchor='center',
+            plot_bgcolor=colors['bg'],
+            paper_bgcolor=colors['bg'],
+            font=dict(color=colors['text']))
+        fig.update_coloraxes(colorbar_title='Distance')
+        fig.update_traces(
+            hovertemplate="Word 1: %{x}<br>Word 2: %{y}<br>Distance: %{z}<extra></extra>",
+            hoverlabel=dict(
+                bgcolor=colors['bg'], 
+                font=dict(color=colors['text']) ))
+
+        return fig
+    
+
+    def plot_clusters(self, n_clusters=5, method='kmeans', red_method='pca', show_centers=False, grid=True, theme='light1', title=None, nlabels=0, use_subset=False):
+        '''
+        Creates a 2D scatterplot of clustered embeddings using a clustering algorithm.
+
+        Parameters:
+        -----------
+        n_clusters : int, default=5
+            Number of clusters to generate.
+        method : str, default='kmeans'
+            Clustering method to use ('kmeans' or others supported by create_clusters).
+        red_method : str, default='pca'
+            Dimensionality reduction method to apply before plotting.
+        show_centers : bool, default=False
+            If True, displays cluster centers on the plot.
+        grid : bool, default=True
+            Whether to display grid lines.
+        theme : str, default='light1'
+            Plot color theme.
+        title : str, optional
+            Title of the plot. If None, no title is shown.
+        nlabels : int, default=0
+            Number of token labels to display on the plot.
+        use_subset : bool, default=False
+            If True, uses the embedding subset instead of the full embeddings.
+
+        Returns:
+        --------
+        fig : matplotlib.figure.Figure
+        ax : matplotlib.axes.Axes
+        '''
+
+        if use_subset:
+            emb, tokens = self.loader.use_subset()
+        else:
+            emb = self.embeddings
+            tokens = self.tokens
+
+        reduced_emb = reduce_dim(emb, method=red_method)
+
+        clusters, centers, reduced_emb = create_clusters(reduced_emb, n_clusters=n_clusters, method=method)
+        clusters_colors, legend_labels = self.map_colors(clusters)
+
+        fig, ax, colors = self._setup_plot(theme, grid, title)
+        ax.scatter(reduced_emb[:, 0], reduced_emb[:, 1], c=clusters_colors, alpha=0.5, s=14, marker='o')
+
+        if show_centers and centers is not None:
+            for i in range(n_clusters):
+                ax.scatter(centers[i, 0], centers[i, 1], edgecolors="grey", color=colors['text'], s=40, alpha=0.8, marker='o')
+
+        legend_elements = [plt.Line2D([0], [0], marker='o',
+                            color=color,                  
+                            label=label_text,
+                            markerfacecolor=color,       
+                            markersize=8,
+                            linestyle='None') 
+                      for label, (color, label_text) in legend_labels.items()]
+
+        texts=[] 
+        if nlabels > 0:
+            sparse_indices = self.select_sparse_labels(reduced_emb, nlabels)
+            for i in sparse_indices:
+                texts.append(ax.text(reduced_emb[i, 0], reduced_emb[i, 1], tokens[i],
+                        color=colors['text'], fontsize=9, alpha=1, ha='center', va='bottom'))
+                
+        ax.legend(handles=legend_elements, facecolor=colors['bg'], labelcolor=colors['text'])
+        adjust_text(texts, ax=ax, expand=(1.2, 2), arrowprops=dict(arrowstyle='-', color=colors['text']))
+        plt.rcParams['figure.dpi'] = 600
+        plt.show()
+        return fig, ax
+
+
+    def interactive_embeddings(self, red_method='pca', grid=True, theme='light1', title=None, use_subset=False):
+        '''
+        Creates an interactive 2D scatterplot of embeddings using Plotly.
+
+        Parameters:
+        -----------
+        red_method : str, default='pca'
+            Dimensionality reduction method to apply before plotting.
+        grid : bool, default=True
+            Whether to display grid lines.
+        theme : str, default='light1'
+            Plot color theme.
+        title : str, optional
+            Title of the plot. If None, no title is shown.
+        use_subset : bool, default=False
+            If True, uses the embedding subset instead of the full embeddings.
+
+        Returns:
+        --------
+        fig : plotly.graph_objects.Figure
+        '''
+
+        if use_subset:
+            emb, tokens = self.loader.use_subset()
+        else:
+            emb = self.embeddings
+            tokens = self.tokens
+
+        reduced_emb = reduce_dim(emb, method=red_method)
+
+        colors = self.get_theme(theme)
+
+        fig = px.scatter(reduced_emb, reduced_emb[:, 0], reduced_emb[:, 1], color_discrete_sequence=[colors['points']])
+        fig.update_traces(
+            text=tokens,
+            textposition='top center',
+            hovertemplate='%{text}<extra></extra>',
+            hoverlabel=dict(
+                bgcolor=colors['bg'], 
+                font=dict(color=colors['text'])),
+            marker=dict(size=6, opacity=0.6, line=dict(width=0))
+        )
+        fig.update_layout(
+            height=600,
+            title=title if title else "Word Embedding Interactive Plot",
+            title_x=0.5,
+            title_xanchor='center',
+            plot_bgcolor=colors['bg'],
+            paper_bgcolor=colors['bg'],
+            font=dict(color=colors['text']),
+            xaxis=dict(showticklabels=False, showgrid=grid, gridcolor=colors['grid'], zeroline=False),
+            yaxis=dict(showticklabels=False, showgrid=grid, gridcolor=colors['grid'], zeroline=False),
+            xaxis_title=None,
+            yaxis_title=None
+        )
+
+        return fig
+    
+
+    
+

wordviz-0.1.1/src/wordviz/similarity.py

@@ -0,0 +1,193 @@
+import numpy as np
+from scipy.spatial.distance import cityblock, euclidean, cosine, chebyshev, canberra, braycurtis
+from scipy.stats import pearsonr, spearmanr
+from sklearn.metrics import pairwise_distances
+from typing import List, Tuple
+import warnings
+from wordviz.loading import EmbeddingLoader
+
+def word_distance(loader: EmbeddingLoader, word1: str, word2: str, dist: str = 'cosine') -> float:
+    '''
+    Computes distance between two words given by user.
+
+    Parameters
+    -----------
+    loader: EmbeddingLoader
+        Object used to load embeddings
+    word1, word2: str
+        Word to compute distance between
+    dist: str, default='cosine'
+        Type of distance to use:
+        - 'braycurtis'
+        - 'canberra'                      
+        - 'chebyshev'
+        - 'cosine'
+        - 'dot'
+        - 'euclidean'
+        - 'manhattan'
+        - 'pearson'
+        - 'pearson'
+
+    Returns
+    --------
+    distance: float
+    '''
+    words = loader.tokens
+
+    missing = [w for w in (word1, word2) if w not in words]
+    if missing:
+        raise ValueError(f"Word(s) not in vocabulary: {', '.join(missing)}")
+
+    vec1 = loader.get_embedding(word1)      
+    vec2 = loader.get_embedding(word2)
+    emb_matrix = loader.embeddings
+
+    match dist:  
+        case 'braycurtis':
+            distance = braycurtis(vec1, vec2) 
+        case 'canberra':                        
+            distance = canberra(vec1, vec2)   
+        case 'chebyshev':
+            distance = chebyshev(vec1, vec2)                              
+        case 'cosine':
+            distance = cosine(vec1, vec2)  
+        case 'dot':
+            distance = -np.dot(vec1, vec2)     
+        case 'euclidean':
+            distance = euclidean(vec1, vec2)  
+        case 'manhattan':
+            distance = cityblock(vec1, vec2)  
+        case 'pearson':
+            pearson_corr, _ = pearsonr(vec1, vec2)
+            distance = 1 - pearson_corr 
+        case 'spearman':
+            spearman_corr, _ = spearmanr(vec1, vec2)
+            distance = 1 - spearman_corr   
+    
+    return distance
+
+
+def n_most_similar2(loader: EmbeddingLoader, target_word: str, dist: str = 'cosine', n: int = 10) -> Tuple[List[str], np.ndarray, List[float]]:
+    '''
+    Finds the n most similar words to a given target word using a specified distance metric.
+
+    Parameters
+    -----------
+    loader : EmbeddingLoader
+        An instance of the embedding loader containing word vectors.
+    target_word : str
+        The word for which to find the most similar neighbors.
+    dist : str, default='cosine'
+        The distance metric to use. Options include 'cosine', 'euclidean', etc.
+    n : int, default=10
+        The number of most similar words to retrieve.
+
+    Returns
+    --------
+    words : list of str
+        The most similar words found.
+    vectors : np.ndarray
+        Embedding vectors corresponding to the most similar words.
+    distances : list of float
+        Distances from the target word to each of the most similar words.
+    '''
+    words = loader.tokens
+
+    if target_word not in words:
+        raise ValueError(f'{target_word} is not in vocabulary')
+    
+    topn_vectors = {}
+
+    for word in words:
+        if word == target_word:
+            continue
+
+        distance = word_distance(loader, word, target_word, dist)
+        if len(topn_vectors) < n:
+            topn_vectors[word] = distance
+        else:
+            max_dist_word = max(topn_vectors, key=topn_vectors.get)
+            if distance < topn_vectors[max_dist_word]:
+                del topn_vectors[max_dist_word]
+                topn_vectors[word] = distance
+    
+    vectors = np.array([loader.get_embedding(word) for word in topn_vectors])
+    words = list(topn_vectors.keys())
+    distances = list(topn_vectors.values())
+
+    return words, vectors, distances  
+
+def n_most_similar(loader: EmbeddingLoader, target_word: str, dist: str = 'cosine', n: int = 10) -> Tuple[List[str], np.ndarray, List[float]]:
+    '''
+    Findsspairwise the n most similar words to a given target word using a specified distance metric.
+    
+    Parameters
+    -----------
+    loader : EmbeddingLoader
+        An instance of the embedding loader containing word vectors.
+    target_word : str
+        The word for which to find the most similar neighbors.
+    dist : str, default='cosine'
+        The distance metric to use. Options include 'cosine', 'euclidean', etc.
+    n : int, default=10
+        The number of most similar words to retrieve.
+    
+    Returns
+    --------
+    words : list of str
+        The most similar words found.
+    vectors : np.ndarray
+        Embedding vectors corresponding to the most similar words.
+    distances : list of float
+        Distances from the target word to each of the most similar words.
+    '''
+    words = loader.tokens
+    
+    if target_word not in words:
+        raise ValueError(f'{target_word} is not in vocabulary')
+    
+    # Ottieni il vettore target
+    target_vector = loader.get_embedding(target_word)
+    target_index = words.index(target_word)
+    
+    # Prepara gli indici di tutte le parole tranne la parola target
+    word_indices = list(range(len(words)))
+    word_indices.remove(target_index)
+    
+    # Sottoinsiemi di parole e vettori corrispondenti
+    filtered_words = [words[i] for i in word_indices]
+    
+    # Per gestire vocabolari molto grandi, possiamo elaborare per batch
+    batch_size = 10000
+    all_distances = []
+    all_indices = []
+    
+    for i in range(0, len(filtered_words), batch_size):
+        batch_words = filtered_words[i:i+batch_size]
+        batch_vectors = np.array([loader.get_embedding(word) for word in batch_words])
+        
+        # Calcola le distanze pairwise tra il vettore target e tutti i vettori batch
+        # Reshape target_vector per ottenere una matrice 1 x dimensione
+        distances = pairwise_distances(
+            target_vector.reshape(1, -1), 
+            batch_vectors, 
+            metric=dist
+        ).flatten()
+        
+        all_distances.extend(distances)
+        all_indices.extend(range(i, min(i+batch_size, len(filtered_words))))
+    
+    # Seleziona gli indici delle n distanze minori
+    if len(all_distances) <= n:
+        top_n_indices = np.argsort(all_distances)
+    else:
+        top_n_indices = np.argpartition(all_distances, n-1)[:n]
+        # Ordina questi n indici per distanza
+        top_n_indices = top_n_indices[np.argsort(np.array(all_distances)[top_n_indices])]
+    
+    # Ottieni le parole, le distanze e i vettori corrispondenti
+    result_words = [filtered_words[all_indices[i]] for i in top_n_indices]
+    result_distances = [all_distances[i] for i in top_n_indices]
+    result_vectors = np.array([loader.get_embedding(word) for word in result_words])
+    
+    return result_words, result_vectors, result_distances