Solving the Top k most frequent words problem using a max-heap

DIRECTORY.md

@@ -327,6 +327,7 @@
   * [Minimum Coin Change](dynamic_programming/minimum_coin_change.py)
   * [Minimum Cost Path](dynamic_programming/minimum_cost_path.py)
   * [Minimum Partition](dynamic_programming/minimum_partition.py)
+  * [Minimum Size Subarray Sum](dynamic_programming/minimum_size_subarray_sum.py)
   * [Minimum Squares To Represent A Number](dynamic_programming/minimum_squares_to_represent_a_number.py)
   * [Minimum Steps To One](dynamic_programming/minimum_steps_to_one.py)
   * [Minimum Tickets Cost](dynamic_programming/minimum_tickets_cost.py)
@@ -339,6 +340,7 @@
   * [Word Break](dynamic_programming/word_break.py)
 
 ## Electronics
+  * [Apparent Power](electronics/apparent_power.py)
   * [Builtin Voltage](electronics/builtin_voltage.py)
   * [Carrier Concentration](electronics/carrier_concentration.py)
   * [Circular Convolution](electronics/circular_convolution.py)
@@ -348,6 +350,7 @@
   * [Electrical Impedance](electronics/electrical_impedance.py)
   * [Ind Reactance](electronics/ind_reactance.py)
   * [Ohms Law](electronics/ohms_law.py)
+  * [Real And Reactive Power](electronics/real_and_reactive_power.py)
   * [Resistor Equivalence](electronics/resistor_equivalence.py)
   * [Resonant Frequency](electronics/resonant_frequency.py)
 
@@ -483,6 +486,7 @@
   * [Astar](machine_learning/astar.py)
   * [Data Transformations](machine_learning/data_transformations.py)
   * [Decision Tree](machine_learning/decision_tree.py)
+  * [Dimensionality Reduction](machine_learning/dimensionality_reduction.py)
   * Forecasting
     * [Run](machine_learning/forecasting/run.py)
   * [Gradient Descent](machine_learning/gradient_descent.py)
@@ -604,6 +608,7 @@
   * [Perfect Number](maths/perfect_number.py)
   * [Perfect Square](maths/perfect_square.py)
   * [Persistence](maths/persistence.py)
+  * [Pi Generator](maths/pi_generator.py)
   * [Pi Monte Carlo Estimation](maths/pi_monte_carlo_estimation.py)
   * [Points Are Collinear 3D](maths/points_are_collinear_3d.py)
   * [Pollard Rho](maths/pollard_rho.py)
@@ -1162,6 +1167,7 @@
   * [Snake Case To Camel Pascal Case](strings/snake_case_to_camel_pascal_case.py)
   * [Split](strings/split.py)
   * [Text Justification](strings/text_justification.py)
+  * [Top K Frequent Words](strings/top_k_frequent_words.py)
   * [Upper](strings/upper.py)
   * [Wave](strings/wave.py)
   * [Wildcard Pattern Matching](strings/wildcard_pattern_matching.py)

data_structures/heap/heap.py

@@ -1,9 +1,28 @@
 from __future__ import annotations
 
+from abc import abstractmethod
 from collections.abc import Iterable
+from typing import Generic, Protocol, TypeVar
 
 
-class Heap:
+class Comparable(Protocol):
+    @abstractmethod
+    def __lt__(self: T, other: T) -> bool:
+        pass
+
+    @abstractmethod
+    def __gt__(self: T, other: T) -> bool:
+        pass
+
+    @abstractmethod
+    def __eq__(self: T, other: object) -> bool:
+        pass
+
+
+T = TypeVar("T", bound=Comparable)
+
+
+class Heap(Generic[T]):
     """A Max Heap Implementation
 
     >>> unsorted = [103, 9, 1, 7, 11, 15, 25, 201, 209, 107, 5]
@@ -27,7 +46,7 @@ class Heap:
     """
 
     def __init__(self) -> None:
-        self.h: list[float] = []
+        self.h: list[T] = []
         self.heap_size: int = 0
 
     def __repr__(self) -> str:
@@ -79,7 +98,7 @@ def max_heapify(self, index: int) -> None:
                 # fix the subsequent violation recursively if any
                 self.max_heapify(violation)
 
-    def build_max_heap(self, collection: Iterable[float]) -> None:
+    def build_max_heap(self, collection: Iterable[T]) -> None:
         """build max heap from an unsorted array"""
         self.h = list(collection)
         self.heap_size = len(self.h)
