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.
nqu_statkit/__init__.py
ADDED
|
@@ -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,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
|