Datetime (sfi.Datetime)

class sfi.Datetime

This class provides a set of core tools for interacting with Stata datetimes.

Method Summary

format(value, format) Get the formatted Python datetime or date string based on the specified Stata internal form (SIF) value and Stata datetime format.
getDatetime(value, format) Get the Python datetime or date based on the specified Stata internal form (SIF) value and Stata datetime format.
getSIF(dt, format) Get the Stata internal form (SIF) value using a Stata datetime format.

Method Detail

static format(value, format)

Get the formatted Python datetime or date string based on the specified Stata internal form (SIF) value and Stata datetime format.

Parameters:
  • value (float) – Stata internal form (SIF) value.
  • format (str) – A valid Stata datetime format.
Returns:

The formatted string.

Return type:

str

Raises:

ValueError – If format is not a valid Stata date format.

static getDatetime(value, format)

Get the Python datetime or date based on the specified Stata internal form (SIF) value and Stata datetime format.

Parameters:
  • value (float) – Stata internal form (SIF) value.
  • format (str) – A valid Stata datetime format.
Returns:

The Python datetime or date if successful. Otherwise returns None.

Return type:

datetime or date

Raises:

ValueError – If format is not a valid Stata date format.

static getSIF(dt, format)

Get the Stata internal form (SIF) value using a Stata datetime format.

Parameters:
  • dt (datetime or date) – The Python datetime or date to format.
  • format (str) – A valid Stata datetime format.
Returns:

The SIF value.

Return type:

float

Raises:

ValueError – If format is not a valid Stata date format.

Examples

The following provides a few quick examples illustrating how to use this class:

>>> from sfi import Datetime
>>> import datetime
>>> dt1 = datetime.datetime(2015, 3, 31, 14, 14, 59)
>>> dt1
datetime.datetime(2015, 3, 31, 14, 14, 59)
>>> dt2 = datetime.date(1998, 5, 12)
>>> dt2
datetime.date(1998, 5, 12)
>>>
>>> Datetime.getSIF(dt1, '%tcDDmonCCYY_HH:MM:SS')
1743430499000.0
>>> Datetime.getSIF(dt2, '%td')
14011.0
>>>
>>> Datetime.getDatetime(1743430499000.0, '%tcDDmonCCYY_HH:MM:SS')
datetime.datetime(2015, 3, 31, 14, 14, 59)
>>> Datetime.getDatetime(14011.0, '%td')
datetime.date(1998, 5, 12)
>>>
>>> Datetime.format(1743430499000.0, '%tcDDmonCCYY_HH:MM:SS')
'31mar2015 14:14:59'
>>> Datetime.format(14011.0, '%td')
'12may1998'

Next we will show you a more concrete example to illustrate how to communicate between Stata and Python using the above methods. Suppose we have a dataset in memory that contains two date variables, login and hiredate, and we want to import them into Python as dates and times.

. webuse fmtxmpl2, clear
. format login %tcDDmonCCYY_HH:MM:SS.ss
. format hiredate %tdDD/NN/CCYY
. list login hiredate

    +------------------------------------+
    |                 login     hiredate |
    |------------------------------------|
 1. | 08nov2006 08:16:42.30   24/01/1986 |
 2. | 08nov2006 08:07:20.53   10/03/1994 |
 3. | 08nov2006 08:10:29.48   29/09/2006 |
 4. | 08nov2006 08:30:02.19   14/04/2006 |
 5. | 08nov2006 08:29:43.25   03/12/1999 |
    |------------------------------------|
 6. | 08nov2006 08:44:57.01   07/02/1998 |
 7. | 08nov2006 09:01:10.31   19/10/2001 |
 8. | 08nov2006 08:59:03.21   18/10/2000 |
 9. | 08nov2006 08:30:46.10   20/01/2001 |
10. | 08nov2006 08:31:00.29   27/03/2005 |
    +------------------------------------+

First, we use the get() method defined in the Data class to get the values of each variable. Then, we use the getDatetime() method to convert the values into Python dates and times.

>>> from sfi import Data, Datetime
>>> login = Data.get('login')
>>> login_dt = [Datetime.getDatetime(i, '%tcDDmonCCYY_HH:MM:SS.ss') for i in login]
>>> login_dt
[datetime.datetime(2006, 11, 8, 8, 16, 42, 300000), datetime.datetime(2006, 11, 8, 8, 7, 20, 530000),
 datetime.datetime(2006, 11, 8, 8, 10, 29, 480000), datetime.datetime(2006, 11, 8, 8, 30, 2, 190000),
 datetime.datetime(2006, 11, 8, 8, 29, 43, 250000), datetime.datetime(2006, 11, 8, 8, 44, 57, 10000),
 datetime.datetime(2006, 11, 8, 9, 1, 10, 310000), datetime.datetime(2006, 11, 8, 8, 59, 3, 210000),
 datetime.datetime(2006, 11, 8, 8, 30, 46, 100000), datetime.datetime(2006, 11, 8, 8, 31, 0, 290000)]
