Skip to content

DOC: Clarify doc for converting timestamps to epoch #57777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

DOC: Clarify doc for converting timestamps to epoch #57777

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions doc/source/user_guide/timeseries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -379,6 +379,17 @@ We subtract the epoch (midnight at January 1, 1970 UTC) and then floor divide by

(stamps - pd.Timestamp("1970-01-01")) // pd.Timedelta("1s")

.. note::


We encourage explicitly subtracting 1970-01-01 from the timestamps over using the
``.timestamp`` method because the ``Timestamp.timestamp`` method in pandas exhibits a
distinct behavior compared to ``datetime.timestamp``, particularly in cases involving
timezone-naive (tznaive) instances. Specifically, ``Timestamp.timestamp`` treats
timezone-naive datetime objects as UTC by default while the ``datetime.timestamp``
method treats them as implicitly belonging to the system's local timezone.
Comment on lines +385 to +390
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @tqa236, but while you say it's true, I think @jbrockmendel's comment was taken out of context.

The reason we are manually substracting the date in the example above it's not because datetime.datetime.timestamp uses the local timezone, which we don't like. The reason is because the stamps object is a DateTimeIndex which doesn't implement a method to get the epoch value. Personally, it feels a bit strange to have this section in the user guide and not have a timestamp method in both DateTimeIndex and the dt accessor. That's a different topic that we can discuss, but for now, there are two independent things getting mixed here:

  • Whether we want to continue to use the manual subtraction in the example, or we want another alternative like the one proposed in the issue stamps.map(lambda x: x.timestamp()) (which does not use the local timezone)
  • Adding a note clarifying that pandas' Timestamp.timestamp is different from datetime.datetime.timestamp for timezone-naive objects

I think for this PR it's fine to keep the note (the beginning should be changed) since there is no .timestamp method as you say, and if recommend subtracting the date is because there is no other vectorized way (that I know) using the public API. But that would be unrelated to the note, and it's what I'd address in a second PR, after further discussion in the issue on what we really want to do:

  • Do recommend subtracting the dates
  • Implement .timestamp
  • Recommend using the simpler not vectorized way with .map

@jbrockmendel @MarcoGorelli does it make sense to you what I say?



.. _timeseries.origin:

Using the ``origin`` parameter
Expand Down