DateHandler

When working with Casys Tools you will use dates in many different places.

  • To define time intervals to work on

  • To define time selection criteria

  • To define time events

All of this can be done using DateHandler.
DateHandler is a utility class allowing to create dates from many formats including python, numpy and pandas dates as well as altimetric related dates like ORF or julian days.
In addition to creating dates from different formats it can convert from one format to another.
DateHandler is a utility class allowing to create dates from many
formats::

    strings:
        DateHandler("12/04/11 20:30:40") -> 12 april 2011
        DateHandler("12/04/11 20:30:40", yearfirst=True) -> 4 november 2012
        DateHandler("12/04/11 20:30:40", dayfirst=False) -> 4 december 2011
        DateHandler("12/04/11 20:30:40", dayfirst=False, yearfirst=True)
         -> 11 april 2012
        DateHandler("20 april 2019 at 20h30")
    julian days:
        DateHandler.from_julian_day(20450)
        DateHandler.from_julian_day((20450, 10, 25450))
    cycle and pass:
        DateHandler.from_orf("C_J3", 122, 1, pos="first")
        DateHandler.from_orf("C_J3", 1, 250, pos="equator")
        DateHandler.from_orf("C_J3", 1, 250, pos="last")
    matplotlib:
        DateHandler.from_mpl(10265)

Parameters
----------
date
    Date as str, datetime or any format you can think of.
kwargs
    Pandas.to_datetime parameters.

Creating a date

From a string

from casys import DateHandler

DateHandler("2020/06/02 13:40:12")

2020-06-02 13:40:12

From an ORF

Generate a date using cycle/pass information contained in an ORF.

Parameters
----------
orf
    Orf or its name/path.
cycle_nb
    Cycle number.
pass_nb
    Pass number.
pos
    Position to get the date from (first, equator or last).
method
    Search method allowing to find the closest pass in the provided direction.
     * before
     * before_or_equal
     * equal
     * after_or_equal
     * after

Returns
-------
:
    A DateHandler object.

from casys import DateHandler

my_date = DateHandler.from_orf(orf="C_J3_GDRD", cycle_nb=122, pass_nb=1, pos="first")
my_date

2019-06-01 05:30:29.807497

Converting a date

To a pandas.Timestamp

my_date.date

Timestamp('2019-06-01 05:30:29.807497')

To a numpy.datetime64

my_date.date_np

np.datetime64('2019-06-01T05:30:29.807497')

To a matplotlib date (useful when working with plots)

my_date.date_mpl

np.float64(18048.229511660844)

To cycle/pass information

Convert to (cycle, pass) tuple.

Parameters
----------
orf
    Orf or its name/path.
method
    Search method allowing to find the closest pass in the provided direction.
     * before
     * before_or_equal
     * equal
     * after_or_equal
     * after

Returns
-------
:
    (cycle, pass) tuple.

my_date.to_cycle_pass(orf="C_J3_GDRD")

(122, 1)

To a julian days float

Convert to julian days as a float.

Parameters
----------
reference
    reference date from where julian days start.
    Default value is :py:data:`CNES_DATE_REFERENCE`

Returns
-------
:
    The julian day as a float

my_date.to_julian_fday()

np.float64(25353.229511660844)

To a julian days, seconds, micro-seconds

Convert to julian days as a tuple.

Parameters
----------
reference
    reference date from where julian days start.
    Default value is :py:data:`CNES_DATE_REFERENCE`

Returns
-------
:
    The julian day as a tuple (days, seconds in day, microseconds in second).

my_date.to_julian_day()

(25353, 19829, 807497)

Exploring ORF content

DateHandler orf_cycles() and orf_passes() methods allow to visualize the list of cycles and passes covered by an ORF.
Provide the list of cycles included in the given ORF along with
their starting and ending dates.

Parameters
----------
orf
    Orf or its name/path.
cycle_min
    Minimum number of the cycle to include.
cycle_max
    Maximum number of the cycle to include.

Returns
-------
:
    List of cycles.

A full list of cycles as well as a subset can be visualized:

