*! version 3.0.0 21 Apr 2026

Title

calgen -- Convert an episode-format diary file into calendar format

Syntax

calgen, did(varlist) slotd(#) [dst(#)]

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

slotd(#) slot duration in minutes; required

dst(#) diary start hour on a 24-hour clock; optional, default is 4

Description

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

In an episode file, each row represents a continuous spell of time. In a calendar file, each row represents a fixed time slot such as 10 or 15 minutes.

Calendar files are especially useful for studying behaviour by time of day, producing tempograms or chronograms, and analysing activity within fixed windows such as 18:00 to 20:00.

After running calgen, each diary contains one row per time slot.

Required variables

start must exist and contain the start minute of each episode.

end must exist and contain the end minute of each episode.

The input data must already be in episode format.

Arguments

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

slotd(#) specifies the desired slot duration in minutes.

Common values are 10, 15, and 30. The slot duration must divide 1440 exactly.

Options

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

For example, dst(0) means the diary begins at midnight, dst(4) means it begins at 04:00, and dst(18) means it begins at 18:00.

If omitted, the default is dst(4).

What the command creates

calgen creates a calendar-format file with one row per slot and adds the following variables:

Output

tslot slot number within diary (1 to N)

start start minute of the slot

end end minute of the slot

The number of slots per diary depends on the slot duration. For example, slotd(10) creates 144 slots per diary, and slotd(15) creates 96.

Diary fields from the episode file are repeated across the relevant slots.

How the command works

Each episode is expanded into as many fixed slots as needed to cover its duration.

For example, with slotd(10), an episode from minute 0 to 30 becomes three rows, while an episode from minute 300 to 360 becomes six rows.

The resulting dataset contains evenly spaced time intervals for every diary.

Checks and warnings

calgen checks that start and end exist, that slotd() divides 1440 exactly, and that the episode structure is compatible with the requested slot size.

If the slot size is incompatible with the episode structure, review the source file or choose a different slot duration.

Dataset after running the command

The output becomes a calendar-format file with one row per time slot.

For example, 1 diaries with slotd(10) become 144 rows, while a diaries with slotd(15) become 96 rows.

Examples

Example 1: Convert to a 10-minute calendar file

. use mtus_hef, clear

. calgen, did(hldid persid id) slotd(10) dst(4)

Each diary now contains 144 rows.

Example 2: Convert to a 15-minute calendar file

. calgen, did(pid day) slotd(15) dst(0)

Each diary now contains 96 rows.

Example 3: Build a tempogram

. calgen, did(id) slotd(10)

. gen work = (activity==2)

. collapse (mean) work, by(start)

The resulting series can then be graphed across the day.

Example 4: Analyse an evening window

. calgen, did(id) slotd(10)

. keep if inrange(start, 840, 960)

This keeps slots between 18:00 and 20:00.

Remarks

1. Choose slot size carefully

Use the slot duration closest to the original diary instrument when possible. Very coarse slots may lose detail, while very fine slots may create unnecessarily large files.

2. Calendar files are often larger

Episode files are compact. Calendar files usually contain many more rows because each diary is repeated across all slots.

3. Calendar format is useful for timing analysis

Calendar format is often the easiest structure for studying behaviour at specific moments of the day.

4. Use epigen to reverse the process

If you later want to reconstruct episodes from a calendar file, use epigen.

5. Slot boundaries matter

Results for narrow time windows depend on the slot size chosen. Smaller slots give more precise timing.

Stored results

calgen 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

epigen to convert calendar files into episode files.

timealloc for diary-level summaries from episode files.