subsetmatrix 0.1.0__py3-none-any.whl

subsetmatrix/dataset_payload.py

@@ -0,0 +1,74 @@
+import numpy as np
+from math import comb
+from subsetmatrix.engine import generateMatrix
+from subsetmatrix.selecting_subsets import normalize_k_values
+from typing import Any
+from subsetmatrix.payload_args_validation import validate_args, validate_kwargs
+
+class ObservationSet:
+    """This class instantiates objects with a set of points and keeps a
+matrix with all possible combinations for subsets, the main dataset and
+performs methods on them for several usecases.
+### properties:
+- X is a list of labels for the observations. They might come as small strings
+or numbers, dates or whatever else picks your fancy, or not come at all, case
+in which we will generate a list of integers as index to the observations;
+- Y is a list of observations. For scientific ends, this one should be some
+type of numeric value, but since this tool is here to answer diversefied needs,
+no use limiting its reach through that, so it might also be a list of anything.
+"""
+    def __init__(self, *args, **kwargs) -> None:
+        # grabbing the first significant argument
+        args_dict = validate_args(*args) if args else {}
+        kwargs_dict = validate_kwargs(
+            **{k:v for k, v in kwargs.items() if k != "indexing_as_one"}
+        ) if kwargs else {}
+        
+        if not args_dict and not kwargs_dict:
+            raise ValueError("No data was detected while initiating this object.")
+        
+        self.Y = args_dict.get("Y")
+        if self.Y is None:
+            self.Y = kwargs_dict.get("Y")
+
+        if self.Y is None:
+            raise ValueError("No values for Y were detected while initiating this object.")
+
+        self.n = len(self.Y)
+
+        self.X = args_dict.get("X")
+        if self.X is None:
+            self.X = kwargs_dict.get("X")
+        
+        if self.X is None:
+            self.indexing_as_one = bool(kwargs.get("indexing_as_one", True))
+            start = 1 if self.indexing_as_one else 0
+            self.X = list(range(start, self.n + start))
+        
+        if len(self.X) != len(self.Y):
+            raise ValueError(f"The length of the X set and of the Y set are of different sizes: X: {len(self.X)} and Y: {len(self.Y)}")
+    
+    def get_subsets(self, k:int|list[int]) -> list[list[list[Any]]]:
+        k_values = normalize_k_values(k, self.n)
+        temp_matrix = generateMatrix(self.n, k_values)
+
+        # one bulk nonzero pass over the whole matrix instead of one
+        # np.flatnonzero call per row: rows are grouped by k in k_values
+        # order and every row within a k-group has exactly k ones, so the
+        # flat column-index stream can be reshaped per group without
+        # re-touching numpy per row.
+        _, col_idx = np.nonzero(temp_matrix)
+
+        res = []
+        pos = 0
+        for k_val in k_values:
+            count = comb(self.n, k_val)
+            # .tolist() converts the whole block in one bulk C call; iterating
+            # a numpy array element-by-element boxes each entry into a numpy
+            # scalar, which is far costlier than plain-int indexing below.
+            block = col_idx[pos:pos + count * k_val].reshape(count, k_val).tolist()
+            pos += count * k_val
+            for combo in block:
+                res.append([[self.X[j], self.Y[j]] for j in combo]) # type: ignore
+        return res
+

subsetmatrix/engine.py

