Skip to main content

time_field()

Create a time column specification for use in a schema.

Usage

Source

time_field(
    min_time=None,
    max_time=None,
    nullable=False,
    null_probability=0.0,
    unique=False,
    generator=None,
)

The time_field() function defines the constraints and behavior for a time-of-day column when generating synthetic data with generate_dataset(). You can control the time range with min_time= and max_time=, enforce uniqueness with unique=True, and introduce null values with nullable=True and null_probability=.

Time values are generated uniformly (at second-level resolution) within the specified range. If no range is provided, the default range is 00:00:00 to 23:59:59. Both min_time= and max_time= accept datetime.time objects or ISO format time strings (e.g., "09:30:00"). The column that generate_dataset() creates holds datetime.time values: a Time column in Polars, and an object column in pandas (which has no time dtype).

Parameters

min_time: str | time | None = None

Minimum time (inclusive). Can be an ISO format string (e.g., "08:00:00") or a datetime.time object. Default is None (defaults to 00:00:00).

max_time: str | time | None = None

Maximum time (inclusive). Can be an ISO format string (e.g., "17:30:00") or a datetime.time object. Default is None (defaults to 23:59:59).

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. With second-level resolution within a time range, uniqueness is feasible for moderate dataset sizes.

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 value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.

Returns

TimeField
A time field specification that can be passed to Schema().

Raises

ValueError
If min_time is later than max_time, or if a time string cannot be parsed.

Examples

The min_time= and max_time= parameters accept datetime.time objects, making it easy to define business-hours ranges:

import pointblank as pb
from datetime import time

schema = pb.Schema(
    start_time=pb.time_field(
        min_time=time(9, 0, 0),
        max_time=time(12, 0, 0),
    ),
    end_time=pb.time_field(
        min_time=time(13, 0, 0),
        max_time=time(17, 0, 0),
    ),
)

pb.preview(pb.generate_dataset(schema, n=100, seed=23))
PolarsRows100Columns2
start_time
Time
end_time
Time
1 09:33:30 16:07:53
2 10:30:01 15:38:28
3 11:52:49 16:18:39
4 10:20:55 14:52:47
5 09:54:28 16:04:02
96 09:57:08 16:43:44
97 11:18:21 14:37:24
98 10:05:24 14:13:00
99 10:48:11 14:24:35
100 10:04:47 16:36:16

ISO format strings can also be used for convenience:

schema = pb.Schema(
    login_time=pb.time_field(min_time="06:00:00", max_time="23:59:59"),
    alarm_time=pb.time_field(min_time="05:00:00", max_time="09:00:00"),
)

pb.preview(pb.generate_dataset(schema, n=30, seed=23))
PolarsRows30Columns2
login_time
Time
alarm_time
Time
1 12:14:22 05:40:14
2 18:51:03 08:03:57
3 23:33:02 05:46:05
4 12:05:09 05:52:36
5 16:46:16 08:18:50
26 14:23:20 06:46:04
27 15:21:40 05:40:46
28 13:20:58 05:48:26
29 13:36:16 07:26:45
30 06:56:22 08:16:30

It’s possible to introduce optional time values with nullable=True and combine them with other field types:

schema = pb.Schema(
    employee_id=pb.int_field(min_val=100, max_val=999, unique=True),
    check_in=pb.time_field(min_time="07:00:00", max_time="10:00:00"),
    check_out=pb.time_field(
        min_time="16:00:00", max_time="20:00:00",
        nullable=True, null_probability=0.15,
    ),
)

pb.preview(pb.generate_dataset(schema, n=30, seed=7))
PolarsRows30Columns3
employee_id
Int64
check_in
Time
check_out
Time
1 214 07:10:21 17:38:42
2 470 09:56:57 17:53:38
3 439 07:23:59 19:24:20
4 732 08:12:40 16:47:22
5 384 08:10:25 None
26 589 07:37:17 18:27:40
27 729 07:06:01 19:17:30
28 466 07:14:24 None
29 629 07:36:53 17:11:09
30 631 08:14:52 None

Every check_in time falls in the morning window and every non-missing check_out time in the late afternoon or evening one, with 7 of the 30 check_out values missing. The employee_id values are distinct three-digit numbers.