bool_field()

Create a boolean column specification for use in a schema.

Usage

bool_field(
    p_true=0.5,
    nullable=False,
    null_probability=0.0,
    unique=False,
    generator=None,
)

The bool_field() function defines the constraints and behavior for a boolean column when generating synthetic data with generate_dataset(). The p_true= parameter controls the probability of generating True values, which is useful for simulating real-world distributions where events may be rare or common (e.g., 5% fraud rate, 80% active users).

By default, True and False are equally likely (p_true=0.5). Setting p_true=0.0 produces all False values, and p_true=1.0 produces all True values.

Parameters

p_true: float = 0.5: Probability of generating True. Default is 0.5 (equal probability). Must be between 0.0 and 1.0.
nullable: bool = False: Whether the column can contain null values. Default is False.
null_probability: float = 0.0: Probability of generating a null value for each row when nullable=True. Must be between 0.0 and 1.0. Default is 0.0.
unique: bool = False: Whether all values must be unique. Default is False. Note that boolean columns can only have 2 unique non-null values, so n must be <= 2 when unique=True (or <= 3 with nullable=True).
generator: Callable[[], Any] | None = None: Custom callable that generates values. When provided, it’s used instead of the other constraints, while unique= and nullable= still apply. The callable should take no arguments and return a single boolean value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.

Returns

BoolField: A boolean field specification that can be passed to Schema().

Raises

ValueError: If p_true is not between 0.0 and 1.0, or if null_probability is not between 0.0 and 1.0.

Examples

The p_true= parameter controls the distribution of True/False values, allowing you to simulate different probabilities:

import pointblank as pb

schema = pb.Schema(
    is_active=pb.bool_field(p_true=0.8),
    is_premium=pb.bool_field(p_true=0.2),
    is_verified=pb.bool_field(),
)

pb.preview(pb.generate_dataset(schema, n=100, seed=23))

	is_active Boolean	is_premium Boolean	is_verified Boolean
PolarsRows100Columns3
1	False	True	True
2	False	False	False
3	True	False	False
4	True	False	True
5	True	False	True
96	True	False	True
97	False	False	True
98	True	False	True
99	True	False	True
100	True	True	True

Optional boolean flags can be simulated by combining nullable=True with null_probability=:

schema = pb.Schema(
    opted_in=pb.bool_field(p_true=0.6),
    has_referral=pb.bool_field(
        p_true=0.3,
        nullable=True, null_probability=0.25,
    ),
)

pb.preview(pb.generate_dataset(schema, n=50, seed=23))

	opted_in Boolean	has_referral Boolean
PolarsRows50Columns2
1	False	False
2	False	False
3	True	None
4	True	False
5	True	None
46	False	None
47	True	None
48	True	True
49	False	False
50	True	False

Boolean fields can be combined with other field types in a realistic schema:

schema = pb.Schema(
    user_id=pb.int_field(min_val=1, max_val=9999, unique=True),
    name=pb.string_field(preset="name"),
    email_verified=pb.bool_field(p_true=0.9),
    is_admin=pb.bool_field(p_true=0.05),
)

pb.preview(pb.generate_dataset(schema, n=30, seed=10))

	user_id Int64	name String	email_verified Boolean	is_admin Boolean
PolarsRows30Columns4
1	9201	Joshua Robinson	True	False
2	5380	Marie Young	True	False
3	6399	Melissa Atkins	False	False
4	623	Paisley Jackson	True	False
5	482	Martha White	True	False
26	4395	Zachary Ramirez	True	False
27	8687	Sarah Gallagher	True	False
28	3867	Kimberly Tran	True	False
29	9008	John Marshall	True	False
30	1786	Linda Garner	True	False

Here, email_verified is True in 24 of the 30 rows and is_admin in 1 of them. These counts are close to, but not exactly, the p_true= values of 0.9 and 0.05, since each value is drawn independently.