nqu-statkit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,35 @@
1
+ """NQU StatKit: beginner-friendly descriptive statistics."""
2
+
3
+ from .core import (
4
+ data_range,
5
+ describe,
6
+ frequency_table,
7
+ maximum,
8
+ mean,
9
+ median,
10
+ minimum,
11
+ mode,
12
+ percentile,
13
+ population_stddev,
14
+ population_variance,
15
+ sample_stddev,
16
+ sample_variance,
17
+ )
18
+
19
+ __version__ = "0.1.0"
20
+
21
+ __all__ = [
22
+ "mean",
23
+ "median",
24
+ "mode",
25
+ "minimum",
26
+ "maximum",
27
+ "data_range",
28
+ "population_variance",
29
+ "sample_variance",
30
+ "population_stddev",
31
+ "sample_stddev",
32
+ "percentile",
33
+ "frequency_table",
34
+ "describe",
35
+ ]
nqu_statkit/core.py ADDED
@@ -0,0 +1,138 @@
1
+ """Core descriptive-statistics functions."""
2
+
3
+ from collections import Counter
4
+ from math import sqrt
5
+ from numbers import Real
6
+ from typing import Iterable, List, Dict, Union
7
+
8
+ Number = Union[int, float]
9
+
10
+
11
+ def _to_numbers(data: Iterable[Number]) -> List[Number]:
12
+ """Convert data to a list and validate its values."""
13
+ try:
14
+ values = list(data)
15
+ except TypeError as exc:
16
+ raise TypeError("data must be an iterable of numbers") from exc
17
+
18
+ if not values:
19
+ raise ValueError("data must contain at least one number")
20
+
21
+ for value in values:
22
+ if isinstance(value, bool) or not isinstance(value, Real):
23
+ raise TypeError("all data values must be real numbers")
24
+
25
+ return values
26
+
27
+
28
+ def mean(data: Iterable[Number]) -> float:
29
+ """Return the arithmetic mean."""
30
+ values = _to_numbers(data)
31
+ return sum(values) / len(values)
32
+
33
+
34
+ def median(data: Iterable[Number]) -> Number:
35
+ """Return the middle value, or the average of the two middle values."""
36
+ values = sorted(_to_numbers(data))
37
+ middle = len(values) // 2
38
+
39
+ if len(values) % 2 == 1:
40
+ return values[middle]
41
+
42
+ return (values[middle - 1] + values[middle]) / 2
43
+
44
+
45
+ def mode(data: Iterable[Number]) -> List[Number]:
46
+ """Return every value tied for the highest frequency, in sorted order."""
47
+ values = _to_numbers(data)
48
+ counts = Counter(values)
49
+ highest_count = max(counts.values())
50
+ return sorted(value for value, count in counts.items() if count == highest_count)
51
+
52
+
53
+ def minimum(data: Iterable[Number]) -> Number:
54
+ """Return the smallest value."""
55
+ return min(_to_numbers(data))
56
+
57
+
58
+ def maximum(data: Iterable[Number]) -> Number:
59
+ """Return the largest value."""
60
+ return max(_to_numbers(data))
61
+
62
+
63
+ def data_range(data: Iterable[Number]) -> Number:
64
+ """Return the difference between the largest and smallest values."""
65
+ values = _to_numbers(data)
66
+ return max(values) - min(values)
67
+
68
+
69
+ def population_variance(data: Iterable[Number]) -> float:
70
+ """Return the population variance (divide by N)."""
71
+ values = _to_numbers(data)
72
+ average = sum(values) / len(values)
73
+ return sum((value - average) ** 2 for value in values) / len(values)
74
+
75
+
76
+ def sample_variance(data: Iterable[Number]) -> float:
77
+ """Return the sample variance (divide by N - 1)."""
78
+ values = _to_numbers(data)
79
+ if len(values) < 2:
80
+ raise ValueError("sample variance requires at least two values")
81
+
82
+ average = sum(values) / len(values)
83
+ return sum((value - average) ** 2 for value in values) / (len(values) - 1)
84
+
85
+
86
+ def population_stddev(data: Iterable[Number]) -> float:
87
+ """Return the population standard deviation."""
88
+ return sqrt(population_variance(data))
89
+
90
+
91
+ def sample_stddev(data: Iterable[Number]) -> float:
92
+ """Return the sample standard deviation."""
93
+ return sqrt(sample_variance(data))
94
+
95
+
96
+ def percentile(data: Iterable[Number], p: float) -> float:
97
+ """Return percentile p (0 to 100) using linear interpolation."""
98
+ values = sorted(_to_numbers(data))
99
+
100
+ if isinstance(p, bool) or not isinstance(p, Real):
101
+ raise TypeError("p must be a number")
102
+ if not 0 <= p <= 100:
103
+ raise ValueError("p must be between 0 and 100")
104
+
105
+ if len(values) == 1:
106
+ return float(values[0])
107
+
108
+ position = (len(values) - 1) * (p / 100)
109
+ lower_index = int(position)
110
+ upper_index = min(lower_index + 1, len(values) - 1)
111
+ fraction = position - lower_index
112
+
113
+ return float(
114
+ values[lower_index]
115
+ + (values[upper_index] - values[lower_index]) * fraction
116
+ )
117
+
118
+
119
+ def frequency_table(data: Iterable[Number]) -> Dict[Number, int]:
120
+ """Return a dictionary mapping each value to its occurrence count."""
121
+ values = _to_numbers(data)
122
+ return dict(sorted(Counter(values).items()))
123
+
124
+
125
+ def describe(data: Iterable[Number]) -> Dict[str, Number]:
126
+ """Return a dictionary containing common descriptive statistics."""
127
+ values = _to_numbers(data)
128
+ return {
129
+ "count": len(values),
130
+ "mean": mean(values),
131
+ "median": median(values),
132
+ "mode": mode(values),
133
+ "minimum": min(values),
134
+ "maximum": max(values),
135
+ "range": max(values) - min(values),
136
+ "population_variance": population_variance(values),
137
+ "population_stddev": population_stddev(values),
138
+ }
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: nqu-statkit
3
+ Version: 0.1.0
4
+ Summary: A beginner-friendly statistics toolkit for Python
5
+ Author: NQU Statistics Toolkit Contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/s111410513-oss/_se/tree/main/HW10
8
+ Project-URL: Repository, https://github.com/s111410513-oss/_se
9
+ Keywords: statistics,mean,median,mode,education
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.9
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # NQU StatKit
25
+
26
+ A small, beginner-friendly Python statistics toolkit. It provides common descriptive-statistics functions without requiring third-party dependencies.
27
+
28
+ ## Features
29
+
30
+ - Mean (average)
31
+ - Median
32
+ - Mode (returns all tied modes)
33
+ - Minimum, maximum, and range
34
+ - Population and sample variance
35
+ - Population and sample standard deviation
36
+ - Percentile (linear interpolation)
37
+ - A combined descriptive-statistics summary
38
+ - Frequency table
39
+
40
+ ## Requirements
41
+
42
+ - Python 3.9 or newer
43
+
44
+ ## Install
45
+
46
+ After the package is published on PyPI:
47
+
48
+ ```bash
49
+ python -m pip install nqu-statkit
50
+ ```
51
+
52
+ ## Quick start
53
+
54
+ ```python
55
+ import nqu_statkit as ns
56
+
57
+ scores = [80, 90, 75, 90, 85]
58
+
59
+ print(ns.mean(scores)) # 84.0
60
+ print(ns.median(scores)) # 85
61
+ print(ns.mode(scores)) # [90]
62
+ print(ns.population_stddev(scores)) # population standard deviation
63
+ print(ns.percentile(scores, 75)) # 90.0
64
+ print(ns.describe(scores))
65
+ ```
66
+
67
+ ## Function examples
68
+
69
+ ```python
70
+ import nqu_statkit as ns
71
+
72
+ data = [10, 20, 20, 30, 40]
73
+
74
+ print("平均數:", ns.mean(data))
75
+ print("中位數:", ns.median(data))
76
+ print("眾數:", ns.mode(data))
77
+ print("全距:", ns.data_range(data))
78
+ print("母體變異數:", ns.population_variance(data))
79
+ print("樣本變異數:", ns.sample_variance(data))
80
+ print("第 90 百分位數:", ns.percentile(data, 90))
81
+ print("次數分配:", ns.frequency_table(data))
82
+ ```
83
+
84
+ ## API
85
+
86
+ | Function | Description |
87
+ |---|---|
88
+ | `mean(data)` | Arithmetic mean |
89
+ | `median(data)` | Median |
90
+ | `mode(data)` | List of most frequent values |
91
+ | `minimum(data)` | Smallest value |
92
+ | `maximum(data)` | Largest value |
93
+ | `data_range(data)` | Maximum minus minimum |
94
+ | `population_variance(data)` | Population variance |
95
+ | `sample_variance(data)` | Sample variance; requires at least 2 values |
96
+ | `population_stddev(data)` | Population standard deviation |
97
+ | `sample_stddev(data)` | Sample standard deviation |
98
+ | `percentile(data, p)` | Percentile for p from 0 to 100 |
99
+ | `frequency_table(data)` | Dictionary of value counts |
100
+ | `describe(data)` | Dictionary containing common summary statistics |
101
+
102
+ All functions accept an iterable of numbers. Empty data raises `ValueError`; non-numeric data raises `TypeError`.
103
+
104
+ ## Run tests
105
+
106
+ From the `HW10` directory, install the project in editable mode and run the tests:
107
+
108
+ ```bash
109
+ python -m pip install -e .
110
+ python -m unittest discover -s tests -v
111
+ ```
112
+
113
+ ## Build the package
114
+
115
+ ```bash
116
+ python -m pip install --upgrade build
117
+ python -m build
118
+ ```
119
+
120
+ The `dist/` directory will contain a source distribution and a wheel.
121
+
122
+ ## Publish to PyPI
123
+
124
+ 1. Create and verify an account at https://pypi.org/.
125
+ 2. Create a PyPI API token in your account settings.
126
+ 3. Build the package with `python -m build`.
127
+ 4. Upload with `python -m pip install --upgrade twine` and `python -m twine upload dist/*`.
128
+ 5. Enter username `__token__` and your PyPI token when prompted.
129
+
130
+ Do not put your API token in this repository or share it in chat. The package is not published merely by pushing this GitHub folder; PyPI upload is a separate authenticated step.
131
+
132
+ ## License
133
+
134
+ MIT
@@ -0,0 +1,7 @@
1
+ nqu_statkit/__init__.py,sha256=HC7LF8ZjveErDsUyR1oGN8xCwZUNWHIsyNwN0IvgyWM,609
2
+ nqu_statkit/core.py,sha256=8lR12hiUYIeLejWIVJ0pvlKhrrx30rcZoZ9uIyjrh6g,4434
3
+ nqu_statkit-0.1.0.dist-info/licenses/LICENSE,sha256=c5BcLuuXgZPj8zv228jSreONmXwfAI-YQlCzCOR7Exw,1102
4
+ nqu_statkit-0.1.0.dist-info/METADATA,sha256=zUu_jFFbEoxMFP9ruVPyCtTRji52DS5sVYdtiH4QF0Y,4157
5
+ nqu_statkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
6
+ nqu_statkit-0.1.0.dist-info/top_level.txt,sha256=LsqTBDfN37tztEa4JSTNZ2Nf_6d67c9vJsgI3nbbkzo,12
7
+ nqu_statkit-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NQU StatKit Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ nqu_statkit