dstklib 1.0.0__py3-none-any.whl

dstk/pipelines.py

@@ -0,0 +1,114 @@
+from .workflow_tools import WorkflowBuilder
+from .pipeline_tools import PipelineBuilder
+from dstk.lib_types import Language, DataFrame
+
+from .text_processor import TextProcessor
+from .text_matrix_builder import TextMatrixBuilder
+from .weight_matrix import WeightMatrix
+from .count_models import CountModels
+from .geometric_distance import GeometricDistance
+from .predict_models import PredictModels
+
+def StandardModel(text: str, model: str | Language, window_size: int = 2, components: int = 100) -> DataFrame:
+    """
+    This pipeline generates word embeddings using the standard model as defined by (Lenci & Sahlgren 97). It preprocesses the text by removing stop words, lowering the words and segmenting the text using a context window. The co-occurrence matrix is weighted with PPMI and reduced with truncated SVD. 
+
+    :param text: The text to extract the embeddings from.
+    :param model: The spaCy NLP model to tokenize the text.
+    :param window_size: The size of the context window to segment the text. Defaults to 2.
+    :param components: The number of dimensions of the embeddings. Defaults to 100.
+    """
+
+    StandardTextWorkflow: WorkflowBuilder = WorkflowBuilder(
+        work_class=TextProcessor, 
+        method_representation={
+            "set_model": {"model": model},
+            "get_tokens": {},
+            "remove_stop_words": {},
+            "get_text": {"lemmatize": True},
+            "to_lower": {},
+            "corpus_by_context_window": {"window_size": window_size}
+        }
+    )
+
+    StandardMatrix: WorkflowBuilder = WorkflowBuilder(
+        work_class=TextMatrixBuilder,
+        method_representation={
+            "create_dtm": {},
+            "create_co_occurrence_matrix": {},
+            "to_dataframe": {}
+        }
+    )
+
+    StandardWeightMatrix: WorkflowBuilder = WorkflowBuilder(
+        work_class=WeightMatrix,
+        method_representation={
+            "pmi": {"positive": True}
+        }
+    )
+
+    StandardCountModels: WorkflowBuilder = WorkflowBuilder(
+        work_class=CountModels,
+        method_representation={
+            "scale_matrix": {},
+            "svd_embeddings": {"n_components": components},
+            "to_dataframe": {}
+        }
+    )
+
+    Model: PipelineBuilder = PipelineBuilder([
+        StandardTextWorkflow,
+        StandardMatrix,
+        StandardWeightMatrix,
+        StandardCountModels
+    ])
+
+    return Model(text=text)
+
+def SGNSModel(text: str, model: str | Language, path: str, **kwargs) -> PredictModels:
+    """
+    This pipeline generates word embeddings using Skip-Gram with Negative Sampling (SGNS) as defined by (Lenci & Sahlgren 162). It preprocesses the text by extracting the sentences, removing stop words and lowering them. The embeddings are extracted by using word2vec to do SGNS. Returns an instance of PredictModels.
+
+    :param text: The text to extract the embeddings from.
+    :param model: The spaCy NLP model to tokenize the text.
+    :param path: The path to save the processed senteces.
+    :param kwargs:  Additional keyword arguments to pass to gensim.models.Word2Vec. Common options include:
+            - vector_size: Size of the word embedding vectors.
+            - workers: Number of CPU cores to be used during the training process.
+            - negative: Specifies how many "noise words" to sample for each positive example during training. Typical values range from 5 to 20. Higher values make training slower but can improve embedding quality.
+            - window (int): Maximum distance between the current and predicted word.
+            - min_count (int): Ignores all words with total frequency lower than this.
+
+            For more information check: https://radimrehurek.com/gensim/models/word2vec.html
+    """
+
+    SGNSTextWorkflow: WorkflowBuilder = WorkflowBuilder(
+        work_class=TextProcessor,
+        method_representation={
+            "set_model": {"model": model},
+            "get_sentences": {},
+            "remove_stop_words": {},
+            "get_text": {"lemmatize": True},
+            "to_lower": {},
+            "join": {},
+            "save_to_file": {"path": path}
+        }
+    )
+
+    SGNSPredictWorkflow: WorkflowBuilder = WorkflowBuilder(
+        work_class=PredictModels,
+        method_representation={
+            "word2vec": {
+                "sg": 1,
+                **kwargs
+            }
+        },
+        result=False
+    )
+
+    Model: PipelineBuilder = PipelineBuilder([
+        SGNSTextWorkflow,
+        SGNSPredictWorkflow
+    ])
+
+    return Model(text=text)

