# Working with dates#

`staircase`

is designed with two domain types in mind: real numbers and time - or in the language of Python computing, floats and datetimes. Even when the domain is real numbers it is quite likely that, semantically, those numbers represent a time value.

In version 1 of `staircase`

a user wanting to use datetimes needed to declare this when creating a `staircase.Stairs`

instance. This is not required in v2:

```
In [1]: import pandas as pd
In [2]: import staircase as sc
In [3]: sf = sc.Stairs().layer(pd.Timestamp("2021"), pd.Timestamp("2022"), 3)
In [4]: sf.plot(arrows=True)
Out[4]: <AxesSubplot: >
```

For datetime domains *v2* has been tested with `numpy.datetime64`

, `datetime.datetime`

, and `pandas.Timestamp`

. This includes **time-zone aware** variants for the latter two of these. If you’re working with datetime domains then arguments to methods with domain-based parameters need to be datetime too. These methods include:

String representations of timestamps can also be used as arguments for `staircase.Stairs.clip()`

, `staircase.Stairs.mask()`

and `staircase.Stairs.where()`

.

Note that when using datetime domains an integral calculation will be a timedelta:

```
In [5]: sf.integral()
Out[5]: Timedelta('1095 days 00:00:00')
```

Unfortunately the `pandas.Timedelta`

class has limitations which may be exceeded with integral calculations (resulting in an overflow error). A workaround may involve scaling your step function values down, by dividing by a constant, before calculating the integral. This begs the question of whether this situation can be avoided by using `numpy.datetime64`

or `datetime.datetime`

. “Under the hood” of `staircase`

datetimes are represented by `pandas.Timestamp`

, even if the original data was another datetime class. This conversion is something that is inherited from `pandas`

and the overflow error remains. If you wish to convert from `pandas.Timestamp`

to another datetime class then the following methods may be of use:

## Timezones#

Datetime data can be timezone-naíve or timezone-aware. For many datetime applications of staircase it may suffice to ignore the concept of timezones and work with timezone-naíve data - an attractive option as working with timezones, and converting between them, can be tricky. However many countries observe Daylight Savings Time which results in one day of the year having 23 hours, and another having 25 hours:

```
In [6]: import pytz
In [7]: timezone = pytz.timezone('Australia/Sydney')
In [8]: sc.Stairs().layer(
...: pd.Timestamp("2021-4-4", tz=timezone),
...: pd.Timestamp("2021-4-5", tz=timezone),
...: ).integral()
...:
Out[8]: Timedelta('1 days 01:00:00')
In [9]: sc.Stairs().layer(
...: pd.Timestamp("2021-10-3", tz=timezone),
...: pd.Timestamp("2021-10-4", tz=timezone),
...: ).integral()
...:
Out[9]: Timedelta('0 days 23:00:00')
```

If you are computing some daily metric and do not take this into account then the calculations on those days will be incorrect, however the consequences, and indeed the calculated result, maybe small enough to ignore. However, for some applications the use of timezone-aware timestamps may be critical.

Given the sheer number of packages available for Python it may be of no surprise that there are several for dealing with timezones. There is one which is clearly the de facto standard: `pytz`

, however staircase supports any timezone package that pandas supports.