1.2. igsn_lib.time¶

This libary provides some convenience methods for working with Julian dates.

A Julian Date is a floating point value that identifies the number of days before or after -4713-11-24 12:00:00.000 UTC. The range is unlimited, for example the estimated age of the universe is about 13.787 billion years [1], and that date is far outside of the common operating parameters for databases and many programmatic representations of time.

In JD, the start of the universe can be reliably expressed as approximately:

import astropy.time
tstart = astropy.time.Time(-13.787E9, format='jyear')
jd = tstart.jd
print(f"Universe started on Julian Date: {jd}")

Universe started on Julian Date: -5035700028955.0

The start of the universe can not be expressed in a python datetime:

try:
  print(tstart.to_datetime(datetime.timezone.utc))
except Exception as e:
  print(f"ERROR: with timezone: {e}")
try:
  print(tstart.to_datetime())
except Exception as e:
  print(f"ERROR: without timezone: {e}")

ERROR: with timezone: name 'datetime' is not defined
ERROR: without timezone: ERFA function "d2dtf" yielded 1 of "unacceptable date (Note 6)"

Julian dates are equally applicable to the current time (and future). For example, this page was last edited:

import datetime
jd = astropy.time.Time(datetime.datetime.now(datetime.timezone.utc)).jd
print(f"It is now: {jd}")

It is now: 2459626.400176718

Julian dates can be used to provide a consistent representation of geological time boundaries, albeit at a higher resolution than the actual boundaries can be determined. For example the Cenozoic [2] period ranges from 66 million years ago to modern time. This can be expressed in JD as:

cenozoic = (
  astropy.time.Time(-66E6, format='jyear').jd,
  astropy.time.Time(1950, format='jyear').jd,
)
print(f"The cenozoic period is JD {cenozoic[0]:.0f} to JD {cenozoic[1]:.0f}.")

The cenozoic period is JD -24104778955 to JD 2433282.

Positions in archeologic and ‘recent’ geologic time are conventionally denoted in years, measured backwards from the present, which is fixed to 1950 when the precision requires it.

The start of the cenozoic is the Cretaceous-Paleogene Boundary (KBP, [3]) determined to be 66.038 +- 0.025/0.049 Ma [4]. That translates to JD:

c0 = astropy.time.Time(-66.038E6, format='jyear').jd
c1 = 365*1E6*0.025
c2 = 365*1E6*0.049
print(f"Cenozoic start = {c0:.0f} +- {c1:.0f}/{c2:.0f}")

Cenozoic start = -24118658455 +- 9125000/17885000

Methods

The following methods are provided in the igsn_lib.time module:

`bceToJd`(bce)	Convert BCE date to Julian date, where 1 BCE = year 0000.
`datetimeDeltaToSeconds`(dtd)
`datetimeFromSomething`(V)
`datetimeToJD`(dt)	Convert a python datetime to Julian date.
`datetimeToJsonStr`(dt)
`dtnow`()	Get datetime for now in UTC timezone.
`jdFromString`(tstr)	Julian date from string representation of time.
`jdToBCE`(jd)	Convert Julian date to BCE, where 1 BCE = year 0000.
`jdToDateTime`(jd)	Convert Julian date to datetime.
`jdToJsonString`(jd)	Convert Julian date to a JSON datetime string.
`jdToMa`(jd)	Convert Julian date to Ma (millions of years ago).
`jdToOAIPMHString`(jd)	Convert Julian date to an OAI-PMH acceptable datetime string.
`jdToString`(jd, format_str)	Convert Julian date to a string representation
`jdnow`()	Current Julian date.
`maToJd`(Ma)	Convert Ma (millions of years ago) to Julian date.

Detail

Time handling routines for igsn_lib.

igsn_lib.time.JSON_TIME_FORMAT = '%Y-%m-%dT%H:%M:%S%z'¶: datetime format string for generating JSON content

igsn_lib.time.OAI_TIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'¶: datetime format string for generating OAI-PMH requests

igsn_lib.time.bceToJd(bce)[source]¶

Convert BCE date to Julian date, where 1 BCE = year 0000.

Positive BCE years are older than year 0000.

Parameters:: bce – float, years BCE
Returns:: float, Julian date

Example

import igsn_lib.time
print(igsn_lib.time.bceToJd(-1))

1721410.25