dstk/plot_embeddings.py

@@ -0,0 +1,240 @@
+import matplotlib.pyplot as plt
+from sklearn.cluster import KMeans
+from sklearn.metrics import silhouette_score
+from kneed import KneeLocator
+from umap import UMAP
+from .workflow_tools import requires, workflow, WorkflowManager
+from .matrix_base import MatrixRepresentation, accept_matrix_representation
+
+from .lib_types import ndarray, PathCollection, Axes, Axes3D, Labels
+
+STAGES = [
+    "start", # The embeddings matrix representation
+    "clusters", # The ideal number of clusters to be plotted
+    "end" # The result of the plot
+]
+
+# Maybe return the interias and the highest score?
+class PlotEmbeddings(WorkflowManager):
+    """
+    Provides a set of methods to visualize word embeddings in both 2D and 3D.
+
+    :param embeddings: A matrix representation of word embeddings.
+    """
+
+    def __init__(self, embeddings: MatrixRepresentation | None = None):
+        """
+        Initializes PlotEmbeddings with given attributes.
+        """
+
+        super().__init__()
+
+        # Stages
+
+        self._clusters: tuple[int, float]
+
+        self._set_workflow(input_arg=embeddings)
+
+    @requires(stages=["start"])
+    @workflow(input_arg="matrix", input_process="_start", output_process="_clusters", next_stage="clusters")
+    @accept_matrix_representation(meta="n_clusters")
+    def elbow_analysis(self, *, matrix: ndarray, max_k: int, show: bool = False, path: str | None = None) -> int:
+        """
+        Generates an Elbow plot to help determine the optimal number of clusters for the word embeddings. Returns the best number of clusters.
+
+        :param matrix: An array to be clustered.
+        :param max_k: The maximum number of clusters to evaluate when applying the Elbow method.
+        :param show: If True, shows the plot. Defaults to False.
+        :param path: If provided, saves the plot in the specified path. Defaults to None.
+
+        This method supports different matrix forms due to decorator-based preprocessing:
+            - matrix: ndarray
+            - matrix representation: MatrixRepresentation
+        """
+        plt.clf() 
+        plt.close("all")
+
+        means: list[int] = []
+        inertias: list[float] = []
+
+        for k in range(1, max_k):
+            kmeans: KMeans = KMeans(n_clusters=k, random_state=42)
+            kmeans.fit(matrix)
+
+            means.append(k)
+            inertias.append(kmeans.inertia_)
+
+        elbow: KneeLocator = KneeLocator(means, inertias, curve="convex", direction="decreasing")
+
+        print(f"The best cluster is {elbow.knee} with an inertia of {elbow.knee_y}")
+
+        elbow.plot_knee()
+
+        if path:
+            plt.savefig(path)
+
+        if show:
+            plt.show()
+
+        return elbow.knee
+
+    @requires(stages=["start"])
+    @workflow(input_arg="matrix", input_process="_start", output_process="_clusters", next_stage="clusters")
+    @accept_matrix_representation(meta="n_clusters")
+    def extract_silhouette_score(self, *, matrix: ndarray, max_k: int, show: bool = False, path: str | None = None, **kwargs) -> int:
+        """
+        Extracts and plots the Silhouette score to help determine the optimal number of clusters for the word embeddings. Returns the best number of clusters based on the highest score.
+
+        :param matrix: An array to be clustered.
+        :param max_k: The maximum number of clusters to evaluate when computing the Silhouette score.
+        :param show: If True, shows the plot. Defaults to False.
+        :param path: If provided, saves the plot in the specified path. Defaults to None.
+        :param kwargs: Additional keyword arguments to pass to sklearn.metrics silhouette_score. For more information check: https://scikit-learn.org/stable/modules/generated/sklearn.metrics.silhouette_score.html
+
+        This method supports different matrix forms due to decorator-based preprocessing:
+            - matrix: ndarray
+            - matrix representation: MatrixRepresentation
+        """
+        plt.clf() 
+        plt.close("all")
+
+        sil_scores: list[tuple[int, float]] = []
+
+        for k in range(2, max_k):
+            kmeans: KMeans = KMeans(n_clusters=k, random_state=42)
+            kmeans.fit(matrix)
+            sil_score: float = silhouette_score(matrix, kmeans.labels_)
+            sil_scores.append((k, sil_score), **kwargs)
+
+        highest_score: tuple[int, float] = max(sil_scores, key=lambda tup: tup[1])
+        print(f"The best cluster is {highest_score[0]} with a Silhouette score of {highest_score[1]}")
+
+        clusters, scores = zip(*sil_scores)
+        
+        plt.plot(clusters, scores, 'o-')
+
+        plt.xlabel("Number of Clusters")
+        plt.ylabel("Silhouette Scores")
+        plt.title("Silhouette Score Plot")
+        plt.grid(True)
+
+        if path:
+            plt.savefig(path)
+
+        if show:
+            plt.show()
+
+        return highest_score[0]
+
+    @requires(stages=["clusters"])
+    @workflow(input_arg="embeddings", input_attrs={"embeddings": None, "n_clusters": {"meta": "n_clusters"}}, input_process="_clusters", output_process="_end", next_stage="end") 
+    def plot_embeddings_2D(self, *, embeddings: MatrixRepresentation, n_clusters: int = 1, alpha: float = 0.8, font_size: int = 8, grid: bool = True, show: bool = True, path: str | None = None, umap_neighbors: int = 15, umap_metric: str = "cosine", umap_dist: float = 0.1) -> PathCollection:
+        """
+        Generates a 2D plot of the word embedddings using UMAP for dimensionality reduction.
+
+        :param embeddings: A matrix representation of word embeddings.
+        :param n_clusters: The number of clusters to form when grouping the word embeddings. Defaluts to 1.
+        :param alpha: The transparency level (alpha) of the plotted dots, between 0 (fully transparent) and 1 (fully opaque). Defaults to 0.8.
+        :param font_size: Specifies the font size for the labels of the plotted dots. Defaults to 8.
+        :param grid: If True, displays a grid on the plot; if False, hides it. Defaults to True.
+        :param show: If True, shows the plot. Defaults to True.
+        :param path: If provided, saves the plot in the specified path. Defaults to None.
+        :param umap_neighbors: Controls how UMAP balances local versus global structure. Higher values consider a broader context when reducing dimensions. Defaults to 15.
+        :param umap_metric: The distance metric UMAP uses to assess similarity between words (e.g., "cosine", "euclidean"). Defaults to "cosine", which is common for word embeddings.
+        :param umap_dist: Controls how tightly UMAP packs points together. Lower values keep similar words closer in the 2D space. Defaults to 0.1.
+
+        :return: A matplotlib PathCollection object representing the plotted points.
+        """
+
+        plt.clf()
+        plt.close("all")
+
+        embeddings_matrix: ndarray = embeddings.matrix
+        labels: Labels = embeddings.rows
+
+        reducer: UMAP = UMAP(n_components=2, n_neighbors=umap_neighbors, min_dist=umap_dist, metric=umap_metric)
+        umap_embeddings: ndarray = reducer.fit_transform(embeddings_matrix)
+
+        kmeans: KMeans = KMeans(n_clusters=n_clusters, random_state=42)
+        clusters: ndarray = kmeans.fit_predict(umap_embeddings)
+        scatter: PathCollection = plt.scatter(umap_embeddings[:, 0], umap_embeddings[:, 1], c=clusters, cmap='Spectral', alpha=alpha)
+
+        if labels is not None:
+            for index, label in enumerate(labels):
+                plt.annotate(label, (umap_embeddings[index, 0], umap_embeddings[index, 1]), fontsize=font_size, alpha=0.6)
+        else:
+            raise ValueError("Rows of embeddings are None. Make sure your matrix contains labeled rows.")
+
+        plt.xlabel("Axis 1")
+        plt.ylabel("Axis 2")
+        plt.title("Projection of word embeddings")
+        plt.colorbar(scatter, label="Cluster")
+        plt.grid(grid)
+        plt.tight_layout()
+
+        if path:
+            plt.savefig(path)
+
+        if show:
+            plt.show()
+        
+        return scatter
+
+    @requires(stages=["clusters"])
+    @workflow(input_arg="embeddings", input_attrs={"embeddings": None, "n_clusters": {"meta": "n_clusters"}}, input_process="_clusters", output_process="_end", next_stage="end") 
+    def plot_embeddings_3D(self, *, embeddings: MatrixRepresentation, n_clusters: int = 1, alpha: float = 0.8, font_size: int = 8, grid: bool = True, show: bool = True, path: str | None = None, umap_neighbors: int = 15, umap_metric: str = "cosine", umap_dist: float = 0.1) -> PathCollection:
+        """
+        Generates a 3D plot of the word embedddings.
+
+        :param embeddings: A matrix representation of word embeddings.
+        :param n_clusters: The number of clusters to form when grouping the word embeddings. Defaults to 1.
+        :param alpha: The transparency level (alpha) of the plotted dots, between 0 (fully transparent) and 1 (fully opaque). Defaults to 0.8.
+        :param font_size: Specifies the font size for the labels of the plotted dots. Defaults to 8.
+        :param grid: If True, displays a grid on the plot; if False, hides it. Defaults to True.
+        :param show: If True, shows the plot. Defaults to True.
+        :param path: If provided, saves the plot in the specified path. Defaults to None.
+        :param umap_neighbors: Controls how UMAP balances local versus global structure. Higher values consider a broader context when reducing dimensions. Defaults to 15.
+        :param umap_metric: The distance metric UMAP uses to assess similarity between words (e.g., "cosine", "euclidean"). Defaults to "cosine", which is common for word embeddings.
+        :param umap_dist: Controls how tightly UMAP packs points together. Lower values keep similar words closer in the 2D space. Defaults to 0.1.
+
+        :return: A matplotlib PathCollection object representing the plotted points.
+        """
+        plt.clf()
+        plt.close("all")
+
+        embeddings_matrix: ndarray = embeddings.matrix
+        labels: Labels = embeddings.rows
+
+        reducer: UMAP = UMAP(n_components=3, n_neighbors=umap_neighbors, min_dist=umap_dist, metric=umap_metric)
+        umap_embeddings: ndarray = reducer.fit_transform(embeddings_matrix)
+
+        kmeans: KMeans = KMeans(n_clusters=n_clusters, random_state=42)
+        clusters = kmeans.fit_predict(umap_embeddings)
+
+        ax: Axes3D = plt.axes(projection="3d")
+
+        scatter: PathCollection = ax.scatter(umap_embeddings
+        [:, 0], umap_embeddings[:, 1], umap_embeddings[:, 2], c=clusters, cmap="Spectral", alpha=alpha)
+
+        if labels is not None:
+            for index, label in enumerate(labels):
+                ax.text(umap_embeddings[index, 0], umap_embeddings[index, 1], umap_embeddings[index, 2], label, size=font_size, alpha=0.6)
+        else:
+            raise ValueError("Rows of embeddings are None. Make sure your matrix contains labeled rows.")
+
+        ax.set_xlabel("Axis 1")
+        ax.set_ylabel("Axis 2")
+        ax.set_zlabel("Axis 3")
+        ax.set_title("3D projection of word embeddings")
+
+        plt.colorbar(scatter, label="Cluster")
+        plt.grid(grid)
+        plt.tight_layout()
+  
+        if path:
+            plt.savefig(path)
+
+        if show:
+            plt.show()
+        
+        return scatter

