Return Today’s Date

For Python, the now object is created by calling the today() function returning the current date that is printed using a default display format. Later in this chapter, we will examine how to alter the default display format. The now object is a datetime object. A Python datetime object is subject to date and time manipulation using both simple and complex methods. A Python date object is analogous to a SAS date constant.

Another difference between Python and SAS is Python displays date objects with a default format, whereas the SAS displays date constants as numeric values. SAS date constants must always be accompanied by either a SAS-supplied or user-supplied format to output values into a human-readable form. The default Python date format corresponds to the SAS-supplied yymmdd10.format.

Date Manipulation

In this example, objects d1 and d2 are date objects formed by calling the date() constructor . As date objects, d1 and d2 can be utilized in date arithmetic such as calculating an interval between two dates. The resulting dif object is a Timedelta which we explore later in the chapter. In this case, there are 21,733 days between the two dates.

In this example, SAS variables d1 and d2 are assigned arbitrary date literal constants. The dif variable returns the number of days between these two dates.

Like any language, multiple methods can be used to solve a given problem. As an example, consider Listing 7-8 which is an alternative for determining the number of intervening days between two dates, similar to Listing 7-6.

The toordinal() method returns the ordinal value for January 2, 1960, and assigns it to the d1 object. Likewise, the toordinal() method returns the ordinal for July 4, 2019, and assigns it to the d2 object. The dif object is assigned the difference between the d1 and d2 object. The result is the number of days between these two dates. Unlike Listing 7-6, the type for the dif object is an int rather than returning a Timedelta.

Where the dow1 object calls the weekday() function , in contrast, the dow2 object calls the isoweekday() function returning integers where integer value one (1) represents Monday and 7 represents Sunday.

Illustrated in this example is the .isocalendar attribute which parses the d1 date object to return a three-tuple value for the ISO year, ISO week number, and ISO day of the week.

In this example, the call to SAS WEEKDAY function is assigned to the dow variable and returns the value 4. The WEEKDAY function uses one (1) to represent Sunday, two (2) to represent Monday, and so on.

The WEEK function returns an integer value between 1 and 53 indicating the week of the year. The week1 variable is assigned the value from the call to the WEEK function using the d1 variable as its first parameter followed by the optional ‘u’ descriptor. This descriptor is the default using Sunday to represent the first day of the week.

The week2 variable is assigned the value from the call to the WEEK function followed by the optional 'v' descriptor. This descriptor uses Monday to represent the first day of the week and includes January 4 and the first Thursday of the year for week 1. If the first Monday of January is the second, third, or fourth, then these days are considered belonging to the week of the preceding year.

While the WEEKDAY functions for both Python and SAS are useful, they are often more meaningful if the returned integer values are mapped to names for the week day. In the case of Python, we introduce the calendar module. Like the date module, the calendar module uses January 1, 0001, as day 1 and provides calendar date handling functions and enables formatting. By default, the firstweekday() function is returns zero (0) and maps to Monday.

In this example, we supply an index value of 6 in order to return the string ‘Sunday’.

Now that we have the calendar module available, we can use it in a manner similar to the way SAS formats map values into other representations.

The dow2 object is used as the index to the calendar.day_name, returning the string ‘Wednesday’. Recall that Python uses a zero-based index. In this case, 0 maps to Monday.

In this example, the d2 variable is a date variable and supplied as the parameter to the WEEKDAY function returning the value 4. The WEEKDAY function returns an integer value where one (1) is Sunday, two (2) is Monday, and so on. The PUT function creates the nod2 variable by assigning the dow2 variable value of 4 as the first parameter along with the SAS-supplied WEEKDATE9. format as the second parameter. The nod2 variable holds the value ‘Wednesday’.

The default Python weekday() function is a 0-based index mapped to Monday as the start of the week, while the SAS WEEKDAY function is a 1-based index mapped to Sunday as the start of the week.

Another common task with date arithmetic is calculating dates based on a duration. The Python replace() method offers a way to substitute the year, month, and day argument for a date object and return a modified date.

The replace() function replaces the day value of 31 with the new value 25, in effect shifting the d1 date object value back by six (6) days. The replace() method is useful for basic date arithmetic such as counting days to a future event.

In this example, the first argument to the date() constructor is the today.year argument which returns the current year followed by the integer 1 to represent January, then followed by the integer 24 to represent the 24th day. The if condition tests whether the input birthdate occurs during the current year.

