Skip to content

Commit

Permalink
update time.coding.rst wrt default time unit
Browse files Browse the repository at this point in the history
  • Loading branch information
kmuehlbauer committed Dec 16, 2024
1 parent 0ba848d commit 6cb8702
Showing 1 changed file with 2 additions and 4 deletions.
6 changes: 2 additions & 4 deletions doc/internals/time-coding.rst
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ Decoding of ``values`` with time unit specification like ``seconds since 1992-10

3. As the unit (here ``seconds``) and the resolution of the reference time ``1992-10-8 15:15:42.5 -6:00`` (here ``milliseconds``) might be different, this has to be aligned to the higher resolution (retrieve new unit). User may also specify their wanted target resolution by setting kwarg ``time_unit`` to one of ``'s'``, ``'ms'``, ``'us'``, ``'ns'`` (default ``'ns'``). This will be included into the alignment process. This is done by multiplying the ``values`` by the ratio of nanoseconds per time unit and nanoseconds per reference time unit. To not break consistency for ``NaT`` a mask is kept and re-introduced after the multiplication.

4. Times encoded as floating point values are checked for fractional parts and the resolution is enhanced in an iterative process until a fitting resolution (or nansosecond) is found. A ``SerializationWarning`` is issued to make the user aware of the possibly problematic encoding.
4. Times encoded as floating point values are checked for fractional parts and the resolution is enhanced in an iterative process until a fitting resolution (or ``'ns'``) is found. A ``SerializationWarning`` is issued to make the user aware of the possibly problematic encoding.

5. Finally, the ``values`` (``int64``) are cast to ``datetime64[unit]`` (using the above retrieved unit) and added to the reference time :py:class:`pandas.Timestamp`.

Expand Down Expand Up @@ -439,6 +439,4 @@ For encoding the process is more or less a reversal of the above, but we have to
Default Time Unit
~~~~~~~~~~~~~~~~~

The default time unit of xarray is ``'s'``. It aligns well with the lower resolution of pandas. For normal operation that has no consequences on the output as all decoded datetimes are already at least in second resolution. Setting the default time unit to ``'ns'`` (the former default) the datetimes will be converted to ``'ns'``-resolution, if possible. Same holds true for ``'us'`` and ``'ms'``.

If the datetimes are decoded to ``'us'`` resolution, this resolution will be kept, even if the default resolution is set to ``'s'`` or ``'ms'``.
The current default time unit of xarray is ``'ns'``. Setting keyword argument ``time_unit`` unit to ``'s'`` (the lowest resolution pandas allows) datetimes will be converted to at least ``'s'``-resolution, if possible. Same holds true for ``'ms'`` and ``'us'``.

0 comments on commit 6cb8702

Please sign in to comment.