sdtoolkit 0.1.0__py3-none-any.whl

sdtoolkit/__init__.py

@@ -0,0 +1,31 @@
+"""sdtoolkit: dependency-free standard deviation, variance and RSD."""
+
+from .core import (
+    StatisticsError,
+    Summary,
+    coefficient_of_variation,
+    describe,
+    mean,
+    population_stdev,
+    population_variance,
+    relative_std_dev,
+    sample_stdev,
+    sample_variance,
+    sum_of_squares,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StatisticsError",
+    "Summary",
+    "coefficient_of_variation",
+    "describe",
+    "mean",
+    "population_stdev",
+    "population_variance",
+    "relative_std_dev",
+    "sample_stdev",
+    "sample_variance",
+    "sum_of_squares",
+]

sdtoolkit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

sdtoolkit/cli.py

@@ -0,0 +1,93 @@
+"""Command-line interface: ``python -m sdtoolkit 2 4 4 4 5 5 7 9``."""
+
+import argparse
+import csv
+import sys
+from typing import List, Optional
+
+from .core import StatisticsError, describe
+
+
+def _parse_number(text: str, where: str) -> float:
+    try:
+        return float(text)
+    except ValueError:
+        raise StatisticsError(f"{where}: {text!r} is not a number") from None
+
+
+def _read_column(path: str, column: str) -> List[float]:
+    with open(path, newline="", encoding="utf-8") as f:
+        # Lines starting with '#' are comments.
+        reader = csv.DictReader(line for line in f if not line.startswith("#"))
+        if reader.fieldnames is None or column not in reader.fieldnames:
+            raise StatisticsError(
+                f"column {column!r} not found; available: {reader.fieldnames}"
+            )
+        values = []
+        for i, row in enumerate(reader, start=1):
+            cell = (row[column] or "").strip()
+            if not cell:
+                raise StatisticsError(
+                    f"{path}: data row {i}: empty cell in {column!r} "
+                    "(missing values are not skipped)"
+                )
+            values.append(_parse_number(cell, f"{path}: data row {i}"))
+    return values
+
+
+def _fmt(x: float) -> str:
+    return f"{x:.10g}"
+
+
+def format_summary(s) -> str:
+    kind = "population" if s.population else "sample"
+    denom = "N" if s.population else "n - 1"
+    rows = [
+        ("n", str(s.n)),
+        ("mean", _fmt(s.mean)),
+        ("min", _fmt(s.minimum)),
+        ("max", _fmt(s.maximum)),
+        ("range", _fmt(s.range)),
+        ("sum of squares", _fmt(s.sum_of_squares)),
+        (f"{kind} variance", _fmt(s.variance)),
+        (f"{kind} std dev", _fmt(s.stdev)),
+        ("RSD (%)", "undefined (mean is 0)" if s.rsd_percent is None else _fmt(s.rsd_percent)),
+    ]
+    width = max(len(k) for k, _ in rows)
+    lines = [f"{k:<{width}}  {v}" for k, v in rows]
+    lines.append(f"(divisor: {denom})")
+    return "\n".join(lines)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sdtoolkit",
+        description="Mean, variance, standard deviation and RSD of a dataset.",
+    )
+    parser.add_argument("values", nargs="*", help="numbers to summarise")
+    parser.add_argument(
+        "--population", action="store_true",
+        help="treat data as the whole population (divide by N, not n - 1)",
+    )
+    parser.add_argument("--csv", metavar="FILE", help="read values from a CSV file")
+    parser.add_argument("--column", metavar="NAME", help="CSV column to use (with --csv)")
+    args = parser.parse_args(argv)
+
+    if args.csv and args.values:
+        parser.error("give either values or --csv, not both")
+    if bool(args.csv) != bool(args.column):
+        parser.error("--csv and --column must be used together")
+    if not args.csv and not args.values:
+        parser.error("no values given")
+
+    try:
+        if args.csv:
+            data = _read_column(args.csv, args.column)
+        else:
+            data = [_parse_number(v, f"argument {i + 1}") for i, v in enumerate(args.values)]
+        summary = describe(data, population=args.population)
+    except (StatisticsError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(format_summary(summary))
+    return 0

sdtoolkit/core.py

@@ -0,0 +1,199 @@
+"""Core dispersion statistics.
+
+Every function takes an iterable of numbers. Inputs are validated and
+converted to ``float`` first:
+
+* ``int``, ``float`` and other real numbers are accepted.
+* ``decimal.Decimal`` and ``fractions.Fraction`` are accepted and converted
+  to ``float``. Results are floats; exact decimal/rational precision is not
+  preserved.
+* ``bool``, ``None``, strings, NaN and infinities are rejected with a
+  :class:`StatisticsError`. Missing values are never skipped silently: clean
+  your data before calling these functions.
+
+Variance is computed with a two-pass algorithm: the mean first, then the
+squared deviations from it, summed with :func:`math.fsum`. A small correction
+term (the sum of deviations, which is zero in exact arithmetic) absorbs the
+rounding error left in the mean. The shortcut ``sum(x**2) - n*mean**2`` is
+never used because it loses most of its significant digits when the data
+sits far from zero.
+"""
+
+import math
+import numbers
+from dataclasses import dataclass, asdict
+from decimal import Decimal
+from typing import Iterable, List, Optional
+
+__all__ = [
+    "StatisticsError",
+    "Summary",
+    "mean",
+    "sum_of_squares",
+    "population_variance",
+    "sample_variance",
+    "population_stdev",
+    "sample_stdev",
+    "relative_std_dev",
+    "coefficient_of_variation",
+    "describe",
+]
+
+
+class StatisticsError(ValueError):
+    """Raised for empty, too-short or invalid input."""
+
+
+def _to_floats(data: Iterable) -> List[float]:
+    if isinstance(data, (str, bytes)):
+        raise StatisticsError("expected an iterable of numbers, got a string")
+    values = []
+    for i, x in enumerate(data):
+        if isinstance(x, bool):
+            raise StatisticsError(f"item {i}: booleans are not numbers ({x!r})")
+        if x is None:
+            raise StatisticsError(
+                f"item {i}: None (missing value); remove or fill it before computing"
+            )
+        if isinstance(x, str):
+            raise StatisticsError(
+                f"item {i}: strings are not accepted ({x!r}); convert with float() first"
+            )
+        if not isinstance(x, (numbers.Real, Decimal)):
+            raise StatisticsError(f"item {i}: {x!r} is not a real number")
+        try:
+            f = float(x)
+        except OverflowError:
+            raise StatisticsError(f"item {i}: {x!r} is too large for a float") from None
+        if math.isnan(f):
+            raise StatisticsError(f"item {i}: NaN is not allowed")
+        if math.isinf(f):
+            raise StatisticsError(f"item {i}: infinity is not allowed")
+        values.append(f)
+    if not values:
+        raise StatisticsError("no data points: at least one value is required")
+    return values
+
+
+def _mean_and_ss(values: List[float]):
+    n = len(values)
+    m = math.fsum(values) / n
+    deviations = [x - m for x in values]
+    # Corrected two-pass: sum(d) is 0 in exact arithmetic; subtracting
+    # sum(d)**2 / n removes the error caused by rounding in m.
+    ss = math.fsum(d * d for d in deviations) - math.fsum(deviations) ** 2 / n
+    return m, max(ss, 0.0)
+
+
+def _need_two(n: int) -> None:
+    if n < 2:
+        raise StatisticsError(
+            f"sample statistics need at least 2 data points, got {n}"
+        )
+
+
+def mean(data: Iterable) -> float:
+    """Arithmetic mean."""
+    values = _to_floats(data)
+    return math.fsum(values) / len(values)
+
+
+def sum_of_squares(data: Iterable) -> float:
+    """Sum of squared deviations from the mean, SS = sum((x - mean)**2)."""
+    return _mean_and_ss(_to_floats(data))[1]
+
+
+def population_variance(data: Iterable) -> float:
+    """Population variance, SS / N."""
+    values = _to_floats(data)
+    return _mean_and_ss(values)[1] / len(values)
+
+
+def sample_variance(data: Iterable) -> float:
+    """Sample variance with Bessel's correction, SS / (n - 1). Needs n >= 2."""
+    values = _to_floats(data)
+    _need_two(len(values))
+    return _mean_and_ss(values)[1] / (len(values) - 1)
+
+
+def population_stdev(data: Iterable) -> float:
+    """Population standard deviation, sqrt(SS / N)."""
+    return math.sqrt(population_variance(data))
+
+
+def sample_stdev(data: Iterable) -> float:
+    """Sample standard deviation, sqrt(SS / (n - 1)). Needs n >= 2."""
+    return math.sqrt(sample_variance(data))
+
+
+def coefficient_of_variation(data: Iterable, population: bool = False) -> float:
+    """Standard deviation divided by |mean|, as a ratio (0.05 means 5 %).
+
+    Uses the sample standard deviation unless ``population=True``.
+    Raises StatisticsError when the mean is zero.
+    """
+    values = _to_floats(data)
+    n = len(values)
+    if not population:
+        _need_two(n)
+    m, ss = _mean_and_ss(values)
+    if m == 0:
+        raise StatisticsError("mean is zero; relative dispersion is undefined")
+    sd = math.sqrt(ss / (n if population else n - 1))
+    return sd / abs(m)
+
+
+def relative_std_dev(data: Iterable, population: bool = False) -> float:
+    """Relative standard deviation in percent: 100 * SD / |mean|.
+
+    Uses the sample standard deviation unless ``population=True``.
+    Raises StatisticsError when the mean is zero.
+    """
+    return 100.0 * coefficient_of_variation(data, population=population)
+
+
+@dataclass(frozen=True)
+class Summary:
+    """Result of :func:`describe`. ``rsd_percent`` is None when the mean is 0."""
+
+    n: int
+    mean: float
+    minimum: float
+    maximum: float
+    range: float
+    sum_of_squares: float
+    variance: float
+    stdev: float
+    rsd_percent: Optional[float]
+    population: bool
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def describe(data: Iterable, population: bool = False) -> Summary:
+    """Summary of location and spread.
+
+    ``population=False`` (default) uses n - 1 in the denominator and needs
+    at least two values; ``population=True`` uses N.
+    """
+    values = _to_floats(data)
+    n = len(values)
+    if not population:
+        _need_two(n)
+    m, ss = _mean_and_ss(values)
+    var = ss / (n if population else n - 1)
+    sd = math.sqrt(var)
+    lo, hi = min(values), max(values)
+    return Summary(
+        n=n,
+        mean=m,
+        minimum=lo,
+        maximum=hi,
+        range=hi - lo,
+        sum_of_squares=ss,
+        variance=var,
+        stdev=sd,
+        rsd_percent=None if m == 0 else 100.0 * (sd / abs(m)),
+        population=population,
+    )

sdtoolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: sdtoolkit
+Version: 0.1.0
+Summary: Dependency-free standard deviation, variance and relative standard deviation for Python
+Author: Ramesh-xyz
+License-Expression: MIT
+Project-URL: Homepage, https://standarddeviationcalculator.net/
+Project-URL: Documentation, https://ramesh-xyz.github.io/statistics-calculator-toolkit/python.html
+Project-URL: Source, https://github.com/Ramesh-xyz/statistics-calculator-toolkit
+Project-URL: Issues, https://github.com/Ramesh-xyz/statistics-calculator-toolkit/issues
+Project-URL: Changelog, https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/CHANGELOG.md
+Keywords: standard deviation,variance,coefficient of variation,statistics
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sdtoolkit for Python
+
+Part of [statistics-calculator-toolkit](https://github.com/Ramesh-xyz/statistics-calculator-toolkit), which ships the same API for
+[several languages](https://ramesh-xyz.github.io/statistics-calculator-toolkit/).
+
+`sdtoolkit` is a small, dependency-free Python package for standard
+deviation, variance, sum of squares, relative standard deviation (RSD) and
+coefficient of variation, with a command-line interface. It uses only the
+standard library and supports Python 3.9 and later.
+
+## Problems it solves
+
+- **Picking the wrong formula.** Population and sample versions have
+  separate, explicitly named functions, and the CLI prints which divisor it
+  used.
+- **Silent precision loss.** The shortcut `Σx² − (Σx)²/n` can return zero or
+  even a negative variance for data far from zero. sdtoolkit uses a two-pass
+  algorithm with `math.fsum`.
+- **Garbage in, number out.** `None`, `NaN`, infinities, booleans and strings
+  raise a clear error instead of producing a plausible-looking result. Missing
+  values are never skipped silently.
+- **Undefined RSD.** A zero mean raises an error instead of returning
+  infinity or dividing by zero.
+
+## Features
+
+| function | returns |
+|---|---|
+| `mean(data)` | arithmetic mean |
+| `sum_of_squares(data)` | SS = Σ(x − x̄)² |
+| `population_variance(data)` | SS / N |
+| `sample_variance(data)` | SS / (n − 1) |
+| `population_stdev(data)` | √(SS / N) |
+| `sample_stdev(data)` | √(SS / (n − 1)) |
+| `relative_std_dev(data, population=False)` | 100 × SD / \|mean\|, in percent |
+| `coefficient_of_variation(data, population=False)` | SD / \|mean\|, as a ratio |
+| `describe(data, population=False)` | `Summary` dataclass with all of the above plus min, max, range |
+
+All errors are raised as `sdtoolkit.StatisticsError`, a subclass of
+`ValueError`.
+
+## Install
+
+```
+pip install sdtoolkit
+```
+
+Or from a clone, without installing:
+
+```
+PYTHONPATH=src python -m sdtoolkit 1 2 3
+```
+
+## Usage
+
+### Python
+
+```python
+>>> import sdtoolkit as sd
+>>> data = [2, 4, 4, 4, 5, 5, 7, 9]
+>>> sd.mean(data)
+5.0
+>>> sd.sum_of_squares(data)
+32.0
+>>> sd.population_variance(data), sd.population_stdev(data)
+(4.0, 2.0)
+>>> sd.sample_variance(data), sd.sample_stdev(data)
+(4.571428571428571, 2.138089935299395)
+>>> sd.relative_std_dev(data)
+42.7617987059879
+>>> sd.coefficient_of_variation(data, population=True)
+0.4
+>>> sd.describe(data)
+Summary(n=8, mean=5.0, minimum=2.0, maximum=9.0, range=7.0, sum_of_squares=32.0, variance=4.571428571428571, stdev=2.138089935299395, rsd_percent=42.7617987059879, population=False)
+>>> sd.describe(data, population=True).as_dict()["stdev"]
+2.0
+```
+
+### Command line
+
+```console
+$ python -m sdtoolkit 2 4 4 4 5 5 7 9
+n                8
+mean             5
+min              2
+max              9
+range            7
+sum of squares   32
+sample variance  4.571428571
+sample std dev   2.138089935
+RSD (%)          42.76179871
+(divisor: n - 1)
+```
+
+```console
+$ python -m sdtoolkit --population 2 4 4 4 5 5 7 9
+n                    8
+mean                 5
+min                  2
+max                  9
+range                7
+sum of squares       32
+population variance  4
+population std dev   2
+RSD (%)              40
+(divisor: N)
+```
+
+Read one column of a CSV file (lines starting with `#` are treated as
+comments):
+
+```console
+$ python -m sdtoolkit --csv examples/sample-datasets.csv --column lab_replicate_mg_l
+n                10
+mean             12.405
+min              12.36
+max              12.45
+range            0.09
+sum of squares   0.00825
+sample variance  0.0009166666667
+sample std dev   0.03027650354
+RSD (%)          0.244066937
+(divisor: n - 1)
+```
+
+Errors go to stderr with exit status 1:
+
+```console
+$ python -m sdtoolkit 1 2 x
+error: argument 3: 'x' is not a number
+$ python -m sdtoolkit 5
+error: sample statistics need at least 2 data points, got 1
+```
+
+After `pip install .` the same CLI is also available as `sdtoolkit`.
+
+## Population vs sample
+
+Use the population functions when your data are the entire group you are
+describing. Use the sample functions when your data are drawn from a larger
+group you want to draw conclusions about. The sample formulas divide by
+n − 1 (Bessel's correction), which makes the sample variance an unbiased
+estimate of the population variance, and they need at least two values.
+
+`describe`, `relative_std_dev`, `coefficient_of_variation` and the CLI
+default to the sample formulas. Details:
+[Sample vs population](https://ramesh-xyz.github.io/statistics-calculator-toolkit/sample-vs-population.html).
+
+## Formulas
+
+```
+x̄   = Σxᵢ / n
+SS   = Σ (xᵢ − x̄)²
+σ²   = SS / N              σ = √σ²
+s²   = SS / (n − 1)        s = √s²
+CV   = s / |x̄|
+RSD  = 100 × s / |x̄|  %
+```
+
+A step-by-step walk-through of these formulas is on the
+[standard deviation formula reference](https://standarddeviationcalculator.net/standard-deviation-formula/).
+
+Further reading:
+
+- [Standard deviation](https://ramesh-xyz.github.io/statistics-calculator-toolkit/standard-deviation.html)
+- [Variance](https://ramesh-xyz.github.io/statistics-calculator-toolkit/variance.html)
+- [Sample vs population](https://ramesh-xyz.github.io/statistics-calculator-toolkit/sample-vs-population.html)
+- [Relative standard deviation](https://ramesh-xyz.github.io/statistics-calculator-toolkit/relative-standard-deviation.html)
+- [Outliers](https://ramesh-xyz.github.io/statistics-calculator-toolkit/outliers.html)
+
+## Example datasets
+
+[`examples/sample-datasets.csv`](https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/examples/sample-datasets.csv) has three
+small columns: lab replicate readings, exam scores and daily temperatures.
+They are **illustrative values made up for teaching, not real research
+data.** [`examples/worked-examples.md`](https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/examples/worked-examples.md) works
+through each one by hand and checks the result with the code.
+
+## Accuracy and edge cases
+
+- **Algorithm.** Two passes: the mean, then the squared deviations from it,
+  each summed with `math.fsum`. A correction term removes the rounding error
+  left in the mean. The test suite compares results with Python's
+  `statistics.pvariance`, `variance`, `pstdev` and `stdev` (which use exact
+  rational arithmetic) to a relative tolerance of 1e-12, including data
+  offset by 10⁹ and 10¹².
+- **Accepted input.** Any iterable of `int`, `float`, `decimal.Decimal` or
+  `fractions.Fraction`. Decimals and fractions are converted to `float`, so
+  their extra precision is not kept and results are always `float`.
+- **Rejected input.** `bool`, `None`, strings, NaN, ±infinity, complex
+  numbers, and integers too large for a float raise `StatisticsError` naming
+  the offending item.
+- **Missing values are not skipped.** `None` raises, and an empty CSV cell
+  raises with its row number. Remove or impute missing data yourself so the
+  choice is visible in your code.
+- **Empty input** raises. **Sample statistics with one value** raise.
+  Population variance of one value is 0.
+- **Zero mean.** `relative_std_dev` and `coefficient_of_variation` raise;
+  `describe` sets `rsd_percent` to `None`. RSD is only meaningful for
+  ratio-scale data; see
+  [Relative standard deviation](https://ramesh-xyz.github.io/statistics-calculator-toolkit/relative-standard-deviation.html).
+
+```python
+>>> sd.mean([1, None, 3])
+Traceback (most recent call last):
+  ...
+sdtoolkit.core.StatisticsError: item 1: None (missing value); remove or fill it before computing
+>>> sd.sample_stdev([1e9 + 4, 1e9 + 7, 1e9 + 13, 1e9 + 16]) ** 2
+30.0
+```
+
+## Tests
+
+```
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The suite uses only `unittest`. GitHub Actions runs it on Python 3.9 to 3.13
+([workflow](https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/.github/workflows/test-python.yml)).
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/Ramesh-xyz/statistics-calculator-toolkit/blob/main/LICENSE).

sdtoolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sdtoolkit/__init__.py,sha256=tOeKKMqYckvf58uHn-PrgDe2iOavGwOycaGEGmtgfW8,586
+sdtoolkit/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+sdtoolkit/cli.py,sha256=3oh9HJllzk3YSrHCjI-dWt7Onq_HT1Xv1Ju5-buWMbk,3336
+sdtoolkit/core.py,sha256=sihuX4gvQlg83hrExRovTfwTWmFKpx7Lwv13XUn9dyo,6330
+sdtoolkit-0.1.0.dist-info/licenses/LICENSE,sha256=FEPoA8cBEIhb-W6J-y_YzTMn8TjdKX9Euh1KvSwb-mY,1067
+sdtoolkit-0.1.0.dist-info/METADATA,sha256=XxCM8hU211f12cIAbC8umt-GtFJ4nLGxcC6DvD9QzzI,9101
+sdtoolkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sdtoolkit-0.1.0.dist-info/entry_points.txt,sha256=z1B6dnaSLOFcFAvsBKvA8p7igpn2kPsCe5eAyY4vhqM,49
+sdtoolkit-0.1.0.dist-info/top_level.txt,sha256=BJAOxl62Hfo46HWNk_oRIoK2IBjYagzpoTsGv6ykmrk,10
+sdtoolkit-0.1.0.dist-info/RECORD,,

sdtoolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sdtoolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sdtoolkit = sdtoolkit.cli:main

sdtoolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramesh-xyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdtoolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sdtoolkit