Home  /  Products  /  Stata 18  /  Datetime functions

<- See Stata 18's new features

Highlights

• Functions related to days of the week (Sunday, Monday, etc.)

• Find dates of first and last given days of the week in a month

• Calculate duration, in days, since previous and until next days of the week

• Find dates of previous and next days of the week

It takes approximately a day for the earth to rotate about its axis, a month for the moon to orbit the earth, and a year for the earth to orbit the sun. The day, month, and year determine a date based on the universally used Gregorian calendar. Stata's mdy(M, D, Y) function turns the month, day, and year into a numeric datetime value suitable for calculations. In Stata 18, we add dmy(D, M, Y), with arguments ordered as they are in most of the world.

The week, in contrast, is a time period that is not based on astronomy. Nonetheless, it plays a central role in planning our day-to-day lives: from weekly meetings, classes, worship, and sports games to celebrating TGIF (Thank God It's Friday) and dealing with Monday blues. Weekly time-series analyses are common, especially in business, economics, and epidemiology. The week was not always 7 days long everywhere; it was once 10 days for Egyptians and 8 days for Etruscans. The 7-day week can be traced back to Babylonians and was later popularized by the Roman Empire. Despite its use worldwide, the week can still be ambiguous and sometimes fits awkwardly in our calendar.

There are two ways to look at the week: first, in terms of duration. For example, how many weeks are there in a year? Second, in terms of specific days of the week: what date is the first Monday of the month? Or how many days remain until the next Friday? While Stata has the weekly date type for bookkeeping the number of weeks as duration, in Stata 18 we introduce functions that deal with specific days of the week.

##### Day of the week

The functions we introduce in Stata 18 are related to the days of the week. This too has its ambiguities. First, what is the first day of the week? It depends on where you are: Sunday in America and South Asia, Monday in China and Europe, and Saturday in the Middle East and North Africa.

In Stata, Sunday is the first day of the week, and is assigned numeric day 0; 1 = Monday, 2 = Tuesday, ..., 6 = Saturday. The dow() function takes a date and returns the corresponding numeric day.

Also, the working days of the week (workweek in American English or weekday in British English) and their complement, the weekend, vary across the world. The most popular workweek is Monday to Friday, with Saturday and Sunday as the weekend. But in many countries, Friday and Saturday constitute the weekend. Some even have a one-day weekend. There are sometimes changes. For example, in 2006 the United Arab Emirates pushed its weekend by one day, to Saturday and Sunday, and thus synchronized with most of the world.

In Stata, working (or business) days are handled by business calendars. No week assumptions are made. Workweeks, weekends, and all holidays can be defined by the user. See [D] bcal for more details.

#### Let's see it work

In Stata 18, we introduce a few functions in both Stata and Mata that make simple calculations about the day of the week convenient. Note that we use "weekday" to mean any day of the week, especially in function names. We provide synonymous functions with "weekday" or "dow" in the names of these functions. For example, previousweekday() and previousdow() are synonyms.

Suppose you work in Human Resources (HR) and you would like to make everybody's day with a fun social event every first Friday of the month in 2023. You can use firstweekdayofmonth() to generate those dates in your dataset (that has a variable, say, month, ranging from 1 to 12):

. generate social_date = firstweekdayofmonth(month, 2023, "Friday")


Instead of "Friday", you can also type 5, the numeric day for Friday, or the first two or more (case-insensitive) letters of the day as a string, e.g., "fr", "Fri", etc. This applies to the rest of the functions below.

HR may also be interested in reviewing the productivity of the last Monday of every month. These review dates can be identified with

. generate review_date = lastweekdayofmonth(month, 2023, "mon")


On any given date, HR may wish to manage the weekly employee effort, say, in person-days, since the previous Monday, the first working day of the week, and until the next Friday, the last working day. The number of days, as of today, since the previous Monday can be obtained with

. display dayssinceweekday(today(), 1)


The number of days, as of today, until the next Friday can be obtained with

. display daysuntilweekday(today(), 5)


The Stata dates of the Monday and Friday that mark the beginning and end of the workweek, relative to Stata date variable date, can be obtained with

. generate begin = previousweekday(date, 1)


and

. generate end = nextweekday(date, 5)


#### Tell me more

Read more in the Stata Data Management Reference Manual; see [D] Datetime and [D] bcal ->

Read more in the Stata Functions Reference Manual; see [FN] Date and time functions ->

For Mata functions, read more in the Stata Mata Reference Manual; see [M-5] date() ->

View all the new features in Stata 18 ->