dstk/predict_models.py

@@ -0,0 +1,189 @@
+from gensim.models import Word2Vec
+import fasttext
+import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
+from pathlib import Path
+from .workflow_tools import requires, workflow, WorkflowManager
+from .matrix_base import MatrixRepresentation
+
+from .lib_types import ndarray, FastText
+
+# The workflow needs to be completely restructured
+
+STAGES = [
+    "start", # The path to the sentences file
+    "predict_model", # After a model has been generated,
+    "embeddings_operations" # After a metric distance has ben applied
+    "end" # After the model was saved or the model was turned into matrix representation
+]
+
+class PredictModels(WorkflowManager):
+    """
+    Provides a unified interface to work seamlessly with Gensim's Word2Vec and Facebook's FastText models.
+
+    This class simplifies the process of training, loading, and using word embeddings by integrating both popular algorithms under a single API.
+
+    :param path: The path to a file conatining a list of sentences or collocations from which to build word embeddings.
+    """
+
+    _start: str
+    _end: str | MatrixRepresentation
+
+    def __init__(self, path: str | None = None):
+        """
+        Initializes PredictModels with given attributes.
+        """
+
+        super().__init__()
+
+        # Stages
+
+        self._predict_model: Word2Vec | FastText
+        self._embeddings_operations: list[tuple[str,float]] | float
+        
+        self._set_workflow(input_arg=path)
+
+    @requires(stages=["start"])
+    @workflow(input_arg="path", input_process="_start", output_process="_predict_model", next_stage="predict_model")
+    def word2vec(self, *, path: str, **kwargs) -> Word2Vec:
+        """
+        Creates word embeddings using the Word2Vec algorithm.
+
+        :param path: The path to a file conatining a list of sentences or collocations from which to build word embeddings.
+        :param kwargs:  Additional keyword arguments to pass to gensim.models.Word2Vec. Common options include:
+            - vector_size: Size of the word embedding vectors.
+            - workers: Number of CPU cores to be used during the training process.
+            - sg: Training algorithm. 1 for skip-gram; 0 for CBOW (Continuous Bag of Words).
+            - window (int): Maximum distance between the current and predicted word.
+            - min_count (int): Ignores all words with total frequency lower than this.
+
+            For more information check: https://radimrehurek.com/gensim/models/word2vec.html
+        """
+
+        return Word2Vec(
+            corpus_file=path,
+            **kwargs
+        )
+
+    @requires(stages=["start"])
+    @workflow(input_arg="path", input_process="_start", output_process="_predict_model", next_stage="predict_model")
+    def fastText(self, *, path: str, **kwargs) -> FastText:
+        """
+        Creates word embeddings using the FastText algorithm.
+
+        :param path: The path to a file conatining a list of sentences or collocations from which to build word embeddings.
+        :param kwargs: Additional keyword arguments to pass to fasttext.train_unsupervised. 
+            Common options include:
+                - dim: Size of the word embedding vectors.
+                - model: Training algorithm: skipgram or cbow (Continuous Bag of Words)
+                - thread: Number of CPU cores to be used during the training process.
+
+                For more information check: https://fasttext.cc/docs/en/options.html
+        """
+
+        return fasttext.train_unsupervised(
+            path,
+            **kwargs
+        )
+
+    @requires(stages=["start"])
+    @workflow(input_arg="path", input_process="_start", output_process="_predict_model", next_stage="predict_model")
+    def load_model(self, *, path: str) -> Word2Vec | FastText:
+        """
+        Loads the trained embeddings in .model (Word2Vec) or .bin (FastText) format, depending on the algorithm used.
+
+        :param path: Path to the saved model file.
+        """
+
+        extension: str = Path(path).suffix.lower()
+
+        if extension == ".model":
+            return Word2Vec.load(path)
+        elif extension == ".bin":
+            return fasttext.load_model(path)
+        else:
+            raise ValueError(f"Model extension {extension} not recognized.")
+
+    @requires(stages=["predict_model", "embeddings_operations"])
+    @workflow(input_arg="model", input_process="_predict_model", output_process="_end", next_stage="end")
+    def save_model(self, *, model: Word2Vec | FastText, path: str) -> str:
+        """
+        Saves the trained embeddings in .model (Word2Vec) or .bin (FastText) format, depending on the algorithm used.
+
+        :param model: A trained Word2Vec or FastText model.
+        :param path: The path (without extension) where to save the model.
+        """
+        full_path: Path = Path(path)
+
+        if isinstance(model, Word2Vec):
+            model.save(str(full_path.with_suffix(".model")))
+        elif isinstance(model, FastText):
+            model.save_model(str(full_path.with_suffix(".bin")))
+        else:
+            raise NotImplementedError(f"Model identifier type {type(model.__name__)} not yet supported")
+        
+        return str(full_path.resolve())
+
+    @requires(stages=["predict_model", "embeddings_operations"], multiple_calls=True)
+    @workflow(input_arg="model", input_process="_predict_model", output_process="_embeddings_operations", next_stage="embeddings_operations")
+    def nearest_neighbors(self, *, model: Word2Vec | FastText, word: str, n_neighbors: int) -> list[tuple[str,float]]:
+        """
+        Returns the top N most semantically similar words to a given target word.
+
+        :param model: A trained Word2Vec or FastText model.
+        :param word: The target word to find neighbors for.
+        :param n_neighbors: Number of nearest neighbors to return.
+        """
+
+        if isinstance(model, Word2Vec):
+            return model.wv.most_similar(word, topn=n_neighbors)
+        elif isinstance(model, FastText):
+            result: list[tuple[float, str]] = model.get_nearest_neighbors(word, k=n_neighbors)
+            return [(word, score) for score, word in result]
+        else:
+            raise NotImplementedError(f"Model identifier type {type(model.__name__)} not yet supported")
+
+    @requires(stages=["predict_model", "embeddings_operations"], multiple_calls=True)
+    @workflow(input_arg="model", input_process="_predict_model", output_process="_embeddings_operations", next_stage="embeddings_operations")
+    def cos_similarity(self, *, model: Word2Vec | FastText, first_word: str, second_word: str) -> float:
+        """
+        Computes the cosine similarity between the embeddings of two words.
+
+        :param model: A trained Word2Vec or FastText model.
+        :param first_word: The first word in the pair.
+        :param second_word: The second word in the pair. 
+        """
+
+        if isinstance(model, Word2Vec):
+            return float(model.wv.similarity(first_word, second_word))
+        elif isinstance(model, FastText):
+            first_word_vector: ndarray = np.array(model[first_word]).reshape(1, -1)
+            second_word_vector: ndarray = np.array(model[second_word]).reshape(1, -1)
+
+            cos_sim: ndarray = cosine_similarity(first_word_vector, second_word_vector)
+
+            return float(cos_sim[0][0])
+        else:
+            raise NotImplementedError(f"Model identifier type {model.__name__} not yet supported")
+
+    @requires(stages=["predict_model"])
+    @workflow(input_arg="model", input_process="_predict_model", output_process="_end", next_stage="end")
+    def to_matrix(self, *, model: Word2Vec | FastText) -> MatrixRepresentation:
+        """
+        Returns a matrix represenation of the word embeddings and their associated labels.
+
+        :param model: A trained Word2Vec or FastText model.
+        """
+
+        word_vectors: ndarray
+        labels: list[str]
+
+        if isinstance(model, Word2Vec):
+            word_vectors = model.wv[model.wv.index_to_key]
+            labels = list(model.wv.index_to_key)
+        elif isinstance(model, FastText):
+            words: list[str] = model.words
+            word_vectors = np.array([model[word] for word in words])
+            labels = words
+
+        return MatrixRepresentation(matrix=word_vectors, rows=labels)

