Merge pull request #21 from rbroc/docstrings

add/fix docstrings, mainly for feature importance functions

Author: x-tabdeveloping

turftopic/base.py

@@ -161,7 +161,7 @@ def print_highest_ranking_documents(
             ID of the topic to display.
         raw_documents: list of str
             List of documents to consider.
-        document_topic_matrix: ndarray of shape (n_topics, n_topics), optional
+        document_topic_matrix: ndarray of shape (n_documents, n_topics), optional
             Document topic matrix to use. This is useful for transductive methods,
             as they cannot infer topics from text.
         top_k: int, default 5

turftopic/feature_importance.py

@@ -1,14 +1,32 @@
 import numpy as np
 import scipy.sparse as spr
 from sklearn.metrics import pairwise_distances
-from sklearn.preprocessing import normalize
 
 
 def cluster_centroid_distance(
     cluster_centroids: np.ndarray,
     vocab_embeddings: np.ndarray,
     metric="cosine",
 ) -> np.ndarray:
+    """Computes feature importances based on distances between
+    topic vectors (cluster centroids) and term embeddings
+
+    Parameters
+    ----------
+    cluster_centroids: np.ndarray
+        Coordinates of cluster centroids of shape (n_topics, embedding_size)
+    vocab_embeddings: np.ndarray
+        Term embeddings of shape (vocab_size, embedding_size)
+    metric: str, defaul 'cosine'
+        Metric used to compute distance from centroid.
+        See documentation for sklearn.metrics.pairwise.distance_metrics
+        for valid values.
+
+    Returns
+    -------
+    ndarray of shape (n_topics, vocab_size)
+        Term importance matrix.
+    """
     distances = pairwise_distances(
         cluster_centroids, vocab_embeddings, metric=metric
     )
@@ -23,6 +41,20 @@ def cluster_centroid_distance(
 def soft_ctf_idf(
     doc_topic_matrix: np.ndarray, doc_term_matrix: spr.csr_matrix
 ) -> np.ndarray:
+    """Computes feature importances using Soft C-TF-IDF
+
+    Parameters
+    ----------
+    doc_topic_matrix: np.ndarray
+        Document-topic matrix of shape (n_documents, n_topics)
+    doc_term_matrix: np.ndarray
+        Document-term matrix of shape (n_documents, vocab_size)
+
+    Returns
+    -------
+    ndarray of shape (n_topics, vocab_size)
+        Term importance matrix.
+    """
     eps = np.finfo(float).eps
     term_importance = doc_topic_matrix.T @ doc_term_matrix
     overall_in_topic = np.abs(term_importance).sum(axis=1)
@@ -36,6 +68,20 @@ def soft_ctf_idf(
 def ctf_idf(
     doc_topic_matrix: np.ndarray, doc_term_matrix: spr.csr_matrix
 ) -> np.ndarray:
+    """Computes feature importances using standard C-TF-IDF
+
+    Parameters
+    ----------
+    doc_topic_matrix: np.ndarray
+        Document-topic matrix of shape (n_documents, n_topics)
+    doc_term_matrix: np.ndarray
+        Document-term matrix of shape (n_documents, vocab_size)
+
+    Returns
+    -------
+    ndarray of shape (n_topics, vocab_size)
+        Term importance matrix.
+    """
     labels = np.argmax(doc_topic_matrix, axis=1)
     n_topics = doc_topic_matrix.shape[1]
     components = []