Merge pull request #5 from glevv/shamos-est

Shamos Estimator

CITATION.cff

@@ -18,5 +18,5 @@ repository-code: 'https://github.com/glevv/obscure_stats'
 repository-artifact: 'https://pypi.org/project/obscure_stats'
 abstract: Collection of lesser-known statistical measures
 license: MIT
-version: 0.1.5
+version: 0.1.6
 date-released: '2023-10-21'

CODE_OF_CONDUCT.md

@@ -1 +1 @@
-This projects adopts Python Code of Conduct, [please read it here](https://www.python.org/psf/conduct/).
+This projects adopts Python Software Foundation Code of Conduct, [please read it here](https://www.python.org/psf/conduct/).

README.md

@@ -2,7 +2,7 @@
 
 | | |
 | --- | --- |
-| CI/CD |[![CI](https://github.com/glevv/obscure_stats/actions/workflows/package.yml/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/package.yml) [![CD](https://github.com/glevv/obscure_stats/actions/workflows/publish.yml/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/publish.yml) [![Coverage](https://codecov.io/github/glevv/obscure_stats/coverage.svg?branch=main)](https://codecov.io/gh/glevv/obscure_stats) [![CodeQL](https://github.com/glevv/obscure_stats/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/github-code-scanning/codeql)
+| CI/CD | [![CI](https://github.com/glevv/obscure_stats/actions/workflows/package.yml/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/package.yml) [![CD](https://github.com/glevv/obscure_stats/actions/workflows/publish.yml/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/publish.yml) [![CodeQL](https://github.com/glevv/obscure_stats/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/glevv/obscure_stats/actions/workflows/github-code-scanning/codeql) [![Coverage](https://codecov.io/github/glevv/obscure_stats/coverage.svg?branch=main)](https://codecov.io/gh/glevv/obscure_stats)
 | Package | [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/obscure_stats?logo=Python)](https://pypi.org/project/obscure_stats/) [![PyPI](https://img.shields.io/pypi/v/obscure_stats?logo=PyPI)](https://pypi.org/project/obscure_stats/) |
 | Meta | [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10206933.svg)](https://doi.org/10.5281/zenodo.10206933)
 
@@ -29,6 +29,7 @@
     * Morisita Index;
     * Quartile Coefficient of Dispersion;
     * Robust Coefficient of Variation;
+    * Shamos Estimator;
     * Standard Quantile Absolute Deviation;
     * Studentized Range.
 - Collection of measures of skewness - `obscure_stats/skewness`:
@@ -86,7 +87,7 @@ Robust measure of central tendency = 1.09, Robust measure of dispersion = 0.42
 
 ## Code of Conduct
 
-This projects adopts Python Code of Conduct, [please read it here](https://www.python.org/psf/conduct/).
+This projects adopts Python Software Foundation Code of Conduct, [please read it here](https://www.python.org/psf/conduct/).
 
 ## License
 

pyproject.toml

@@ -1,11 +1,11 @@
 [tool.poetry]
 name = "obscure_stats"
-version = "0.1.5"
+version = "0.1.6"
 description = "Collection of lesser-known statistical functions"
 authors = ["Gleb Levitski"]
 readme = "README.md"
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
+    "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
@@ -20,6 +20,7 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Typing :: Typed",
     "Operating System :: OS Independent",
+    "Natural Language :: English",
 ]
 
 [tool.poetry.dependencies]

src/obscure_stats/dispersion/__init__.py

@@ -8,6 +8,7 @@
     morisita_index,
     quartile_coefficient_of_dispersion,
     robust_coefficient_of_variation,
+    shamos_estimator,
     standard_quantile_absolute_deviation,
     studentized_range,
 )
@@ -22,4 +23,5 @@
     "standard_quantile_absolute_deviation",
     "studentized_range",
     "robust_coefficient_of_variation",
+    "shamos_estimator",
 ]

src/obscure_stats/dispersion/dispersion.py

@@ -257,3 +257,40 @@ def standard_quantile_absolute_deviation(x: np.ndarray) -> float:
     k = 1.0 + 0.762 / n + 0.967 / n**2
     # constant value that maximizes efficiency for normal distribution
     return k * np.nanquantile(np.abs(x - med), q=0.682689492137086)
+
+
+def shamos_estimator(x: np.ndarray) -> float:
+    """Calculate Shamos robust estimator of dispersion.
+
+    This measure is complementary to Hodges-Lehmann-Sen estimator.
+
+    Parameters
+    ----------
+    x : array_like
+        Input array.
+
+    Returns
+    -------
+    se : float
+        The value of Hodges-Lehmann-Sen estimator.
+
+    References
+    ----------
+    Shamos, M. I. (1976).
+    Geometry and statistics: Problems at the interface (p. 0032).
+    Carnegie-Mellon University. Department of Computer Science.
+
+    Notes
+    -----
+    This implementation uses cartesian product, so the time and memory complexity
+    are N^2. It is best to not use it on large arrays.
+
+    See Also
+    --------
+    obscure_stats.central_tendency.hodges_lehmann_sen_location - Hodges-Lehmann-Sen loc.
+    """
+    # In the original paper authors suggest use only upper triangular
+    # of the cartesian product, but in this implementation we use
+    # whole matrix, which is equvalent.
+    product = np.meshgrid(x, x, sparse=True)
+    return np.nanmedian(np.abs(product[0] - product[1]))

tests/test_dispersion.py

@@ -12,6 +12,7 @@
     morisita_index,
     quartile_coefficient_of_dispersion,
     robust_coefficient_of_variation,
+    shamos_estimator,
     standard_quantile_absolute_deviation,
     studentized_range,
 )
@@ -26,6 +27,7 @@
     quartile_coefficient_of_dispersion,
     standard_quantile_absolute_deviation,
     studentized_range,
+    shamos_estimator,
 ]
 
 
@@ -58,6 +60,7 @@ def test_mock_aggregation_functions(
         morisita_index,
         quartile_coefficient_of_dispersion,
         standard_quantile_absolute_deviation,
+        shamos_estimator,
     ],
 )
 @pytest.mark.parametrize("seed", [1, 42, 99])