scikit-sampling 0.1.0__tar.gz

scikit_sampling-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leonardo Moraes <leomaurodesenv>
+
+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.

scikit_sampling-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: scikit-sampling
+Version: 0.1.0
+Summary: A set of python modules for dataset sampling
+Author-email: Leonardo Moraes <leomaurodesenv@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy<2,>=1.15.0
+Provides-Extra: build
+Requires-Dist: setuptools<90,>=80.9.0; extra == "build"
+Dynamic: license-file
+
+# 🧪 Scikit-Sampling
+
+[![GitHub](https://img.shields.io/static/v1?label=Code&message=GitHub&color=blue&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling)
+[![MIT license](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)](LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/leomaurodesenv/scikit-sampling/continuous-integration.yml?label=Build&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling/actions/workflows/continuous-integration.yml)
+
+
+Scikit-Sampling (or `sksampling`) is a Python library for dataset sampling techniques. It provides a unified API for common sampling strategies, making it easy to integrate into your data science and machine learning workflows.
+
+## Installation
+
+You can install `sksampling` using pip:
+
+```bash
+pip install scikit-sampling
+```
+
+## Features
+
+`sksampling` offers a range of sampling methods, including:
+
+- `sample_size`: Computes the ideal sample size based confidence level and interval.
+
+## Usage
+
+`sksampling` follows the `scikit-learn` API, making it intuitive to use.
+
+```python
+from sksampling import sample_size
+
+# Example usage
+population_size: int = 100_000
+confidence_level: float = 0.95
+confidence_interval: float = 0.02
+sample_size(population_size, confidence_level, confidence_interval) # approx 2345
+```

scikit_sampling-0.1.0/README.md

@@ -0,0 +1,36 @@
+# 🧪 Scikit-Sampling
+
+[![GitHub](https://img.shields.io/static/v1?label=Code&message=GitHub&color=blue&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling)
+[![MIT license](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)](LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/leomaurodesenv/scikit-sampling/continuous-integration.yml?label=Build&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling/actions/workflows/continuous-integration.yml)
+
+
+Scikit-Sampling (or `sksampling`) is a Python library for dataset sampling techniques. It provides a unified API for common sampling strategies, making it easy to integrate into your data science and machine learning workflows.
+
+## Installation
+
+You can install `sksampling` using pip:
+
+```bash
+pip install scikit-sampling
+```
+
+## Features
+
+`sksampling` offers a range of sampling methods, including:
+
+- `sample_size`: Computes the ideal sample size based confidence level and interval.
+
+## Usage
+
+`sksampling` follows the `scikit-learn` API, making it intuitive to use.
+
+```python
+from sksampling import sample_size
+
+# Example usage
+population_size: int = 100_000
+confidence_level: float = 0.95
+confidence_interval: float = 0.02
+sample_size(population_size, confidence_level, confidence_interval) # approx 2345
+```

scikit_sampling-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=80.9.0,<90"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scikit-sampling"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "A set of python modules for dataset sampling"
+authors = [
+  {name = "Leonardo Moraes", email = "leomaurodesenv@users.noreply.github.com"}
+]
+classifiers=[
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python",
+  "Topic :: Scientific/Engineering",
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "scipy>=1.15.0,<2",
+]
+
+[project.optional-dependencies]
+build = [
+    "setuptools>=80.9.0,<90",
+]
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.8.3,<5",
+    "pre-commit>=4.2.0,<5",
+    "pytest>=8.4.1,<9",
+    "pytest-cov>=6.2.1,<7",
+]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "."
+]
+addopts = "--cov=sksampling --cov-report term-missing"

scikit_sampling-0.1.0/scikit_sampling.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: scikit-sampling
+Version: 0.1.0
+Summary: A set of python modules for dataset sampling
+Author-email: Leonardo Moraes <leomaurodesenv@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy<2,>=1.15.0
+Provides-Extra: build
+Requires-Dist: setuptools<90,>=80.9.0; extra == "build"
+Dynamic: license-file
+
+# 🧪 Scikit-Sampling
+
+[![GitHub](https://img.shields.io/static/v1?label=Code&message=GitHub&color=blue&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling)
+[![MIT license](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)](LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/leomaurodesenv/scikit-sampling/continuous-integration.yml?label=Build&style=flat-square)](https://github.com/leomaurodesenv/scikit-sampling/actions/workflows/continuous-integration.yml)
+
+
+Scikit-Sampling (or `sksampling`) is a Python library for dataset sampling techniques. It provides a unified API for common sampling strategies, making it easy to integrate into your data science and machine learning workflows.
+
+## Installation
+
+You can install `sksampling` using pip:
+
+```bash
+pip install scikit-sampling
+```
+
+## Features
+
+`sksampling` offers a range of sampling methods, including:
+
+- `sample_size`: Computes the ideal sample size based confidence level and interval.
+
+## Usage
+
+`sksampling` follows the `scikit-learn` API, making it intuitive to use.
+
+```python
+from sksampling import sample_size
+
+# Example usage
+population_size: int = 100_000
+confidence_level: float = 0.95
+confidence_interval: float = 0.02
+sample_size(population_size, confidence_level, confidence_interval) # approx 2345
+```

scikit_sampling-0.1.0/scikit_sampling.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+scikit_sampling.egg-info/PKG-INFO
+scikit_sampling.egg-info/SOURCES.txt
+scikit_sampling.egg-info/dependency_links.txt
+scikit_sampling.egg-info/requires.txt
+scikit_sampling.egg-info/top_level.txt
+sksampling/__init__.py
+tests/test_sampling.py

scikit_sampling-0.1.0/scikit_sampling.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scikit_sampling-0.1.0/scikit_sampling.egg-info/requires.txt

@@ -0,0 +1,4 @@
+scipy<2,>=1.15.0
+
+[build]
+setuptools<90,>=80.9.0

scikit_sampling-0.1.0/scikit_sampling.egg-info/top_level.txt

@@ -0,0 +1 @@
+sksampling

scikit_sampling-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scikit_sampling-0.1.0/sksampling/__init__.py

@@ -0,0 +1,44 @@
+import math
+import scipy.stats as st
+
+
+def _get_z_score(confidence_level: float) -> float:
+    """
+    Retrieves the Z-score for a given confidence level.
+
+    Args:
+        confidence_level: The confidence level as a float (e.g., 0.95 for 95%).
+
+    Returns:
+        The Z-score for the given confidence level.
+    """
+    return st.norm.ppf(1 - (1 - confidence_level) / 2)
+
+
+def sample_size(
+    population_size: int,
+    confidence_level: float = 0.95,
+    confidence_interval: float = 0.02,
+) -> int:
+    """
+    Calculates the sample size for a finite population using Cochran's formula.
+
+    Args:
+        population_size: The total size of the population.
+        confidence_level: The desired confidence level (e.g., 0.95 for 95%).
+        confidence_interval: The desired confidence interval (margin of error).
+                             Default is 0.02 (2%).
+
+    Returns:
+        The calculated sample size as an integer.
+    """
+
+    # For sample size calculation, we assume the worst-case variance, where p=0.5
+    p = 0.5
+    z_score = _get_z_score(confidence_level)
+    # Calculate sample size for an infinite population
+    n_0 = (z_score**2 * p * (1 - p)) / (confidence_interval**2)
+    # Adjust sample size for the finite population
+    n = n_0 / (1 + (n_0 - 1) / population_size)
+
+    return int(math.ceil(n))

scikit_sampling-0.1.0/tests/test_sampling.py

@@ -0,0 +1,31 @@
+import pytest
+from sksampling import _get_z_score, sample_size
+
+
+def test_sample_size_basic():
+    """
+    Tests the sample_size function with a few known sets of inputs and
+    expected outputs.
+    """
+    error_margin = 1
+    # Test case from original print statement
+    assert sample_size(100_000, 0.95, 0.02) == pytest.approx(2345, abs=error_margin)
+    # Test with a smaller population
+    assert sample_size(500, 0.95, 0.05) == pytest.approx(218, abs=error_margin)
+    # Test with higher confidence and smaller interval
+    assert sample_size(10_000, 0.99, 0.01) == pytest.approx(6239, abs=error_margin)
+    # Test with a very large population, approaching the infinite case
+    assert sample_size(1_000_000, 0.95, 0.05) == pytest.approx(385, abs=error_margin)
+
+
+def test_z_score():
+    """
+    Tests the _get_z_score helper function with common confidence levels.
+    """
+    error_margin = 1e-2
+    # Z-score for 90% confidence level should be approximately 1.645
+    assert _get_z_score(0.90) == pytest.approx(1.645, abs=error_margin)
+    # Z-score for 95% confidence level should be approximately 1.96
+    assert _get_z_score(0.95) == pytest.approx(1.96, abs=error_margin)
+    # Z-score for 99% confidence level should be approximately 2.58
+    assert _get_z_score(0.99) == pytest.approx(2.58, abs=error_margin)