curryer.spicetime.convert
=========================

.. py:module:: curryer.spicetime.convert

.. autoapi-nested-parse::

   Convert between time formats (ttype).

   Routine Listings
   ----------------
   adapt
       Convert from one time format to another. Maintains container type (e.g.,
       scalar input returns a scalar, list input returns a list).
   SpiceTime
       Subclass of numpy's ndarray that stores the data's time format `ttype`, and
       facilitates converting to other time formats.

   .. rubric:: Examples

   >>> utc = adapt([0, 1], from_='ugps', to='utc')
   >>> print('Adapt API:
           {!r}
           type={}'.format(utc, type(utc)))
   Adapt API:
           ['1980-01-06 00:00:00.000000', '1980-01-06 00:00:00.000001']
           type=<class 'list'>

   >>> ugps = SpiceTime([0, 1], ttype='ugps')
   >>> utc_arr = ugps.to_utc()
   >>> print('SpiceTime API:
           {!r}'.format(utc_arr))
   SpiceTime API:
           SpiceTime(['1980-01-06 00:00:00.000000', '1980-01-06 00:00:00.000001'],
         dtype='<U26', ttype='utc')

   @author: Brandon Stone



Attributes
----------

.. autoapisummary::

   curryer.spicetime.convert.conversions
   curryer.spicetime.convert.TTYPE_TO_DTYPE
   curryer.spicetime.convert._py_to_spice_format
   curryer.spicetime.convert.PY_TO_SPICE_FORMAT


Classes
-------

.. autoapisummary::

   curryer.spicetime.convert.SpiceTime


Functions
---------

.. autoapisummary::

   curryer.spicetime.convert.adapt
   curryer.spicetime.convert.from_et
   curryer.spicetime.convert.from_ugps
   curryer.spicetime.convert.from_gps
   curryer.spicetime.convert.from_tai
   curryer.spicetime.convert.from_utc
   curryer.spicetime.convert.to_et
   curryer.spicetime.convert.to_ugps
   curryer.spicetime.convert.to_gps
   curryer.spicetime.convert.to_tai
   curryer.spicetime.convert.to_utc
   curryer.spicetime.convert.spice_strftime


Module Contents
---------------

.. py:function:: adapt(dt_val, from_=None, to=None, **kwargs)

   Convert between different date time formats.

   Time Formats
   ------------
   et : float64, seconds
       Ephemeris time, seconds since J2000 in ET. Also called Barycentric
       Dynamical Time (TDB) in SPICE documentation. Most times are converted
       to and from ET.
   ugps : int64, microseconds
       GPS microseconds since 1980-01-06T00:00:00.0 UTC. Supports native (no
       SPICE) conversion to/from `dt64` and `epoch` et al.
   gps : float64, seconds
       GPS seconds since 1980-01-06T00:00:00.0 UTC.
   tai : float64, seconds
       International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC.
       NOTE: Within the SPICE system "TAI" often represents the J2000 epoch,
       we deviate from that to support the standard 1958 epoch.
   utc : str, ISO
       Coordinated Universal Time (UTC), including leapseconds. The default
       input and output format is ISO. The output format can be specified
       with a Python-style datetime format string and the keyword
       `date_format` (e.g.,`date_format='%Y-%d-%m'`). Some format keys are not
       supported.
   iso : str, ISO
       Alias for utc.
   dt64 : np.datetime64, ns
       Numpy datetime64 type with nanosecond precision. Does *not* support
       leapseconds. Default is to round those times up to the nearest second.
       Set `ceil_leapseconds=False` to raise errors instead.
   epoch : float64, days
       Fractional days since an epoch without leapseconds. The epoch name is
       defined with `from_epoch` or `to_epoch`, depending on the direction.
       See `sds_spice.spicetime.constants.EpochGpsDays`. Typically results in
       a loss of microsecond precision. Leapseconds are accounted for when
       determining the day, but the fraction for days with leapseconds assumes
       8.64e4 seconds per day (no leapsecond). Times within leapseconds are
       rounded up.
   sorce : float64, days
       Fractional days since 2003-01-24. See `epoch` for details.
   tcte : float64, days
       Fractional days since 2013-11-18. See `epoch` for details.
   tsis : float64, days
       Fractional days since 2017-12-14. See `epoch` for details.
   tsis1 : float64, days
       Alias for `tsis`. See `tsis` for details.
   tsis2 : float64, days
       Fractional days since 2017-12-14 (placeholder; launch TBD).
       See `epoch` for details.
   ctim : float64, days
       Fractional days since 2022-07-02. See `epoch` for details.
   gpsd : float64, days
       Fractional days since 1980-01-06. See `epoch` for details.
   mjd : float64, days
       Fractional days since the Modified Julian epoch (1858-11-17). See
       `epoch` for details.
   jd : float64, days
       Fractional days since the Julian epoch. See `epoch` for details.
       Least precision of all time formats.

   :param dt_val: One or more time values to convert from one time format to another.
   :type dt_val: scalar or list or tuple or numpy.ndarray of str or int or float
   :param from_: Time format (ttype) of the input data `dt_val`. Default='ugps'.
                 Note: Either one or both of `from_` or `to` must be specified.
   :type from_: str, optional
   :param to: Time format (ttype) to convert the input data `dt_val`, to.
              Default='ugps'. Note: Either one or both of `from_` or `to` must be
              specified.
   :type to: str, optional
   :param \*\*kwargs: Passes extra keywords that are not None to the conversion functions
                      that support them (e.g., "date_format" when `to="utc"`).

   :returns: The converted time(s). Each time value has the data type of output
             time format specified by `to` (e.g., str for "utc"). When converting
             multiple times, the output container matches the input `dt_val`.
   :rtype: scalar or list or tuple or numpy.ndarray of str or int or float


.. py:function:: from_et(dt_val)

   Convert times from Ephemeris Time (SPICE; float64).


.. py:function:: from_ugps(dt_val)

   Convert times from GPS microseconds.


.. py:function:: from_gps(dt_val)

   Convert times from GPS seconds.


.. py:function:: from_tai(dt_val)

   Convert times from International Atomic Time seconds (1958).


.. py:function:: from_utc(dt_val)

   Convert times from UTC string(s) (ISO format).


.. py:function:: to_et(dt_val)

   Convert times to Ephemeris Time (SPICE; float64).


.. py:function:: to_ugps(dt_val)

   Convert times to GPS microseconds (int64).


.. py:function:: to_gps(dt_val)

.. py:function:: to_tai(dt_val)

   Convert times to International Atomic Time seconds (1958; float64).


.. py:function:: to_utc(dt_val, date_format=None)

   Convert times to UTC strings (ISO format).


.. py:data:: conversions

.. py:data:: TTYPE_TO_DTYPE

.. py:class:: SpiceTime(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

   Bases: :py:obj:`numpy.ndarray`


   SPICE Date and Time Conversions.

   Time Formats
   ------------
   et : float64, seconds
       Ephemeris time, seconds since J2000 in ET. Also called Barycentric
       Dynamical Time (TDB) in SPICE documentation. All times are converted
       to and from ET.
   ugps : int64, microseconds
       GPS microseconds since 1980-01-06T00:00:00.0 UTC.
   gps : float64, seconds
       GPS seconds since 1980-01-06T00:00:00.0 UTC.
   tai : float64, seconds
       International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC.
       NOTE: Within the SPICE system "TAI" often represents the J2000 epoch,
       we deviate from that to support the standard 1958 epoch.
   utc : str, ISO
       Coordinated Universal Time (UTC), including leapseconds. The default
       input and output format is ISO. The output format can be specified
       with a Python-style datetime format string and the keyword
       `date_format` (e.g.,`date_format='%Y-%d-%m'`). Some format keys are not
       supported.

   .. attribute:: ttype

      Date time format (e.g., "ugps"). Read-only, unless None.

      :type: str

   :param in_arr: Scalar or array of times.
   :type in_arr: float
   :param ttype: Supported format string specifying the input time format.
   :type ttype: str

   .. rubric:: Examples

   >>> st = SpiceTime('2016-05-09 14:49:17.371099', 'utc')
   >>> print(repr(st))
   SpiceTime('2016-05-09 14:49:17.371099',
         dtype='<U26', ttype='utc')

   >>> print('Ephemeris Time: {}'.format(st.to_et()))
   Ephemeris Time: 516077425.55644935

   >>> print('uGPS: {}'.format(st.to_ugps()))
   uGPS: 1146840574371099

   >>> gps = st.to_gps()
   >>> print(gps.ttype)
   gps

   >>> st = SpiceTime([0, 1], 'gps')
   >>> print(st, st.ttype)
   [ 0.  1.] gps

   >>> print(st.to_utc('%S.%f'))
   ['00.000000' '01.000000']

   .. rubric:: Notes

   - Requires a leapsecond kernel to be loaded (automated by library).


   .. py:method:: __array_finalize__(obj)

      Numpy's replacement for "__init__", supports construction, casting,
      and templates.

      .. rubric:: Notes

      Three possible ways to create this subclass:
          1) Explicit construction:   arr = SpiceTime(np.arange(3), fmt='et')
              type(`obj`) is ndarray; `self` is built in `SpiceTime.__new__`
          2) View casting:            arr = np.arange(3).view(SpiceTime)
              type(`obj`) can be `SpiceTime` or another
          3) New-from-template:       arr = np.SpiceTime(arange(3))[1:]
              type(`obj`) is `SpiceTime`

      The optional method `__array_prepare__` is similar, but before the
      values are calculated.

      .. rubric:: References

      - https://docs.scipy.org/doc/numpy/user/basics.subclassing.html



   .. py:method:: __array_prepare__(out_arr, context=None)

      Numpy's way of supporting subclassing from ufuncs (e.g.,
      `np.min(et_arr)`). Allows viewing (ONLY) the output data structure and
      context (func & args) before the calculation.



   .. py:method:: __array_wrap__(out_arr, context=None)

      Numpy's way of supporting subclassing from ufuncs (e.g.,
      `np.min(et_arr)`). Allows tweaking the output (`out_arr`), before final
      casting as `SpiceTime`.



   .. py:method:: __repr__()

      String representation of the array with the time format `ttype`.



   .. py:property:: ttype

      Time format.


   .. py:method:: adapt(to, **kwargs)

      Convert from the current time format to another.



   .. py:method:: to_et()

      Convert times to Ephemeris Time (SPICE; float64).



   .. py:method:: to_ugps()

      Convert times to GPS microseconds (int64).



   .. py:method:: to_gps()

      Convert times to GPS seconds (float64).



   .. py:method:: to_tai()

      Convert times to International Atomic Time seconds (1958; float64).



   .. py:method:: to_utc(date_format=None)

      Convert times to UTC strings (ISO format).



.. py:data:: _py_to_spice_format

.. py:data:: PY_TO_SPICE_FORMAT

.. py:function:: spice_strftime(date_format)

   Convert a Python datetime format string to an equivalent SPICE string.

   :param date_format: Python datetime format string (e.g., "%Y-%m-%d %H:%M:%S.%f").
                       NOTE: Does not support every Python format code. Formats with a
                       non-none return in `PY_TO_SPICE_FORMAT` are supported.
   :type date_format: str

   :returns: SPICE UTC format string.
   :rtype: str

   .. rubric:: Examples

   >>> py_format = '%Y-%m-%d %H:%M:%S.%f'
   >>> print(spice_strftime(py_format))
   'YYYY-MM-DD HR:MN:SC.######::RND ::UTC'

   .. rubric:: References

   Python's format string:
       https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior
   SPICE's format string:
       https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/timout_c.html#Particulars