If the birthday has already occurred in the current year, the if condition is False and not executed. If the birthday has not occurred in the current year, then the condition is True, and the replace() method is called to increment the year argument to year + 1.

calculates the number of days between the input birthdate and today’s date.

With the next_birth_day calculated in this section of the code, the number of days remaining can be calculated and assigned to the days_until variable.

In the other case, when the input birthdate is greater than the current date (the false condition for the IF-THEN/DO-END), the ELSE/DO-END condition is executed to calculate the days remaining.

Shifting Dates

In this example, the date() constructor is called assigning the d1 datetime object a value of January 1, 2019. In order to determine the calendar date 1,001 days hence, the d1 datetime object calls the toordinal() method returning the number of days from the ordinal start date of January 1, 0001, and the date value for the d1 object assigning this value to the to_ord object. The to_ord object is then incremented by 1,001, and assigned to the inc object. Finally, the fromordinal() function is called with the inc object as an argument returning the incremented date to the d2 object.

Dates to Strings

The d3 datetime object is created by calling the date() constructor to set its date to December 25, 2019. Subsequently, three datetime-formatted strings are returned by calling the strftime() method with differing format directives. The format directive is given as the second argument to the strftime() method call and is composed of directives listed in Table 7-1. While these examples use a hyphen (-) as the field separator, you may use any separator such as a percent sign (%), slashes (/), colons (:), blanks (ASCII 32), and so on as well as including any arbitrary characters. Format directives are enclosed in quotes.

The PUT function is called to convert a numeric variable to a character variable. The PUT function returns a value using the format specified in the function call, in this case, the SAS-supplied YYMMDD8., YYMMDD10., and WORDDATX. formats. The VTYPE function returns the variable type, C for character and N for numeric.

returning the week day full name.

Strings to Dates

where the first argument is the dt_str object and the second argument is the directive matching this string.

Recall the strptime() method returns a datetime object, even though we are supplying a date string and the associated directive. As the name suggests, a datetime object holds a value for both date and time and is discussed later in this chapter. Since we do not have a time portion defined, the resulting d5 datetime object is set to midnight.

In contrast to Listing 7-21, this example uses the INPUT function to map a date string assigned to the dt_str variable as a date constant. The VTYPE function returns the data type for the d5 and dt_str variables.

Time of Day

In some cases, the analysis we are performing needs to consider elapsed time with a start time independent of the current day. For this purpose, Python and SAS provision functions to return the current time of day. These functions make calls to the underlying OS to return time of day from the processor’s clock. Later in this chapter, we will explore how to handle variations in reported time influenced by time zone considerations.

For now, let’s consider the basics for obtaining the current time as shown in Listing 7-28. Recall that in Listing 7-25 we use the gmtime() function to create a struct_time object by supplying the number of seconds from the Python time offset, which is zero (0) in that case. In this example, we call the time.time() function without an argument to return the local time.

creates the now object by calling the localtime() function using the time.time() as an argument, which returns today’s timestamp to the localtime() function. The result is the struct.time object assigned to the now object.

converts the time.struct object (created by the localtime() function call) to a string displaying day of week, date, time, and year. The asctime() function converts the Python struct_time object into a string.

The now variable is a time constant with a value from today’s date and time. The PUT function converts this numeric variable to a character variable, in this case, using the DATEPART, TIMEPART, and YEAR functions returning constitute datetime components. The TRANWRD function strips the comma (,) following the week day name.

Time Formatting

Formatting time values follows the same pattern discussed earlier in the chapter for formatting date values using the same format directives used for date and datetime objects. Additionally, the strftime() method converts struct_time object into strings representing the constituent parts of time.

Conversely, the strptime() method creates a time object from a string representing time values by using a corresponding format directive to control its appearances. The result from calling the strptime() function is a datetime object whose output is controlled by the corresponding format directive.

It is often the case that time and datetime values need conversion to strings or we have strings representing time and datetime values which need conversion to time or datetime objects and variables. The next four examples illustrate these conversions along with formatting time and datetime examples.

Times to Strings

without the need to supply a format directive.

Objects n2, n3, and n4 display the same datetime with different format directives. Format directives are supplied as a single argument composed of the directives listed in Table 7-1, in this case, using different separators such as hyphens (-), slashes (/), and colons (:) and any arbitrary characters.

