*! version 1.0.0
help clocktominb

Syntax

clocktominb var1 var2, epnum(string) diaryid(string) diaryst(n)

Description

clocktominb -- takes the string variables containing the start and end time of an episode of activity and creates the variables 'start' and 'end',
which measure the beginning and end of the activity in minutes elapsed since the beginning of the diary, as required by the programs in the timeuse package.
An example of time use files that express activity timings in this format is the American Time Use Survey.
In the original variable containing the start time of the activity, 4:30 am is represented as "04:30:00", whereas in the 'start' and 'end' variables, 4:30 am is represented by the number 30 (assuming the diary starts at 4 am).
However, when inspecting the variables in the data editor, they will still display the time as a clock because the program attaches clock-like value labels, but 'start' and 'end' are numerical.
If only the beginning or the end of the episode of activity is provided in the original dataset, use the programs clocktomins or clocktomine instead.

ATUS datasets have one peculiarity, the end of the last episode of activity reported is not the same as the time at which the diary started -as most time use surveys- but the actual time at which the activity ended.
In case the user is working with a file from ATUS, the program provides a second end variable, 'end_atus' which captures the true end time for the last episode of activity in each diary.
If the file is not an ATUS file, 'end_atus' will probably take the same value as 'end'.

Arguments

var1: variable containing the start time of the activity as a string that looks like a clock that also shows seconds, eg. "04:00:00".

var2: variable containing the end time of the activity as a string that looks like a clock that also shows seconds, eg. "04:00:00".

epnum(string): name of the variable containing the episode number.
It is the variable that indicates the sequence in which the different episodes of activity happen.
If no such variable exists in the dataset but the episodes of activity are ordered, simply create it like this: "bysort diaryid: gen epnum=_n".

diaryid(string): the names of the variable or variables that when considered jointly uniquely identify the diary.

diaryst(n): number that indicates the start time of the diary in a 24 hour system clock, with "0" representing midnight, "4" is 4am, and "18" would be 6pm.

Outcomes

start: start time of the episode expressed as minute of day.
'start' can take values from 0 to 1439. The first episode of the diary should start at minute
0.

end: end time of the episode expressed as minute of day.
'end' can take values from 1 to 1440. The last episode of the diary should end at minute 1440.

Example

The following lines of code load the dataset "atusdiary.dta" and creates the variables 'start', 'end', and 'end_atus' from the string variables included in the dataset.
'start', 'end', and 'end_atus' measure the time at which the activity ends expressed as minute-of-the-day.
"example_atusdiary.dta" is a small dataset with the exact same format as the American Time Use Survey (although with just a few variables).
The variables 'tustarttim' and 'tustoptime' are the variables containing the start and end time of the episode of activity.

. net get timeuse

. use atusdiary, clear

. clocktominb tustarttim tustoptime, diaryid(tucaseid) epnum(tuactivity_n) diaryst(4)

Author

Juana Lamote de Grignon Pérez, Centre for Time Use Research (UCL), juana.lamote@gmail.com

Thanks for citing this software as follows:

Lamote de Grignon, J. (2024). clocktominb: Stata module to convert episode start and end time from string to minute-of-the-day. Available from: https://ideas.repec.org/c/boc/bocode/s459346.html.

Acknowledgments

I am grateful to Elena Mylona and Margarita Vega Rapún for their feedback during the development of the program.