4.11 Working with time-series data

Time-series data need to be handled carefully. If times and dates are specified in local time, then conversions may be necessarily between timezones, especially around the beginning and end of daylight saving time.

Even when this it not an issue, months have different lengths and leap years have an extra day, which mean it is not straightforward to convert a series of calendar dates into elapsed times between the data points.

On a more basic level, even time expressed in hours and minutes are complicated by being expressed as non-decimal fractions of days.

To simplify the process of working with dates and times, Pyxplot has native date object type, together with pre-defined functions in the time module for creating and manipulating such objects. A date object represents a specific moment in time, and can be created from a time and date specified in any arbitrary timezone. It is then possible to read out the time and date components of this date object in any other arbitrary timezone.

The functions for creating date objects are as follows:

time.fromCalendar(year,month,day,hour,min,sec,<timezone>)

This function creates a date object from the specified calendar date. It takes six compulsary numerical inputs: the year, the month number (1–12), the day of the month (1–31), the hour of day (0–24), the number of minutes (0–59), and the number of seconds (0–59). To enter dates before AD 1, a year of $0$ should be passed to indicate 1 BC, $-1$ should be passed to indicate the year 2 BC, and so forth.

A timezone may optionally be specified as the final argument to the function. If no timezone is specified, then the default is used, which may be set using the set timezone command. The timezone should be specified as a location string, of the form Europe/London, America/New_York or Australia/Perth, as used by the tz database. A complete list of available timezones can be found here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

Daylight saving time will be applied as appropriate for the specified location. Note that strings such as GMT, EDT or CEST are not allowed as timezones; a location should be specified.

If universal time is used, the timezone may be specified as UTC.

time.fromUnix(t)

This function creates a date object from the specified numerical Unix time – i.e. the number of seconds ellapsed since midnight on 1st January 1970 UTC.

time.fromJD(t)

This function creates a date object from the specified numerical Julian date.

time.fromMJD(t)

This function creates a date object from the specified numerical modified Julian date.

time.now()

This function takes no arguments, returns a date object corresponding to the current system clock time, as in the following example:

pyxplot> print time.now()
Tue 2012 Sep 4 20:57:00 UTC
pyxplot> set timezone "America/Los_Angeles"
pyxplot> print time.now()
Tue 2012 Sep 4 13:57:41 PDT

Note that the date object created by the time.now() function is identical regardless of timezone, but it is displayed differently depending upon the current timezone.

The following example creates a date object representing midnight on 1st January 2000, in universal time, and in Western Australian time:

pyxplot> print time.fromCalendar(2000,1,1,0,0,0)
Sat 2000 Jan 1 00:00:00 UTC
pyxplot> a = time.fromCalendar(2000,1,1,0,0,0,"Australia/Perth")
pyxplot> print a # Note that this does not use Australian time
Fri 1999 Dec 31 15:59:59 UTC
pyxplot> set timezone "Pacific/Chatham"
pyxplot> print a
Sat 2000 Jan 1 05:45:00 CHADT
pyxplot> set timezone "Antarctica/South_Pole"
pyxplot> print a
Sat 2000 Jan 1 05:00:00 NZDT
pyxplot> print a.toYear() # at the south pole
2000
pyxplot> print a.toYear("Europe/London")
1999

Once created, it is possible to add numbers with physical units of time to dates, as in the following example:

pyxplot> myDate = time.fromCalendar(2012,8,1,0,0,0)
pyxplot> print myDate + unit(7*day)
Wed 2012 Aug 8 00:00:00 UTC
pyxplot> print myDate - unit(2000*day)
Fri 2007 Feb 9 00:00:00 UTC

Standard string representations of calendar dates can be produced with the print command. It is also possible to use the string substitution operator, as in "%s"%(date), or the str method of date objects, as in date.str().

In addition, the time.string function can be used to choose a custom display format for the date, or to specify the timezone in which the date should be displayed. Its arguments are as follows:

time.string(t,<format>,<timezone>)

This function returns a string representation of the specified date object $t$ . The second argument is optional, and may be used to control the format of the output. If no format string is provided, then the format
"%a %Y %b %d %H:%M:%S %Z"
is used. In such format strings, the following tokens are substituted for various parts of the date:

Token	Value
`%%`	A literal % sign.
`%a`	Three-letter abbreviated weekday name.
`%A`	Full weekday name.
`%b`	Three-letter abbreviated month name.
`%B`	Full month name.
`%C`	Century number, e.g. 21 for the years 2000-2099.
`%d`	Day of month.
`%H`	Hour of day, in range 00-23.
`%I`	Hour of day, in range 01-12.
`%k`	Hour of day, in range 0-23.
`%l`	Hour of day, in range 1-12.
`%m`	Month number, in range 01-12.
`%M`	Minute, in range 00-59.
`%p`	Either `am` or `pm`.
`%S`	Second, in range 00-59.
`%y`	Last two digits of year number.
`%Y`	Year number.
`%Z`	Timezone name (e.g. UTC, CEST, EDT).

The third argument is also optional, and specifies the timezone that the time should be displayed in. As above, this should be specified in the form Europe/London, America/New_York or Australia/Perth, as used by the tz database. A complete list of available timezones can be found here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones. If universal time is used, the timezone may be specified as UTC. If no timezone is specified, the default is used as set in the set timezone command.

Several functions are provided for converting date objects back into various numerical forms of timekeeping and components of calendar dates, which are listed below. Where appropriate, an optional timezone may be specified to obtain a calendar date for a particular location:

toDayOfMonth( $<timezone>$ )
The toDayOfMonth( $<timezone>$ ) method returns the day of the month of a date object in the current calendar.

toDayWeekName( $<timezone>$ )
The toDayWeekName( $<timezone>$ ) method returns the name of the day of the week of a date object.

toDayWeekNum( $<timezone>$ )
The toDayWeekNum( $<timezone>$ ) method returns the day of the week (1–7) of a date object.

toHour( $<timezone>$ )
The toHour( $<timezone>$ ) method returns the integer hour component (0–23) of a date object.

toJD()
The toJD() method converts a date object to a numerical Julian date.

toMinute( $<timezone>$ )
The toMinute( $<timezone>$ ) method returns the integer minute component (0–59) of a date object.

toMJD()
The toMJD() method converts a date object to a modified Julian date.

toMonthName( $<timezone>$ )
The toMonthName( $<timezone>$ ) method returns the name of the month in which a date object falls.

toMonthNum( $<timezone>$ )
The toMonthNum( $<timezone>$ ) method returns the number (1–12) of the month in which a date object falls.

toSecond( $<timezone>$ )
The toSecond( $<timezone>$ ) method returns the seconds component (0–60) of a date object, including the non-integer component.

toUnix()
The toUnix() method converts a date object to a Unix time.

toYear( $<timezone>$ )
The toYear( $<timezone>$ ) method returns the year in which a date object falls in the current calendar.

For example:

pyxplot> a = time.fromCalendar(2000,1,1,0,0,0)
pyxplot> time.string(a)
Sat 2000 Jan 1 00:00:00 UTC
pyxplot> time.string(a,"%d %B %Y")
1 January 2000
pyxplot> set calendar muslim
pyxplot> time.string(a,"%d %B %Y")
21 Dhu l-Qa’da 1389