help numdate

Title

numdate -- Generate numeric date-time variable

Syntax

numdate datetimetype newdatevar = varlist [if] [in],

pattern(pattern)

[ dryrun format(format) topyear(topyear)
varlabel(variable label) ]

Description

numdate is for generating a new Stata numeric date-time variable
newdatevar from one or more existing variables varlist containing
date or date-time or time information.

The subcommand datetimetype is required and should be one of

clock
Clock
daily
date (a synonym for daily)
weekly
monthly
quarterly
halfyearly or
yearly

(any abbreviation is allowed, down to single letters)

or alternatively one of

tc
tC
td
tw
tm
tq
th or
ty.

As specified to numdate, varlist may be string or numeric. For
example, it could be a single string variable containing values
indicating daily dates like "2015Mar28" or quarterly dates like
"2015Q2". Or, it could be a single numeric variable containing
integers such as 20150328 which are to be parsed (in this case) as
daily dates. Or, it could be two or more variables, say three variables
indicating day, month, and year for daily dates.

Whenever any variable within varlist is numeric, its contents are
treated by numdate on the fly as string values.

Remarks

Use of numdate requires understanding of how Stata holds dates and
times: see the help for datetime. A brief summary follows.

With the exception of calendar years, Stata records dates and date-times
with origin 0 as the start of 1960. For example, for daily dates 0 is 1
January 1960 and 42 is 12 February 1960; for monthly dates 0 is January
1960 and 42 is July 1963; for quarterly dates 0 is the first quarter of
1960 and 42 is the third quarter of 1970. Using numeric variables to
hold dates makes it very easy to sort observations in date order and to
calculate differences between dates. Using what is admittedly an
arbitrary convention is not a real problem for tables or graphs or other
output, as dates can and should be assigned display formats that make
sense. But given Stata's convention of origin at the start of 1960, it is
often necessary to map variables containing date or time data in other
form to Stata's numeric date-time variables.

numdate does this, and more. By default it applies a minimal
appropriate display format. It also automatically generates tc
(clock) and tC (Clock) variables as double, as
is necessary to maintain precision. It also allows users a dry run, to
test assumptions about the structure of the data.

People interested in weekly dates may be best advised to record weeks in
terms of some convenient daily dates that define them, say their
beginnings, ends, or middles. For detailed discussion, see Cox (2010,
2012a, 2012b).

For the converse problem of generating a string variable containing date
information, consider using generate sdatevar
= string(newdatevar, "date_format") or
alternatively tostring with date format explicit.

More remarks: What if numdate disappoints?

When numdate works as you expect, you can be happy. When it does not,
then you need to know more about how it should work and what else you can do.

The main idea of numdate is to serve as a wrapper for whichever function
out of

clock()
Clock()
daily()
weekly()
monthly()
quarterly()
halfyearly() or
yearly()

is appropriate for generating a new date variable. However, these functions are not equally smart. Thus, note that for example

. di monthly("20-09-17 11:22:33", "DM20Yhms")

just yields missing, as monthly()
is not smart enough to ignore irrelevant detail. Short of adding work-arounds,
this can be considered a limitation of numdate.

Experience is that this bites most often with generation of coarse dates from fine information. The positive advice to to use convdate, part of the
same package. The following examples illustrates some technique.

. clear

. set obs 1

. gen sandbox = "20-09-17 11:22:33"

. numdate clock call_end_c = sandbox, pattern(DM20Yhms) varlabel("Time of Call closure")

. convdate daily call_end_d = call_end_c, varlabel("Date of Call closure")

. convdate monthly call_end_m = call_end_c, varlabel("Month/Year of Call closure")

. convdate yearly call_end_y = call_end_c, varlabel("Year of Call closure")

In short, consider using numdate to generate the first date variable and
then convdate to convert that to other dates.

Options

pattern() specifies a pattern indicating the date-time elements of
date or date-time values. It is a required option. Details here are
based on the help for datetime translation.

The pattern specifies the order of the date and time components and is
a string composed of a sequence of these elements:

Code | Meaning
------+

Y | 4-digit year
19Y | 2-digit year to be interpreted as 19xx
20Y | 2-digit year to be interpreted as 20xx
H | half-year number (half-yearly dates only)
Q | quarter number (quarterly dates only)
M | month
W | week number (weekly dates only)
D | day within month
|
h | hour of day
m | minutes within hour
s | seconds within minute
|
# | ignore one element
------+

For dates from weekly to half-yearly, a pair of numbers to be translated -
one giving the year and the other the week, month, quarter or half-year -
shoud ideally be separated by a space or punctuation. Note that symbols such as
w, m, q, or h are acceptable punctuation. Whenever
varlist consists of two or more variables, numdate respects this
automatically by combining values from different variables together with
intervening spaces. Otherwise no extra characters are allowed.

For dates from weekly to half-yearly that are run together, such as 20153 or
"20153", an attempt is made to parse into year and other parts. It is
especially advisable to use the dryrun option to check whether the
parsing was done correctly.

