Repository: pandas-dev/pandas

Issue:
Period(Index) claims to be relative to 0001-01-01 00:00:00
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
```



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

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)

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?

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])
```

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

_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])
```


Resolving patch:
diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py
--- a/pandas/core/indexes/period.py
+++ b/pandas/core/indexes/period.py
@@ -125,15 +125,7 @@ def _new_PeriodIndex(cls, **d):
 class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index):
     """
     Immutable ndarray holding ordinal values indicating regular periods in
-    time such as particular years, quarters, months, etc. 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
+    time such as particular years, quarters, months, etc.
 
     Index keys are boxed to Period objects which carries the metadata (eg,
     frequency information).


Test patch: