Skip to content

Commit fec6a99

Browse files
author
maddogghoek
committed
copy and update cftime_range() documentation notes to date_range() (pydata#9886)
1 parent 1076dab commit fec6a99

File tree

1 file changed

+144
-2
lines changed

1 file changed

+144
-2
lines changed

‎xarray/coding/cftime_offsets.py

+144-2
Original file line numberDiff line numberDiff line change
@@ -1128,7 +1128,7 @@ def cftime_range(
11281128
pandas.date_range
11291129
"""
11301130
emit_user_level_warning(
1131-
"cftime_range() is deprecated, please use xarray.date_range(use_cftime=True) instead.",
1131+
"cftime_range() is deprecated, please use xarray.date_range(..., use_cftime=True) instead.",
11321132
DeprecationWarning,
11331133
stacklevel=2,
11341134
)
@@ -1270,12 +1270,154 @@ def date_range(
12701270
If True, always return a CFTimeIndex.
12711271
If False, return a pd.DatetimeIndex if possible or raise a ValueError.
12721272
If None (default), return a pd.DatetimeIndex if possible,
1273-
otherwise return a CFTimeIndex. Defaults to False if `tz` is not None.
1273+
otherwise return a CFTimeIndex. Overridden to False if `tz` is not None.
12741274
12751275
Returns
12761276
-------
12771277
CFTimeIndex or pd.DatetimeIndex
12781278
1279+
Notes
1280+
-----
1281+
When use_cftime=True, this function is an analog of ``pandas.date_range``
1282+
for use in generating sequences of ``cftime.datetime`` objects. It supports most of the
1283+
features of ``pandas.date_range`` (e.g. specifying how the index is
1284+
``closed`` on either side, or whether or not to ``normalize`` the start and
1285+
end bounds); however, there are some notable exceptions:
1286+
1287+
- You cannot specify a ``tz`` (time zone) argument.
1288+
- Start or end dates specified as partial-datetime strings must use the
1289+
`ISO-8601 format <https://en.wikipedia.org/wiki/ISO_8601>`_.
1290+
- It supports many, but not all, frequencies supported by
1291+
``pandas.date_range``. For example it does not currently support any of
1292+
the business-related or semi-monthly frequencies.
1293+
- Compound sub-monthly frequencies are not supported, e.g. '1H1min', as
1294+
these can easily be written in terms of the finest common resolution,
1295+
e.g. '61min'.
1296+
1297+
Valid simple frequency strings for use with ``cftime``-calendars include
1298+
any multiples of the following.
1299+
1300+
+--------+--------------------------+
1301+
| Alias | Description |
1302+
+========+==========================+
1303+
| YE | Year-end frequency |
1304+
+--------+--------------------------+
1305+
| YS | Year-start frequency |
1306+
+--------+--------------------------+
1307+
| QE | Quarter-end frequency |
1308+
+--------+--------------------------+
1309+
| QS | Quarter-start frequency |
1310+
+--------+--------------------------+
1311+
| ME | Month-end frequency |
1312+
+--------+--------------------------+
1313+
| MS | Month-start frequency |
1314+
+--------+--------------------------+
1315+
| D | Day frequency |
1316+
+--------+--------------------------+
1317+
| h | Hour frequency |
1318+
+--------+--------------------------+
1319+
| min | Minute frequency |
1320+
+--------+--------------------------+
1321+
| s | Second frequency |
1322+
+--------+--------------------------+
1323+
| ms | Millisecond frequency |
1324+
+--------+--------------------------+
1325+
| us | Microsecond frequency |
1326+
+--------+--------------------------+
1327+
1328+
Any multiples of the following anchored offsets are also supported.
1329+
1330+
+------------+--------------------------------------------------------------------+
1331+
| Alias | Description |
1332+
+============+====================================================================+
1333+
| Y(E,S)-JAN | Annual frequency, anchored at the (end, beginning) of January |
1334+
+------------+--------------------------------------------------------------------+
1335+
| Y(E,S)-FEB | Annual frequency, anchored at the (end, beginning) of February |
1336+
+------------+--------------------------------------------------------------------+
1337+
| Y(E,S)-MAR | Annual frequency, anchored at the (end, beginning) of March |
1338+
+------------+--------------------------------------------------------------------+
1339+
| Y(E,S)-APR | Annual frequency, anchored at the (end, beginning) of April |
1340+
+------------+--------------------------------------------------------------------+
1341+
| Y(E,S)-MAY | Annual frequency, anchored at the (end, beginning) of May |
1342+
+------------+--------------------------------------------------------------------+
1343+
| Y(E,S)-JUN | Annual frequency, anchored at the (end, beginning) of June |
1344+
+------------+--------------------------------------------------------------------+
1345+
| Y(E,S)-JUL | Annual frequency, anchored at the (end, beginning) of July |
1346+
+------------+--------------------------------------------------------------------+
1347+
| Y(E,S)-AUG | Annual frequency, anchored at the (end, beginning) of August |
1348+
+------------+--------------------------------------------------------------------+
1349+
| Y(E,S)-SEP | Annual frequency, anchored at the (end, beginning) of September |
1350+
+------------+--------------------------------------------------------------------+
1351+
| Y(E,S)-OCT | Annual frequency, anchored at the (end, beginning) of October |
1352+
+------------+--------------------------------------------------------------------+
1353+
| Y(E,S)-NOV | Annual frequency, anchored at the (end, beginning) of November |
1354+
+------------+--------------------------------------------------------------------+
1355+
| Y(E,S)-DEC | Annual frequency, anchored at the (end, beginning) of December |
1356+
+------------+--------------------------------------------------------------------+
1357+
| Q(E,S)-JAN | Quarter frequency, anchored at the (end, beginning) of January |
1358+
+------------+--------------------------------------------------------------------+
1359+
| Q(E,S)-FEB | Quarter frequency, anchored at the (end, beginning) of February |
1360+
+------------+--------------------------------------------------------------------+
1361+
| Q(E,S)-MAR | Quarter frequency, anchored at the (end, beginning) of March |
1362+
+------------+--------------------------------------------------------------------+
1363+
| Q(E,S)-APR | Quarter frequency, anchored at the (end, beginning) of April |
1364+
+------------+--------------------------------------------------------------------+
1365+
| Q(E,S)-MAY | Quarter frequency, anchored at the (end, beginning) of May |
1366+
+------------+--------------------------------------------------------------------+
1367+
| Q(E,S)-JUN | Quarter frequency, anchored at the (end, beginning) of June |
1368+
+------------+--------------------------------------------------------------------+
1369+
| Q(E,S)-JUL | Quarter frequency, anchored at the (end, beginning) of July |
1370+
+------------+--------------------------------------------------------------------+
1371+
| Q(E,S)-AUG | Quarter frequency, anchored at the (end, beginning) of August |
1372+
+------------+--------------------------------------------------------------------+
1373+
| Q(E,S)-SEP | Quarter frequency, anchored at the (end, beginning) of September |
1374+
+------------+--------------------------------------------------------------------+
1375+
| Q(E,S)-OCT | Quarter frequency, anchored at the (end, beginning) of October |
1376+
+------------+--------------------------------------------------------------------+
1377+
| Q(E,S)-NOV | Quarter frequency, anchored at the (end, beginning) of November |
1378+
+------------+--------------------------------------------------------------------+
1379+
| Q(E,S)-DEC | Quarter frequency, anchored at the (end, beginning) of December |
1380+
+------------+--------------------------------------------------------------------+
1381+
1382+
Finally, the following calendar aliases are supported.
1383+
1384+
+--------------------------------+---------------------------------------+----------------------------+
1385+
| Alias | Date type | Available use_cftime=False |
1386+
+================================+=======================================+============================+
1387+
| standard, gregorian | ``cftime.DatetimeGregorian`` | True |
1388+
+--------------------------------+---------------------------------------+----------------------------+
1389+
| proleptic_gregorian | ``cftime.DatetimeProlepticGregorian`` | True |
1390+
+--------------------------------+---------------------------------------+----------------------------+
1391+
| noleap, 365_day | ``cftime.DatetimeNoLeap`` | False |
1392+
+--------------------------------+---------------------------------------+----------------------------+
1393+
| all_leap, 366_day | ``cftime.DatetimeAllLeap`` | False |
1394+
+--------------------------------+---------------------------------------+----------------------------+
1395+
| 360_day | ``cftime.Datetime360Day`` | False |
1396+
+--------------------------------+---------------------------------------+----------------------------+
1397+
| julian | ``cftime.DatetimeJulian`` | False |
1398+
+--------------------------------+---------------------------------------+----------------------------+
1399+
1400+
As in the standard pandas function, three of the ``start``, ``end``,
1401+
``periods``, or ``freq`` arguments must be specified at a given time, with
1402+
the other set to ``None`` if use_cftime=False. If use_cftime=True, exactly
1403+
3 of the 4 can be set or 2 out of ``start``, ``end``, and``periods`` can be
1404+
set and ``freq`` will default to 'D'. See the `pandas documentation
1405+
<https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html>`_
1406+
for more examples of the behavior of ``date_range`` with each of the
1407+
parameters.
1408+
1409+
Examples
1410+
--------
1411+
This function returns a ``CFTimeIndex``, populated with ``cftime.datetime``
1412+
objects associated with the specified calendar type, e.g.
1413+
1414+
>>> xr.date_range(
1415+
... start="2000", periods=6, freq="2MS", calendar="noleap", use_cftime=True
1416+
... )
1417+
CFTimeIndex([2000-01-01 00:00:00, 2000-03-01 00:00:00, 2000-05-01 00:00:00,
1418+
2000-07-01 00:00:00, 2000-09-01 00:00:00, 2000-11-01 00:00:00],
1419+
dtype='object', length=6, calendar='noleap', freq='2MS')
1420+
12791421
See also
12801422
--------
12811423
pandas.date_range

0 commit comments

Comments
 (0)