*! version 3.0.0 21 Apr 2026

Title

epigen -- Create an episode file from a calendar-format diary file

Syntax

epigen varlist, did(varlist) [dst(#) nolabel]

where varlist contains the diary fields that define when a new episode begins.

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

dst(#) diary start hour on a 24-hour clock; required unless nolabel is specified

nolabel do not create clock-time labels or clockst

Description

epigen converts a calendar-format diary file into an episode-format diary file.

In a calendar file, each row usually represents one fixed time slot, such as 10 minutes. In an episode file, consecutive time slots with the same values on selected diary fields are merged into a single episode.

A new episode is created whenever there is a change in one or more of the variables supplied in varlist.

This is useful because episode files are typically more compact and are needed by several downstream commands, including timealloc.

If you are unsure which diary fields you may need later, a good strategy is to first build
a detailed episode file using all available diary fields. You can then simplify or
redefine episodes later if needed.

Required variables

tslot must exist in the data, must be numeric, and must indicate the order of time slots within each diary.

For example, in a diary with 144 ten-minute slots, tslot should run from 1 to 144 within each diary.

If tslot is not present, but the observations are already correctly ordered within diary, create it before running epigen.

Arguments

varlist specifies the diary fields that define the episodes. A new episode is created whenever any of these variables changes value from one slot to the next.

Variables in varlist may be numeric or string.

The current version allows up to 20 variables in varlist.

did(varlist) specifies one or more variables that jointly identify each diary uniquely. Variables may be numeric or string.

Options

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

This option is used to create readable clock-time labels for start and end, and to create the variable clockst.

If nolabel is not specified, then dst() is required.

nolabel suppresses creation of clock-time labels and suppresses the variable clockst.

This is useful when you only need numeric start and end times.

What the command creates

epigen creates one row per episode and adds the following variables:

Output

epnum episode number within diary

start start minute of episode, from 0 to 1439

end end minute of episode, from 1 to 1440

time episode duration in minutes

clockst start time on a 24-hour clock; created unless nolabel is used

The diary fields supplied in varlist are retained in the resulting episode file.

How episode boundaries are defined

Within each diary, epigen compares consecutive time slots across the variables in varlist. Consecutive slots are merged into the same episode only if all supplied variables remain unchanged.

A new episode begins as soon as at least one of those variables changes.

This means that the level of detail in the final episode file depends directly on the variables you include in varlist.

For example, using only activity usually gives broader episodes, while using activity location alone usually gives more detailed episodes.

How timing is calculated

epigen determines the expected number of slots per diary by taking the median of the maximum observed tslot values across diaries. It then calculates slot duration as:

1440 / number of slots

For example, if diaries typically contain 144 slots, slot duration is treated as 10 minutes.

Then:

start = tslot*slotdur - slotdur

end = next episode's start

time = end - start

For the last episode in a diary, end is set to 1440.

Checks and warnings

Before creating episodes, epigen checks that tslot exists and is numeric.

If nolabel is not specified, it also checks that dst() has been supplied and that its value is between 0 and 23.

The command warns if any observations have missing values in the variables listed in did(). Those observations are dropped before episodes are created.

The command also runs tslotcheck, quiet internally.

Dataset after running the command

After running epigen, the file is reduced from one row per time slot to one row per episode.

The output is ordered so that the diary identifiers and newly created episode variables come first, followed by the diary fields used to define episodes.

The original variable tslot is dropped from the final dataset.

Examples

Example 1: Create episodes using one diary field

This creates a new episode each time the activity changes.

. epigen activity, did(uid day) dst(4)

Example 2: Create episodes using several diary fields

This creates a new episode whenever any of the supplied diary fields changes.

. epigen activity location alone, did(uid day) dst(4)

Example 3: Skip clock labels

Use nolabel if you do not need labeled times or clockst.

. epigen activity location, did(uid day) nolabel

Example 4: Calendar file begins at midnight but diary starts at 4 a.m.

Suppose the file is ordered from 00:00 onward, but the diary day actually begins at 04:00. In that case, first rebuild tslot so that slot 1 corresponds to 04:00, then run epigen.

. bysort uid ad4: gen xtslot = _n

. gen tslot = xtslot - 24 if xtslot >= 25

. replace tslot = 120 + xtslot if xtslot < 25

. tslotcheck, did(uid ad4)

. sort uid ad4 tslot

. epigen activity activity2 transport alone partner parent kids, did(uid ad4) dst(4)

Remarks

1. Choose episode-defining variables carefully

The more variables you include in varlist, the more episodes you will usually create. Even small changes in any included field will split an episode.

2. Start with a rich episode file if unsure

If you are uncertain which diary fields will matter later, it is often safer to build a detailed episode file first and simplify later if needed.

3. Slot ordering must be correct

epigen assumes that tslot correctly represents the within-diary order of the time slots. If tslot is wrong, the resulting episodes will also be wrong.

4. dst() affects labels, not episode boundaries

Episode boundaries are determined by tslot and the variables in varlist. The dst() option is used only to label times and create clockst.

5. Input file should contain complete slot sequences

Because slot duration is inferred from the diary structure, it is good practice to check the calendar file first and confirm that diaries have the expected number of slots.

Stored results

epigen does not store results in r() or e(). Results are returned through the transformed dataset.

Author

Juana Lamote de Grignon-Pérez

Centre for Time Use Research (CTUR)

Also see

epigenx to redefine an existing episode file using different episode boundaries.

timealloc for diary-level summaries from episode files.