Skip to content

[Doc]: document julian2num and num2julian? #24136

New issue
New issue
Closed
#24224
Closed
[Doc]: document julian2num and num2julian?#24136
#24224
Labels
Documentationtopic: date handling
Milestone
 
v3.7.0
@oscargus

Description

@oscargus
oscargus
opened on Oct 10, 2022

Documentation Link

https://matplotlib.org/stable/api/dates_api.html

Problem

These two methods have a decent doc-string, but are not in the documentation.

matplotlib/lib/matplotlib/dates.py

Lines 461 to 503 in 7de767e

def julian2num(j):
"""
Convert a Julian date (or sequence) to a Matplotlib date (or sequence).
Parameters
----------
j : float or sequence of floats
Julian dates (days relative to 4713 BC Jan 1, 12:00:00 Julian
calendar or 4714 BC Nov 24, 12:00:00, proleptic Gregorian calendar).
Returns
-------
float or sequence of floats
Matplotlib dates (days relative to `.get_epoch`).
"""
ep = np.datetime64(get_epoch(), 'h').astype(float) / 24.
ep0 = np.datetime64('0000-12-31T00:00:00', 'h').astype(float) / 24.
# Julian offset defined above is relative to 0000-12-31, but we need
# relative to our current epoch:
dt = JULIAN_OFFSET - ep0 + ep
return np.subtract(j, dt) # Handles both scalar & nonscalar j.
def num2julian(n):
"""
Convert a Matplotlib date (or sequence) to a Julian date (or sequence).
Parameters
----------
n : float or sequence of floats
Matplotlib dates (days relative to `.get_epoch`).
Returns
-------
float or sequence of floats
Julian dates (days relative to 4713 BC Jan 1, 12:00:00).
"""
ep = np.datetime64(get_epoch(), 'h').astype(float) / 24.
ep0 = np.datetime64('0000-12-31T00:00:00', 'h').astype(float) / 24.
# Julian offset defined above is relative to 0000-12-31, but we need
# relative to our current epoch:
dt = JULIAN_OFFSET - ep0 + ep
return np.add(n, dt) # Handles both scalar & nonscalar j.

They were added 2006-08-10

Suggested improvement

Maybe add them to the documentation?

It would make sense to add them towards the end of the page and include those and all functions after the last Locator in a new subsection "Miscellaneous date functions" or something.

Edit: looking at the source, https://github.com/matplotlib/matplotlib/blob/main/doc/api/dates_api.rst it is not really clear why they are not there...

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentationtopic: date handling

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions