|
Size: 8464
Comment:
|
← Revision 10 as of 2025-05-20 19:25:08 ⇥
Size: 8446
Comment: Date diff functions
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| Stata supports these '''datetime functions''' in the global scope. | Stata supports these '''datetime functions''' (i.e., numeric function designed for [[Stata/DataFormats#Date_and_Datetime_Formats|date and datetime formatted values]]) in the global scope. |
| Line 11: | Line 11: |
| == Functions Creating a Datetime == | == Functions Converting Integers == See [[Stata/NumericFunctions#Date_and_Time_Functions|Numeric Functions]]. ---- == Functions Converting a String == |
| Line 26: | Line 34: |
| ---- === Clock === Convert a string date and time into the number of milliseconds since the Stata epoch (`01jan1960 00:00:00.000`). There are two functions: '''`clock`''' and '''`Clock`'''. To create a datetime that ''ignores'' leap seconds, try: {{{ generate double datetime = clock(string, "YMDhms") format datetime %tc }}} To create a datetime that ''includes'' leap seconds since the epoch, try: {{{ generate double datetime = Clock(string, "YMDhms") format datetime %tC }}} As noted above, the mask should be composed of: `"Y"`, `"M"`, `"D"`, `"h"`, `"m"`, and `"s"`. ---- === Date === Convert a string date into the number of days since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate long date = date(string, "MDY") format date %td }}} As noted above, the mask should be composed of: `"Y"`, `"M"`, and `"D"`. See above for details on masks. ---- === HalfYearly === Convert a string date into the number of half years since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int halfyear = halfyearly(string, "YH") format halfyear %th }}} As noted above, the mask should be composed of: `"Y"` and `"H"`. See above for details on masks. ---- === Monthly === Convert a string like `"2012m12"` into the number of months since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int month = monthly(string, "YM") format month %tm }}} As noted above, the mask should be composed of: `"Y"` and `"M"`. See above for details on masks. If a string is instead formatted like `"201212"` or `"2000-12"`, try: {{{ generate int month = mofd(date(string, "YM")) format month %tm }}} ---- === Quarterly === Convert a string like `"2012q4"` into the number of quarters since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int quarter = quarterly(string, "YQ") format quarter %tq }}} As noted above, the mask should be composed of: `"Y"` and `"Q"`. See above for details on masks. ---- === Weekly === Convert a string date into the number of weeks since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int week = weekly(string, "YW") format week %tw }}} As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks. ---- === Yearly === Convert a string date into the number of years since the Stata epoch (`01jan1960 00:00:00.000`). {{{ generate int year = yearly(string, "Y") format year %ty }}} As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks. |
||'''Function Name'''||'''Meaning''' ||'''Output Format'''||'''Example''' || ||`clock(s,m)` ||Parse a datetime||`%tc` ||`clock(s,"YMDhms")` || ||`Clock(s,m)` ||Parse a datetime||`%tC` ||`Clock(s,"YMDhms")` || ||`date(s,m)` ||Parse a date ||`%td` ||`date(s,"MDY")` || ||`halfyearly(s,m)` ||Parse a halfyear||`%th` ||`halfyearly(s,"YH")`|| ||`monthly(s,m)` ||Parse a month ||`%tm` ||`monthly(s,"YM")` || ||`quarterly(s,m)` ||Parse a quarter ||`%tq` ||`quarterly(s,"YQ")` || ||`weekly(s,m)` ||Parse a week ||`%tw` ||`weekly(s,"YW")` || ||`yearly(s,m)` ||Parse a year ||`%ty` ||`yearly(s,"Y")` || |
| Line 155: | Line 50: |
| These functions should only be used on numeric variables with a [[Stata/DataFormats#Date_and_Datetime_Data|date or datetime format]]. | These functions are intended for use on [[Stata/DataFormats#Date_and_Datetime_Formats|date and datetime formatted values]]. |
| Line 157: | Line 52: |
| ||'''Function Name''' ||'''Meaning''' ||'''Output Format'''|| ||`cofC(x)` ||Converts a `%tC`-formatted datetime ||`%tc` || ||`cofd(x)` ||Converts a date ||`%tc` || ||`Cofc(x)` ||Converts a `%tc`-formatted datetime ||`%tC` || ||`Cofd(x)` ||Converts a date ||`%tC` || ||`day(x)` ||Extracts the days component from a date ||n/a, in [1,31] || ||`dayssincedow(x,n)` ||Days between reference date and last weekday `n` ||n/a, in [1,7] || ||`dayssinceweekday(x,n)`||Days between reference date and last weekday `n` ||n/a, in [1,7] || ||`daysuntildow(x,n)` ||Days between reference date and next weekday `n` ||n/a, in [1,7] || ||`daysuntilweekday(x,n)`||Days between reference date and next weekday `n` ||n/a, in [1,7] || ||`dofc(x)` ||Converts a `%tc`-formatted datetime ||`%td` || ||`dofC(x)` ||Converts a `%tC`-formatted datetime ||`%td` || ||`dofh(x)` ||Converts a number of halfyears since the epoch ||`%td` || ||`dofm(x)` ||Converts a number of months since the epoch ||`%td` || ||`dofq(x)` ||Converts a number of quarters since the epoch ||`%td` || ||`dofw(x)` ||Converts a number of weeks since the epoch ||`%td` || ||`dofy(x)` ||Converts a number of years since the epoch ||`%td` || ||`dow(x)` ||Extracts the day of week from a date ||n/a, in [0,6] || ||`doy(x)` ||Extracts the day of year from a date ||n/a, in [1,366] || ||`halfyear(x)` ||Extracts the halfyear from a date ||n/a, in [1,2] || ||`hofd(x)` ||Converts a date ||`%th` || ||`hh(x)` ||Extracts the hours component from a `%tc`-formatted datetime ||n/a || ||`hhC(x)` ||Extracts the hours component from a `%tC`-formatted datetime ||n/a || ||`mm(x)` ||Extracts the minutes component from a `%tc`-formatted datetime||n/a || ||`mmC(x)` ||Extracts the minutes component from a `%tC`-formatted datetime||n/a || ||`month(x)` ||Extracts the months component from a date ||n/a, in [1,12] || ||`quarter(x)` ||Extracts the quarter from a date ||n/a, in [1,4] || ||`ss(x)` ||Extracts the seconds component from a `%tc`-formatted datetime||n/a || ||`ssC(x)` ||Extracts the seconds component from a `%tC`-formatted datetime||n/a || ||`week(x)` ||Extracts the week from a date ||n/a, in [1,52] || ||`year(x)` ||Extracts the years component from a date ||n/a || ||`mofd(x)` ||Converts a date ||`%tm` || ||`qofd(x)` ||Converts a date ||`%tq` || ||`wofd(x)` ||Converts a date ||`%tw` || ||`yofd(x)` ||Converts a date ||`%ty` || |
|
| Line 158: | Line 88: |
=== COfC === Convert a datetime around the handling of leap seconds. '''`Cofc`''' takes a datetime ''ignoring'' leap seconds since the Stata epoch (`01jan1960 00:00:00.000`) as input, and returns a datetime ''including'' them. '''`cofC`''' does the reverse. {{{ generate double datetime2 = cofC(datetime) format datetime2 %tc generate double datetime3 = Cofc(datetime) format datetime3 %tC }}} |
Note that weekdays are encoded such that 0 is Sunday and 6 is Saturday. This is used for both argument values (e.g., `dayssincedow`) and return values (e.g., `dow`). |
| Line 179: | Line 94: |
| === COfD === | == Difference Functions == |
| Line 181: | Line 96: |
| Convert a date into a datetime. | The following functions calculate the difference between two dates, or two datetimes, in a variable unit. |
| Line 183: | Line 98: |
| There are two functions: '''`cofd`''' and '''`Cofd`'''. They return a numeric value that should be formatted as `%tc` or `%tC`, respectively. | ||'''Function Name''' ||'''Meaning''' || ||`age(dob,d)` ||Integer age calculated from `dob` and reference date || ||`age_frac(dob,d)` ||Decimal age calculated from `dob` and reference date || ||`Clockdiff(a,b,u)` ||Integer difference between two datetimes, assuming `%tC` format|| ||`Clockdiff_frac(a,b,u)`||Decimal difference between two datetimes, assuming `%tC` format|| ||`clockdiff(a,b,u)` ||Integer difference between two datetimes, assuming `%tc` format|| ||`clockdiff_frac(a,b,u)`||Decimal difference between two datetimes, assuming `%tc` format|| ||`datediff(a,b,u)` ||Integer difference between two dates || ||`datediff_frac(a,b,u)` ||Decimal difference between two dates || |
| Line 185: | Line 108: |
| {{{ generate double datetime = cofd(date) format datetime %tc |
Most of the above functions require a (case-insensitive) unit `u` argument, specifying what the return value should be encoded as. This then also determines ''whether'' there is a fractional element that can be returned by the `_frac` version of the function. * For date differences (e.g., `datediff`), `u` can be: * `"day"` or `"d"` for days * `"month"`, `"mon"`, or `"m"` for months * `"year"` or `"y"` for years * For datetime differences (e.g., `clockdiff`), `u` can be: * `"day"` or `"d"` for days * `"hour"` or `"h"` for hours * `"minute"`, `"min"`, or `"m"` for minutes * `"second"`, `"sec"`, or `"s"` for seconds * `"millisecond"` or `"ms"` for milliseconds |
| Line 189: | Line 120: |
| generate double datetime2 = Cofd(date) format datetime2 %tC }}} |
Additionally, the functions operating on dates (e.g., `datediff`) can take an (case-insensitive) optional argument, specifying what date should be considered the anniversary for February 29th outside of leap years. This argument can be: * `"1mar"`, `"01mar"`, `"mar1"`, or `"mar01"` (the default) * `"28feb"` or `"feb28"` |
| Line 197: | Line 128: |
| === Day === | == See also == |
| Line 199: | Line 130: |
| Extract the day of the month number (1 to 31) from a date (i.e. `%td`-formatted value). {{{ generate byte day = day(date) }}} ---- === DOfC === Convert a datetime into a date. There are two functions: '''`dofc`''' and '''`dofC`'''. They take a numeric value as input, formatted as `%tc` or `%tC` respectively. {{{ generate long date = dofc(datetime) #or generate long date = dofC(datetime) format date %td }}} ---- === DOfH === Convert a half-year (i.e. a `%th`-formatted value) into a date. {{{ generate long date = dofh(halfyear) format date %td }}} ---- === DOfM === Convert a month (i.e. a `%tm`-formatted value) into a date. {{{ generate long date = dofm(month) format date %td }}} ---- === DOfQ === Convert a quarter (i.e. a `%tq`-formatted value) into a date. {{{ generate long date = dofq(quarter) format date %td }}} ---- === DOfW === Convert a week (i.e. a `%tw`-formatted value) into a date. {{{ generate long date = dofw(week) format date %td }}} ---- === DOfY === Convert a year (i.e. a `%ty`-formatted value) into a date. {{{ generate long date = dofy(year) format date %td }}} ---- === Dow === Extract the day of the week number (0 to 6; Sunday is 0) from a date (i.e. `%td`-formatted value). {{{ generate byte day = dow(date) }}} ---- === Doy === Extract the day of the year number (1 to 366) from a date (i.e. `%td`-formatted value). {{{ generate byte day = doy(date) }}} ---- === HalfYear === Extract the half year number (1 to 2) from a date (i.e. `%td`-formatted value). {{{ generate byte halfyear = halfyear(date) }}} ---- === HOfD === Convert a date (i.e. a `%td`-formatted value) into a half year. {{{ generate int halfyear = hofd(date) format halfyear %th }}} ---- === Hh === Extract the hours from a `%tc`-formatted datetime. {{{ generate byte hours =hh(datetime) }}} ---- === HhC === Extract the hours from a `%tC`-formatted datetime. {{{ generate byte hours =hhC(datetime) }}} ---- === Mm === Extract the minutes from a `%tc`-formatted datetime. {{{ generate byte minutes = mm(datetime) }}} ---- === MmC === Extract the minutes from a `%tC`-formatted datetime. {{{ generate byte minutes = mmC(datetime) }}} ---- === MOfD === Convert a date (i.e. a `%td`-formatted value) into a month. {{{ generate int month = mofd(date) format month %tm }}} ---- === Month === Extract the month number (1 to 12) from a date (i.e. `%td`-formatted value). {{{ generate byte month = month(date) }}} ---- === QOfD === Convert a date (i.e. a `%td`-formatted value) into a quarter. {{{ generate int quarter = qofd(date) format quarter %tq }}} ---- === Quarter === Extract the quarter number (1 to 4) from a date (i.e. `%td`-formatted value). {{{ generate byte quarter = quarter(date) }}} ---- === Ss === Extract the seconds from a `%tc`-formatted datetime. {{{ generate byte seconds = ss(datetime) }}} ---- === SsC === Extract the seconds from a `%tC`-formatted datetime. {{{ generate byte seconds = ssC(datetime) }}} ---- === Week === Extract the week number (1 to 52) from a date (i.e. `%td`-formatted value). {{{ generate byte week = week(date) }}} ---- === WOfD === Convert a date (i.e. a `%td`-formatted value) into a week. {{{ generate int week = wofd(date) format week %tw }}} ---- === Year === Extract the year from a date (i.e. `%td`-formatted value). {{{ generate byte year = year(date) }}} ---- === YOfD === Convert a date (i.e. a `%td`-formatted value) into a year. {{{ generate int year = yofd(date) format year %ty }}} |
[[https://www.stata.com/manuals/ddatetime.pdf|Stata datetimes]] |
Stata Datetime Functions
Stata supports these datetime functions (i.e., numeric function designed for date and datetime formatted values) in the global scope.
Contents
Functions Converting Integers
See Numeric Functions.
Functions Converting a String
These functions convert a string into a numeric value that represents a date or time. Masks instruct how a date or time as represented in string data. A datetime format still must be separately applied to the numeric value.
As an example, the mask of "DMY" can parse all of:
"21nov2006"
"21 November 2006"
"21-11-2006"
"21112006"
Spaces are ignored in a mask; "DMY" is equivalent to "D M Y".
The mask "DMY" cannot parse a string with a two-digit year. A two-digit prefix can be applied to "Y" in the mask, such as "DM19Y". If a string has a two-digit year, such a mask will cause the year to be interpreted as being within the 1900s. If a string has a four-digit year, the mask will not mutate the value.
Function Name |
Meaning |
Output Format |
Example |
clock(s,m) |
Parse a datetime |
%tc |
clock(s,"YMDhms") |
Clock(s,m) |
Parse a datetime |
%tC |
Clock(s,"YMDhms") |
date(s,m) |
Parse a date |
%td |
date(s,"MDY") |
halfyearly(s,m) |
Parse a halfyear |
%th |
halfyearly(s,"YH") |
monthly(s,m) |
Parse a month |
%tm |
monthly(s,"YM") |
quarterly(s,m) |
Parse a quarter |
%tq |
quarterly(s,"YQ") |
weekly(s,m) |
Parse a week |
%tw |
weekly(s,"YW") |
yearly(s,m) |
Parse a year |
%ty |
yearly(s,"Y") |
Datetime Functions
These functions are intended for use on date and datetime formatted values.
Function Name |
Meaning |
Output Format |
cofC(x) |
Converts a %tC-formatted datetime |
%tc |
cofd(x) |
Converts a date |
%tc |
Cofc(x) |
Converts a %tc-formatted datetime |
%tC |
Cofd(x) |
Converts a date |
%tC |
day(x) |
Extracts the days component from a date |
n/a, in [1,31] |
dayssincedow(x,n) |
Days between reference date and last weekday n |
n/a, in [1,7] |
dayssinceweekday(x,n) |
Days between reference date and last weekday n |
n/a, in [1,7] |
daysuntildow(x,n) |
Days between reference date and next weekday n |
n/a, in [1,7] |
daysuntilweekday(x,n) |
Days between reference date and next weekday n |
n/a, in [1,7] |
dofc(x) |
Converts a %tc-formatted datetime |
%td |
dofC(x) |
Converts a %tC-formatted datetime |
%td |
dofh(x) |
Converts a number of halfyears since the epoch |
%td |
dofm(x) |
Converts a number of months since the epoch |
%td |
dofq(x) |
Converts a number of quarters since the epoch |
%td |
dofw(x) |
Converts a number of weeks since the epoch |
%td |
dofy(x) |
Converts a number of years since the epoch |
%td |
dow(x) |
Extracts the day of week from a date |
n/a, in [0,6] |
doy(x) |
Extracts the day of year from a date |
n/a, in [1,366] |
halfyear(x) |
Extracts the halfyear from a date |
n/a, in [1,2] |
hofd(x) |
Converts a date |
%th |
hh(x) |
Extracts the hours component from a %tc-formatted datetime |
n/a |
hhC(x) |
Extracts the hours component from a %tC-formatted datetime |
n/a |
mm(x) |
Extracts the minutes component from a %tc-formatted datetime |
n/a |
mmC(x) |
Extracts the minutes component from a %tC-formatted datetime |
n/a |
month(x) |
Extracts the months component from a date |
n/a, in [1,12] |
quarter(x) |
Extracts the quarter from a date |
n/a, in [1,4] |
ss(x) |
Extracts the seconds component from a %tc-formatted datetime |
n/a |
ssC(x) |
Extracts the seconds component from a %tC-formatted datetime |
n/a |
week(x) |
Extracts the week from a date |
n/a, in [1,52] |
year(x) |
Extracts the years component from a date |
n/a |
mofd(x) |
Converts a date |
%tm |
qofd(x) |
Converts a date |
%tq |
wofd(x) |
Converts a date |
%tw |
yofd(x) |
Converts a date |
%ty |
Note that weekdays are encoded such that 0 is Sunday and 6 is Saturday. This is used for both argument values (e.g., dayssincedow) and return values (e.g., dow).
Difference Functions
The following functions calculate the difference between two dates, or two datetimes, in a variable unit.
Function Name |
Meaning |
age(dob,d) |
Integer age calculated from dob and reference date |
age_frac(dob,d) |
Decimal age calculated from dob and reference date |
Clockdiff(a,b,u) |
Integer difference between two datetimes, assuming %tC format |
Clockdiff_frac(a,b,u) |
Decimal difference between two datetimes, assuming %tC format |
clockdiff(a,b,u) |
Integer difference between two datetimes, assuming %tc format |
clockdiff_frac(a,b,u) |
Decimal difference between two datetimes, assuming %tc format |
datediff(a,b,u) |
Integer difference between two dates |
datediff_frac(a,b,u) |
Decimal difference between two dates |
Most of the above functions require a (case-insensitive) unit u argument, specifying what the return value should be encoded as. This then also determines whether there is a fractional element that can be returned by the _frac version of the function.
For date differences (e.g., datediff), u can be:
"day" or "d" for days
"month", "mon", or "m" for months
"year" or "y" for years
For datetime differences (e.g., clockdiff), u can be:
"day" or "d" for days
"hour" or "h" for hours
"minute", "min", or "m" for minutes
"second", "sec", or "s" for seconds
"millisecond" or "ms" for milliseconds
Additionally, the functions operating on dates (e.g., datediff) can take an (case-insensitive) optional argument, specifying what date should be considered the anniversary for February 29th outside of leap years. This argument can be:
"1mar", "01mar", "mar1", or "mar01" (the default)
"28feb" or "feb28"