{smcl}
{* 04jun2007}{...}
{hline}
help for {hi:ntimeofday}{right:(SJ6-1: dm0018)}
{hline}

{title:Generate numeric time-of-day variables from string time-of-day variables}

{p 8 17 2} 
{cmd:ntimeofday}
{it:strvarlist}
{ifin}
{cmd:,}
{cmdab:g:enerate(}{it:newvarlist}{cmd:)} 
{cmdab:n:umeric(}{it:units}{cmd:)} 
{cmdab:s:tring(}{it:specification}{cmd:)} 
[{cmd:am(}{it:am_strings}{cmd:)}
{cmd:pm(}{it:pm_strings}{cmd:)}
{cmdab:c:end(}{it:century_end}{cmd:)} 
{cmdab:e:xtremes}
{cmdab:p:arse(}{it:parse_strings}{cmd:)}
{cmdab:t:ype(}{it:variable_type}{cmd:)}] 


{title:Description} 

{p 4 4 2} 
{cmd:ntimeofday} takes one or more string variables indicating times of
day, or dates including times of day, or timings, and generates
corresponding numeric variables giving those times, date-times, or
timings in specified units. All the string variables must share the same
specification of time or date elements.  Depending on user choice, the
resulting variables will have units that are days, hours, minutes, or
seconds.  Either all numeric variables requested will be generated or
none will, whenever any error arises in processing. The list of new
variable names will be returned in {cmd:r(varlist)}. 


{title:Options} 

{p 4 8 2}
{cmd:generate(}{it:newvarlist}{cmd:)} specifies a list of new names for the
new numeric variables. There must be as many new names as there are existing
composite string variables. {cmd:generate()} is required. 

{p 4 8 2}
{cmd:numeric(}{it:units}{cmd:)} indicates units for the new numeric variables.
One of {cmd:days}, {cmd:hours} (or {cmd:hrs}), {cmd:minutes}, or {cmd:seconds}
must be specified but may be abbreviated in any way. {cmd:numeric()} is
required.  

{p 4 8 2} 
{cmd:string(}{it:specification}{cmd:)} specifies the sequence of time or date
elements followed in each of the string variables supplied.  Each element
specified must occur just once in any value. The minimum requirement is one
element.  Elements should be separated by spaces, punctuation, or other
nonnumeric characters.  {cmd:string()} is required. 
See also {cmd:parse()} option below.

{p 8 8 2} 
Elements may be specified using the following terms from groups (1), (2),
or (3). Minimal abbreviations are indicated.  Note the limitations
below.  

{space 8}(1)
{space 8}{cmdab:ym:d}{col 32}years, months, days
{space 8}{cmdab:yd:m}{col 32}years, days, months 
{space 8}{cmdab:my:d}{col 32}months, years, days
{space 8}{cmdab:md:y}{col 32}months, days, years 
{space 8}{cmdab:dy:m}{col 32}days, years, months
{space 8}{cmdab:dm:y}{col 32}days, months, years

{p 8 8 2}
At most, one of this group may be specified.  Each group indicates
dates to be interpreted with 
{cmd:date("}{it:date}{cmd:", "}{it:element}{cmd:")}.  
See {helpb date()} and also {cmd:cend()} option below. 

{space 8}(2)
{space 8}{cmdab:ye:ars} or {cmdab:yr:s} {col 32}years
{space 8}{cmdab:mo:nths}                {col 32}months
{space 8}{cmdab:da:ys}                  {col 32}(numeric) days

{p 8 8 2}
None of group (1) may be combined with any of {cmd:years}, {cmd:yrs},
{cmd:months}, or {cmd:days} from group (2). 

{p 8 8 2}
The following combinations of {cmd:years}, {cmd:months}, and {cmd:days}
elements are regarded as invalid and valid. 

{space 8}{cmd:years}                  invalid
{space 8}{cmd:years} and {cmd:months}       invalid 
{space 8}{cmd:years}, {cmd:months}, {cmd:days}    valid    (a)
{space 8}{cmd:months}, {cmd:days}           invalid 
{space 8}{cmd:months}                 invalid 
{space 8}{cmd:days}                   valid    (b)  
{space 8}{cmd:years}, {cmd:days}            valid    (c) 
{space 8}(none)                 valid 

{pmore}
Given type (a), the elements are used to construct Stata daily
dates.  If the {cmd:months} element is a string, it is interpreted first
using {cmd:month(}{cmd:date}{cmd:("}{it:month} {cmd:1 1960", "mdy"))}.  Then 
{helpb mdy()} is used.  Invalid or unintelligible dates will result in missing
values.{p_end}

{pmore}
Given type (b), the {cmd:days} specified are treated literally,
that is to say, numerically.

{pmore}
Given type (c), the {cmd:days} specified are treated as day of
year (e.g., 1 = 1 January). Thus the elements are interpreted as Stata
daily dates using  
{cmd:mdy(1,1,}{it:year}{cmd:) + (}{it:day} {cmd:- 1)}. 
If day of year is not in the range 1 ... 366, allowing for leap years,
an error message is generated.{p_end}

{space 8}(3)
{space 8}{cmdab:h:ours} or {cmdab:h:rs} {col 32}hours
{space 8}{cmdab:mi:nutes}               {col 32}minutes
{space 8}{cmdab:s:econds}               {col 32}seconds

