Merge pull request #42 from UBC-MDS/dev

Dev v2

Author: nicolelink33

README.md

@@ -11,13 +11,13 @@ DumbPy is an alternative version of NumPy, which facilitates scientific computin
 
 DumbPy Functions:
 
--   Helper functions - these functions will test the inputted object, and will catch any input besides a list of numbers and produce suitable error messages. Additionally, there will be a helper function that will take user input on whether to flatten an inputted list of lists into one list.
+-   `support_functions` - these functions will test the inputted object, and will catch any input besides a list of numbers and produce suitable error messages. Additionally, there will be a helper function that will take user input on whether to flatten an inputted list of lists into one list.
 
--   Mean - the mean function will calculate and return the mean, or the average, of the inputted numerical list.
+-   `arithmetic_mean` - the mean function will calculate and return the mean, or the average, of the inputted numerical list.
 
--   Standard Deviation - the standard deviation function will calculate and return the standard deviation of the inputted numerical list.
+-   `std_deviation` - the standard deviation function will calculate and return the standard deviation of the inputted numerical list.
 
--   Median - the median function will calculate and return the median value of the inputted numerical list
+-   `median` - the median function will calculate and return the median value of the inputted numerical list
 
 As stated above, the NumPy package already exists and provides similar functions. NumPy can be found at the following link: <https://numpy.org/>. DumbPy is an alternative version, which is much simpler and has a narrower focus.
 
@@ -35,13 +35,12 @@ You can install this package into your preferred Python environment using pip:
 $ pip install dumbpy
 ```
 
-TODO: Add a brief example of how to use the package to this section
-
 To use dumbpy in your code:
 
 ``` python
 >>> import dumbpy