igsn_lib.time.datetimeDeltaToSeconds(dtd)[source]¶

igsn_lib.time.datetimeFromSomething(V)[source]¶

igsn_lib.time.datetimeToJD(dt)[source]¶

Convert a python datetime to Julian date.

Naive datetime is assumed to be UTC.

Parameters:: dt – datetime.datetime
Returns:: float, Julian date

Example

import igsn_lib.time
import datetime

dt = datetime.datetime.now(datetime.timezone.utc)
print(dt)
print(igsn_lib.time.datetimeToJD(dt))

2022-02-15 21:36:15.734862+00:00
2459626.4001821163

igsn_lib.time.datetimeToJsonStr(dt)[source]¶

igsn_lib.time.dtnow()[source]¶

Get datetime for now in UTC timezone.

Returns:: datetime.datetime with UTC timezone

Example

import igsn_lib.time
print(igsn_lib.time.dtnow())

2022-02-15 21:36:15.742878+00:00

igsn_lib.time.jdFromString(tstr)[source]¶

Julian date from string representation of time.

Uses dateparser.parse to get date time from the string.

See https://dateparser.readthedocs.io/en/latest/

Parameters:: tstr – string, time in text.
Returns:: float, Julian date

Example

import igsn_lib.time

print(igsn_lib.time.jdFromString("now"))
print(igsn_lib.time.jdFromString("100 years ago"))
print(igsn_lib.time.jdFromString("2020-08-15 16:30:00 ET"))

2459626.40018275
2423101.400182816
2459077.3958333335

igsn_lib.time.jdToBCE(jd)[source]¶

Convert Julian date to BCE, where 1 BCE = year 0000.

Positive BCE years are older than year 0000.

Parameters:: jd – Julian Date
Returns:: float, BCE year

Example

import igsn_lib.time
print(igsn_lib.time.jdToBCE(0.0))

4712.964407939768

igsn_lib.time.jdToDateTime(jd)[source]¶

Convert Julian date to datetime.

Note that Julian date values can exceed the range supported by python datetime, in which case astropy or datetime will raise an exception, and this method will return None.

Parameters:: jd – float, Julian date/
Returns:: datetime with UTC timezone or None

Example

import igsn_lib.time
print(igsn_lib.time.jdToDateTime(2459125.5))

2020-10-03 00:00:00+00:00

igsn_lib.time.jdToJsonString(jd)[source]¶

Convert Julian date to a JSON datetime string.

Parameters:: jd – float, Julian date
Returns:: string or None on error

Example

import igsn_lib.time
print(igsn_lib.time.jdToJsonString(2459125.5))

2020-10-03T00:00:00+0000

igsn_lib.time.jdToMa(jd)[source]¶

Convert Julian date to Ma (millions of years ago).

Note that positive Ma values are in the past.

By convention, 0Ma = 1950 present time..

Parameters:: jd – float, Julian date
Returns:: float, Ma

Example

import igsn_lib.time
print(igsn_lib.time.jdToMa(-363521138))

0.999978598220397

igsn_lib.time.jdToOAIPMHString(jd)[source]¶

Convert Julian date to an OAI-PMH acceptable datetime string.

Parameters:: jd – float, Julian date
Returns:: string or None on error

Example

import igsn_lib.time
print(igsn_lib.time.jdToOAIPMHString(2459125.5))

2020-10-03T00:00:00Z

igsn_lib.time.jdToString(jd, format_str)[source]¶

Convert Julian date to a string representation

Parameters:

jd – float, Julian date
format_str – python strftime format string

Returns:

string

Example

import igsn_lib.time
print(igsn_lib.time.jdToString(2459125.5, "%Y%m%d"))

20201003

igsn_lib.time.jdnow()[source]¶

Current Julian date.

Returns:: float, Julian date

Example

import igsn_lib.time
print(igsn_lib.time.jdnow())

2459626.4001837736

igsn_lib.time.maToJd(Ma)[source]¶

Convert Ma (millions of years ago) to Julian date.

Note that positive Ma values are in the past.

Parameters:: Ma – float, millions of years ago
Returns:: float, Julian date

Example

import igsn_lib.time
print(igsn_lib.time.maToJd(-1.0))

366971045.0

1.1. igsn_lib Package 1.3. igsn_lib.oai

igsn_lib 0.1 documentation

1.2. igsn_lib.time¶