dstk/text_matrix_builder.py

@@ -0,0 +1,87 @@
+import pandas as pd
+from sklearn.feature_extraction.text import CountVectorizer
+import numpy as np
+from .workflow_tools import requires, workflow, WorkflowManager
+from .matrix_base import MatrixRepresentation, matrix_to_dataframe
+
+from .lib_types import csr_matrix, ndarray, DataFrame, csc_matrix, Matrix, Labels
+
+STAGES = [
+    "start", # Before any processing
+    "matrix_operations" # Matrix operations and transformations
+    "end" # Dataframe operations
+]
+
+class TextMatrixBuilder(WorkflowManager):
+    """
+    Creates a Document Term Matrix, a Co-ocurrence Matrix, and dataframes from them.
+
+    :param corpus: A list of sentences or collocations from which to build a matrix.
+    """
+
+    _start: list[str]
+    _end: DataFrame
+
+    def __init__(self, corpus: list[str] | None = None):
+        """
+        Initializes TextMatrixBuilder with given attributes.
+        """
+
+        super().__init__()
+
+        self._matrix_operations: MatrixRepresentation
+        
+        self._set_workflow(input_arg=corpus)
+
+    @requires(stages=["start"])
+    @workflow(input_arg="corpus", input_process="_start", output_process="_matrix_operations", next_stage="matrix_operations")
+    def create_dtm(self, *, corpus: list[str], **kwargs) -> MatrixRepresentation:
+        """
+        Creates Document Term Matrix (DTM).
+
+        :param corpus: A list of sentences or collocations from which to build a matrix.
+        :param kwargs: Additional keyword arguments to pass to sklearn's CountVectorizer.
+            Common options include:
+                - stop_words: If provided, a list of stopwords to remove from the corpus.
+                - ngram_range: A tuple (min_n, max_n) specifying the range of n-grams to consider.
+            For more information check: https://scikit-learn.org/stable/modules/generated/sklearn.feature_extraction.text.CountVectorizer.html
+        """
+
+        vectorizer: CountVectorizer = CountVectorizer(**kwargs)
+
+        dtm: csr_matrix = vectorizer.fit_transform(corpus)
+
+        return MatrixRepresentation(
+            matrix=dtm,
+            rows=np.array(corpus), 
+            columns=vectorizer.get_feature_names_out()
+        )
+
+    @requires(stages=["matrix_operations"])
+    @workflow(input_arg="matrix", input_attrs={"matrix": "matrix", "rows": "columns", "columns": "columns"},  input_process="_matrix_operations", output_process="_matrix_operations")
+    def create_co_occurrence_matrix(self, *, matrix: csr_matrix, rows: Labels = None, columns: Labels = None) -> csc_matrix:
+        """
+        Creates a Co-occurrence matrix.
+
+        :param matrix: A Document Term Matrix (DTM) from which o build a Co-occurrence matrix.
+        """
+
+        co_matrix = matrix.T @ matrix
+
+        return MatrixRepresentation(
+            matrix=co_matrix,
+            rows=rows,
+            columns=columns
+        )
+
+    @requires(stages=["matrix_operations"])
+    @workflow(input_arg="matrix", input_process="_matrix_operations", output_process="_end", next_stage="end")
+    def to_dataframe(self, *, matrix: MatrixRepresentation, **kwargs) -> DataFrame:
+        """
+        Creates a dataframe from a matrix representation.
+
+        :param matrix: A matrix representation from which to create a dataframe.
+        :param kwargs: Additional keyword arguments to pass to sklearn's pandas' DataFrame.
+        """
+        
+        return matrix_to_dataframe(matrix=matrix, **kwargs)