special_datetime

This module converts between Python datetime and other time represenations.

It has two forms of each time conversion:

• scalar : function takes and returns only Python primatives (float,int) or datetime.datetime objects
• vector : functions generated programatically from scalar functions which take numpy arrays or lists and return numpy arrays

Array shape convention for vector functions

Vector functions output arrays which match the shape of the input. If the inputs are lists or other iterables that don’t have a shape, a flat (1D) array is returned.

Time types handled (abbreviation: description)

• ymdhms: year,month,day,hour,minute,second
• sod: decimal (float) second of day
• soy: decimal (float) second of year
• doy: decimal (float) day of year
• jd: julian date (days since 12:00 PM on January 1, 4713 B.C.)
• j2000: j2000 (julian date, but relative to January 1, 2000 at 12:00 PM)
• datenum: matlab datenumber

Naming convention

src_abbrev + ('arr' if vector else '') + '2' + dest_abbrev

For example:

• datetime2jd - converts from datetime.datetime to julian date
• sodarr2datetime - converts an array of seconds of the day to an array of datetimes

API

geospacepy.special_datetime.datenum2datetime(mlep)

Matlab epoch (datenum) to python datetime

Parameters:mlep (float) – Returns:dt Return type:datetime.datetime

geospacepy.special_datetime.datenumarr2datetime(mlep)

Matlab epoch (datenum) to python datetime (vectorized)

Parameters:mlep (float) – Returns:dt Return type:datetime.datetime

geospacepy.special_datetime.datetime2datenum(dt)

Python datetime to matlab epoch (datenum)

Parameters:dt (datetime.datetime) – Returns:mlep Return type:float

geospacepy.special_datetime.datetime2doy(dt)

Python datetime to (decimal) day of year

Parameters:dt (datetime.datetime) – Returns:doy Return type:float

geospacepy.special_datetime.datetime2j2000(dt)

Datetime to Julian date relative to j2000 Epoch (Noon on Jan 1, 2000)

Parameters:dt (datetime.datetime) – Returns:j2000 Return type:float

geospacepy.special_datetime.datetime2jd(dt)

Converts between Python datetime and Julian Date (days since 12:00 PM on January 1, 4713 B.C.) Implementation is valid from 1900-2199

Parameters:dt (datetime.datetime) – Returns:jd Return type:float

geospacepy.special_datetime.datetime2sod(dt)

Python datetime to (decimal) second of day

Parameters:dt (datetime.datetime) – Returns:sod Return type:float

geospacepy.special_datetime.datetime2soy(dt)

Datetime to second of year

Parameters:dt (datetime.datetime) – Returns:soy Return type:float

geospacepy.special_datetime.datetimearr2datenum(dt)

Python datetime to matlab epoch (datenum) (vectorized)

Parameters:dt (datetime.datetime) – Returns:mlep Return type:float

geospacepy.special_datetime.datetimearr2doy(dt)

Python datetime to (decimal) day of year (vectorized)

Parameters:dt (datetime.datetime) – Returns:doy Return type:float

geospacepy.special_datetime.datetimearr2jd(dt)

Converts between Python datetime and Julian Date (vectorized) (days since 12:00 PM on January 1, 4713 B.C.) Implementation is valid from 1900-2199

Parameters:dt (datetime.datetime) – Returns:jd Return type:float

geospacepy.special_datetime.datetimearr2sod(dt)

Python datetime to (decimal) second of day (vectorized)

Parameters:dt (datetime.datetime) – Returns:sod Return type:float

geospacepy.special_datetime.doy2datetime(doy, year)

Day of year to python datetime

Parameters:

• doy (float) –
• year (float or int) –

Returns:

dt

Return type:

datetime.datetime

geospacepy.special_datetime.doyarr2datetime(doy, year)

Day of year to python datetime (vectorized)

Parameters:

• doy (float) –
• year (float or int) –

Returns:

dt

Return type:

datetime.datetime

geospacepy.special_datetime.fastMatchTimes(primary_dt, dt, tol_us=400000.0, fail_on_duplicates=True, allow_duplicates=False)

Finds a matching timestamp in primary_dt within tolerance tol_us (given in microseconds) for every value in dt.

Parameters:

• - np.array(dtype=object), size=n (dt) – The array of timestamps (Python datetime) for which you want to find matches
• - np.array(dtype=object), size=m (primary_dt) – The array of timestamps (Python datetimes) which will be searched

Returns:

Array of len(dt) of indices into primary_dt or NaN if no match was found for a partiuclar dt value.

Return type:

inds - np.ndarray, size=n

geospacepy.special_datetime.j20002datetime(j2000)

Julian date relative to j2000 Epoch (Noon on Jan 1, 2000) to datetime

Parameters:j2000 (float) – Returns:dt Return type:datetime.datetime

geospacepy.special_datetime.jd2datetime(jd)

Converts between Julian Date (days since 12:00 PM on January 1, 4713 B.C.) and Python datetime. Implementation is valid for 1900-2199

Parameters:jd (float) – Returns:dt Return type:datetime.datetime

geospacepy.special_datetime.jdarr2datetime(jd)

Converts between Julian Date (days since 12:00 PM on January 1, 4713 B.C.) (vectorized) and Python datetime. Implementation is valid for 1900-2199

Parameters:jd (float) – Returns:dt Return type:datetime.datetime

geospacepy.special_datetime.sod2datetime(sod, year, month, day)

Second of day to datetime

Parameters:

• sod (float) –
• year (float or int) –
• month (float or int) –
• day (float or int) –

Returns:

sod

Return type:

float

geospacepy.special_datetime.sodarr2datetime(sod, year, month, day)

Second of day to datetime (vectorized)

Parameters:

• sod (float) –
• year (float or int) –
• month (float or int) –
• day (float or int) –

Returns:

sod

Return type:

float

geospacepy.special_datetime.soy2datetime(soy, year)

Second of year to datetime

Parameters:

• soy (float) –
• year (float or int) –

Returns:

dt

Return type:

datetime.datetime