{p 4 8 2}
{cmd:am(}{it:am_strings}{cmd:)} and {cmd:pm(}{pm_strings}{cmd:)} specify any
text used in the string variables to indicate whether times are a.m. or p.m.
If two or more different text indicators are used, all should be specified.
Thus {cmd:am(am)} specifies that at least some times a.m. are flagged with the
text ``am''.  Times a.m. are naturally not adjusted, but the use of such
indicators should be declared.  Similarly, {cmd:pm(pm p.m.)}
specifies that at least some times p.m. are flagged with one of those
indicators. Times p.m. are adjusted by adding 12 to hours from 1 to 11.  A
p.m. time given as (say) {cmd:23:45 pm} will not therefore be adjusted. Again
the use of such indicators should be declared. 

{p 4 8 2}
{cmd:cend(}{it:century_end}{cmd:)} specifies a century-end to apply to
two-digit years whenever the element is one of  
{cmd:ymd}, 
{cmd:ydm}, 
{cmd:myd}, 
{cmd:mdy}, 
{cmd:dym}, or 
{cmd:dmy},
and such dates are to be interpreted with 
{cmd:date("}{it:date}{cmd:", "}{it:element}{cmd:", }{it:century_end}{cmd:)}. 
See {helpb date()}. 

{p 4 8 2}
{cmd:extremes} requests a display of the minimum and maximum of each
date element. {cmd:ntimeofday} performs some checks, and invalid or
unintelligible dates will yield missing values.  However, the user is
advised to apply more, drawing upon knowledge of what the data should
be. In particular, as far as {cmd:ntimeofday} is concerned, the number
of hours, minutes, and seconds may reasonably be or exceed 24, 60, and 60,
respectively, depending on what is supplied. Inspection of extremes is
thus advised. 

{p 4 8 2}
{cmd:parse(}{it:parse_strings}{cmd:)} supplies parse strings, that is,
separators, to {helpb split}, which divides string variables into components
before they are reassembled.  By default, {cmd:ntimeofday} causes {cmd:split}
to parse on spaces and colons. 

{p 4 8 2}
{cmd:type(}{it:variable_type}{cmd:)} specifies that numeric variables
be generated as a specified variable type. By default,
variables are created {cmd:double}s in {cmd:ntimeofday}.  {cmd:type()} is a
rarely used option. Specifying {cmd:type(long)} will result in loss
of information whenever the times or dates contain fractional parts in the
units specified. 


{title:Remarks} 

{p 4 4 2}
A time of day might look like 12:34:56. A date with time of day
might look like 21 January 2006 12:34:56. In these examples, it is
clear that the elements are in sequence hours, minutes, and seconds in the
first case, and day, month, year, hours, minutes, and seconds in the second
case. A timing could be 12h 34m 56s, indicating that some task or
state lasted 12 hours 34 minutes 56 seconds. As far as {cmd:ntimeofday} is
concerned, there is no difference between times of day and timings; the
distinction is in the user's knowledge. 

{p 4 4 2}
The examples 8/7/1977 12:34 and 12:34 indicate that matters
are not always so clear-cut. Does 8/7 mean July 8 or August 7?  Does
12:34 mean hours and minutes or minutes and seconds? Thus, in general,
the user must specify what each element is, as {cmd:ntimeofday} cannot
determine by itself. 

{p 4 4 2} 
{cmd:ntimeofday} neither ignores nor allows for indicators of time zones
(e.g., CET) or days of the week (e.g., Mon). These should be
removed first, say, with {helpb subinstr()}. 

{p 4 4 2} 
{cmd:ntimeofday} does not support run-together dates, such as
20060121, or run-together times, such as 1234.  For an official
comment on how to tackle run-together dates, see
{browse "http://www.stata.com/support/faqs/data/dateseq.html":http://www.stata.com/support/faqs/data/dateseq.html}
and for a user-written program, see {stata ssc desc todate:ssc desc todate}. 

{p 4 4 2}
{cmd:ntimeofday} makes no adjustments for leap seconds or other
astronomical subtleties. Each day in a year is presumed to have 24
hours, each being 60 minutes, and each minute in turn being 60 seconds. 


{title:Examples} 

{p 4 4 2}
Suppose that a typical date-time is 21 Jan 2006 12:34:56. Then specify
{cmd:string(day mo yr h mi s)}. No arguments need be supplied to
{cmd:parse()} as the separators of space and colon are its default. 

{p 8 12 2}{cmd:. ntimeofday datetime, gen(ndatetime) s(day mo yr h mi s) n(day)}

{p 4 4 2}
Suppose that a typical date-time is 21jan06 12:34:56. Then specify
{cmd:string(dmy h mi s) cend(2050)}. Again no arguments need be
supplied to {cmd:parse()}, as the separators of space and colon are its
default. 

{p 8 12 2}{cmd:. ntimeofday datetime, gen(ndatetime) s(dmy h mi s) n(day) cend(2050)}

{p 4 4 2}Suppose that timings are specified as 12h 34m 56s. Then 
specify {cmd:string(h mi s)}. The separators here are {cmd:parse(h m s)}.
{cmd:split} automatically trims the remaining spaces. We also ask 
for a display of {cmd:extremes}. 

{p 8 12 2}{cmd:. ntimeofday timing, gen(ntiming) s(h mi s) n(day) parse(h m s) extremes}


{title:Author}

{p 4 4 2}Nicholas J. Cox, Durham University, UK{break}
         n.j.cox@durham.ac.uk


{title:Acknowledgments}

{p 4 4 2}
Kit Baum, William Gould, and Vince Wiggins produced programs or comments that
were helpful in identifying user needs and possible solutions. 


{title:Also see}

{p 4 13 2}
Online:  {helpb stimeofday}, {helpb split}, {helpb date()}, 
{helpb mdy()}, {helpb subinstr()}, {helpb todate} (if installed) 
{p_end}