>>>
>>> hiredate = Data.get('hiredate')
>>> hiredate_dt = [Datetime.getDatetime(i, '%tdDD/NN/CCYY') for i in hiredate]
>>> hiredate_dt
[datetime.date(1986, 1, 24), datetime.date(1994, 3, 10), datetime.date(2006, 9, 29),
 datetime.date(2006, 4, 14), datetime.date(1999, 12, 3), datetime.date(1998, 2, 7),
 datetime.date(2001, 10, 19), datetime.date(2000, 10, 18), datetime.date(2001, 1, 20),
 datetime.date(2005, 3, 27)]

Now, we have two date and time lists, login_dt and hiredate_dt, in Python, and we want to store them in the dataset in memory. We can first create two variables, say, login_py and hiredate_py. Then, we get the Stata internal form (SIF) values using the getSIF() method and store them in Stata using the store() method defined in the Data class. Lastly, we format the two variables in Python.

>>> Data.addVarDouble('login_py')
>>> Data.addVarFloat('hiredate_py')
>>>
>>> login_py = [Datetime.getSIF(i, '%tcDDmonCCYY_HH:MM:SS.ss') for i in login_dt]
>>> Data.store('login_py', None, login_py)
>>>
>>> hiredate_py = [Datetime.getSIF(i, '%tdDD/NN/CCYY') for i in hiredate_dt]
>>> Data.store('hiredate_py', None, hiredate_py)
>>>
>>> Data.setVarFormat('login_py', '%tcDDmonCCYY_HH:MM:SS.ss')
>>> Data.setVarFormat('hiredate_py', '%tdDD/NN/CCYY')
>>> Data.list('login hiredate login_py hiredate_py')

                    login    hiredate               login_py  hiredate~y
 0  08nov2006 08:16:42.30  24/01/1986  08nov2006 08:16:42.30  24/01/1986
 1  08nov2006 08:07:20.53  10/03/1994  08nov2006 08:07:20.53  10/03/1994
 2  08nov2006 08:10:29.48  29/09/2006  08nov2006 08:10:29.48  29/09/2006
 3  08nov2006 08:30:02.19  14/04/2006  08nov2006 08:30:02.19  14/04/2006
 4  08nov2006 08:29:43.25  03/12/1999  08nov2006 08:29:43.25  03/12/1999
 5  08nov2006 08:44:57.01  07/02/1998  08nov2006 08:44:57.01  07/02/1998
 6  08nov2006 09:01:10.31  19/10/2001  08nov2006 09:01:10.31  19/10/2001
 7  08nov2006 08:59:03.21  18/10/2000  08nov2006 08:59:03.21  18/10/2000
 8  08nov2006 08:30:46.10  20/01/2001  08nov2006 08:30:46.10  20/01/2001
 9  08nov2006 08:31:00.29  27/03/2005  08nov2006 08:31:00.29  27/03/2005

In case you have lost track of what we have typed, we put our complete session in a do-file as follows:

webuse fmtxmpl2, clear

format login %tcDDmonCCYY_HH:MM:SS.ss
format hiredate %tdDD/NN/CCYY
list login hiredate

python:
from sfi import Data, Datetime
login = Data.get('login')
login_dt = [Datetime.getDatetime(i, '%tcDDmonCCYY_HH:MM:SS.ss') for i in login]
login_dt

hiredate = Data.get('hiredate')
hiredate_dt = [Datetime.getDatetime(i, '%tdDD/NN/CCYY') for i in hiredate]
hiredate_dt
end

python:
Data.addVarDouble('login_py')
Data.addVarFloat('hiredate_py')

login_py = [Datetime.getSIF(i, '%tcDDmonCCYY_HH:MM:SS.ss') for i in login_dt]
Data.store('login_py', None, login_py)

hiredate_py = [Datetime.getSIF(i, '%tdDD/NN/CCYY') for i in hiredate_dt]
Data.store('hiredate_py', None, hiredate_py)

Data.setVarFormat('login_py', '%tcDDmonCCYY_HH:MM:SS.ss')
Data.setVarFormat('hiredate_py', '%tdDD/NN/CCYY')
Data.list('login hiredate login_py hiredate_py')
end