This example calls the DATETIME function to return the current date and time similar to the Python time() function. The Python time() function returns the struct_time object, whereas the SAS TIME function returns a time constant, ‘12:34:56’t, representing the number of seconds from midnight.

In order to replicate the results in Listing 7-30, this example uses different SAS functions such as DATEPART and TIMEPART to extract the constituent elements from the current date and time, respectively. The TZONENAME function is a relatively new function introduced with release 9.4, returning the time zone name, assuming this option is set. By default, this option is not set and is set using the OPTIONS statement. We provide further details for handling time zone later in this chapter.

Strings to Time

converts the string "12:34:56 PM" into a struct_time object called t. The attributes tm_hour, tm_min, and tm_sec attached to the t object return integer values representing the hour, minute, and seconds, respectively.

In this example, the characters '12:34:56' are assigned to the t_str variable. The INPUT function maps this string as a numeric value assigned to the t variable, creating a SAS time constant. The HOUR, MINUTE, and SECOND functions return numerics representing the hour, minute, and second, respectively, from the t variable.

Combining Times and Dates

And as one would expect, the data type returned for the dt_comb object is datetime.

Calling the DHMS function returns a numeric value that represents a SAS datetime value. The py_fmt. format is created in Listing 7-35.

Now let’s turn our attention to extracting constituent components from a datetime object . Both Python and SAS provide methods to extract datetime components to returning these values as integers and strings.

Returning Datetime Components

Not shown in this example are the microsecond and tzinfo attributes which in this case return None.

All of the variables in this example are numeric.

Strings to Datetimes

Converting a SAS character variable to a datetime constant is similar to the earlier examples in this chapter for converting character variables to date and time constants. Consider Listing 7-41 which illustrates this conversion. In this case, if the SAS variable value of 'August 4, 2001 1:23PM' had a delimiter between the date and time value, we can use the ANYDTDTM. informat.

The format directive '%B %d, %Y %I:%0M%p' on the PICTURE statement matches the input character variable value 'August 4, 2001 1:23PM'. The SAS Data Step creating the py_infmt dataset contains the minimum variables for defining a CNTLIN= dataset needed by PROC FORMAT, with the type, label, and start variables. In order to be recognized as a cntlin= dataset, these names for variables are required. SAS datetime values have a 1-second level of granularity, and since the user-defined informat deals with a minute interval, the DO loop to generate the datetime labels is divided by 60.

assigns the SAS datetime constant to the dt_obj variable by calling the INPUT function with the user-defined py_infmt32. informat.

Datetimes to Strings

A format specifier is appended following the colon (:) and while the format specifiers can be a range of valid format specifiers, since we are dealing with datetime, we illustrate those in Table 7-1.

In order to render the output identical to the Python example in Listing 7-42, the CAT function is called to left-pad the value for the hr_str variable with a zero (0).

Naïve and Aware Datetimes

The Python Standard Library for datetime has two types of date and datetime objects: “naïve” and “aware”. Up to this point, the Python date and datetime examples used in our examples are “naïve”, meaning it is up to the program logic to determine the context for what the date and datetime values represent. This is much the same way a calculated linear distance value can be rendered in miles, meters, or kilometers. The benefit of using “naïve” datetime types is the simplicity for manipulation and ease of understanding. The downside is they do not have enough information to deal with civil adjustments to times or other shifts in time like those described previously.

In this section we will touch on the Python timezone object as means for representing time and datetime objects with an offset from UTC. We also introduce the pytz module to provide consistent cross-time zone time and datetime handling. The pytz module augments working with “aware” time and datetime objects by exposing an interface to the tz database⁴ managed by the Internet Corporation for Assigned Names and Numbers, or ICANN. The tz database is a collection of rules for civil time adjustments around the world.

As a general practice, datetime functions and arithmetic should be conducted using the UTC time zone and then converting to the local time zone for human-readable output. No Daylight Savings time occurs in UTC making it a useful time zone for performing datetime arithmetic, not to mention that nearly all scientific datetime measurements use UTC and not the local time zone.

A datetime object is “naïve” if its .tzinfo attribute returns None. The following examples illustrate the distinctions between “naïve” and “aware” datetime objects.

In this example, using the Python Standard Library, we make three requests for the current time assigning returned values to datetime objects. The first request calls the datetime.now() method returning the current local time to the “naïve” datetime object dt_local. In this case, the current local time comes from the US Eastern time zone, although the time zone is inferred, since we do not provide one when making the call. The tzinfo attribute value returned from the dt_local object confirms this is a “naïve” datetime by returning None.

