mlsampler

A constraint-aware sampling library for reverse analysis and design of experiments.

mlsampler generates synthetic rows that satisfy constraints you declare, across continuous, integer, binary and categorical columns at the same time. Give it a sample of your data; it infers each column's type and range, and samples within them.

Installation

pip install mlsampler

HyperGridSampler additionally needs scipy:

pip install mlsampler scipy

Requires Python 3.11 or newer.

Quick start

import pandas as pd
from mlsampler import RandomSampler

train = pd.DataFrame({
    "is_active":   [1, 0, 1, 1, 0],
    "is_negative": [0, 1, 0, 0, 1],
    "score":       [10, 0, 50, 100, 5],
    "temperature": [-5.5, 20.0, 36.6, -1.2, 15.8],
    "category":    ["A", "B", "C", "D", "100"],
    "city":        ["Tokyo", "Osaka", "Nagoya", "Fukuoka", "Sapporo"],
})

sampler = RandomSampler.setup(train.values, random_state=42)

# exactly one of the two flags is on
sampler.set_constraints("multihot", cols=[0, 1], n_hot=1)
# keep temperature in a range the training data never covered
sampler.set_constraints("range", cols=[3], low=-10.0, high=40.0)
# category and city must stay a combination that actually occurs
sampler.set_constraints(
    "categories",
    cols=[4, 5],
    values=train[["category", "city"]].to_numpy(),
    strength="soft",
)

result = sampler.sample(1000)
print(pd.DataFrame(result, columns=train.columns))

Columns are addressed by integer position, not by name.

Which sampler?

Constraint reference

Register constraints with set_constraints(name, **kwargs).

"step" takes col (a single integer). Every other constraint takes cols (a list). This is the one inconsistency in the API; passing cols= to "step" raises a ConstraintValidationError telling you so.

All constraints also accept rng, honoured only when n_jobs=1.

A callable receives the row after every other constraint has shaped it. Return a bool to accept or reject, or a numpy array to write into cols:

sampler.set_constraints(lambda row: float(row[3]) < 30.0, cols=[3])

Rows are dtype=object arrays, since one row mixes numbers with category strings — cast before doing arithmetic.

Reproducibility

Equal random_state under equal n_jobs produces equal output, with or without constraints.

a = RandomSampler.setup(X, random_state=42, n_jobs=1).sample(100)
b = RandomSampler.setup(X, random_state=42, n_jobs=1).sample(100)
(a == b).all()   # True

Three things to know:

• A seeded sampler restarts its stream on each sample() call, so calling sample() twice on one sampler returns the same rows. Use a different seed, or random_state=None, for fresh draws.
• Output is not guaranteed to match across different n_jobs values.
• n_jobs=-1 resolves to the machine's core count, so it does not reproduce across machines with different core counts. Pass an explicit integer if you need that.

Parallel execution

n_jobs defaults to 1. Enabling parallelism only pays off when constraints reject most candidates, since starting worker processes costs more than generating a row. Measured speedup against serial:

Below 100 requested rows the serial path is used regardless of n_jobs.

Limitations

• HyperGridSampler does not support constraints; set_constraints() raises NotImplementedError.
• HyperGridSampler requires scipy.
• Constraints are applied per row, so very large draws are bounded by Python-level iteration rather than vectorised numpy.
• Input must not contain missing values; setup() raises on NaN/None.

Upgrading to 0.4.0

This release fixes reproducibility, which was broken whenever a constraint was registered. It contains breaking changes.

Output changes for the same seed. Constraints are now seeded from the sampler instead of drawing from fresh entropy, and one generator serves a whole sample() call instead of one per row. Rows generated by 0.3.x cannot be reproduced by 0.4.0. In exchange, random_state now actually works with constraints — before, it did not.

Two things that used to fail silently now raise:

• HyperGridSampler.set_constraints(...) accepted constraints and ignored them. It now raises NotImplementedError.
• set_constraints("multihot", ..., min_used=1) and similar were accepted for constraints that cannot use them. They are now rejected at registration.

One thing that used to raise now works: categories with strength="hard" rejects and redraws instead of aborting with ConstraintViolationError, which is what makes it usable at all.

Documentation

https://jugais.github.io/randsampler/

Use cases

• Reverse analysis — finding inputs that satisfy target conditions
• Candidate generation for optimization
• Design of experiments over a mixed continuous/categorical space