Create a date column specification for use in a schema.
Usage
The date_field() function defines the constraints and behavior for a date column when generating synthetic data with generate_dataset(). You can control the date range with min_date= and max_date=, enforce uniqueness with unique=True, and introduce null values with nullable=True and null_probability=.
Dates are generated uniformly within the specified range. If no range is provided, the default range is 2000-01-01 to 2030-12-31. Both min_date= and max_date= accept either datetime.date objects or ISO 8601 date strings (e.g., "2024-06-15").
min_date: str | date | None = NoneMinimum date (inclusive). Can be an ISO format string (e.g., "2020-01-01") or a datetime.date object. Default is None (defaults to 2000-01-01).
max_date: str | date | None = NoneMaximum date (inclusive). Can be an ISO format string (e.g., "2024-12-31") or a datetime.date object. Default is None (defaults to 2030-12-31).
nullable: bool = FalseWhether the column can contain null values. Default is False.
null_probability: float = 0.0Probability 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 = FalseWhether all values must be unique. Default is False. When True, the generator will retry until it produces n distinct dates. Ensure the date range is large enough to accommodate the requested number of unique dates.
generator: Callable[[], Any] | None = Noneunique= and nullable= still apply. The callable should take no arguments and return a single datetime.date value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.
DateField ValueErrormin_date is later than max_date, or if a date string cannot be parsed.
The min_date= and max_date= parameters accept datetime.date objects to define date ranges:
import pointblank as pb
from datetime import date
schema = pb.Schema(
birth_date=pb.date_field(
min_date=date(1960, 1, 1),
max_date=date(2005, 12, 31),
),
hire_date=pb.date_field(
min_date=date(2020, 1, 1),
max_date=date(2024, 12, 31),
),
)
pb.preview(pb.generate_dataset(schema, n=100, seed=23))PolarsRows100Columns2 |
||
birth_date Date |
hire_date Date |
|
|---|---|---|
| 1 | 1983-05-26 | 2023-12-11 |
| 2 | 1987-05-07 | 2024-02-27 |
| 3 | 2002-04-20 | 2022-06-14 |
| 4 | 1978-09-08 | 2023-11-03 |
| 5 | 1973-03-31 | 2022-03-09 |
| 96 | 1999-10-20 | 2022-04-15 |
| 97 | 1982-10-12 | 2023-01-15 |
| 98 | 1964-05-24 | 2022-07-25 |
| 99 | 1986-08-27 | 2020-03-05 |
| 100 | 1963-08-21 | 2022-10-06 |
For convenience, ISO format strings can be used instead of date objects:
schema = pb.Schema(
event_date=pb.date_field(min_date="2024-01-01", max_date="2024-12-31"),
signup_date=pb.date_field(min_date="2023-06-01", max_date="2024-06-01"),
)
pb.preview(pb.generate_dataset(schema, n=50, seed=23))PolarsRows50Columns2 |
||
event_date Date |
signup_date Date |
|
|---|---|---|
| 1 | 2024-06-28 | 2024-05-07 |
| 2 | 2024-08-11 | 2023-07-17 |
| 3 | 2024-02-06 | 2023-12-16 |
| 4 | 2024-10-08 | 2024-02-09 |
| 5 | 2024-12-29 | 2023-10-13 |
| 46 | 2024-04-25 | 2024-05-06 |
| 47 | 2024-09-27 | 2023-12-25 |
| 48 | 2024-05-04 | 2023-09-04 |
| 49 | 2024-12-23 | 2024-04-27 |
| 50 | 2024-03-13 | 2023-06-13 |
We can introduce missing dates with nullable=True and enforce distinct values using unique=True:
schema = pb.Schema(
order_date=pb.date_field(
min_date="2024-01-01", max_date="2024-03-31",
unique=True,
),
cancel_date=pb.date_field(
min_date="2024-01-01", max_date="2024-12-31",
nullable=True, null_probability=0.5,
),
)
pb.preview(pb.generate_dataset(schema, n=30, seed=7))PolarsRows30Columns2 |
||
order_date Date |
cancel_date Date |
|
|---|---|---|
| 1 | 2024-01-11 | 2024-08-27 |
| 2 | 2024-02-06 | None |
| 3 | 2024-03-15 | None |
| 4 | 2024-03-07 | None |
| 5 | 2024-01-03 | 2024-08-14 |
| 26 | 2024-02-26 | 2024-11-09 |
| 27 | 2024-03-10 | None |
| 28 | 2024-01-04 | None |
| 29 | 2024-03-13 | 2024-05-10 |
| 30 | 2024-01-12 | 2024-03-26 |
All 30 order_date values are distinct, which is possible because the first quarter of 2024 has 91 days to choose from. About half of the cancel_date values are missing (20 of 30 here). Each column is generated independently, so a few cancellation dates fall before the order date in the same row.