The second request uses the datetime.utcnow() method call to return the current time from the UTC time zone and assign it to the dt_naive object. Interestingly, when we request the current time from the UTC time zone, we are returned a “naïve” datetime object. And because both the dt_local and dt_naive objects are “naïve” datetimes, this explains why the request for the time zone value using the (%Z) format directive returns an empty value when printing.

The third request illustrates returning the current UTC time zone and assigning the value to the “aware” dt_aware datetime object calling the datetime.now(dt.timezone.utc) method. In this case, the .tzinfo attribute returns UTC to indicate this datetime object is “aware”.

Using the Standard Library, we can convert a “naïve” datetime object to an “aware” datetime object, but only to the UTC time zone by calling the replace() method using the timezone.utc argument. The conversion of a “naïve” to an an “aware” datetime object is illustrated in Listing 7-51.

As a result, the tzinfo attribute for the dt_aware object returns UTC .

pytz Library

creates the dt_est “aware” datetime object by calling the pytz timezone() function which has the effect of setting this object’s tzinfo attribute to “US/Eastern”. The localize() method is chained to this call to convert the “naïve” dt_naive datetime object to an “aware” object. The localize() method takes into account the transition to Daylight Savings time.

In this example, we return a random sample of ten time zone values from the common_timezones list. Another source of time zone values is the all_timezones list which is an exhaustive list of time zone available to the pytz timezone() function.

Returning to the pytz timezone() function , let’s look at additional examples and pitfalls to avoid.

In this case, the dt_sha object is an “aware” object, but returns the Local Mean Time (LMT) with a time difference between New York and Shanghai of 13 hours and 6 minutes. Obviously, if both times are the same times represented by different time zone, there is no time difference.

The before datetime object is created using the normalize() method to subtract a Timedelta of 10 minutes from the dt_loc datetime object returning a datetime for Eastern Daylight Time. And by adding a Timedelta of 20 minutes to the before datetime object, it returns a datetime for Eastern Standard Time.

Nonetheless, the preferred way of handling datetime manipulation is to first convert datetimes to the UTC time zone, perform the manipulation, and then convert back to the local time zone for publishing results. This recommendation is illustrated in Listing 7-59. This example illustrates the problem of finding a duration between two datetimes when the duration includes the transition date from Daylight Savings to Standard Time.

Now the correct start datetime is returned from the tm_start_edt object as shown by calling the second print() function in the program.

SAS Time zone

As we have seen, Python handles time zone for datetime objects by assigning values to the tzinfo attribute , which is a component of the datetime object itself. The SAS implementation for time zone is handled by setting options for the execution environment using the SAS System option TIMEZONE. Unless otherwise set, the default value is blank (ASCII 32) indicating that SAS uses the time zone value called from the underlying operating system. In this case, a PC running Windows 10 with the time zone set to US Eastern.

Despite the fact an explicit SAS TIMEZONE option is not in effect, calling the DATETIME function returns a datetime representing the local time for the Eastern US. This is indicated by using the SAS-supplied, ISO 8601 e8601LX. datetime format which writes the datetime and appends the time zone difference between the local time and UTC. ISO 8601 is an international standard for representing dates, time, and interval values. SAS supports basic and extended ISO 8601 date, time, datetime, and interval values.

And regardless of whether an instance of SAS has the TIMEZONE option explicitly set, or is implied, the TZONEOFF function always returns the number of seconds between the local time zone (which is obtained from the OS when not explicitly set) and UTC. In this case, the local UTC offset is for the Eastern US. As we shall see subsequently, the TZONEOFF function automatically takes into account transitions from Daylight Savings and Standard Time.

The first thing to notice is how values returned by the DATETIME function are a function of the TIMEZONE option in effect. Secondly, writing datetime values created with one TIMEZONE option in effect and subsequently reading them using a different TIMEZONE option does not alter the values.

Which then raises the question of converting SAS datetimes written with a TIMEZONE option in effect to datetimes for another time zone? One approach is to utilize the TZONEOFF function together with the INTNX function illustrated in Listing 7-64. The purpose of this example is to illustrate datetime conversions using the INTCK function to shift datetimes based on time zone offsets.

The dates chosen for this example illustrate the behavior of the TZONEOFF function when dealing with datetime values that include transition dates from Daylight Savings to Standard Time in the Eastern time zone.