Period(Index) claims to be relative to 0001-01-01 00:00:00

[jorisvandenbossche]

See the docstring of PeriodIndex: https://github.com/pydata/pandas/blob/master/pandas/tseries/period.py#L557, it says:

A value of 1 is the period containing the Gregorian proleptic datetime Jan 1, 0001 00:00:00.
This ordinal representation is from the scikits.timeseries project.

For instance,
    # construct period for day 1/1/1 and get the first second
    i = Period(year=1,month=1,day=1,freq='D').asfreq('S', 'S')
    i.ordinal
    ===> 1

but that is not really the truth:

In [24]: pd.Period('1970-01-01', freq='D')
Out[24]: Period('1970-01-01', 'D')

In [25]: pd.Period('1970-01-01', freq='D').ordinal
Out[25]: 0

In [34]: pd.Period(year=1,month=1,day=1,freq='D').ordinal
Out[34]: -719162

[jreback]

no this is NOT true, nor guaranteed. A period index is a mapping between arbitrary (well freq based integers and the periods).

[jorisvandenbossche]

Something else a bit strange:

In [33]: pd.Period('0001-01-01', freq='D')
Out[33]: Period('2001-01-01', 'D')

Is this expected or a bug? (returns 2001 instead of 0001)

[jorisvandenbossche]

But isn't it just a mapping of the number of periods of a certain freq relative to 1970-01-01 ? Or is that also not guaranteed?

[jreback]

no, has no fixed date at all, that's the whole point, they can represent ANY datetime. Timestamps are the opposite, they have really fine precision but limited range.

In [19]: pd.period_range('2013',freq='Y',periods=5)
Out[19]: 
<class 'pandas.tseries.period.PeriodIndex'>
[2013, ..., 2017]
Length: 5, Freq: A-DEC

In [20]: pd.period_range('2013',freq='Y',periods=5).values
Out[20]: array([43, 44, 45, 46, 47])

[jorisvandenbossche]

but still, the values in your example are just the number of periods (years) since 1970. I know it is not a 'fixed' moment in time, but the underlying representation is well defined no? Or do I miss something?
I mean, in that case, we could just update those docstring to say it is relative to 1970 instead of 0001

[jreback]

some codes ARE relative, but it depends on the frequency. This is implementation detail.
It might be tied to 1970 for some frequencies. Its an 'arbitrary' mapping. (though it may have some basis in the 1970).

The only point of the differening numbers is for disambiguation. They could be anything.

In [16]: pd.period_range('1000',periods=5,freq='Y')       
Out[16]: 
<class 'pandas.tseries.period.PeriodIndex'>
[1000, ..., 1004]
Length: 5, Freq: A-DEC

 [13]: pd.period_range('1000',periods=5,freq='Y').values
Out[13]: array([-970, -969, -968, -967, -966])

In [15]: pd.period_range('1000',periods=5,freq='D')       
Out[15]: 
<class 'pandas.tseries.period.PeriodIndex'>
[1000-01-01, ..., 1000-01-05]
Length: 5, Freq: D

In [14]: pd.period_range('1000',periods=5,freq='D').values
Out[14]: array([-354285, -354284, -354283, -354282, -354281])