help extrdate

Title

extrdate -- Generate date or time component from date-time
variable

Syntax

extrdate component newvar = datevar
[if] [in],

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

Description

extrdate is for generating a new Stata numeric variable
newvar extracting a date or time component from an existing
date-time variable datevar containing date or date-time or time
information.

The subcommand component is required and should be one of

ss seconds
mm minutes
hh hours
dow day of week
day day of month
doy day of year
week week of year
month month of year
quarter quarter of year
halfyear halfyear of year
year year

Any umambiguous abbreviation is allowed, down to single letters.

Remarks

extrdate relies exclusively on the display format of datevar
to indicate its date-time type. Note that in particular the difference
between Clock and clock is so inferred and the appropriate
function to use is automated thereby.

extrdate is just a wrapper for the corresponding Stata function as
given by the full name in the list above, except that

extrdate will use ssC(), mmC() or hhC()
rather than ss(), mm() or hh() whenever it detects a
variable formatted %tC rather than %tc.

extrdate will map dates for periods longer than days to
daily dates before attempting to apply any of the other functions.

Note that extrdate does no more. For example, suppose you want to
convert a time 11:22:33 to the equivalent in some other units, say
hours, minutes or seconds. All that extrdate will do is apply
whichever of hh, mm, ss you specify. It will not
change units for you.

Use of extrdate 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, 2012b).

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 new 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 datevar and/or to see the results of a
particular format, whether default or specified.

format() specifies a format other than the default. This option
is rarely used, as almost all results of this command are variables
containing relatively small integers, the exception being possibly results in
seconds.

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

Examples

. clear

. set obs 3

. * first examples: date-time variable

. gen str42 whatever = "1952 03 28 02:00:00"

. replace whatever = "1999 12 31 23:59:59.999" in 2

. replace whatever = "2017 08 03 15:48:00" in 3

. gen double dtime = clock(whatever, "Y M D hms")

. format dtime %tc

. list

. extrdate y year=dtime , dryrun

. extrdate hh hh=dtime , dryrun

. extrdate ss ss=dtime , dryrun

. extrdate doy doy=dtime, dryrun

. * second examples: daily date variable

. gen mydate = mdy(3, 28, 2017)

. replace mydate = mdy(12, 31, 2016) in 1

. replace mydate = mdy(8, 21, 2017) in 3

. format mydate %td

. extrdate y Year=mydate, dryrun

. extrdate ha Half=mydate, dryrun

. extrdate q Quar=mydate, dryrun

. extrdate mo Mont=mydate, dryrun

. extrdate doy Doy=mydate, dryrun

. extrdate y Year=mydate

. extrdate ha Half=mydate

. extrdate q Quar=mydate

. extrdate mo Mont=mydate

. extrdate doy Doy=mydate

. list mydate Year Half Quar Mont Doy

. describe

. * third examples: quarterly date variable

. webuse turksales, clear

. extrdate y y=t , dryrun

. extrdate q q=t , dryrun

. extrdate mo m=t , dryrun

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 111: More on working with weeks, erratum.
Stata Journal 12(4): 765.

Also see

numdate Generate numeric date-time variable

convdate Generate variable of other date-time type

[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