DateHandler.orf_cycles(orf="C_J3_GDRD", cycle_min=122, cycle_max=135)
Cycle # Starting date Ending date
122 2019-06-01T05:30:29 2019-06-11T03:29:01
123 2019-06-11T03:29:01 2019-06-21T01:27:33
124 2019-06-21T01:27:33 2019-06-30T23:26:04
125 2019-06-30T23:26:04 2019-07-10T21:24:35
126 2019-07-10T21:24:35 2019-07-20T19:23:06
127 2019-07-20T19:23:06 2019-07-30T17:21:37
128 2019-07-30T17:21:37 2019-08-09T15:20:08
129 2019-08-09T15:20:08 2019-08-19T13:18:39
130 2019-08-19T13:18:40 2019-08-29T11:17:12
131 2019-08-29T11:17:12 2019-09-08T09:15:43
132 2019-09-08T09:15:44 2019-09-18T07:14:15
133 2019-09-18T07:14:15 2019-09-28T05:12:47
134 2019-09-28T05:12:47 2019-10-08T03:11:18
135 2019-10-08T03:11:19 2019-10-18T01:09:49 
Return the list of passes of the given cycle along with their
starting and ending dates.

Parameters
----------
orf
    Orf or its name/path.
cycle_nb
    Cycle number.
pass_min
    Minimum number of the pass to include.
pass_max
    Maximum number of the pass to include.

Returns
-------
:
    List of passes.

Same goes for the list of passes of a given cycle.

DateHandler.orf_passes(orf="C_J3_GDRD", cycle_nb=122, pass_max=10)
Pass # Starting date Ending date
1 2019-06-01T05:30:29 2019-06-01T06:26:41
2 2019-06-01T06:26:42 2019-06-01T07:22:55
3 2019-06-01T07:22:55 2019-06-01T08:19:08
4 2019-06-01T08:19:08 2019-06-01T09:15:21
5 2019-06-01T09:15:21 2019-06-01T10:11:34
6 2019-06-01T10:11:34 2019-06-01T11:07:47
7 2019-06-01T11:07:47 2019-06-01T12:03:59
8 2019-06-01T12:03:59 2019-06-01T13:00:12
9 2019-06-01T13:00:12 2019-06-01T13:56:24
10 2019-06-01T13:56:25 2019-06-01T14:52:38

Note

These orf_cycles() and orf_passes() methods return a python object designed to have a readable output in notebooks.
Using the data attribute on the output transform the result to a list of tuples containing (cycle or pass number, starting date, ending date) allowing to programmatically use and iterate over these data.
DateHandler.orf_passes(orf="C_J3_GDRD", cycle_nb=122, pass_max=10).data

[(1,
  np.datetime64('2019-06-01T05:30:29.807497'),
  np.datetime64('2019-06-01T06:26:41.577266')),
 (2,
  np.datetime64('2019-06-01T06:26:42.595975'),
  np.datetime64('2019-06-01T07:22:55.085157')),
 (3,
  np.datetime64('2019-06-01T07:22:55.543576'),
  np.datetime64('2019-06-01T08:19:08.256378')),
 (4,
  np.datetime64('2019-06-01T08:19:08.358249'),
  np.datetime64('2019-06-01T09:15:21.210770')),
 (5,
  np.datetime64('2019-06-01T09:15:21.414510'),
  np.datetime64('2019-06-01T10:11:34.072981')),
 (6,
  np.datetime64('2019-06-01T10:11:34.174852'),
  np.datetime64('2019-06-01T11:07:47.045807')),
 (7,
  np.datetime64('2019-06-01T11:07:47.198613'),
  np.datetime64('2019-06-01T12:03:59.113426')),
 (8,
  np.datetime64('2019-06-01T12:03:59.928395'),
  np.datetime64('2019-06-01T13:00:12.501012')),
 (9,
  np.datetime64('2019-06-01T13:00:12.908496'),
  np.datetime64('2019-06-01T13:56:24.632179')),
 (10,
  np.datetime64('2019-06-01T13:56:25.650889'),
  np.datetime64('2019-06-01T14:52:38.134732'))]