Sampler Parameters
The sampler_params module defines parameter configuration objects for all Data Designer sampler types. Sampler parameters are used within the SamplerColumnConfig to specify how values should be generated for sampled columns.
Displaying available samplers and their parameters
The config builder has an info attribute that can be used to display the
available sampler types and their parameters:
config_builder.info.display("samplers")
Classes:
| Name | Description |
|---|---|
BernoulliMixtureSamplerParams |
Parameters for sampling from a Bernoulli mixture distribution. |
BernoulliSamplerParams |
Parameters for sampling from a Bernoulli distribution. |
BinomialSamplerParams |
Parameters for sampling from a Binomial distribution. |
CategorySamplerParams |
Parameters for categorical sampling with optional probability weighting. |
DatetimeSamplerParams |
Parameters for uniform datetime sampling within a specified range. |
GaussianSamplerParams |
Parameters for sampling from a Gaussian (Normal) distribution. |
PersonFromFakerSamplerParams |
|
PersonSamplerParams |
Parameters for sampling synthetic person data with demographic attributes. |
PoissonSamplerParams |
Parameters for sampling from a Poisson distribution. |
ScipySamplerParams |
Parameters for sampling from any scipy.stats continuous or discrete distribution. |
SubcategorySamplerParams |
Parameters for subcategory sampling conditioned on a parent category column. |
TimeDeltaSamplerParams |
Parameters for sampling time deltas relative to a reference datetime column. |
UUIDSamplerParams |
Parameters for generating UUID (Universally Unique Identifier) values. |
UniformSamplerParams |
Parameters for sampling from a continuous Uniform distribution. |
BernoulliMixtureSamplerParams
Bases: ConfigBase
Parameters for sampling from a Bernoulli mixture distribution.
Combines a Bernoulli distribution with another continuous distribution, creating a mixture where values are either 0 (with probability 1-p) or sampled from the specified distribution (with probability p). This is useful for modeling scenarios with many zero values mixed with a continuous distribution of non-zero values.
Common use cases include modeling sparse events, zero-inflated data, or situations where an outcome either doesn't occur (0) or follows a specific distribution when it does occur.
Attributes:
| Name | Type | Description |
|---|---|---|
p |
float
|
Probability of sampling from the mixture distribution (non-zero outcome). Must be between 0.0 and 1.0 (inclusive). With probability 1-p, the sample is 0. |
dist_name |
str
|
Name of the scipy.stats distribution to sample from when outcome is non-zero. Must be a valid scipy.stats distribution name (e.g., "norm", "gamma", "expon"). |
dist_params |
dict
|
Parameters for the specified scipy.stats distribution. |
BernoulliSamplerParams
Bases: ConfigBase
Parameters for sampling from a Bernoulli distribution.
Samples binary values (0 or 1) representing the outcome of a single trial with a fixed probability of success. This is the simplest discrete probability distribution, useful for modeling binary outcomes like success/failure, yes/no, or true/false.
Attributes:
| Name | Type | Description |
|---|---|---|
p |
float
|
Probability of success (sampling 1). Must be between 0.0 and 1.0 (inclusive). The probability of failure (sampling 0) is automatically 1 - p. |
BinomialSamplerParams
Bases: ConfigBase
Parameters for sampling from a Binomial distribution.
Samples integer values representing the number of successes in a fixed number of independent Bernoulli trials, each with the same probability of success. Commonly used to model the number of successful outcomes in repeated experiments.
Attributes:
| Name | Type | Description |
|---|---|---|
n |
int
|
Number of independent trials. Must be a positive integer. |
p |
float
|
Probability of success on each trial. Must be between 0.0 and 1.0 (inclusive). |
CategorySamplerParams
Bases: ConfigBase
Parameters for categorical sampling with optional probability weighting.
Samples values from a discrete set of categories. When weights are provided, values are sampled according to their assigned probabilities. Without weights, uniform sampling is used.
Attributes:
| Name | Type | Description |
|---|---|---|
values |
list[Union[str, int, float]]
|
List of possible categorical values to sample from. Can contain strings, integers, or floats. Must contain at least one value. |
weights |
Optional[list[float]]
|
Optional unnormalized probability weights for each value. If provided, must be
the same length as |
DatetimeSamplerParams
Bases: ConfigBase
Parameters for uniform datetime sampling within a specified range.
Samples datetime values uniformly between a start and end date with a specified granularity. The sampling unit determines the smallest possible time interval between consecutive samples.
Attributes:
| Name | Type | Description |
|---|---|---|
start |
str
|
Earliest possible datetime for the sampling range (inclusive). Must be a valid datetime string parseable by pandas.to_datetime(). |
end |
str
|
Latest possible datetime for the sampling range (inclusive). Must be a valid datetime string parseable by pandas.to_datetime(). |
unit |
Literal['Y', 'M', 'D', 'h', 'm', 's']
|
Time unit for sampling granularity. Options: - "Y": Years - "M": Months - "D": Days (default) - "h": Hours - "m": Minutes - "s": Seconds |
GaussianSamplerParams
Bases: ConfigBase
Parameters for sampling from a Gaussian (Normal) distribution.
Samples continuous values from a normal distribution characterized by its mean and standard deviation. The Gaussian distribution is one of the most commonly used probability distributions, appearing naturally in many real-world phenomena due to the Central Limit Theorem.
Attributes:
| Name | Type | Description |
|---|---|---|
mean |
float
|
Mean (center) of the Gaussian distribution. This is the expected value and the location of the distribution's peak. |
stddev |
float
|
Standard deviation of the Gaussian distribution. Controls the spread or width of the distribution. Must be positive. |
decimal_places |
Optional[int]
|
Optional number of decimal places to round sampled values to. If None, values are not rounded. |
PersonFromFakerSamplerParams
Bases: ConfigBase
Attributes:
| Name | Type | Description |
|---|---|---|
generator_kwargs |
list[str]
|
Keyword arguments to pass to the person generator. |
generator_kwargs
property
Keyword arguments to pass to the person generator.
PersonSamplerParams
Bases: ConfigBase
Parameters for sampling synthetic person data with demographic attributes.
Generates realistic synthetic person data including names, addresses, phone numbers, and other demographic information. Data can be sampled from managed datasets (when available) or generated using Faker. The sampler supports filtering by locale, sex, age, geographic location, and can optionally include synthetic persona descriptions.
Attributes:
| Name | Type | Description |
|---|---|---|
locale |
str
|
Locale string determining the language and geographic region for synthetic people. Format: language_COUNTRY (e.g., "en_US", "en_GB", "fr_FR", "de_DE", "es_ES", "ja_JP"). Defaults to "en_US". |
sex |
Optional[SexT]
|
If specified, filters to only sample people of the specified sex. Options: "Male" or "Female". If None, samples both sexes. |
city |
Optional[Union[str, list[str]]]
|
If specified, filters to only sample people from the specified city or cities. Can be a single city name (string) or a list of city names. |
age_range |
list[int]
|
Two-element list [min_age, max_age] specifying the age range to sample from (inclusive). Defaults to a standard age range. Both values must be between minimum and maximum allowed ages. |
with_synthetic_personas |
bool
|
If True, appends additional synthetic persona columns including personality traits, interests, and background descriptions. Only supported for certain locales with managed datasets. |
sample_dataset_when_available |
bool
|
If True, samples from curated managed datasets when available for the specified locale. If False or unavailable, falls back to Faker-generated data. Managed datasets typically provide more realistic and diverse synthetic people. |
generator_kwargs
property
Keyword arguments to pass to the person generator.
PoissonSamplerParams
Bases: ConfigBase
Parameters for sampling from a Poisson distribution.
Samples non-negative integer values representing the number of events occurring in a fixed interval of time or space. The Poisson distribution is commonly used to model count data like the number of arrivals, occurrences, or events per time period.
The distribution is characterized by a single parameter (mean/rate), and both the mean and variance equal this parameter value.
Attributes:
| Name | Type | Description |
|---|---|---|
mean |
float
|
Mean number of events in the fixed interval (also called rate parameter λ). Must be positive. This represents both the expected value and the variance of the distribution. |
ScipySamplerParams
Bases: ConfigBase
Parameters for sampling from any scipy.stats continuous or discrete distribution.
Provides a flexible interface to sample from the wide range of probability distributions available in scipy.stats. This enables advanced statistical sampling beyond the built-in distribution types (Gaussian, Uniform, etc.).
See: scipy.stats documentation
Attributes:
| Name | Type | Description |
|---|---|---|
dist_name |
str
|
Name of the scipy.stats distribution to sample from (e.g., "beta", "gamma", "lognorm", "expon"). Must be a valid distribution name from scipy.stats. |
dist_params |
dict
|
Dictionary of parameters for the specified distribution. Parameter names and values must match the scipy.stats distribution specification (e.g., {"a": 2, "b": 5} for beta distribution, {"scale": 1.5} for exponential). |
decimal_places |
Optional[int]
|
Optional number of decimal places to round sampled values to. If None, values are not rounded. |
SubcategorySamplerParams
Bases: ConfigBase
Parameters for subcategory sampling conditioned on a parent category column.
Samples subcategory values based on the value of a parent category column. Each parent category value maps to its own list of possible subcategory values, enabling hierarchical or conditional sampling patterns.
Attributes:
| Name | Type | Description |
|---|---|---|
category |
str
|
Name of the parent category column that this subcategory depends on. The parent column must be generated before this subcategory column. |
values |
dict[str, list[Union[str, int, float]]]
|
Mapping from each parent category value to a list of possible subcategory values. Each key must correspond to a value that appears in the parent category column. |
TimeDeltaSamplerParams
Bases: ConfigBase
Parameters for sampling time deltas relative to a reference datetime column.
Samples time offsets within a specified range and adds them to values from a reference datetime column. This is useful for generating related datetime columns like order dates and delivery dates, or event start times and end times.
Note
Years and months are not supported as timedelta units because they have variable lengths. See: pandas timedelta documentation
Attributes:
| Name | Type | Description |
|---|---|---|
dt_min |
int
|
Minimum time-delta value (inclusive). Must be non-negative and less than |
dt_max |
int
|
Maximum time-delta value (exclusive). Must be positive and greater than |
reference_column_name |
str
|
Name of an existing datetime column to add the time-delta to. This column must be generated before the timedelta column. |
unit |
Literal['D', 'h', 'm', 's']
|
Time unit for the delta values. Options: - "D": Days (default) - "h": Hours - "m": Minutes - "s": Seconds |
UUIDSamplerParams
Bases: ConfigBase
Parameters for generating UUID (Universally Unique Identifier) values.
Generates UUID4 (random) identifiers with optional formatting options. UUIDs are useful for creating unique identifiers for records, entities, or transactions.
Attributes:
| Name | Type | Description |
|---|---|---|
prefix |
Optional[str]
|
Optional string to prepend to each UUID. Useful for creating namespaced or typed identifiers (e.g., "user-", "order-", "txn-"). |
short_form |
bool
|
If True, truncates UUIDs to 8 characters (first segment only). Default is False for full 32-character UUIDs (excluding hyphens). |
uppercase |
bool
|
If True, converts all hexadecimal letters to uppercase. Default is False for lowercase UUIDs. |
UniformSamplerParams
Bases: ConfigBase
Parameters for sampling from a continuous Uniform distribution.
Samples continuous values uniformly from a specified range, where every value in the range has equal probability of being sampled. This is useful when all values within a range are equally likely, such as random percentages, proportions, or unbiased measurements.
Attributes:
| Name | Type | Description |
|---|---|---|
low |
float
|
Lower bound of the uniform distribution (inclusive). Can be any real number. |
high |
float
|
Upper bound of the uniform distribution (inclusive). Must be greater than |
decimal_places |
Optional[int]
|
Optional number of decimal places to round sampled values to. If None, values are not rounded and may have many decimal places. |