For clock and daily dates or date-times, blanks are also allowed in pattern, which
can make the pattern easier to read, but they otherwise have no
significance.

Examples of patterns include

"MDY" varlist
contains month, day, and year, in that order.

"MD19Y" means the same as "MDY" except that
varlist may contain two-digit years, and when it does,
they are to be treated as if they are 4-digit years beginning with 19.

"MDYhms" varlist
contains month, day, year, hour, minute, and second, in that order.

"MDY hms" means the same as "MDYhms"; the blank has no
meaning.

"MDY#hms" means that one element between the year and
the hour is to be ignored. For example, varlist contains values like
"1-1-2010 at 15:23:17" or values like "1-1-2010 at 3:23:17 PM".

dryrun indicates that results of the conversion should be shown
without generating a new variable. Results are listed to show at most no
more than 5 non-missing values of the implied date variable, and no more
than 20 missing values, depending on which condition is satisfied first.
This dry run should allow the user to check assumptions about the
structure of values of varlist and/or to see the results of a
particular format, whether default or specified.

format() specifies a format other than the default for the
particular date-time type. For full details, see help for
datetime display formats.

topyear() specifies a "top year" when two-digit years are
supplied. The explanation here is based on that in
datetime translation.

What if our data include 01-12-06 14:22 and also 15-06-98 11:01? We
want to interpret the first year as 2006 and the second year as 1998.
When you specify topyear, you are stating that when years in
varlist are two digits, so the full year is to be obtained by finding the
largest year that does not exceed topyear. Thus with
topyear(2020) the two-digit year 06 would be interpreted as 2006
because 2006 does not exceed 2020. The two-digit year 98 would be
interpreted as 1998 because 2098 does exceed 2020.

varlabel() specifies a variable label to override the default.

Examples

. clear

. set obs 1

clock date-times:

. gen ctest1 = "2015 Mar 28 11:22:33"

. gen ctest2 = "20152803112233"

. gen double ctest3 = 20152803112233

. format ctest3 %20.0f

. numdate clock c1 = ctest1, pattern(YMDhms)

. numdate clock c2 = ctest2, pattern(YDMhms)

. numdate clock c3 = ctest3, pattern(YDMhms)

daily dates:

. gen dtest1 = "2015mar28"

. gen dtest2 = "mar2815"

. gen long dtest3 = 20152803

. numdate daily d1 = dtest1, pattern(YMD) dryrun

. numdate daily d1 = dtest1, pattern(YMD)

. numdate daily d2 = dtest2, pattern(MDY) topyear(2050) dryrun

. numdate daily d2 = dtest2, pattern(MDY) topyear(2050)

. numdate daily d3 = dtest3, pattern(YDM) dryrun

. numdate daily d3 = dtest3, pattern(YDM)

monthly dates:

. gen mtest1 = "Mar2015"

. gen mtest2 = "2015 3"

. gen mtest3 = "20153"

. numdate monthly m1 = mtest1, pattern(MY) dryrun

. numdate monthly m1 = mtest1, pattern(MY)

. numdate monthly m2 = mtest2, pattern(YM) dryrun

. numdate monthly m2 = mtest2, pattern(YM)

. numdate monthly m3 = mtest3, pattern(YM) dryrun

. numdate monthly m3 = mtest3, pattern(YM)

quarterly dates:

. gen qtest1 = "2015q4"

. gen qtest2 = "2015 4"

. numdate quarterly q1 = qtest1, pattern(YQ) dryrun

. numdate quarterly q1 = qtest1, pattern(YQ)

. numdate q q2 = qtest2, pattern(YQ) dryrun format(%tqY_q)

. numdate q q2 = qtest2, pattern(YQ) format(%tqY_q)

date information in several variables:

. gen s1test1 = 2015

. gen s1test2 = 3

. gen s1test3 = 28

. numdate td s1date = s1test1 s1test2 s1test3, pattern(YMD)

. gen s2test1 = 2015

. gen s2test2 = 3

. numdate tq s2date = s2test1 s2test2, pattern(YQ)

. list c*

. list d*

. list m*

. list q*

. list s1*

. list s2*

Author

Nicholas J. Cox, Durham University, UK

n.j.cox@durham.ac.uk

Acknowledgments

Discussions with William Gould and Robert Picard were stimulating
and helpful. Rasool Baloch kindly reported a bug. Marc Kaulisch posted an
example which led to "More remarks" above.

References

Cox, N.J. 2010. Stata tip 68: Week assumptions.
Stata Journal 10(4): 682-685.

Cox, N.J. 2012a.
Stata tip 111: More on working with weeks.
Stata Journal 12(3): 565-569.

Cox, N.J. 2012b.
Stata tip 111: More on working with weeks, erratum.
Stata Journal 12(4): 765.

Also see

convdate Generate variable of other date-time type

extrdate Generate date-time component variable

[D] datetimes Date and time values and variables

[D] datetime display formats Display
formats for dates and times

[D] datetime translation String to
numeric date translation functions