# 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 AD1, a year of should be passed to indicate 1BC, should be passed to indicate the year 2BC, 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 . 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()
The toDayOfMonth() method returns the day of the month of a date object in the current calendar.

toDayWeekName()
The toDayWeekName() method returns the name of the day of the week of a date object.

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

toHour()
The toHour() 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()
The toMinute() 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()
The toMonthName() method returns the name of the month in which a date object falls.

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

toSecond()
The toSecond() 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()
The toYear() 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`

- 4.11.1 Calendars
- 4.11.2 Time intervals