fewlab 0.1.0__tar.gz

fewlab-0.1.0/LICENSE

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

fewlab-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: fewlab
+Version: 0.1.0
+Summary: Pick the fewest items to label for unbiased OLS on shares
+Author: Gaurav Sood
+Project-URL: Homepage, https://github.com/finite-sample/fewlab
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Dynamic: license-file
+
+# fewlab
+
+Pick the **few**est items to **lab**el for unbiased OLS on shares — fast, deterministic, and simple.
+
+## What it does
+
+Given:
+- a counts matrix `C` (units × items), and
+- a covariate matrix `X` (units × predictors),
+
+`fewlab.items_to_label(C, X, K)` returns **which K items** to label to make OLS on the trait share unbiased (Horvitz–Thompson over items) and **variance-efficient** in the A-optimal sense.
+
+It computes, for each item `j`:
+- `v_j = c_{·j} / T` (row-normalized exposure),
+- `g_j = X^T v_j`,
+- `w_j = g_j^T (X^T X)^{-1} g_j`,
+then picks the **top-K** items by `w_j`. This is the deterministic fixed-budget version of the square-root A-optimal allocation.
+
+## Install
+
+```bash
+pip install -e .

fewlab-0.1.0/README.md

@@ -0,0 +1,22 @@
+# fewlab
+
+Pick the **few**est items to **lab**el for unbiased OLS on shares — fast, deterministic, and simple.
+
+## What it does
+
+Given:
+- a counts matrix `C` (units × items), and
+- a covariate matrix `X` (units × predictors),
+
+`fewlab.items_to_label(C, X, K)` returns **which K items** to label to make OLS on the trait share unbiased (Horvitz–Thompson over items) and **variance-efficient** in the A-optimal sense.
+
+It computes, for each item `j`:
+- `v_j = c_{·j} / T` (row-normalized exposure),
+- `g_j = X^T v_j`,
+- `w_j = g_j^T (X^T X)^{-1} g_j`,
+then picks the **top-K** items by `w_j`. This is the deterministic fixed-budget version of the square-root A-optimal allocation.
+
+## Install
+
+```bash
+pip install -e .

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

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: fewlab
+Version: 0.1.0
+Summary: Pick the fewest items to label for unbiased OLS on shares
+Author: Gaurav Sood
+Project-URL: Homepage, https://github.com/finite-sample/fewlab
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Dynamic: license-file
+
+# fewlab
+
+Pick the **few**est items to **lab**el for unbiased OLS on shares — fast, deterministic, and simple.
+
+## What it does
+
+Given:
+- a counts matrix `C` (units × items), and
+- a covariate matrix `X` (units × predictors),
+
+`fewlab.items_to_label(C, X, K)` returns **which K items** to label to make OLS on the trait share unbiased (Horvitz–Thompson over items) and **variance-efficient** in the A-optimal sense.
+
+It computes, for each item `j`:
+- `v_j = c_{·j} / T` (row-normalized exposure),
+- `g_j = X^T v_j`,
+- `w_j = g_j^T (X^T X)^{-1} g_j`,
+then picks the **top-K** items by `w_j`. This is the deterministic fixed-budget version of the square-root A-optimal allocation.
+
+## Install
+
+```bash
+pip install -e .

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

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+fewlab/fewlab.egg-info/PKG-INFO
+fewlab/fewlab.egg-info/SOURCES.txt
+fewlab/fewlab.egg-info/dependency_links.txt
+fewlab/fewlab.egg-info/requires.txt
+fewlab/fewlab.egg-info/top_level.txt
+tests/test_api.py
+tests/test_quality.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+numpy>=1.23
+pandas>=1.5

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

@@ -0,0 +1 @@
+

fewlab-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fewlab"
+version = "0.1.0"
+description = "Pick the fewest items to label for unbiased OLS on shares"
+authors = [{name = "Gaurav Sood"}]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.23", "pandas>=1.5"]
+
+[project.urls]
+Homepage = "https://github.com/finite-sample/fewlab"
+
+[tool.setuptools.packages.find]
+where = ["fewlab"]

fewlab-0.1.0/setup.cfg

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

fewlab-0.1.0/tests/test_api.py

@@ -0,0 +1,19 @@
+import pandas as pd
+from fewlab import items_to_label
+from .data_synth import make_synth
+
+def test_basic_api():
+    counts, X = make_synth(n=50, m=80, p=5, seed=0)
+    K = 15
+    chosen = items_to_label(counts, X, K=K)
+    assert isinstance(chosen, list)
+    assert len(chosen) == K
+    # ensure they are item column names
+    assert set(chosen).issubset(set(counts.columns))
+
+def test_zero_rows_are_dropped():
+    counts, X = make_synth(n=30, m=40, p=4, seed=1)
+    # force some zero-total rows
+    counts.iloc[:3, :] = 0
+    chosen = items_to_label(counts, X, K=10)
+    assert len(chosen) == 10

fewlab-0.1.0/tests/test_quality.py

@@ -0,0 +1,32 @@
+import numpy as np
+import pandas as pd
+from fewlab import items_to_label
+from .data_synth import make_synth
+
+def compute_w(counts, X, ridge=None):
+    T = counts.sum(axis=1).to_numpy(float)
+    keep = T > 0
+    counts = counts.loc[keep]; X = X.loc[keep]; T = T[keep]
+    V = counts.to_numpy(float) / T[:, None]
+    Xn = X.to_numpy(float)
+    XtX = Xn.T @ Xn
+    if ridge is None:
+        cond = np.linalg.cond(XtX)
+        if not np.isfinite(cond) or cond > 1e12:
+            ridge = 1e-8
+    if ridge:
+        XtX = XtX + ridge * np.eye(XtX.shape[0])
+    XtX_inv = np.linalg.inv(XtX)
+    G = Xn.T @ V
+    w = np.einsum("jp,pk,kj->j", G.T, XtX_inv, G)
+    return w, counts.columns
+
+def test_selected_items_have_higher_w():
+    counts, X = make_synth(n=120, m=200, p=6, seed=1234)
+    K = 30
+    chosen = items_to_label(counts, X, K=K)
+    w, cols = compute_w(counts, X)
+    w_map = {c: w[i] for i, c in enumerate(cols)}
+    w_chosen = np.median([w_map[c] for c in chosen])
+    w_rest = np.median([w_map[c] for c in cols if c not in chosen])
+    assert w_chosen >= w_rest, "Selected items should have larger median w"