->>> dumbpy.hello_world()
+>>> dumbpy.arithmetic_mean([1,2,3])
+2.0
 ```
 
 ## Copyright

environment.yml

@@ -0,0 +1,9 @@
+name: dumbpy-env
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - hatch
+  - copier
+  - pytest
+  - pip

pyproject.toml

@@ -38,10 +38,10 @@ keywords = []
 dependencies = []
 
 [project.urls]
-Homepage = "https://github.com/hpalafoxp/dumbpy"
-"Source Code" = "https://github.com/hpalafoxp/dumbpy"
-"Bug Tracker" = "https://github.com/hpalafoxp/dumbpy/issues"
-Documentation = "https://github.com/hpalafoxp/dumbpy/blob/main/README.md"
+Homepage = "https://github.com/UBC-MDS/dumbpy/dumbpy"
+"Source Code" = "https://github.com/UBC-MDS/dumbpy/dumbpy"
+"Bug Tracker" = "https://github.com/UBC-MDS/dumbpy/dumbpy/issues"
+Documentation = "https://github.com/UBC-MDS/dumbpy/dumbpy/blob/main/README.md"
 Download = "https://pypi.org/project/dumbpy/#files"
 
 [project.optional-dependencies]

src/dumbpy/__init__.py

@@ -22,8 +22,36 @@
 # SOFTWARE.
 
 """
-Add a docstring here for the init module.
+dumbpy
+======
 
-This might include a very brief description of the package,
-its purpose, and any important notes.
+A small statistics-oriented package providing simple utilities for working with
+nested iterables of numeric values.
+
+Public API
+----------
+mean
+    Compute the arithmetic mean of numeric values.
+stddev
+    Compute the population standard deviation of numeric values.
+median
+    Compute the median of numeric values.
+flatten
+    Flatten a nested iterable into a one-dimensional list.
+validate
+    Flatten input and ensure all elements are numeric.
 """
+
+from dumbpy.arithmetic_mean import arithmetic_mean
+from dumbpy.median import median
+from dumbpy.std_deviation import std_deviation
+from dumbpy.support_functions import flatten_list
+from dumbpy.support_functions import validate_list
+
+__all__: list[str] = [
+    "arithmetic_mean",
+    "std_deviation",
+    "median",
+    "flatten_list",
+    "validate_list"
+]

src/dumbpy/arithmetic_mean.py

@@ -1,27 +1,56 @@
 """
-A module that calculates the arithmetic mean of a list of numbers
+dumbpy.arithmetic_mean
+======================
 
+Compute the arithmetic mean of numeric values.
+
+The input may be a nested iterable; nesting is flattened via
+:func:`dumbpy.support_functions.validate_list`.
 """
 
-from support_functions import *
+from collections.abc import Iterable
+from typing import Any
+
+from dumbpy.support_functions import Numeric, validate_list
 
-def arithmetic_mean(values: list[float | int]):
+
+def arithmetic_mean(values: Iterable[Any]) -> float:
     """
-    Calculate the arithmetich mean of the inputted list and return the result.
+    Compute the arithmetic mean of numeric values.
 
     Parameters
     ----------
-    values : list[float | int]
-        A list of numbers.
+    values : Iterable[Any]
+        A (possibly nested) iterable containing numeric values.
 
     Returns
     -------
     float
-        The arithmetic mean of the list of numbers.
+        The arithmetic mean of the numeric values.
+
+    Raises
+    ------
+    ValueError
+        If the flattened input contains no elements.
+    TypeError
+        If the input is not a valid iterable for flattening, or if any element
+        is non-numeric (raised by :func:`validate_list`).
 
     Examples
     --------
     >>> arithmetic_mean([1, 2, 3, 4])
     2.5
+    >>> arithmetic_mean([1, [2, 3]])
+    2.0
     """
-    pass
+    numbers: list[Numeric] = validate_list(values)
+    n_elements: int = len(numbers)
+
+    if n_elements == 0:
+        raise ValueError("The number list needs to have at least one numeric element")
+
+    total: float | int = 0
+    for x in numbers:
+        total += x
+
+    return total / n_elements

src/dumbpy/median.py

@@ -1,29 +1,44 @@
 """
-A module that calculates the median of a list of numbers.
+dumbpy.median
+=============
+
+Compute the median of numeric values.
+
+The input may be a nested iterable; nesting is flattened via
+:func:`dumbpy.support_functions.validate_list`.
 """
 
+from collections.abc import Iterable
+from typing import Any
+
+from dumbpy.support_functions import Numeric, validate_list
 
-def median(input):
+
+def median(values: Iterable[Any]) -> Numeric | float:
     """
-    Calculate the median of the inputted list and return the result.
+    Compute the median of numeric values.
 
     Parameters
     ----------
-    input : list
-        A non-empty list of numbers.
+    values : Iterable[Any]
+        A (possibly nested) iterable containing numeric values.
 
     Returns
     -------
-    float
-        The median value of the list. If the list length is even, the median is
-        the average of the two middle values.
+    Numeric | float
+        The median value of the input after sorting. For odd-length inputs, the
+        middle element is returned (so the type may be ``int``, ``float``, or
+        ``bool``). For even-length inputs, the average of the two middle values
+        is returned, which is typically a ``float`` (but can be an ``int``/``bool``
+        when the middle values are equal in this implementation).
 
     Raises
     ------
-    TypeError
-        If x is not a list or contains non-numeric values.
     ValueError
-        If x is an empty list.
+        If the flattened input contains no elements.
+    TypeError
+        If the input is not a valid iterable for flattening, or if any element
+        is non-numeric (raised by :func:`validate_list`).
 
     Examples
     --------
@@ -32,4 +47,19 @@ def median(input):
     >>> median([1, 2, 3, 4])
     2.5
     """
-    pass
+    numbers: list[Numeric] = validate_list(values)
+    n_elements: int = len(numbers)
+
+    if n_elements == 0:
+        raise ValueError("The number list needs to have at least one numeric element")
+
+    numbers_sorted: list[Numeric] = sorted(numbers)
+    mid: int = n_elements // 2
+
+    if n_elements % 2 == 1:
+        return numbers_sorted[mid]
+
+    if numbers_sorted[mid - 1] == numbers_sorted[mid]:
+        return numbers_sorted[mid - 1]
+
+    return (numbers_sorted[mid - 1] + numbers_sorted[mid]) / 2

src/dumbpy/std_deviation.py

@@ -1,28 +1,60 @@
 """
-A module that calculates the standard deviation of a list of numbers.
+dumbpy.std_deviation
+====================
 
+Compute the population standard deviation of numeric values.
+
+The input may be a nested iterable; nesting is flattened via
+:func:`dumbpy.support_functions.validate_list`.
 """
 
-from support_functions import *
+from collections.abc import Iterable
+from typing import Any
+
+from dumbpy.arithmetic_mean import arithmetic_mean
+from dumbpy.support_functions import Numeric, validate_list
+
 
-def std_deviation(values: list[float | int]):
+def std_deviation(values: Iterable[Any]) -> float:
     """
-    Calculate the standard deviation of the inputted list and return the result.
+    Compute the population standard deviation of numeric values.
+
+    This uses the population variance definition:
+
+    ``variance = sum((x - mean)**2) / n``
 
     Parameters
     ----------
-    values : list[float | int]
-        A list of numbers.
+    values : Iterable[Any]
+        A (possibly nested) iterable containing numeric values.
 
     Returns
     -------
     float
-        The standard deviation of the list of numbers.
+        The population standard deviation of the numeric values.
+
+    Raises
+    ------
+    ValueError
+        If the flattened input contains no elements.
+    TypeError
+        If the input is not a valid iterable for flattening, or if any element
+        is non-numeric (raised by :func:`validate_list`).
 
     Examples
     --------
     >>> std_deviation([1, 1, 1, 1])
-    0
+    0.0
+    >>> std_deviation([1, 2, 3, 4])
+    1.118033988749895
     """
-    pass
-    
+    numbers: list[Numeric] = validate_list(values)
+
+    if len(numbers) == 0:
+        raise ValueError("The number list needs to have at least one numeric element")
+
+    n: int = len(numbers)
+    mean: float = arithmetic_mean(numbers)
+
+    variance: float = sum((x - mean) ** 2 for x in numbers) / n
+    return variance**0.5