@@ -0,0 +1,52 @@
+import numpy as np
+import numpy.typing as npt
+from math import comb
+from typing import Iterator
+
+def iter_k_masks(n: int, k: int) -> Iterator[int]:
+    """Generator yielding subsets with the same ammount
+of points (k) to the limit of observations on the set."""
+    if not 0 < k <= n:
+        raise ValueError("K must satisfy 0 < k <= n")
+    limit = (1 << n) # assuming n = 3, we would have 1 -> 2 -> 4 -> 8, thus the limit is 8
+    mask = (1 << k) - 1 # assuming k = 2, first k would be 1 -> 2 -> 4, 4 - 1 = 3
+
+    while mask < limit:
+        yield mask
+
+        # Gosper's hack: next integer with the same number of set bits, implying subsets of the same size
+        c = mask & -mask
+        r = mask + c
+        mask = (((r ^ mask) >> 2) // c) | r
+
+def cardinality(mask: int) -> int:
+    """Useful if you're getting a mask outside of context and needs to know where it belongs."""
+    return mask.bit_count()
+
+def generateMatrix(n:int, K:list=[]) -> npt.NDArray[np.uint32]:
+    """The matrix won't follow the cardinal order of growth, but the k-sized groups."""
+    if not K:
+        K = list(range(2, n + 1)) # skip singletons (k=1); include the full set (k=n)
+    if n < 3:
+        raise ValueError("The number of observations should be > 2.")
+    if n > 20:
+        raise ValueError("Dense uint32 generation is temporarily capped at n <=20")
+
+    total_rows = sum(comb(n, k) for k in K) # sized to whatever K actually requests, not the full 2**n - 2 span
+    matr = np.empty((total_rows, n), dtype=np.uint32)
+    bits = np.arange(n, dtype=np.uint32)
+    row_start = 0
+    for k in K:
+        # mask generation stays a plain-Python loop (cheap); the mask -> row
+        # expansion is done ONCE per k-group via broadcasting instead of once
+        # per row, since numpy's per-call dispatch overhead otherwise dwarfs
+        # the actual work on rows this small.
+        count = comb(n, k)
+        masks = np.fromiter(iter_k_masks(n, k), dtype=np.uint32, count=count)
+        matr[row_start:row_start + count] = (masks[:, None] >> bits[None, :]) & 1
+        row_start += count
+    return matr
+
+
+# if __name__ == "__main__":
+#     generateMatrix(3)

subsetmatrix/payload_args_validation.py

@@ -0,0 +1,139 @@
+def validate_args(*args) -> dict:
+    """Validates args and delivers them organized in a preconceived dict."""
+    res = {}
+    all_args = [arg for arg in args]
+    if not all_args:
+        return res
+
+    if isinstance(all_args[0], dict):
+        points = all_args[0]
+        y_temp = points.get("Y")
+        x_temp = points.get("X")
+        if isinstance(y_temp, dict) or isinstance(x_temp, dict):
+            raise ValueError("Y and X should be lists or tuples, like so: 'Y': [1, 2, 3, 4, 5].")
+        if isinstance(y_temp, list|tuple) and len(y_temp) > 2:
+            # for now we keep iterables out of the story. Later on it makes sense to consider
+            pairs = [p for p in y_temp if isinstance(p, list|tuple) and len(p) == 2]
+            if len(pairs) > 2:
+                res["Y"] = []
+                res["X"] = []
+                for i in pairs:
+                    if isinstance(i[0], int|float|complex|str) and isinstance(i[1], int|float|complex|str):
+                        res["X"].append(i[0])
+                        res["Y"].append(i[1])
+            else:
+                res["Y"] = [x for x in y_temp if isinstance(x, int|float|complex|str)]
+        elif isinstance(y_temp, dict) and len(y_temp) > 2:
+            res["Y"] = []
+            res["X"] = []
+            for k, v in y_temp.items():
+                if isinstance(k, int|float|complex|str) and isinstance(v, int|float|complex|str):
+                    res["X"].append(k)
+                    res["Y"].append(v)
+        if isinstance(x_temp, list|tuple):
+            res["X"] = [x for x in x_temp if isinstance(x, int|float|complex|str)]
+
+    elif isinstance(all_args[0], list|tuple) and len(all_args[0]) > 2:
+        y_temp = all_args[0]
+        # I could seed directly into res["Y"] and res["X"], but checking if this fits sounds better
+        pairs = [p for p in y_temp if isinstance(p, list|tuple) and len(p) == 2]
+        if len(pairs) > 2:
+            res["Y"] = []
+            res["X"] = []
+            for i in pairs:
+                if isinstance(i[0], int|float|complex|str) and isinstance(i[1], int|float|complex|str):
+                    res["X"].append(i[0])
+                    res["Y"].append(i[1])
+        elif not pairs:
+            res["Y"] = [y for y in y_temp if isinstance(y, int|float|complex|str)]
+
+    else:
+        # by now we stablished args[0] wasn't a list|tuple, so it should
+        # make no sense to treat args as pairs, therefore I'll just grab
+        # whatever is args and not an iterable
+        res["Y"] = [y for y in all_args if isinstance(y, int|float|complex|str)]
+        res["residual_args"] = [r for r in all_args[1:] if not isinstance(r, int|float|complex|str)]
+    
+    if not res.get("Y"):
+        return {"residual_args": all_args}
+
+    if len(res["Y"]) < 3:
+        raise ValueError("There should be more than two 'Y' entries.")
+    if len(all_args) > 1 and not res.get("residual_args"):
+        res["residual_args"] = all_args[1:]
+    
+    # I shouldn't worry about building X from list(range(len(res["Y"]))) now, only after calling both methods on object creation
+    return res
+
+def validate_kwargs(**kwargs) -> dict:
+    """Validates kwargs and delivers them organized in a preconceived dict."""
+    res = {}
+    all_kwargs = dict(kwargs)
+    if not all_kwargs:
+        return res
+    
+    if "Y" in all_kwargs:
+        y_temp = all_kwargs.get("Y") # it makes no sense to validate it to points since the
+                                     # argument came as "Y" inside a kwarg, so I won't.
+        
+        if not isinstance(y_temp, list|tuple):
+            raise ValueError("If you're trying to send Y values via kwarg, the value should be a list, like so: 'Y': [1, 2, 3, 4, 5].")
+
+        if len(y_temp) > 2:
+            res["Y"] = [y for y in y_temp if isinstance(y, int|float|complex|str)]
+        
+        res["residual_kwargs"] = {k:v for k, v in all_kwargs.items() if k != "Y" and k != "X"}
+
+    if "X" in all_kwargs:
+        x_temp = all_kwargs.get("X")
+        if isinstance(x_temp, list|tuple) and len(x_temp) > 2:
+            res["X"] = [x for x in x_temp if isinstance(x, int|float|complex|str)]
+        if "residual_kwargs" not in res:
+            res["residual_kwargs"] = {k: v for k, v in all_kwargs.items() if k != "Y" and k != "X"}
+
+    if not "Y" in res and not "X" in res:
+        if "points" in all_kwargs:
+            points = all_kwargs.get("points")
+            if not points:
+                raise ValueError("Points should have values into it.")
+
+            if "Y" in points:
+                y_temp = points.get("Y")
+                y_temp_temp = [y for y in y_temp if isinstance(y, int|float|complex|str)]
+                if not y_temp_temp or len(y_temp_temp) < 3:
+                    raise ValueError("There should be more than two 'Y' entries.")
+                res["Y"] = y_temp_temp
+
+            if "Y" in res and len(res["Y"]) > 2 and "X" in points:
+                x_temp = points.get("X")
+                x_temp_temp = [x for x in x_temp if isinstance(x, int|float|complex|str)]
+                if not x_temp_temp or len(x_temp_temp) != len(res["Y"]):
+                    raise ValueError("There should be the same amount of values in X than there are in Y.")
+                res["X"] = x_temp_temp
+            
+            res["residual_kwargs"] = {k:v for k, v in all_kwargs.items() if k != "X" and k != "Y"}
+
+    if not "points" in all_kwargs and not "Y" in all_kwargs:
+        res["Y"] = []
+        res["X"] = []
+        for k, v in all_kwargs.items():
+            if isinstance(k, int|float|complex|str) and isinstance(v, int|float|complex|str):
+                res["X"].append(k)
+                res["Y"].append(v)
+        res["residual_kwargs"] = {k:v for k, v in all_kwargs.items() if not isinstance(k, int|float|complex|str) or not isinstance(v, int|float|complex|str)}
+
+    if not "Y" in res:
+        raise ValueError("No valid entry for Y values was detected in your keyword arguments.")
+
+    if len(res["Y"]) < 3:
+        raise ValueError("There should be more than two 'Y' entries.")
+
+    if not "X" in res and "X" in all_kwargs:
+        x_temp = all_kwargs.get("X")
+        if not isinstance(x_temp, list|tuple):
+            raise ValueError("X should be a list or a tuple.")
+        x_temp_temp = [x for x in x_temp if isinstance(x, int|float|complex|str)]
+        if len(x_temp_temp) != res["Y"]:
+            raise ValueError("There should be an equal ammount of itens in X and Y.")
+
+    return res

subsetmatrix/selecting_subsets.py

@@ -0,0 +1,70 @@
+import numpy as np
+import numpy.typing as npt
+from math import comb
+from operator import index
+
+def total_window_size(k_values:list[int], n:int) -> int:
+    """Calculates the window size for a list of k values. Mainly for array building purposes."""
+    if not k_values:
+        raise ValueError("k_values cannot be empty.")
+    return sum(comb(n, k) for k in k_values)
+
+def validate_k(k: int, n: int) -> int:
+    """Validates k, and normalizes it in cases like np.int64(3), against an n-observation matrix."""
+    if isinstance(k, bool):
+        raise TypeError(f"k must be an integer, not bool. Received {k}.")
+
+    try:
+        k = index(k)
+    except TypeError as exc:
+        raise TypeError(f"k must be an integer. Received {k}.") from exc
+
+    if not 0 < k <= n:
+        raise ValueError(f"k must satisfy 0 < k <= n. Received k={k}, n={n}.")
+
+    return k
+
+def normalize_k_values(k: int | list[int], n: int) -> list[int]:
+    """Normalize k input into a sorted list of valid integer k values."""
+    if isinstance(k, list):
+        if not k:
+            raise ValueError("k cannot be an empty list.")
+
+        k_values = [validate_k(x, n) for x in k]
+        return sorted(set(k_values))
+
+    return [validate_k(k, n)]
+
+def extract_k_window(
+    matrix: npt.NDArray[np.uint32],
+    k: int | list[int],
+) -> npt.NDArray[np.uint32]:
+    """
+    Extract one or more k-sized subset groups from a generated subset matrix.
+
+    If k is a list, groups are returned in ascending k order.
+
+    Offsets are computed from n and k alone, assuming `matrix` was built
+    with the canonical full k=1..n-1 sweep (e.g. engine.generateMatrix(n,
+    list(range(1, n)))). engine.generateMatrix's bare-call default no
+    longer produces that layout (it skips k=1 and includes k=n), so
+    passing a bare generateMatrix(n) result here silently extracts the
+    wrong rows instead of raising.
+    """
+    if matrix.ndim != 2:
+        raise ValueError("matrix must be a 2D array filled with integers.")
+
+    n = matrix.shape[1]
+    k_values = normalize_k_values(k, n)
+    window_size = total_window_size(k_values, n)
+    base = np.empty((window_size, n), dtype=matrix.dtype)
+    current_row = 0
+    for i in k_values:
+        start = sum(comb(n, j) for j in range(1, i))
+        size = comb(n, i)
+        end = start + size
+
+        base[current_row: current_row + size] = matrix[start:end]
+        current_row += size
+
+    return base

subsetmatrix-0.1.0.dist-info/METADATA

@@ -0,0 +1,671 @@
+Metadata-Version: 2.4
+Name: subsetmatrix
+Version: 0.1.0
+Summary: Generate, select, and materialize subset membership matrices from observation sets.
+Author: Lucas Dornelles Cherobim
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EngDornelles/subsetMatrix
+Project-URL: Repository, https://github.com/EngDornelles/subsetMatrix
+Project-URL: Issues, https://github.com/EngDornelles/subsetMatrix/issues
+Keywords: subsets,combinations,matrix,numpy,combinatorics,dataset,mask
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# subsetMatrix
+
+`subsetMatrix` is a small Python library for generating, selecting, and materializing subsets from an observation set.
+
+It starts with a simple idea:
+
+> Given `n` observations, generate a binary matrix where each row represents one subset.
+
+Each column represents one observation.
+Each row represents one subset.
+A value of `1` means the observation belongs to that subset.
+A value of `0` means it does not.
+
+For `n = 3`, the generated matrix is:
+
+```text
+[[1 0 0]
+ [0 1 0]
+ [0 0 1]
+ [1 1 0]
+ [1 0 1]
+ [0 1 1]]
+```
+
+The empty subset `[0 0 0]` and the full subset `[1 1 1]` are excluded by default.
+
+---
+
+## Why this exists
+
+Many workflows need to explore combinations of observations, points, features, candidates, or records.
+
+`subsetMatrix` provides a deterministic substrate for that kind of work.
+
+It can be useful for:
+
+* combinatorial analysis;
+* subset generation;
+* fixed-size subset selection;
+* dataset slicing;
+* candidate generation;
+* research prototypes;
+* model experimentation;
+* matrix-based workflows;
+* observation-subset analysis.
+
+The library intentionally keeps interpretation out of the core.
+
+It does not decide what a subset means.
+It only helps generate, select, and materialize subsets.
+
+---
+
+## Core behavior
+
+For `n` observations, there are:
+
+```text
+2^n
+```
+
+possible subsets.
+
+`subsetMatrix` excludes the empty and full subsets, so the generated matrix has:
+
+```text
+2^n - 2
+```
+
+rows.
+
+The matrix shape is:
+
+```text
+(2^n - 2, n)
+```
+
+Examples:
+
+```text
+n = 3  → 6 rows
+n = 4  → 14 rows
+n = 20 → 1,048,574 rows
+```
+
+Rows are grouped by subset size `k`.
+
+For `n = 4`, rows are ordered as:
+
+```text
+k = 1 → subsets with one active observation
+k = 2 → subsets with two active observations
+k = 3 → subsets with three active observations
+```
+
+The groups `k = 0` and `k = n` are skipped.
+
+---
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/EngDornelles/subsetMatrix.git
+cd subsetMatrix
+```
+
+Create a virtual environment.
+
+On Windows PowerShell:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\activate
+```
+
+Install the package in editable mode:
+
+```powershell
+py -m pip install -e .
+```
+
+Install test dependencies:
+
+```powershell
+py -m pip install pytest
+```
+
+Run tests:
+
+```powershell
+py -m pytest -v
+```
+
+---
+
+## Quick start
+
+### Generate a subset matrix
+
+```python
+from subsetmatrix.engine import generateMatrix
+
+matrix = generateMatrix(3)
+
+print(matrix)
+```
+
+By default (no `K` given), rows are grouped by k, skipping singletons
+(k=1) and including the full set (k=n):
+
+Output:
+
+```text
+[[1 1 0]
+ [1 0 1]
+ [0 1 1]
+ [1 1 1]]
+```
+
+To include singletons or restrict to specific subset sizes, pass `K`
+explicitly:
+
+```python
+matrix = generateMatrix(3, [1, 2, 3])
+```
+
+---
+
+## User-facing dataset workflow
+
+The easiest way to use the library is through `ObservationSet`.
+
+```python
+from subsetmatrix.dataset_payload import ObservationSet
+
+obs = ObservationSet(
+    {
+        "Y": [10, 20, 30, 40],
+        "X": ["A", "B", "C", "D"],
+    }
+)
+
+subsets = obs.get_subsets(2)
+
+print(subsets)
+```
+
+Output:
+
+```python
+[
+    [["A", 10], ["B", 20]],
+    [["A", 10], ["C", 30]],
+    [["B", 20], ["C", 30]],
+    [["A", 10], ["D", 40]],
+    [["B", 20], ["D", 40]],
+    [["C", 30], ["D", 40]],
+]
+```
+
+`X` contains labels.
+`Y` contains observations.
+
+If `X` is not provided, labels are generated automatically.
+
+```python
+obs = ObservationSet(
+    {
+        "Y": [10, 20, 30, 40],
+    }
+)
+
+print(obs.X)
+```
+
+Output:
+
+```python
+[1, 2, 3, 4]
+```
+
+By default, generated labels are one-based.
+
+To use zero-based labels:
+
+```python
+obs = ObservationSet(
+    {
+        "Y": [10, 20, 30, 40],
+    },
+    indexing_as_one=False,
+)
+
+print(obs.X)
+```
+
+Output:
+
+```python
+[0, 1, 2, 3]
+```
+
+---
+
+## Selecting subset windows by `k`
+
+You can extract only the rows for a specific subset size.
+
+`extract_k_window` computes row offsets assuming `matrix` was built
+with the full k=1..n-1 sweep, so pass that explicit `K` to
+`generateMatrix` — its own default (no `K`) skips k=1 and includes
+k=n, which no longer matches those offsets. If you just want specific
+k-sized subsets, prefer calling `generateMatrix(n, K)` directly (see
+above) instead of going through `extract_k_window`.
+
+```python
+from subsetmatrix.engine import generateMatrix
+from subsetmatrix.selecting_subsets import extract_k_window
+
+matrix = generateMatrix(4, list(range(1, 4)))
+
+k2_matrix = extract_k_window(matrix, 2)
+
+print(k2_matrix)
+```
+
+Output:
+
+```text
+[[1 1 0 0]
+ [1 0 1 0]
+ [0 1 1 0]
+ [1 0 0 1]
+ [0 1 0 1]
+ [0 0 1 1]]
+```
+
+You can also extract multiple `k` groups:
+
+```python
+selected = extract_k_window(matrix, [1, 3])
+```
+
+The list is normalized, sorted, and deduplicated.
+
+So this:
+
+```python
+extract_k_window(matrix, [3, 1, 1])
+```
+
+behaves like:
+
+```python
+extract_k_window(matrix, [1, 3])
+```
+
+---
+
+## Fixed-size mask generation
+
+`subsetMatrix` uses integer masks internally to generate subset rows.
+
+You can generate masks directly for a fixed subset size `k`:
+
+```python
+from subsetmatrix.engine import iter_k_masks
+
+for mask in iter_k_masks(n=4, k=2):
+    print(mask)
+```
+
+Output:
+
+```text
+3
+5
+6
+9
+10
+12
+```
+
+Those masks correspond to:
+
+```text
+0011
+0101
+0110
+1001
+1010
+1100
+```
+
+Each mask has exactly two active bits.
+
+---
+
+## Cardinality
+
+You can check how many active observations a mask contains:
+
+```python
+from subsetmatrix.engine import cardinality
+
+print(cardinality(5))
+```
+
+Output:
+
+```text
+2
+```
+
+Because:
+
+```text
+5 = 0101
+```
+
+has two active bits.
+
+---
+
+## Current API
+
+### `generateMatrix(n: int, K: list[int] = [])`
+
+Generates the subset membership matrix for the requested subset sizes,
+grouped by k. If `K` is omitted, defaults to `range(2, n + 1)` —
+singletons (k=1) are skipped and the full set (k=n) is included.
+
+```python
+from subsetmatrix.engine import generateMatrix
+
+matrix = generateMatrix(4)
+```
+
+For `n = 4`, the shape is:
+
+```text
+(11, 4)
+```
+
+Pass `K` explicitly to select specific subset sizes:
+
+```python
+matrix = generateMatrix(4, [2])       # only pairs
+matrix = generateMatrix(4, [1, 2, 3]) # the pre-1.0 default: full k=1..n-1 sweep
+```
+
+---
+
+### `iter_k_masks(n: int, k: int)`
+
+Yields integer masks with exactly `k` active observations.
+
+```python
+from subsetmatrix.engine import iter_k_masks
+
+masks = list(iter_k_masks(4, 2))
+```
+
+---
+
+### `cardinality(mask: int)`
+
+Returns how many active bits exist in a mask.
+
+```python
+from subsetmatrix.engine import cardinality
+
+cardinality(12)
+```
+
+---
+
+### `extract_k_window(matrix, k)`
+
+Extracts rows for one or more subset sizes.
+
+```python
+from subsetmatrix.selecting_subsets import extract_k_window
+
+k2 = extract_k_window(matrix, 2)
+mixed = extract_k_window(matrix, [1, 3])
+```
+
+---
+
+### `ObservationSet(points).get_subsets(k)`
+
+Materializes actual dataset subsets.
+
+```python
+from subsetmatrix.dataset_payload import ObservationSet
+
+obs = ObservationSet(
+    {
+        "Y": [10, 20, 30, 40],
+        "X": ["A", "B", "C", "D"],
+    }
+)
+
+obs.get_subsets(2)
+```
+
+---
+
+## Repository structure
+
+```text
+subsetMatrix/
+├── LICENSE
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── subsetmatrix/
+│       ├── __init__.py
+│       ├── engine.py
+│       ├── selecting_subsets.py
+│       └── dataset_payload.py
+└── tests/
+    ├── test_engine.py
+    ├── test_selecting_subsets.py
+    └── test_dataset_payload.py
+```
+
+---
+
+## Design notes
+
+### Matrix generation
+
+The generated matrix is a binary membership matrix.
+
+Each row is a subset.
+Each column is an observation.
+
+Example:
+
+```text
+[1 0 1 0]
+```
+
+means:
+
+```text
+include observation 0
+exclude observation 1
+include observation 2
+exclude observation 3
+```
+
+---
+
+### Cardinality grouping
+
+Rows are grouped by subset size `k`.
+
+This makes it possible to extract all subsets of a specific size without scanning the whole matrix.
+
+For example, if you only need subsets with `k = 3`, you can extract only that window.
+
+---
+
+### Empty and full subsets
+
+The empty subset and full subset are excluded.
+
+They are usually not useful for workflows where subsets are being compared, sampled, scored, or transformed.
+
+Excluded rows:
+
+```text
+[0 0 0 ... 0]
+[1 1 1 ... 1]
+```
+
+---
+
+### Dense matrix warning
+
+The full dense matrix grows quickly.
+
+```text
+n = 20 → 1,048,574 rows
+n = 26 → 67,108,862 rows
+```
+
+Future versions may add:
+
+* mask-only output;
+* chunked generation;
+* memory estimation;
+* packed storage;
+* optional export formats;
+* lazy payload materialization.
+
+The current version prioritizes clarity and deterministic behavior.
+
+---
+
+## Testing
+
+Run:
+
+```powershell
+py -m pytest -v
+```
+
+Current test coverage validates:
+
+* matrix shape;
+* exact output for `n = 3`;
+* cardinality grouping;
+* exclusion of empty and full rows;
+* invalid `n`;
+* k-window extraction;
+* sorted and deduplicated `k` lists;
+* rejection of invalid `k`;
+* NumPy integer support;
+* dataset payload materialization;
+* default generated labels;
+* custom labels;
+* invalid input handling.
+
+Example current test result:
+
+```text
+18 passed
+```
+
+---
+
+## Development status
+
+`subsetMatrix` is in early development.
+
+Current stable layers:
+
+```text
+engine.py
+→ generate subset matrix
+
+selecting_subsets.py
+→ extract k-window slices
+
+dataset_payload.py
+→ materialize dataset subsets
+```
+
+Planned improvements may include:
+
+* snake_case aliases;
+* chunked matrix generation;
+* mask-first public workflows;
+* memory estimation helpers;
+* optional pandas helpers;
+* optional export utilities;
+* expanded documentation;
+* performance benchmarks.
+
+---
+
+## Naming
+
+The GitHub repository is named:
+
+```text
+subsetMatrix
+```
+
+The Python package is imported as:
+
+```python
+import subsetmatrix
+```
+
+This follows Python package naming conventions while preserving the repository’s public name.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+See:
+
+```text
+LICENSE
+```
+
+---
+
+## Author
+
+Created by Lucas Dornelles Cherobim.
+
+GitHub: [EngDornelles](https://github.com/EngDornelles)

subsetmatrix-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+subsetmatrix/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+subsetmatrix/dataset_payload.py,sha256=oTMZf-0-bmHrSQl5iYmhRJlLbWSWI00XqDc_IWroUok,3299
+subsetmatrix/engine.py,sha256=6j3P13R0gqWUoPVMgoBOcY05913vc0xyHy18p53-Ygg,2155
+subsetmatrix/payload_args_validation.py,sha256=PEnVcHsMfYx4sBHZGkey4eh4CoLpzfLPSzw1Lm0rMzI,6489
+subsetmatrix/selecting_subsets.py,sha256=PGbx9_IdT4-C7zAOMlAJHSXp_rukHeos_r9adTZF_sU,2421
+subsetmatrix-0.1.0.dist-info/licenses/LICENSE,sha256=OBAWiIKPH-1aydk7x5_lVYVqJh8dFJZp_iH4uv9F4f8,1081
+subsetmatrix-0.1.0.dist-info/METADATA,sha256=wOchTwwvvl-bT-TE1KZISAX6ZNGJc5wnBb3VKL5BsGg,11261
+subsetmatrix-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+subsetmatrix-0.1.0.dist-info/top_level.txt,sha256=Q-tNlDpdWaJvJ64Of70xUTDDqDyVk9BwXVyqfCv7ByA,13
+subsetmatrix-0.1.0.dist-info/RECORD,,

subsetmatrix-0.1.0.dist-info/WHEEL

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

subsetmatrix-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Dornelles Cherobim
+
+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.

subsetmatrix-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+subsetmatrix