*! version 3.0.0 21 Apr 2026

Title

epitrans -- Transform wide-interval diary rows into standard episode format

Syntax

epitrans actvar, did(varlist) sim(varname) napi(#) [dur(varname)]

actvar activity variable to be transformed; required

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

sim(varname) simultaneity flag (1 = simultaneous, 0 = sequential); required

napi(#) maximum number of activity layers to create (2 to 6); required

dur(varname) within-slot duration variable for unequal sequential splits; optional

Description

epitrans restructures data from wide-interval diary formats, where multiple activities are listed in separate rows sharing the same time interval.

These formats are common in some surveys where respondents report several activities within a broad slot (for example 30 minutes or 1 hour), and the raw file stores one row per listed activity rather than one row per final episode.

epitrans converts this structure into a standard episode-format file with clear start and end times and layered activity fields such as primary, secondary, and tertiary activities.

Sequential activities within the same slot are converted into consecutive non-overlapping sub-episodes. Simultaneous activities are consolidated into a single time window with multiple activity layers.

Required variables

start must exist and contain the start minute of the interval or episode.

end must exist and contain the end minute of the interval or episode.

The input data may already be in episode-style rows or may come from fixed slots converted into start/end using clock2min or similar preparation.

Arguments

actvar is the activity variable. It may be numeric or string.

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

sim(varname) specifies the simultaneity flag.

Expected coding is:

1 = simultaneous activity

0 = sequential activity

napi(#) specifies the maximum number of activity layers to retain in the output. Allowed values are from 2 to 6.

dur(varname) specifies a numeric duration variable containing within-slot durations for sequential activities.

When supplied, these durations are used instead of equal splitting for sequential activities. Durations attached to simultaneous rows are ignored.

What the command creates

epitrans transforms the data into an episode-format file and creates standard layered activity variables:

Output

__pri primary activity

__sec secondary activity

__ter tertiary activity

__quat quaternary activity

__fif fifth activity layer

__six sixth activity layer

Only the layers required by napi() are kept.

The original activity variable supplied to epitrans is removed and replaced by these standardised activity layers.

How the transformation works

Within each diary and time interval, epitrans groups rows that share the same start/end boundaries.

Then:

If all activities are sequential
The interval is split into consecutive sub-episodes.

If all activities are simultaneous
The interval remains one episode, with activities stored across layers.

If a mixture is present
Sequential rows are laid out as separate episodes, while simultaneous rows are layered within the relevant interval according to row order.

Incoming row order matters. The command respects the order of rows when deciding sequence and activity priority.

How duration splitting works

By default, sequential activities sharing the same interval receive equal durations.

If equal division leaves remainder minutes, the earliest created sub-episode(s) receive the extra minute(s) so that the total duration matches the original interval exactly.

If dur() is supplied, those durations are used for sequential activities instead.

Checks and warnings

epitrans checks that:

- start and end exist

- napi() is between 2 and 6

- required variables are present

The command also reports summary tables describing the transformed overlap blocks.

Dataset after running the command

The dataset remains in episode format, but with corrected timing and standardised activity layers.

The number of rows may increase or decrease depending on how many intervals are split or consolidated.

Examples

Example 1: Basic transformation

. epitrans act, did(hid pid) sim(simult) napi(3)

Creates primary, secondary, and tertiary layers.

Example 2: Use recorded unequal durations

. epitrans act, did(id) sim(sim) napi(2) dur(durmins)

Uses durmins to split sequential activities within intervals.

Example 3: Check result afterward

. epicheck, did(hid pid)

Useful to confirm the transformed file is structurally valid.

Remarks

1. Sort order matters

Before running epitrans, sort carefully by diary identifier, then by interval (start/end), and then by any within-slot priority variable if one exists.

2. Use a major-activity indicator when available

If the source data indicate which activity is the main one, sort so that the main activity appears first within each block.

3. Choose napi() realistically

Most datasets only require 2 or 3 layers. Larger values retain more simultaneous activities but create wider files.

4. Equal splitting is a fallback

If real within-slot durations are available, use dur() whenever possible.

5. Good harmonisation workflow

A common sequence is:

raw file -> clock2min -> epitrans -> epicheck -> analysis

Stored results

epitrans does not store results in r() or e(). Results are returned through the transformed dataset and printed summaries.

Author

Juana Lamote de Grignon-Pérez

Centre for Time Use Research (CTUR)

Also see

epicheck for diagnosing structural issues in episode files.

clock2min for creating start and end from clock-style variables.