# spacepy.time.Ticktock

class spacepy.time.Ticktock(data, dtype)

  Ticktock class holding various time coordinate systems (TAI, UTC, ISO, JD, MJD, GPS, UNX, RDT, CDF, DOY, eDOY, APT)

  Possible input data types:

  ISO

    ISO standard format like ‘2002-02-25T12:20:30’

  UTC

    datetime object with UTC time

  TAI

    Elapsed seconds since 1958-1-1 (includes leap seconds)

  GPS

    Elapsed seconds since 1980-1-6 (includes leap seconds)

  UNX

    Elapsed seconds since 1970-1-1 ignoring leapseconds (all days have 86400 secs).

  JD

    Julian days elapsed

  MJD

    Modified Julian days

  RDT

    Rata Die days elapsed since 0001-1-1

  CDF

    CDF Epoch type: float milliseconds since 0000-1-1 ignoring leapseconds

  APT

    AstroPy `Time`. Requires AstroPy 1.0. (New in version 0.2.2.)

  Possible output data types: All those listed above, plus:

  DOY

    Integer day of year, starts with day 1

  eDOY

    Fractional day of year, starts at day 0

  It is strongly recommended to access various time systems via the attributes listed above, as in the examples. They will be calculated automatically if necessary. Using the `get` methods will force a recalculation.

  The original input data will always be available as the `data` attribute.

  Changed in version 0.2.2: In earlier versions of SpacePy, most values were derived from the `datetime`-based `UTC` representation. This did not properly handle leap seconds in many cases. Now most are derived from `TAI` (exceptions being `DOY` and `eDOY`). In addition to differences around actual leap seconds, this may result in small differences between versions of SpacePy, with relative magnitude on the order of the resolution of a 64-bit float (2e-16). For times in the modern era, this is about 50 microseconds (us) for `JD`, 15 us for `CDF`, 1.5 us for `RDT`, 1 us for `MJD`, and 360 nanoseconds for `TAI`.

  The relationships between parameters and how they are calculated are listed in the `get` methods and illustrated below.

  Parameters:
    data array_like (int, datetime, float, string)

      time stamp

    dtype string {CDF, ISO, UTC, TAI, ‘GPS’, UNX, JD, MJD, RDT, APT} or function

      data type for data, if a function it must convert input time format to Python datetime

  Returns:
    out Ticktock

      instance with self.data, self.dtype, self.UTC etc

  Other Parameters:
    isoformat str, optional

      New in version 0.2.2.

      Format string used for parsing and outputting ISO format. Input is not forced to be in this format; it is tried first, and other common formats tried if parsing fails. Because of this, if ISO input is in a consistent format, specifying this can speed up the input parsing. Can be changed on existing `Ticktock` with `isoformat()` method. Default `'%Y-%m-%dT%H:%M:%S'`.

  See also

  `datetime.datetime.strptime`, `isoformat`

  Notes

  UTC data type is implemented as Python datetime, which cannot represent leap seconds. The time within a leap second is regarded as not happening.

  The CDF data type is the older CDF_EPOCH time type, not the newer CDF_TIME_TT2000. It similarly cannot represent leap seconds. Year 0 is considered a leap year.

  Examples

      >>> x = Ticktock([2452331.0142361112, 2452332.0142361112], 'JD')
      >>> x.ISO
      dmarray(['2002-02-25T12:20:30', '2002-02-26T12:20:30'], dtype='|S19')
      >>> x.DOY # Day of year
      dmarray([ 56.,  57.])
      >>> y = Ticktock(['01-01-2013', '20-03-2013'], lambda x: datetime.datetime.strptime(x, '%d-%m-%Y'))
      >>> y.UTC
      dmarray([2013-01-01 00:00:00, 2013-03-20 00:00:00], dtype=object)
      >>> y.DOY # Day of year
      dmarray([  1.,  79.])

  `append`(other) | Will be called when another Ticktock instance has to be appended to the current one
  `argsort`() | This will return the indices that would sort the Ticktock values
  `convert`(dtype) | convert a Ticktock instance into a new time coordinate system provided in dtype
  `getAPT`() | a.APT or a.getAPT()
  `getCDF`() | a.getCDF() or a.CDF
  `getDOY`() | a.DOY or a.getDOY()
  `getGPS`() | a.GPS or a.getGPS()
  `getISO`() | a.ISO or a.getISO()
  `getJD`() | a.JD or a.getJD()
  `getMJD`() | a.MJD or a.getMJD()
  `getRDT`() | a.RDT or a.RDT()
  `getTAI`() | a.TAI or a.getTAI()
  `getUNX`() | a.UNX or a.getUNX()
  `getUTC`() | a.UTC or a.getUTC()
  `geteDOY`() | a.eDOY or a.geteDOY()
  `getleapsecs`() | a.leaps or a.getleapsecs()
  `isoformat`(b, attrib) | This changes the self._isofmt attribute by and subsequently this function will update the ISO attribute.
  `now`() | Create Ticktock with the current UTC time.
  `sort`() | This will sort the Ticktock values in place based on the values in data.
  `today`() | Create Ticktock with the current UTC date and time set to 00:00:00
  `update_items`(attrib) | After changing the self.data attribute by either __setitem__ or __add__ etc this function will update all other attributes.

  append(other)

    Will be called when another Ticktock instance has to be appended to the current one

    Parameters:
      other Ticktock

        other (Ticktock instance)

  argsort()

    This will return the indices that would sort the Ticktock values

    Returns:
      out list

        indices that would sort the Ticktock values

    Other Parameters:
      kind str, optional

        Sort algorithm to use, default ‘quicksort’.

        Changed in version 0.2.2: Default is now ‘quicksort’ to match numpy default; previously was ‘mergesort’.

    See also

    `argsort`, `numpy.argsort`
  convert(dtype)

    convert a Ticktock instance into a new time coordinate system provided in dtype

    Parameters:
      dtype string

        data type for new system, possible values are {CDF, ISO, UTC, TAI, UNX, JD, MJD, RDT}

    Returns:
      out Ticktock

        Ticktock instance with new time coordinates

    See also

    `CDF`
    `ISO`
    `UTC`

    Examples

        >>> a = Ticktock(['2002-02-02T12:00:00', '2002-02-02T12:00:00'], 'ISO')
        >>> s = a.convert('TAI')
        >>> type(s)
        <class 'time.Ticktock'>
        >>> s
        Ticktock( [1391342432 1391342432] ), dtype=TAI

  getAPT()

    a.APT or a.getAPT()

    Return AstroPy time object.

    Always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `APT` attribute.

    Returns:
      out astropy.time.Time

        AstroPy Time object

    See also

    `getUTC`, `getUNX`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getISO`, `getDOY`, `geteDOY`
    `getGPS`

    Notes

    New in version 0.2.2.

    Requires AstroPy 1.0. The returned value will be on the `tai` scale in `gps` format (unless the `Ticktock` was created from a `Time` object, in which case it will be the original input.) See the `astropy.time` docs for conversion to other scales and formats.

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.APT
        <Time object: scale='tai' format='gps' value=696686413.0>

  getCDF()

    a.getCDF() or a.CDF

    Return CDF Epoch time which is milliseconds since 0000-1-1 at 00:00:00.000. “Year zero” is a convention chosen by NSSDC to measure epoch values. This date is more commonly referred to as 1 BC and is considered a leap year.

    The CDF date/time calculations do not take into account the change to the Gregorian calendar or leap seconds, and cannot be directly converted into Julian date/times.

    Returns `data` if it was provided in CDF; otherwise always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `CDF` attribute.

    Returns:
      out numpy array

        milliseconds since 0000-01-01T00:00:00 assuming no discontinuities.

    See also

    `getUTC`
    `getUNX`
    `getRDT`
    `getJD`
    `getMJD`
    `getISO`
    `getTAI`
    `getDOY`
    `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.CDF
        array([  6.31798704e+13])

  getDOY()

    a.DOY or a.getDOY()

    extract DOY (days since January 1st of given year)

    Always recalculates from the current value of `UTC`, which will be created if necessary.

    Updates the `DOY` attribute.

    Returns:
      out numpy array

        day of the year

    See also

    `getUTC`
    `getUNX`
    `getRDT`
    `getJD`
    `getMJD`
    `getISO`
    `getTAI`
    `getDOY`
    `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.DOY
        array([ 33])

  getGPS()

    a.GPS or a.getGPS()

    Return seconds since the GPS epoch (1980-1-6T00:00 UT)

    Always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `GPS` attribute.

    Returns:
      out numpy array

        elapsed secs since 1980-1-6. Leap seconds are counted; i.e. there are no discontinuities.

    See also

    `getUTC`, `getUNX`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getISO`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.GPS
        dmarray([6.96686413e+08])

  getISO()

    a.ISO or a.getISO()

    convert dtype data into ISO string

    Always recalculates from the current value of `UTC`, which will be created if necessary. Applies leapsecond correction based on `TAI`, also created as necessary.

    Updates the `ISO` attribute.

    Returns:
      out list of strings

        date in ISO format

    See also

    `getUTC`, `getUNX`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getTAI`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.ISO
        dmarray(['2002-02-02T12:00:00'])

  getJD()

    a.JD or a.getJD()

    convert dtype data into Julian Date (JD)

    Returns `data` if it was provided in JD; otherwise always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `JD` attribute.

    Returns:
      out numpy array

        elapsed days since 4713 BCE 01-01T12:00

    See also

    `getUTC`
    `getUNX`
    `getRDT`
    `getJD`
    `getMJD`
    `getISO`
    `getTAI`
    `getDOY`
    `geteDOY`
    `getAPT`

    Notes

    This is based on the UTC day, defined as JD(UTC), per the recommendation of IAU General Assembly XXIII resolution B1. Julian days with leapseconds are 86401 seconds long and each second is a smaller fraction of the day. Note this “stretching” is across the Julian Day, noon to noon.

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.JD
        array([ 2452308.])

  getMJD()

    a.MJD or a.getMJD()

    convert dtype data into MJD (modified Julian date)

    Returns `data` if it was provided in MJD; otherwise always recalculates from the current value of `TAI` which will be created if necessary.

    Updates the `MJD` attribute.

    Returns:
      out numpy array

        elapsed days since 1858-11-17T00:00 (Julian date of 1858-11-17T12:00 was 2 400 000)

    See also

    `getUTC`, `getUNX`, `getRDT`, `getJD`, `getISO`, `getCDF`, `getTAI`, `getDOY`, `geteDOY`
    `getAPT`

    Notes

    This is based on the UTC day, defined as JD(UTC) - 2 400 000.5, per the recommendation of IAU General Assembly XXIII resolution B1. Julian days with leapseconds are 86401 seconds long and each second is a smaller fraction of the day. Note this “stretching” is across the Julian Day not the MJD, so it will affect the last half of the MJD before the leap second and the first half of the following MJD, so that MJD is always JD - 2 400 000.5 This also means that the MJD following a leap second does not begin exactly at midnight.

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.MJD
        array([ 52307.5])
        >>> a = Ticktock('2009-01-01T00:00:00', 'ISO')
        >>> a.MJD
        array([ 54832.00000579])

  getRDT()

    a.RDT or a.RDT()

    convert dtype data into Rata Die (lat.) Time, or elapsed days counting 0001-01-01 as day 1. This is a naive conversion: it ignores the existence of leapseconds for fractional days and ignores the conversion from Julian to Gregorian calendar, i.e. it assumes Gregorian calendar infinitely into the past.

    Returns `data` if it was provided in RDT; otherwise always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `RDT` attribute.

    Returns:
      out numpy array

        elapsed days counting 1/1/1 as day 1.

    See also

    `getUTC`, `getUNX`, `getISO`, `getJD`, `getMJD`, `getCDF`, `getTAI`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.RDT
        array([ 730883.5])

  getTAI()

    a.TAI or a.getTAI()

    return TAI (International Atomic Time), elapsed secs since 1958-1-1 (leap seconds are counted.) Ticktock’s handling of TAI and UTC conversions treats the UTC second as always equal in length to the SI second (and thus TAI), ignoring frequency changes and fractional leap seconds from 1958 through 1972, i.e. the UTC to TAI offset is always treated as an integer, truncated (not rounded) from the value at the most recent leap second (or fraction thereof).

    Return value comes from (in priority order):

    > 1. If `data` was provided in TAI, returns `data`.

    > 2. Else recalculates directly from `data` if it was provided in APT, CDF, GPS, ISO, JD, MJD, RDT, or UNX.

    > 3. Else calculates from current value of `UTC`, which will be created if necessary.

    Updates the `TAI` attribute; will also create the `UTC` and `ISO` attributes from `data` if input is in `ISO` (but will not overwrite an existing `ISO` or `UTC`). This is for efficiency, as computation from ISO requires calculating UTC and makes creating a formatted ISO string easy.

    Returns:
      out numpy array

        TAI as seconds since 1958-1-1.

    See also

    `getUTC`, `getUNX`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getISO`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.TAI
        array([1391342432])

  getUNX()

    a.UNX or a.getUNX()

    convert dtype data into Unix Time (Posix Time) seconds since 1970-1-1 (not counting leap seconds)

    Returns `data` if it was provided in UNX; otherwise always recalculates from the current value of `TAI`, which will be created if necessary.

    Updates the `UNX` attribute.

    Returns:
      out numpy array

        elapsed secs since 1970-1-1 (not counting leap secs)

    See also

    `getUTC`, `getISO`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getTAI`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.UNX
        array([  1.01265120e+09])

  getUTC()

    a.UTC or a.getUTC()

    convert dtype data into UTC object a la datetime()

    Return value comes from (in priority order):

    > 1. If `data` was provided in UTC, returns `data`.

    > 2. Else recalculates directly from `data` if it was provided in ISO.

    > 3. Else calculates from current value of `TAI`, which will be created if necessary. (`data` is TAI, GPS, JD, MJD, RDT, CDF, UNX)).

    Updates the `UTC` attribute.

    Returns:
      out list of datetime objects

        datetime object in UTC time

    See also

    `getISO`, `getUNX`, `getRDT`, `getJD`, `getMJD`, `getCDF`, `getTAI`, `getDOY`, `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.UTC
        [datetime.datetime(2002, 2, 2, 12, 0)]

  geteDOY()

    a.eDOY or a.geteDOY()

    extract eDOY (elapsed days since midnight January 1st of given year)

    Always recalculates from the current value of `UTC`, which will be created if necessary.

    Updates the `eDOY` attribute.

    Returns:
      out numpy array

        days elapsed since midnight bbedJan. 1st

    See also

    `getUTC`
    `getUNX`
    `getRDT`
    `getJD`
    `getMJD`
    `getISO`
    `getTAI`
    `getDOY`
    `geteDOY`
    `getAPT`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.eDOY
        array([ 32.5])

  getleapsecs()

    a.leaps or a.getleapsecs()

    retrieve leapseconds from lookup table, used in getTAI

    Always recalculates from current value of `TAI` if `data` is dtype `TAI`, otherwise from the current value of `UTC`, which will be created if necessary.

    Updates the `leaps` attribute.

    Returns:
      out numpy array

        leap seconds

    See also

    `getTAI`

    Examples

        >>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
        >>> a.leaps
        array([32])

  isoformat(b, attrib)

    This changes the self._isofmt attribute by and subsequently this function will update the ISO attribute.

    Parameters:
      fmt string, optional
  classmethod now()

    Create Ticktock with the current UTC time.

    Equivalent to datetime.utcnow()

    Changed in version 0.2.2: This now returns a UTC time; previously it returned a Ticktock UTC object, but in the local timezone, which made all conversions incorrect.

    Returns:
      out ticktock

        Ticktock object with the current time, equivalent to datetime.utcnow()

    See also

    `datetime.datetime.now`, `datetime.datetime.utcnow`
  sort()

    This will sort the Ticktock values in place based on the values in data. If you need a stable sort use kind=’mergesort’

    Other Parameters:
      kind str

        Sort algorithm to use, default ‘quicksort’.

    See also

    `argsort`, `numpy.argsort`
  classmethod today()

    Create Ticktock with the current UTC date and time set to 00:00:00

    Similar to date.today() with time included but in UTC and with the time included (zero hours, minutes, seconds)

    Changed in version 0.2.2: This now returns the UTC day; previously it returned a Ticktock UTC object, but in the local timezone, which made all conversions incorrect.

    Returns:
      out ticktock

        Ticktock object with the current UTC day

    See also

    `datetime.date.today`
  update_items(attrib)

    After changing the self.data attribute by either __setitem__ or __add__ etc this function will update all other attributes. This function is called automatically in __add__, __init__, and __setitem__.

    Parameters:
      attrib str

        attribute that was updated; update others from this

    Other Parameters:
      cls type

        Deprecated since version 0.2.2: Class is now taken from the `self` of the bound instance.

        Class to use for finding possible attributes; now ignored.

    See also

    `spacepy.Ticktock.__setitem__`
    `spacepy.Ticktock.__add__`
    `spacepy.Ticktock.__sub__`