feat(algorithms, heaps): top k and kth largest

DIRECTORY.md

@@ -140,6 +140,8 @@
   * Heap
     * Schedule Tasks
       * [Test Schedule Tasks On Minimum Machines](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/heap/schedule_tasks/test_schedule_tasks_on_minimum_machines.py)
+    * Topklargest
+      * [Test Top K Largest Elements](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/heap/topklargest/test_top_k_largest_elements.py)
   * Huffman
     * [Decoding](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/huffman/decoding.py)
     * [Encoding](https://github.com/BrianLusina/PythonSnips/blob/master/algorithms/huffman/encoding.py)

algorithms/heap/topklargest/README.md

@@ -0,0 +1,106 @@
+# Top-K Largest Elements in an Array
+
+Given an integer array nums, return the 3 largest elements in the array in any order.
+
+## Example
+
+```text
+Input: nums = [9, 3, 7, 1, -2, 6, 8]
+Output: [8, 7, 9]
+# or [7, 9, 8] or [9, 7, 8] ...
+```
+
+## Solution
+
+Here's how we can solve this problem using a min-heap:
+
+- Create a min-heap that stores the first 3 elements of the array. These represent the 3 largest elements we have seen so 
+  far, with the smallest of the 3 at the root of the heap.
+  ![Solution 1](./images/solutions/top_k_largest_element_in_array_solution_1.png)
+
+- Iterate through the remaining elements in the array.
+  - If the current element is larger than the root of the heap, pop the root and push the current element into the heap.
+  - Otherwise, continue to the next element.
+
+  ![Solution 2](./images/solutions/top_k_largest_element_in_array_solution_2.png)
+  ![Solution 3](./images/solutions/top_k_largest_element_in_array_solution_3.png)
+  ![Solution 4](./images/solutions/top_k_largest_element_in_array_solution_4.png)
+  ![Solution 5](./images/solutions/top_k_largest_element_in_array_solution_5.png)
+
+After iterating through all the elements, the heap contains the 3 largest elements in the array.
+
+### Complexity Analysis
+
+#### Time Complexity Breakdown
+
+- The heapify function takes O(3) = O(1) time
+- We iterate through all elements in the array once: O(n) time
+- The heappop and heappush operations take O(log 3) = O(1) time each
+
+#### Space Complexity
+
+- We use a heap of size 3 to store the 3 largest elements: O(3) = O(1) space 
+- The algorithm uses constant space regardless of input size
+
+Note: The time and space complexity become more interesting when 3 is a variable number k.
+
+---
+
+# Kth Largest Element in an Array
+
+Write a function that takes an array of unsorted integers nums and an integer k, and returns the kth largest element in
+the array. This function should run in O(n log k) time, where n is the length of the array.
+
+## Examples
+
+```text
+Input:
+nums = [5, 3, 2, 1, 4]
+k = 2
+
+Output: 4
+```
+
+## Solutions
+
+- [Approach 1](#approach-1-sorting)
+- [Approach 2](#approach-2-min-heap)
+
+### Approach 1: Sorting
+
+The simplest approach is to sort the array in descending order and return the kth element. This approach has a time 
+complexity of O(n log n) where n is the number of elements in the array, and a space complexity of O(1).
+
+### Approach 2: Min Heap
+
+By using a min-heap, we can reduce the time complexity to O(n log k), where n is the number of elements in the array and
+k is the value of k.
+The idea behind this solution is to iterate over the elements in the array while storing the k largest elements we've
+seen so far in a min-heap. At each element, we check if it is greater than the smallest element (the root) of the heap.
+If it is, we pop the smallest element from the heap and push the current element into the heap. This way, the heap will
+always contain the k largest elements we've seen so far.
+After iterating over all the elements, the root of the heap will be the kth largest element in the array.
+
+![Solution 2.1](./images/solutions/kth_largest_element_in_array_solution_1.png)
+![Solution 2.2](./images/solutions/kth_largest_element_in_array_solution_2.png)
+![Solution 2.3](./images/solutions/kth_largest_element_in_array_solution_3.png)
+![Solution 2.4](./images/solutions/kth_largest_element_in_array_solution_4.png)
+![Solution 2.5](./images/solutions/kth_largest_element_in_array_solution_5.png)
+![Solution 2.6](./images/solutions/kth_largest_element_in_array_solution_6.png)
+![Solution 2.7](./images/solutions/kth_largest_element_in_array_solution_7.png)
+![Solution 2.8](./images/solutions/kth_largest_element_in_array_solution_8.png)
+![Solution 2.9](./images/solutions/kth_largest_element_in_array_solution_9.png)
+![Solution 2.10](./images/solutions/kth_largest_element_in_array_solution_10.png)
+![Solution 2.11](./images/solutions/kth_largest_element_in_array_solution_11.png)
+
+#### Complexity Analysis
+
+##### Time Complexity: O(n log k)
+
+Where n is the number of elements in the array and k is the input parameter. We iterate over
+all elements, and in the worst case, we both push and pop each element from the heap, which takes O(log k) time per
+element.
+
+##### Space Complexity: O(k)
+
+Where k is the input parameter. The space is used by the heap to store the k largest elements.

algorithms/heap/topklargest/__init__.py

@@ -0,0 +1,76 @@
+from typing import List
+import heapq
+
+
+def k_largest(nums: List[int], k: int = 3) -> List[int]:
+    """
+    Finds the k largest elements in a given list. K is defaulted to three, but can be used to tweak the k largest
+     elements in the array
+    Args:
+        nums(list): list of elements to check for
+        k(int): number of elements to check, defaulted to 3
+    Returns:
+        list: top k largest elements
+    """
+    # create a minimum heap with the first k elements
+    min_heap = nums[:k]
+    heapq.heapify(min_heap)
+
+    # iterate through the remaining elements
+    for num in nums[k:]:
+        # if the current number is greater than the element at the top of the heap
+        if num > min_heap[0]:
+            # Remove it and add this element
+            heapq.heappushpop(min_heap, num)
+
+    # return the top k elements
+    return min_heap
+
+
+def kth_largest(nums: List[int], k: int) -> int:
+    """
+    Finds the kth largest element in a given list
+    Args:
+        nums(list): list of elements to check for
+        k(int): the kth largest element to return
+    Returns:
+        int: the kth largest element
+    """
+    # input validation to ensure we don't get unexpected results
+    if not nums or k <= 0 or k > len(nums):
+        return -1
+
+    # create a minimum heap with the first k elements
+    min_heap = []
+
+    # iterate through the remaining elements
+    for num in nums:
+        if len(min_heap) < k:
+            heapq.heappush(min_heap, num)
+        # if the current number is greater than the element at the top of the heap
+        elif num > min_heap[0]:
+            # Remove it and add this element
+            heapq.heappushpop(min_heap, num)
+
+    # return the top kth element
+    return min_heap[0]
+
+
+def kth_largest_sorting(nums: List[int], k: int) -> int:
+    """
+    Finds the kth largest element in a given list using sorting
+    Args:
+        nums(list): list of elements to check for
+        k(int): the kth largest element to return
+    Returns:
+        int: the kth largest element
+    """
+    # input validation to ensure we don't get unexpected results
+    if not nums or k <= 0 or k > len(nums):
+        return -1
+
+    # Sort the list in place which incurs a time complexity cost of O(n log(n)). Space complexity is O(n) due to using
+    # an in-memory data structure to store the elements during sorting using timsort in Python
+    nums.sort(reverse=True)
+    # Return the kth largest element
+    return nums[k - 1]

algorithms/heap/topklargest/test_top_k_largest_elements.py

@@ -0,0 +1,45 @@
+import unittest
+from typing import List
+from parameterized import parameterized
+from algorithms.heap.topklargest import k_largest, kth_largest, kth_largest_sorting
+
+K_LARGEST_ELEMENTS_TEST_CASES = [
+    ([9, 3, 7, 1, -2, 6, 8], 3, [8, 7, 9]),
+    ([5, 3, 2, 1, 4], 2, [5, 4]),
+]
+
+
+class TopKLargestElementsTestCase(unittest.TestCase):
+    @parameterized.expand(K_LARGEST_ELEMENTS_TEST_CASES)
+    def test_top_k_largest_elements(self, nums: List[int], k: int, expected: List[int]):
+        actual = k_largest(nums, k)
+        self.assertListEqual(sorted(expected), sorted(actual))
+
+
+KTH_LARGEST_ELEMENTS_TEST_CASES = [
+    ([3, 2, 1, 5, 6, 4], 2, 5),
+    ([3, 2, 3, 1, 2, 4, 5, 5, 6], 4, 4),
+    ([1], 1, 1),
+    ([7, 10, 4, 3, 20, 15], 3, 10),
+    ([7, 10, 4, 3, 20, 15], 4, 7),
+    ([7, 10, 4, 3, 20, 15], 5, 4),
+    ([5, 3, 2, 1, 4], 2, 4),
+]
+
+
+class TopKthLargestElementsTestCase(unittest.TestCase):
+    @parameterized.expand(KTH_LARGEST_ELEMENTS_TEST_CASES)
+    def test_top_kth_largest_element(self, nums: List[int], k: int, expected: int):
+        actual = kth_largest(nums, k)
+        self.assertEqual(expected, actual)
+
+    @parameterized.expand(KTH_LARGEST_ELEMENTS_TEST_CASES)
+    def test_top_kth_largest_element_sorting(
+        self, nums: List[int], k: int, expected: int
+    ):
+        actual = kth_largest_sorting(nums, k)
+        self.assertEqual(expected, actual)
+
+
+if __name__ == "__main__":
+    unittest.main()