*! version 3.0.0 21 Apr 2026

Title

clock2min -- Convert clock-style time variables into minute-of-day start and end

Syntax

clock2min var1 [var2], did(varlist) dst(#) clockt(type)

where var1 is the clock-style start-time variable and var2, if supplied, is the clock-style end-time variable.

did(varlist) variable(s) that uniquely identify each diary; required

dst(#) diary start hour on a 24-hour clock (0 to 23); required

clockt(type) format of the input clock strings: h, hm, or hms; required

Description

clock2min creates the variables start and end in the minute-of-day format used by the time-use commands in this toolkit.

Many diary datasets store times as strings such as "11:30", "04:00:00", or "7". clock2min converts those clock-style variables into numeric minutes measured relative to the diary start time.

This command is especially useful when preparing data for commands such as epigen, epigenx, timealloc, timeallocx, or epicheck.

The command is a wrapper around Stata's built-in date-time conversion functions.

Required variables

The dataset must contain the variables supplied as var1 and, if used, var2.

The data should be sorted or sortable by the diary identifiers in did() and by episode order if var2 is omitted.

Arguments

var1 is a string variable containing the start time of each episode in clock format.

Examples:

"04"

"04:30"

"04:30:15"

var2, if supplied, is a string variable containing the end time of each episode in the same clock format.

If var2 is omitted, end is inferred from the start time of the following episode within diary. The final episode of each diary is assigned end = 1440.

Options

did(varlist) specifies one or more variables that jointly identify each diary uniquely.

dst(#) specifies the diary start hour using an integer from 0 to 23.

Examples:

dst(0) = diary begins at midnight

dst(4) = diary begins at 04:00

dst(18) = diary begins at 18:00

Minute values are measured relative to this diary start time.

clockt(type) specifies the format of the input clock variables.

Allowed values are:

h = hours only (for example "04")

hm = hours and minutes (for example "04:30")

hms = hours, minutes, and seconds (for example "04:30:15")

What the command creates

clock2min creates:

Output

start episode start time in minute-of-day format

end episode end time in minute-of-day format

The created variables receive readable clock-time value labels.

How minute-of-day works

Minute-of-day values are measured from the diary start time given in dst().

For example, with dst(4):

start = 0 means 04:00

start = 60 means 05:00

start = 120 means 06:00

With dst(0), minute 0 corresponds to midnight.

How the command works

clock2min converts the supplied clock strings into internal clock times, adjusts them relative to the diary start time, and expresses the result as minutes from 0 to 1440.

If an observed clock time occurs earlier than the diary start hour, it is treated as belonging to the following calendar day. This allows diaries that cross midnight to be handled correctly.

When var2 is omitted, the command calculates end using the next episode's start time within each diary.

Checks and warnings

clock2min checks that:

- one or two variables have been supplied

- dst() is between 0 and 23

- clockt() is one of h, hm, or hms

If invalid values are supplied, the command stops with an error message.

Dataset after running the command

The dataset remains in its original structure. No observations are added or removed.

The command simply adds or replaces the variables start and end.

Examples

Example 1: Start and end stored separately

. use us2020, clear

. clock2min tustarttim tustoptime, did(tucaseid) dst(4) clockt(hms)

This creates start and end using two clock variables.

Example 2: Only start times available

. clock2min clock_start, did(id) dst(4) clockt(hm)

Here end is inferred from the next episode's start time, and the last episode ends at 1440.

Example 3: Diary begins at midnight

. clock2min stime etime, did(pid day) dst(0) clockt(hm)

Example 4: Inspect created values

. list tustarttim start tustoptime end in 1/5

. list tustarttim start tustoptime end in 1/5, nolabel

The first display shows clock labels; the second shows raw numeric minutes.

Remarks

1. Use the correct clock format

Choose clockt(h), clockt(hm), or clockt(hms) to match the stored strings exactly.

2. Two-variable input is preferable when available

If end times are explicitly recorded, supplying both variables is usually preferable to inferring end.

3. Midnight crossing is handled automatically

Times earlier than the diary start hour are treated as next-day times.

4. Check sorting when inferring end times

If only one variable is supplied, ensure observations are correctly ordered within diary before running the command.

5. Useful first step in harmonisation

Many raw diary files need start/end before other commands can be used. clock2min is often the first preparation step.

Stored results

clock2min does not store results in r() or e(). Results are returned through the created variables.

Author

Juana Lamote de Grignon-Pérez

Centre for Time Use Research (CTUR)

Also see

epigen to create episodes from slot-based calendar files.

timealloc for diary-level summaries once start and end exist.