duration_field()

Create a duration column specification for use in a schema.

Usage

duration_field(
    min_duration=None,
    max_duration=None,
    nullable=False,
    null_probability=0.0,
    unique=False,
    generator=None,
)

The duration_field() function defines the constraints and behavior for a duration (timedelta) column when generating synthetic data with generate_dataset(). You can control the duration range with min_duration= and max_duration=, enforce uniqueness with unique=True, and introduce null values with nullable=True and null_probability=.

Duration values are generated uniformly (at second-level resolution) within the specified range. If no range is provided, the default range is 0 seconds to 30 days. Both min_duration= and max_duration= accept datetime.timedelta objects or colon-separated strings in "HH:MM:SS" or "MM:SS" format.

Parameters

min_duration: str | timedelta | None = None: Minimum duration (inclusive). Can be a "HH:MM:SS" or "MM:SS" string, or a datetime.timedelta object. Default is None (defaults to 0 seconds).
max_duration: str | timedelta | None = None: Maximum duration (inclusive). Can be a "HH:MM:SS" or "MM:SS" string, or a datetime.timedelta object. Default is None (defaults to 30 days).
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 duration 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 datetime.timedelta value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.

Returns

DurationField: A duration field specification that can be passed to Schema().

Raises

ValueError: If min_duration is greater than max_duration, or if a duration string cannot be parsed.

Examples

The min_duration= and max_duration= parameters accept timedelta objects for defining duration ranges:

import pointblank as pb
from datetime import timedelta

schema = pb.Schema(
    session_length=pb.duration_field(
        min_duration=timedelta(minutes=5),
        max_duration=timedelta(hours=2),
    ),
    wait_time=pb.duration_field(
        min_duration=timedelta(seconds=30),
        max_duration=timedelta(minutes=15),
    ),
)

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

	session_length Duration	wait_time Duration
PolarsRows100Columns2
1	1:36:08	0:08:55
2	1:25:07	0:04:42
3	0:10:20	0:11:09
4	0:08:03	0:05:40
5	1:33:16	0:04:30
96	0:23:10	0:10:55
97	1:31:24	0:03:15
98	1:11:52	0:07:40
99	1:13:05	0:09:55
100	1:58:22	0:10:56

Colon-separated strings can also be used for quick duration definitions:

schema = pb.Schema(
    call_duration=pb.duration_field(min_duration="0:01:00", max_duration="1:30:00"),
    break_time=pb.duration_field(min_duration="0:05:00", max_duration="0:30:00"),
)

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

	call_duration Duration	break_time Duration
PolarsRows30Columns2
1	0:42:46	0:07:00
2	1:27:53	0:23:55
3	0:33:12	0:29:15
4	0:29:35	0:05:33
5	0:30:59	0:08:32
26	0:33:01	0:12:12
27	1:27:59	0:18:13
28	0:56:46	0:19:53
29	0:37:15	0:17:08
30	0:52:53	0:22:33

Optional durations can be created with nullable=True, and duration fields work well alongside other field types:

schema = pb.Schema(
    task_id=pb.int_field(min_val=1, max_val=500, unique=True),
    time_spent=pb.duration_field(
        min_duration=timedelta(minutes=1),
        max_duration=timedelta(hours=8),
    ),
    overtime=pb.duration_field(
        min_duration=timedelta(0),
        max_duration=timedelta(hours=4),
        nullable=True, null_probability=0.6,
    ),
)

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

	task_id Int64	time_spent Duration	overtime Duration
PolarsRows30Columns3
1	126	4:11:34	None
2	314	5:02:27	2:24:24
3	87	6:06:30	None
4	40	1:51:03	None
5	340	4:43:48	2:27:00
26	352	7:07:54	None
27	252	5:24:11	None
28	286	1:56:47	2:44:22
29	9	6:03:07	0:27:10
30	30	2:18:33	None

The time_spent values range from one minute to eight hours, while the overtime column is missing in most rows (20 of 30 here, in line with the null_probability= of 0.6). Both columns have a duration dtype, so they can take part in arithmetic with dates and datetimes.