help convdate

Title

convdate -- Convert numeric date-time variable,
generating variable of another date-time type

Syntax

convdate datetimetype newdatevar = datevar [if] [in]

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

Description

convdate is for generating a new Stata numeric date-time variable
newdatevar of specified date-time type from an existing variable
datevar that is already a numeric date-time variable. For example, you
might want to create a monthly date variable (example display: 2017m8)
from a daily date variable (example display: 1aug2017), or vice versa.

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 convdate, datevar must be a numeric date-time
variable. The test of that is whether the variable has been assigned a
date-time display format starting with any of the designators from the
list just above.

For example, suppose you ask for a monthly date to be calculated from
your variable mydate. convdate looks at the display format
of mydate to determine what conversion function(s) to use.

Details: "-" signs indicating left alignment are also accommodated.
Variables holding years are not an exception, regardless of the fact
that formats ending in g or f can work well otherwise for
such variables.

convdate applies no other test to determine what makes sense: if
in doubt on this or any other grounds, use the dryrun option.

Fundamentally, going from a finer date-time to a coarser
date-time (e.g. daily to monthly) loses information and that going
from a coarser date-time to a finer date-time (e.g. monthly to daily)
cannot reinstate any detail present in an earlier incarnation of
datevar. Stata's convention with coarse to fine conversions is to
return the first possible date: for example, the first day in each
month, or the first month in each quarter. The last option of
convdate uses the reverse convention of yielding (in these
examples) the last day of a month or the last month in a quarter. This
option thereby goes beyond what is immediately possible with Stata's
inbuilt functions.

convdate automatically generates tc
(clock) and tC (Clock) variables as double, as
is necessary to maintain precision.

Remarks

Use of convdate 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.

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, 2012c).

A common pitfall is to think that changing the display format will
convert one kind of date-time to another. Only exceptionally will this
produce the right answer, as the underlying numbers will not be changed.
For more, see Cox (2012b).

convdate does not offer an option for middle dates. The
calculation is either obvious or a little arbitrary. It is left to users
to decide what is adequate for their purposes. Thus day 15 may be good
enough as the middle day in each month, even though months differ in
length: trivially that date is 14 days later than the first day in each
month. An easier example is that the middle month in each quarter
is one after the first month and one before the last month.

Options

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
values of varname 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.

last specifies that the last possible date be used in coarse to fine
conversions, not the first. For example, given a monthly date variable
and a request to return a daily date variable, the Stata function dofm(), used within convdate for such problems,
returns the daily date which is the first day of each month. This option
insists on the last day of each month, or more generally the last possible date.

For application elsewhere, consider this easy example.
The last day of August 2017 is one day before the first day of September
2017.

. di %td dofm(ym(2017, 8) + 1) - 1
31aug2017

To get there, add 1 to the monthly date; convert to a
daily date; and then subtract 1 from the daily date.

Evidently the same trick applies to any month.
Hence you never need to wrestle with the complications of different
month lengths and whether a year is leap to determine whether the last
day of a month is 28, 29, 30 or 31. Always use
dofm(monthly date + 1) - 1 .

In general, the rule is that the last possible fine date
from a given coarse date is that before the first possible
fine date corresponding to the next coarse date.

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

Examples

. clear

. set obs 1

. gen double ctest = clock("2015 Mar 28 11:22:33", "YMD hms")

. format ctest %tc

. convdate daily c1=ctest

. convdate month c2=ctest

. convdate year c3=ctest

. list c*

. gen dtest = daily("2015mar28", "YMD")

. format dtest %td

. convdate month d1=dtest

. convdate year d2=dtest

. list d*

. gen mtest = monthly("Mar2015", "MY")

. format mtest %tm

. convdate daily m1=mtest

. convdate daily m2=mtest, last

. convdate year m3=mtest

. list m*

. describe

Author

Nicholas J. Cox, Durham University, UK

n.j.cox@durham.ac.uk

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 113: Changing a variable's format.
Stata Journal 12(4): 761-764.

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

Also see

numdate Generate numeric date-time variable

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