*! version 3.0.0 21 Apr 2026

Title

epicheck -- Diagnose structural problems in episode-format diary files

Syntax

epicheck, did(varlist) [quiet]

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

quiet suppress output when no issues are detected

Description

epicheck is a diagnostic command for episode-format diary files.

Given a diary identifier and the variables start and end, it scans each diary for
several types of structural problems that commonly arise in episode data.
These include overlaps, gaps, zero-length episodes, and missing time boundaries.

The command is intended as a quality-checking step before analysis. Problems detected
by epicheck should usually be investigated and, where appropriate, corrected
before proceeding. In many workflows, these issues can later be addressed using a
repair command such as epifix.

A related command, tslotcheck, performs analogous checks on calendar-format files.

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 dataset should already be in episode format, with one row per episode.

Arguments

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

Option

quiet suppresses output when no issues are detected.

If issues are found, the report is still printed even when quiet is specified.

Issues checked

epicheck checks for the following eight issue types:

1. Full overlap
Two or more episodes within a diary have the same start and end times.

2. Nested episode
One episode fully contains the next episode.

3. Partial overlap
Two consecutive episodes overlap in time without complete containment.

4. Gap at min 0
The first episode of a diary does not begin at minute 0.

5. Gap at end of diary
The final episode of a diary ends before minute 1440.

6. Gap between episodes
A positive gap exists between consecutive episodes.

7. Row with start==end
An episode has zero duration.

8. Row with start==.|end==.
At least one of start or end is missing.

What the command creates

When issues are detected, epicheck creates episode-level and diary-level flag variables in the dataset.

Output variables

__flag_case episode-level issue code: 0 = no issue, 1 to 8 = issue type

__flag_diary diary-level flag: 1 if the diary contains any issue

__flag_diary_1 diary contains at least one full overlap

__flag_diary_2 diary contains at least one nested episode

__flag_diary_3 diary contains at least one partial overlap

__flag_diary_4 diary contains a gap at the beginning

__flag_diary_5 diary contains a gap at the end

__flag_diary_6 diary contains a gap between episodes

__flag_diary_7 diary contains at least one zero-length episode

__flag_diary_8 diary contains at least one row with missing start or end

If no issues are detected, these flag variables are dropped before the command finishes.

How issue coding works

Each episode is assigned at most one value in __flag_case. If a row could qualify for more than one issue type, the command applies the following priority order:

8 > 7 > 1 > 2 > 3 > 4 > 5 > 6

This means, for example, that a row with missing start or end is classified as issue 8 even if other problems would also apply.

How missing values are handled

Rows with missing values in one or more variables listed in did() are not dropped from the dataset. However, they are ignored during structural issue detection, and the command reports how many such rows were found.

Rows with missing start or end are kept in the data and are classified as issue 8 in the final output.

Output in the Results window

If no issues are detected, epicheck prints:

No issues detected.

Otherwise, it prints a summary table showing: the number of flagged rows (Cases), number of diaries affected (Diaries), and
percentage of diaries affected

A total row is shown at the bottom of the table.

Dataset after running the command

epicheck does not reshape or collapse the dataset. The file remains at the episode level.

The command is diagnostic: it inspects the data, reports issues, and adds flag variables when needed.

Examples

Example 1: Basic episode check

. use mtus_hef, clear

. epicheck, did(hldid persid id)

If the file is structurally sound, the command reports that no issues were detected.

Example 2: Quiet mode

. epicheck, did(hldid persid id) quiet

This suppresses output only when no issues are present.

Example 3: Investigate flagged rows

. epicheck, did(hldid persid id)

. tab __flag_case

. list hldid persid id start end if __flag_case>0

This lets you inspect the problematic rows directly.

Remarks

1. Run before analysis

It is good practice to run epicheck before commands that rely on structurally valid episode timing.

2. Flags are diagnostic, not corrections

epicheck identifies problems but does not repair them. Use the flags to inspect the data or pass the file to a repair workflow.

3. Missing diary identifiers are treated separately

Rows with missing values in did() are not used in the structural checks, because they cannot be assigned reliably to a diary.

4. Zero-length and missing-bound rows are preserved

Unlike some structural checks that work on temporary filtered copies internally, the final output restores these rows and flags them in the original dataset.

5. No flag variables remain if the file is clean

If the command finds no issues at all, the flag variables are removed before exit.

Stored results

epicheck does not store results in r() or e(). Results are returned through the report and, when relevant, through the created flag variables.

Author

Juana Lamote de Grignon-Pérez

Centre for Time Use Research (CTUR)

Also see

epifix for repairing structural issues in episode files.

tslotcheck for analogous checks in calendar-format files.