@@ -88,7 +107,7 @@ def build_max_heap(self, collection: Iterable[float]) -> None:
             for i in range(self.heap_size // 2 - 1, -1, -1):
                 self.max_heapify(i)
 
-    def extract_max(self) -> float:
+    def extract_max(self) -> T:
         """get and remove max from heap"""
         if self.heap_size >= 2:
             me = self.h[0]
@@ -102,7 +121,7 @@ def extract_max(self) -> float:
         else:
             raise Exception("Empty heap")
 
-    def insert(self, value: float) -> None:
+    def insert(self, value: T) -> None:
         """insert a new value into the max heap"""
         self.h.append(value)
         idx = (self.heap_size - 1) // 2
@@ -144,7 +163,7 @@ def heap_sort(self) -> None:
     ]:
         print(f"unsorted array: {unsorted}")
 
-        heap = Heap()
+        heap: Heap[int] = Heap()
         heap.build_max_heap(unsorted)
         print(f"after build heap: {heap}")
 

machine_learning/linear_discriminant_analysis.py

@@ -399,7 +399,7 @@ def main():
         if input("Press any key to restart or 'q' for quit: ").strip().lower() == "q":
             print("\n" + "GoodBye!".center(100, "-") + "\n")
             break
-        system("clear" if name == "posix" else "cls")  # noqa: S605
+        system("cls" if name == "nt" else "clear")  # noqa: S605
 
 
 if __name__ == "__main__":

strings/top_k_frequent_words.py

@@ -0,0 +1,101 @@
+"""
+Finds the top K most frequent words from the provided word list.
+
+This implementation aims to show how to solve the problem using the Heap class
+already present in this repository.
+Computing order statistics is, in fact, a typical usage of heaps.
+
+This is mostly shown for educational purposes, since the problem can be solved
+in a few lines using collections.Counter from the Python standard library:
+
+from collections import Counter
+def top_k_frequent_words(words, k_value):
+    return [x[0] for x in Counter(words).most_common(k_value)]
+"""
+
+
+from collections import Counter
+from functools import total_ordering
+
+from data_structures.heap.heap import Heap
+
+
+@total_ordering
+class WordCount:
+    def __init__(self, word: str, count: int) -> None:
+        self.word = word
+        self.count = count
+
+    def __eq__(self, other: object) -> bool:
+        """
+        >>> WordCount('a', 1).__eq__(WordCount('b', 1))
+        True
+        >>> WordCount('a', 1).__eq__(WordCount('a', 1))
+        True
+        >>> WordCount('a', 1).__eq__(WordCount('a', 2))
+        False
+        >>> WordCount('a', 1).__eq__(WordCount('b', 2))
+        False
+        >>> WordCount('a', 1).__eq__(1)
+        NotImplemented
+        """
+        if not isinstance(other, WordCount):
+            return NotImplemented
+        return self.count == other.count
+
+    def __lt__(self, other: object) -> bool:
+        """
+        >>> WordCount('a', 1).__lt__(WordCount('b', 1))
+        False
+        >>> WordCount('a', 1).__lt__(WordCount('a', 1))
+        False
+        >>> WordCount('a', 1).__lt__(WordCount('a', 2))
+        True
+        >>> WordCount('a', 1).__lt__(WordCount('b', 2))
+        True
+        >>> WordCount('a', 2).__lt__(WordCount('a', 1))
+        False
+        >>> WordCount('a', 2).__lt__(WordCount('b', 1))
+        False
+        >>> WordCount('a', 1).__lt__(1)
+        NotImplemented
+        """
+        if not isinstance(other, WordCount):
+            return NotImplemented
+        return self.count < other.count
+
+
+def top_k_frequent_words(words: list[str], k_value: int) -> list[str]:
+    """
+    Returns the `k_value` most frequently occurring words,
+    in non-increasing order of occurrence.
+    In this context, a word is defined as an element in the provided list.
+
+    In case `k_value` is greater than the number of distinct words, a value of k equal
+    to the number of distinct words will be considered, instead.
+
+    >>> top_k_frequent_words(['a', 'b', 'c', 'a', 'c', 'c'], 3)
+    ['c', 'a', 'b']
+    >>> top_k_frequent_words(['a', 'b', 'c', 'a', 'c', 'c'], 2)
+    ['c', 'a']
+    >>> top_k_frequent_words(['a', 'b', 'c', 'a', 'c', 'c'], 1)
+    ['c']
+    >>> top_k_frequent_words(['a', 'b', 'c', 'a', 'c', 'c'], 0)
+    []
+    >>> top_k_frequent_words([], 1)
+    []
+    >>> top_k_frequent_words(['a', 'a'], 2)
+    ['a']
+    """
+    heap: Heap[WordCount] = Heap()
+    count_by_word = Counter(words)
+    heap.build_max_heap(
+        [WordCount(word, count) for word, count in count_by_word.items()]
+    )
+    return [heap.extract_max().word for _ in range(min(k_value, len(count_by_word)))]
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()