mlsampler 0.3.0__tar.gz

mlsampler-0.3.0/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright (c) 2026 Jugai O
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files...

mlsampler-0.3.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: mlsampler
+Version: 0.3.0
+Summary: Flexible constrained random sampler for reverse analysis in machine learning
+Author: Jugai O
+License: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: joblib
+Dynamic: license-file
+
+# RandomSampler
+
+Flexible constrained random sampler for reverse analysis in machine learning.
+
+## Installation
+
+```bash
+pip install mlsampler

mlsampler-0.3.0/README.md

@@ -0,0 +1,8 @@
+# RandomSampler
+
+Flexible constrained random sampler for reverse analysis in machine learning.
+
+## Installation
+
+```bash
+pip install mlsampler

mlsampler-0.3.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mlsampler"
+version = "0.3.0"
+description = "Flexible constrained random sampler for reverse analysis in machine learning"
+authors = [
+  { name="Jugai O" }
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "numpy",
+  "joblib"
+]
+
+license = { text= "LICENSE" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

mlsampler-0.3.0/setup.cfg

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

mlsampler-0.3.0/src/constraints/__init__.py

@@ -0,0 +1,25 @@
+from .constraints import (
+    SumConstraint, 
+    SumIntConstraint, 
+    MultihotConstraint, 
+    RandomSelectConstraint, 
+    RangeConstraint, 
+    CategoriesConstraint,
+    StepConstraint, 
+    StepSumConstraint,
+    FunctionConstraint
+)
+from .base import Constraints
+
+__all__ = [
+    "Constraints",
+    "SumConstraint", 
+    "SumIntConstraint", 
+    "MultihotConstraint", 
+    "RandomSelectConstraint", 
+    "RangeConstraint", 
+    "CategoriesConstraint",
+    "StepConstraint",
+    "StepSumConstraint",
+    "FunctionConstraint"
+]

mlsampler-0.3.0/src/constraints/base.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+from .. import validate as v
+import numpy as np
+
+class Constraints(ABC):
+    def __init__(self, cols: list[int]):
+        v.validate_cols(cols)
+        self.cols = cols
+
+    def _rng(
+            self, 
+            rng: Optional[np.random.Generator] = None
+        ) -> np.random.Generator:
+        return rng if rng is not None else np.random.default_rng()
+    
+    def __call__(self, row: np.ndarray, rng: Optional[np.random.Generator] = None):
+        return self._constrain(row, rng)
+    
+    def __repr__(self):
+        if not self.cols:
+            return f"{self.__class__.__name__}"
+        return f"{self.__class__.__name__}(cols={self.cols})"
+    
+    @abstractmethod
+    def _constrain(self, row: np.ndarray, rng: Optional[np.random.Generator] = None):
+        pass
+
+
+class SelectConstraint(Constraints):
+    def __init__(
+            self, 
+            cols: list[int], 
+            min_used: int = 1, 
+            max_used: Optional[int] = None,
+            reset_cols: bool = True,
+            **kwargs
+        ):
+        
+        if max_used is None:
+            max_used = len(cols)
+        v.validate_usage(min_used, max_used)
+
+        super().__init__(cols)
+        self.min_used = min_used
+        self.max_used = max_used 
+        self.reset_cols = reset_cols
+
+    def _reset_cols(self, row:np.ndarray, cols:list, value: float = 0):
+        row[cols] = value
+        return row
+    
+    def _constrain(self, 
+            row: np.ndarray, 
+            rng: Optional[np.random.Generator] = None
+        ) -> np.ndarray:
+        rng = self._rng(rng)
+        self.rng = rng
+        if self.reset_cols:
+            row = self._reset_cols(row, self.cols)
+        used = rng.integers(self.min_used, self.max_used + 1)
+        selected = rng.choice(self.cols, size=used, replace=False)
+
+        return self._constrain_selected(row, selected)
+
+    @abstractmethod
+    def _constrain_selected(self, row: np.ndarray, selected: np.ndarray) -> np.ndarray:
+        pass
+
+

mlsampler-0.3.0/src/constraints/constraints.py

@@ -0,0 +1,270 @@
+import numpy as np
+from numpy.random import Generator
+from .base import Constraints, SelectConstraint
+from .. import validate as v
+from ..types import Numeric, ArrayLike, Bool, ConstraintFn
+from typing import Optional, Callable
+from ..errors import ConstraintViolationError, ConstraintError
+
+class MultihotConstraint(SelectConstraint):
+    def __init__(
+            self, 
+            cols: list[int], 
+            n_hot: int = 1,
+            **kwargs
+        ):
+        super().__init__(
+            cols, 
+            min_used=n_hot, 
+            max_used=n_hot, 
+            **kwargs
+        )
+        self.n_hot = n_hot
+
+    def _constrain_selected(
+            self, 
+            row: np.ndarray, 
+            selected: np.ndarray,
+            rng: Optional[np.random.Generator] = None,
+        ) -> np.ndarray:
+        row[selected] = 1
+        return row
+    
+class RandomSelectConstraint(SelectConstraint):
+    def __init__(
+            self, 
+            cols: list[int], 
+            rng: Optional[np.random.Generator] = None,
+            **kwargs
+        ):
+        super().__init__(cols, reset_cols=False, **kwargs)
+        self.rng = rng
+    
+    def _constrain_selected(
+            self, 
+            row: np.ndarray, 
+            selected: np.ndarray
+        ) -> np.ndarray:
+        
+        not_selected = np.setdiff1d(self.cols, selected)
+        row[not_selected] = 0
+        return row
+    
+class SumConstraint(SelectConstraint):
+    def __init__(self, 
+            cols: list[int], 
+            sum_value: Numeric = 1, 
+            alpha: Optional[np.ndarray] = None,
+            rng: Optional[np.random.Generator] = None,
+            **kwargs
+        ):
+        v.validate_values(sum_value)
+
+        super().__init__(cols, **kwargs)
+        self.sum_value = sum_value
+        self.alpha = alpha
+        self.rng = self._rng(rng)
+
+    def _constrain_selected(self, 
+            row: np.ndarray, 
+            selected: np.ndarray
+        ) -> np.ndarray:
+        """
+        Args:
+            row (np.ndarray): numpy array representing the row to be modified
+            selected (np.ndarray): numpy array of selected column indices
+            sum_value (float, optional): The desired sum of the selected columns. Defaults to 1.
+            alpha (Optional[np.ndarray], optional): The concentration parameters for the Dirichlet distribution. Defaults to None.
+            rng (Optional[np.random.Generator], optional): The random number generator. Defaults to None.
+
+        Returns:
+            np.ndarray: The modified row
+        """
+        if self.alpha is None:
+            alpha = np.ones(len(selected))
+        else:
+            alpha = self.alpha
+
+        weights = self.rng.dirichlet(alpha)
+
+        row[selected] = weights * self.sum_value
+        return row
+
+class SumIntConstraint(SumConstraint):
+    def __init__(self, cols: list[int], sum_value: int = 100, rng: Generator | None = None, **kwargs):
+        if sum_value < 0:
+            raise TypeError("sum_value must be a non-negative integer")
+        super().__init__(cols, sum_value=sum_value, rng=rng, **kwargs)
+
+    def _constrain_selected(self, row: np.ndarray, selected: np.ndarray) -> np.ndarray:
+        k = len(selected)
+        if k == 1:
+            row[selected[0]] = self.sum_value
+            return row
+
+        cuts = np.sort(self.rng.choice((self.sum_value + k - 1), k - 1, replace=False))
+        parts = np.diff(np.concatenate(([-1], cuts, [self.sum_value + k - 1]))) - 1
+
+        row[selected] = parts
+        return row
+
+class CategoriesConstraint(Constraints):
+    def __init__(self, cols: list[int], values: list[list], strength:str = "hard", **kwargs):
+        super().__init__(cols, **kwargs)
+        self.strength = strength
+        val_tuples = [tuple(v) for v in values]
+        if len(set(val_tuples)) != len(values):
+            raise ConstraintViolationError("values must be unique")
+        
+        self.values = np.array(values, dtype=object)
+
+    def _constrain(
+            self, 
+            row: np.ndarray, 
+            rng: Optional[np.random.Generator] = None,
+        ) -> np.ndarray:
+        rng = self._rng(rng)
+        
+        current_row = row[self.cols]
+        mask = np.ones(len(self.values), dtype=bool)
+        if self.strength == "hard":
+            for i, col in enumerate(self.cols):
+                if current_row[i] is not None:
+                    mask &= (self.values[:, i] == current_row[i])
+        elif self.strength == "soft":
+            mask = mask
+        else:
+            raise ConstraintError(f"{self.strength} was not supported")
+        
+        valid_patterns = self.values[mask]
+        if len(valid_patterns) == 0:
+            raise ConstraintViolationError("No patterns found in categories")
+
+        idx = rng.integers(len(valid_patterns))
+        selected_pattern = valid_patterns[idx]
+        
+        row[self.cols] = selected_pattern
+        return row
+    
+class RangeConstraint(Constraints):
+    def __init__(self, cols: list[int], low: float = 0, high: float = 1, **kwargs):
+        super().__init__(cols, **kwargs)
+        self.low = low
+        self.high = high
+
+    def _constrain(self, row: np.ndarray, rng: Optional[np.random.Generator] = None) -> np.ndarray:
+        # No need to reset cols here
+        rng = self._rng(rng)
+        row[self.cols] = rng.uniform(self.low, self.high, size=len(self.cols))
+        return row
+
+class StepConstraint(Constraints):
+    def __init__(self, col:int, low: float, high: float, step: float, **kwargs):
+        super().__init__(cols=[col], **kwargs)
+        self.values = np.arange(low, high + step, step)
+        self.col = col
+        self.step = step
+
+    def _constrain(
+            self, 
+            row: np.ndarray, 
+            rng: Optional[np.random.Generator] = None
+        ) -> np.ndarray:
+        rng = self._rng(rng)
+        
+        if row[self.col] is not None:
+            if np.any(np.isclose(row[self.col], self.values)):
+                return row
+        
+        row[self.col] = rng.choice(self.values)
+        return row
+
+class StepSumConstraint(StepConstraint):
+    def __init__(
+            self, 
+            cols: list[int], 
+            sum_value: float, 
+            lows: Optional[ArrayLike] = None, 
+            highs: Optional[ArrayLike] = None, 
+            step: float = 1, 
+            **kwargs
+        ):
+        # Initialize parent with the first column's range
+        lows = lows if lows is not None else np.zeros(len(cols))
+        highs = highs if highs is not None else np.ones(len(cols))*100
+        
+        super().__init__(
+            col=cols[0], 
+            low=lows[0], 
+            high=highs[0], 
+            step=step, 
+            **kwargs
+        )
+        self.cols = cols
+
+        self.lows = np.array(lows)
+        self.highs = np.array(highs)
+        self.sum_value = sum_value
+        self.step = step
+
+    def _constrain(self, row: np.ndarray, rng: Optional[np.random.Generator] = None) -> np.ndarray:
+        rng = self._rng(rng)
+        
+        # 1. Initialize all target columns with their respective minimum (low) values
+        current_values = self.lows.copy().astype(float)
+        
+        # 2. Calculate the difference to reach the target sum_value
+        current_sum = np.sum(current_values)
+        residual = self.sum_value - current_sum
+        
+        # Basic validation for feasibility
+        if residual < -1e-9:
+            raise ConstraintViolationError(f"Sum of lows ({current_sum}) exceeds sum_value ({self.sum_value}).")
+        
+        if not np.isclose(residual % self.step, 0) and not np.isclose(residual % self.step, self.step):
+            raise ConstraintViolationError(f"Residual ({residual}) is not a multiple of step ({self.step}).")
+
+        # 3. Randomly distribute the residual in 'step' increments
+        num_steps = int(round(residual / self.step))
+        
+        for _ in range(num_steps):
+            # Find indices where adding a step won't exceed the specific column's high limit
+            eligible_indices = [
+                i for i, val in enumerate(current_values)
+                if val + self.step <= self.highs[i] + 1e-9
+            ]
+            
+            if not eligible_indices:
+                raise ConstraintViolationError("Target sum_value is unreachable within defined highs.")
+            
+            # Pick a random column and increment it
+            target_idx = rng.choice(eligible_indices)
+            current_values[target_idx] += self.step
+            
+        # 4. Final assignment to the row
+        row[self.cols] = current_values
+        return row
+
+
+class FunctionConstraint(Constraints):
+    def __init__(self, fn: ConstraintFn):
+        super().__init__(cols=[])
+        self.fn = fn
+    
+    def _constrain(
+            self, 
+            row: np.ndarray, 
+            rng: Optional[np.random.Generator] = None
+        ) -> Optional[np.ndarray]:
+        result = self.fn(row)
+
+        if isinstance(result, Bool):
+            if not result:
+                return None
+            else:
+                return row
+        elif isinstance(result, np.ndarray):
+            return result
+        else:
+            from ..errors import ConstraintTypeError
+            raise ConstraintTypeError("Constraint function must return either a boolean or a numpy array")

mlsampler-0.3.0/src/engine/__init__.py

@@ -0,0 +1,10 @@
+from .random import RandomSampler
+from ..base import BaseSampler
+
+__annotations__ = {
+    "RandomSampler": BaseSampler,
+}
+
+__all__ = [
+    "RandomSampler",
+]

mlsampler-0.3.0/src/engine/random.py

@@ -0,0 +1,236 @@
+import numpy as np
+
+from ..base import BaseSampler, SamplerConfig, DtypeMeta as dm
+from ..constraints import *
+from ..errors import (
+    ConstraintViolationError, 
+    ConstraintTypeError, 
+    DuplicateColumnWarning
+)
+
+from typing import Optional, Callable
+from collections import defaultdict
+from joblib import Parallel, delayed
+
+import warnings
+
+class RandomSampler(BaseSampler):
+    """
+    Random constraint-based sampler.
+
+    This sampler generates samples based on feature metadata
+    inferred from training data. Users can register constraints 
+    that are applied during sample generation.
+
+    Parameters
+    ----------
+    config : SamplerConfig
+        Configuration object containing feature metadata and sampling settings.
+
+    Notes
+    -----
+    Two types of constraints are supported:
+
+    - Validation constraints: return a boolean.
+    - Constructive constraints: return a modified numpy array.
+
+    Sampling is performed with retry logic up to `max_retries`.
+    Parallel generation is supported via joblib.
+    """
+    
+    __qualname__ = "RandomSampler"
+    
+    def __init__(self, config: SamplerConfig):
+        super().__init__(config)
+        self.rng = np.random.default_rng(config.random_state)
+        self.features = config.features
+        self.batch_size = config.batch_size
+        self.n_jobs = config.n_jobs
+        self.seed = config.random_state
+        self.max_retries = config.max_retries
+
+        self.dim = len(self.features)
+        self.constraints:list[Constraints] = []
+        self._registry = {
+            "sum": SumConstraint,
+            "sumint": SumIntConstraint,
+            "multihot": MultihotConstraint,
+            "random": RandomSelectConstraint,
+            "range": RangeConstraint,
+            "categories": CategoriesConstraint,
+            "step": StepConstraint,
+            "stepsum": StepSumConstraint
+        }
+
+    def reset_constraints(self):
+        """Clear all registered constraints."""
+        self.constraints = []
+    
+    def set_constraints(
+            self,
+            constraint_fn: str | Callable = "sum",
+            replace=False,
+            **kwargs
+        ):
+        """
+        Set a constraint to the sampler.
+        Parameters
+        ----------
+        constraint_fn : str or callable, default="sum"
+            Type of constraint. Supported types:
+            - callable: user-defined function that takes a row and returns a boolean. Required `fn` parameter.
+            - "sum": constraint based on the sum of selected columns. `sum_value` and `cols` must be provided in kwargs.
+            - "sumint": similar to "sum" but ensures the sum is an integer. `sum_value` and `cols` must be provided in kwargs.
+            - "multihot": constraint ensuring a specified number of columns in a set are active.`n_hot` and `cols` must be provided in kwargs.
+            - "random": constraint selecting a random subset of columns. `cols`, `min_used`, and `max_used` can be provided in kwargs.
+            - "range": constraint setting values within a specified range. `cols`, `min_val`, and `max_val` must be provided in kwargs.
+            - "categories": constraint selecting from a list of categorical values. `col` and `values` must be provided in kwargs.
+        replace : bool, default=True
+            If True, clears existing constraints before adding the new one.
+        **kwargs
+            Additional parameters specific to the constraint type.
+            
+        Examples
+        --------
+        >>> from mlsampler import RandomSampler
+        >>> sampler = RandomSampler.setup(X_train)
+        >>> # Custom function constraint
+        >>> sampler.set_constraints(lambda x: (0 < x[0] < 1) and (0 < x[1] < 1))
+        >>> # Sum constraint
+        >>> sampler.set_constraints("sum", sum_value=1, cols=[2, 3, 4], max_used=3)
+        """
+
+        if replace:
+            self.constraints = []
+        
+        if callable(constraint_fn):
+            self.constraints.append(FunctionConstraint(fn=constraint_fn))
+        elif isinstance(constraint_fn, str) and constraint_fn in self._registry:
+            self.constraints.append(self._registry[constraint_fn](**kwargs))
+        else:
+            raise ConstraintTypeError(
+                    f"Unsupported constraint type: {constraint_fn}"
+                )
+        
+    def _base_sample(self, rng: np.random.Generator):
+        # x = np.empty(self.dim, dtype=float)
+        x = np.empty(len(self.config.features), dtype=object)
+
+        for i, f in enumerate(self.features):
+            if f.dtype == dm.bin:
+                x[i] = rng.integers(0, 2)
+            elif f.dtype == dm.integer:
+                x[i] = rng.integers(int(f.low), int(f.high) + 1)
+            elif f.dtype == dm.flt:
+                x[i] = rng.uniform(f.low, f.high)
+            else:
+                x[i] = 0
+
+        return x
+    
+    def _fill_categorical_features(self, x, rng: np.random.Generator):
+        for i, f in enumerate(self.features):
+            if f.dtype == dm.cat:
+                if f.categories:
+                    x[i] = rng.choice(f.categories)
+                else:
+                    x[i] = "unknown"
+        return x
+
+    def _apply_constraints(self, row: np.ndarray) -> Optional[np.ndarray]:
+        """
+        Apply registered constraints to a generated row.
+
+        Parameters
+        ----------
+        row : np.ndarray
+            The generated sample to validate/modify.
+
+        Returns
+        -------
+        np.ndarray or None
+            The modified row if constructive constraints are applied, 
+            or the original row if only validation constraints are present.
+            Returns None if any validation constraint fails.
+        """
+        for constraint in self:
+            row = constraint(row)
+            if row is None:
+                return None  # Constraint violation
+        return row
+    
+    def _detect_conflicts(self):
+        col_usage = defaultdict(list)
+
+        for i, c in enumerate(self.constraints):
+            for col in getattr(c, "cols", []):
+                col_usage[col].append(i)
+
+        for col, ids in col_usage.items():
+            if len(ids) > 1:
+                warnings.warn(
+                    f"Column {col} used in multiple constraints {ids}",
+                    DuplicateColumnWarning
+                )
+    
+    def _generate_one(self, seed_offset: int = 0):
+        base_seed = self.seed if self.seed is not None else None
+        rng = np.random.default_rng(
+            None if base_seed is None else base_seed + seed_offset
+        )
+
+        for _ in range(self.max_retries):
+            x = self._base_sample(rng)
+            x = self._fill_categorical_features(x, rng)
+            x = self._apply_constraints(x) 
+            if x is not None:
+                return x
+        
+        raise ConstraintViolationError("Max retries exceeded.")
+    
+    def _generate_batch(self, batch_size):
+        return np.array([self._generate_one() for _ in range(batch_size)])
+
+    def sample(self, n_samples: int):
+        """
+        Generate samples satisfying all registered constraints.
+
+        Parameters
+        ----------
+        n_samples : int
+            Total number of samples to generate.
+
+        Returns
+        -------
+        np.ndarray
+            Array of shape (n_samples, n_features).
+
+        """
+
+        self._detect_conflicts()
+
+        batches = []
+        remaining = n_samples
+
+        print("sampling...", flush=True)
+
+        while remaining > 0:
+            current_batch = min(self.batch_size, remaining)
+
+            if self.n_jobs == 1:
+                batch = self._generate_batch(current_batch)
+            else:
+                results = Parallel(n_jobs=self.n_jobs)(
+                    delayed(self._generate_one)()
+                    for _ in range(current_batch)
+                )
+                batch = np.array(results)
+
+            batches.append(batch)
+
+            remaining -= current_batch
+
+            print(f"{n_samples - remaining}/{n_samples}", flush=True)
+
+        return np.vstack(batches)
+    

mlsampler-0.3.0/src/mlsampler.egg-info/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: mlsampler
+Version: 0.3.0
+Summary: Flexible constrained random sampler for reverse analysis in machine learning
+Author: Jugai O
+License: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: joblib
+Dynamic: license-file
+
+# RandomSampler
+
+Flexible constrained random sampler for reverse analysis in machine learning.
+
+## Installation
+
+```bash
+pip install mlsampler

mlsampler-0.3.0/src/mlsampler.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/constraints/__init__.py
+src/constraints/base.py
+src/constraints/constraints.py
+src/engine/__init__.py
+src/engine/random.py
+src/mlsampler.egg-info/PKG-INFO
+src/mlsampler.egg-info/SOURCES.txt
+src/mlsampler.egg-info/dependency_links.txt
+src/mlsampler.egg-info/requires.txt
+src/mlsampler.egg-info/top_level.txt

mlsampler-0.3.0/src/mlsampler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mlsampler-0.3.0/src/mlsampler.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy
+joblib

mlsampler-0.3.0/src/mlsampler.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+constraints
+engine