astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- Time and Dates (`astropy.time`) »
- Time

# Time

class `astropy.time.``Time`(val, val2=None, format=None, scale=None, precision=None, in_subfmt=None, out_subfmt=None, location=None, copy=False)

  Bases: `object`

  Represent and manipulate times and dates for astronomy.

  A `Time` object is initialized with one or more times in the `val` argument. The input times in `val` must conform to the specified `format` and must correspond to the specified time `scale`. The optional `val2` time input should be supplied only for numeric input formats (e.g. JD) where very high precision (better than 64-bit precision) is required.

  The allowed values for `format` can be listed with:

      >>> list(Time.FORMATS)
      ['jd', 'mjd', 'decimalyear', 'unix', 'cxcsec', 'gps', 'plot_date',
       'datetime', 'iso', 'isot', 'yday', 'fits', 'byear', 'jyear', 'byear_str',
       'jyear_str']

  Parameters:

  val : sequence, str, number, or `Time` object

  > Value(s) to initialize the time or times.

  val2 : sequence, str, or number; optional

  > Value(s) to initialize the time or times.

  format : str, optional

  > Format of input value(s)

  scale : str, optional

  > Time scale of input value(s), must be one of the following: (‘tai’, ‘tcb’, ‘tcg’, ‘tdb’, ‘tt’, ‘ut1’, ‘utc’)

  precision : int, optional

  > Digits of precision in string representation of time

  in_subfmt : str, optional

  > Subformat for inputting string times

  out_subfmt : str, optional

  > Subformat for outputting string times

  location : `EarthLocation` or tuple, optional

  > If given as an tuple, it should be able to initialize an an EarthLocation instance, i.e., either contain 3 items with units of length for geocentric coordinates, or contain a longitude, latitude, and an optional height for geodetic coordinates. Can be a single location, or one for each input time.

  copy : bool, optional

  > Make a copy of the input values

  Attributes Summary

  `FORMATS` | Dict of time formats
  `SCALES` | List of time scales
  `T` | Return a time instance with the data transposed.
  `delta_tdb_tt` | TDB - TT time scale offset
  `delta_ut1_utc` | UT1 - UTC time scale offset
  `format` | Get or set time format.
  `in_subfmt` | Unix wildcard pattern to select subformats for parsing string input times.
  `info` | Container for meta information like name, description, format.
  `isscalar` |
  `jd1` | First of the two doubles that internally store time value(s) in JD.
  `jd2` | Second of the two doubles that internally store time value(s) in JD.
  `ndim` |
  `out_subfmt` | Unix wildcard pattern to select subformats for outputting times.
  `precision` | Decimal precision when outputting seconds as floating point (int value between 0 and 9 inclusive).
  `scale` | Time scale
  `shape` | The shape of the time instances.
  `size` |
  `value` | Time value(s) in current format

  Methods Summary

  `argmax`([axis, out]) | Return indices of the maximum values along the given axis.
  `argmin`([axis, out]) | Return indices of the minimum values along the given axis.
  `argsort`([axis]) | Returns the indices that would sort the time array.
  `copy`([format]) | Return a fully independent copy the Time object, optionally changing the format.
  `diagonal`(*args, **kwargs) | Return a time instance with the specified diagonals.
  `flatten`(*args, **kwargs) | Return a copy with the time array collapsed into one dimension.
  `get_delta_ut1_utc`([iers_table, return_status]) | Find UT1 - UTC differences by interpolating in IERS Table.
  `max`([axis, out, keepdims]) | Maximum along a given axis.
  `min`([axis, out, keepdims]) | Minimum along a given axis.
  `now`() | Creates a new object corresponding to the instant in time this method is called.
  `ptp`([axis, out, keepdims]) | Peak to peak (maximum - minimum) along a given axis.
  `ravel`(*args, **kwargs) | Return an instance with the time array collapsed into one dimension.
  `replicate`([format, copy]) | Return a replica of the Time object, optionally changing the format.
  `reshape`(*args, **kwargs) | Returns a time instance containing the same data with a new shape.
  `sidereal_time`(kind[, longitude, model]) | Calculate sidereal time.
  `sort`([axis]) | Return a copy sorted along the specified axis.
  `squeeze`(*args, **kwargs) | Return a time instance with single-dimensional shape entries removed
  `swapaxes`(*args, **kwargs) | Return a time instance with the given axes interchanged.
  `take`(indices[, axis, mode]) | Return a Time object formed from the elements the given indices.
  `to_datetime`([timezone]) | Convert to (potentially timezone-aware) `datetime` object.
  `transpose`(*args, **kwargs) | Return a time instance with the data transposed.

  Attributes Documentation

  `FORMATS` = OrderedDict([(u'jd', <class 'astropy.time.formats.TimeJD'>), (u'mjd', <class 'astropy.time.formats.TimeMJD'>), (u'decimalyear', <class 'astropy.time.formats.TimeDecimalYear'>), (u'unix', <class 'astropy.time.formats.TimeUnix'>), (u'cxcsec', <class 'astropy.time.formats.TimeCxcSec'>), (u'gps', <class 'astropy.time.formats.TimeGPS'>), (u'plot_date', <class 'astropy.time.formats.TimePlotDate'>), (u'datetime', <class 'astropy.time.formats.TimeDatetime'>), (u'iso', <class 'astropy.time.formats.TimeISO'>), (u'isot', <class 'astropy.time.formats.TimeISOT'>), (u'yday', <class 'astropy.time.formats.TimeYearDayTime'>), (u'fits', <class 'astropy.time.formats.TimeFITS'>), (u'byear', <class 'astropy.time.formats.TimeBesselianEpoch'>), (u'jyear', <class 'astropy.time.formats.TimeJulianEpoch'>), (u'byear_str', <class 'astropy.time.formats.TimeBesselianEpochString'>), (u'jyear_str', <class 'astropy.time.formats.TimeJulianEpochString'>)])

    Dict of time formats

  `SCALES` = (u'tai', u'tcb', u'tcg', u'tdb', u'tt', u'ut1', u'utc')

    List of time scales

  `T`

    Return a time instance with the data transposed.

    Parameters are as for `T`. All internal data are views of the data of the original.

  `delta_tdb_tt`

    TDB - TT time scale offset

  `delta_ut1_utc`

    UT1 - UTC time scale offset

  `format`

    Get or set time format.

    The format defines the way times are represented when accessed via the `.value` attribute. By default it is the same as the format used for initializing the `Time` instance, but it can be set to any other value that could be used for initialization. These can be listed with:

        >>> list(Time.FORMATS)
        ['jd', 'mjd', 'decimalyear', 'unix', 'cxcsec', 'gps', 'plot_date',
         'datetime', 'iso', 'isot', 'yday', 'fits', 'byear', 'jyear', 'byear_str',
         'jyear_str']

  `in_subfmt`

    Unix wildcard pattern to select subformats for parsing string input times.

  `info`

    Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.

  `isscalar`
  `jd1`

    First of the two doubles that internally store time value(s) in JD.

  `jd2`

    Second of the two doubles that internally store time value(s) in JD.

  `ndim`
  `out_subfmt`

    Unix wildcard pattern to select subformats for outputting times.

  `precision`

    Decimal precision when outputting seconds as floating point (int value between 0 and 9 inclusive).

  `scale`

    Time scale

  `shape`

    The shape of the time instances.

    Like `shape`, can be set to a new shape by assigning a tuple.

    Raises: | AttributeError: if the shape of the ``jd1``, ``jd2``, ``location``, ``delta_ut1_utc``, or ``delta_tdb_tt`` attributes cannot be changed without the arrays being copied. For these cases, use the `Time.reshape` method.

  `size`
  `value`

    Time value(s) in current format

  Methods Documentation

  `argmax`(axis=None, out=None)

    Return indices of the maximum values along the given axis.

    This is similar to `argmax()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used. See `argmax()` for detailed documentation.

  `argmin`(axis=None, out=None)

    Return indices of the minimum values along the given axis.

    This is similar to `argmin()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used. See `argmin()` for detailed documentation.

  `argsort`(axis=-1)

    Returns the indices that would sort the time array.

    This is similar to `argsort()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used, and that corresponding attributes are copied. Internally, it uses `lexsort()`, and hence no sort method can be chosen.

  `copy`(format=None)

    Return a fully independent copy the Time object, optionally changing the format.

    If `format` is supplied then the time format of the returned Time object will be set accordingly, otherwise it will be unchanged from the original.

    In this method a full copy of the internal time arrays will be made. The internal time arrays are normally not changeable by the user so in most cases the `replicate()` method should be used.

    Parameters:

    format : str, optional

    > Time format of the copy.

    Returns:

    tm : Time object

    > Copy of this object

  `diagonal`(*args, **kwargs)

    Return a time instance with the specified diagonals.

    Parameters are as for `diagonal()`. All internal data are views of the data of the original.

  `flatten`(*args, **kwargs)

    Return a copy with the time array collapsed into one dimension.

    Parameters are as for `flatten()`.

  `get_delta_ut1_utc`(iers_table=None, return_status=False)

    Find UT1 - UTC differences by interpolating in IERS Table.

    Parameters:

    iers_table : `astropy.utils.iers.IERS` table, optional

    > Table containing UT1-UTC differences from IERS Bulletins A and/or B. If `None`, use default version (see `astropy.utils.iers`)

    return_status : bool

    > Whether to return status values. If `False` (default), iers raises `IndexError` if any time is out of the range covered by the IERS table.

    Returns:

    ut1_utc : float or float array

    > UT1-UTC, interpolated in IERS Table

    status : int or int array

    > Status values (if `return_status=`True``):: `astropy.utils.iers.FROM_IERS_B` `astropy.utils.iers.FROM_IERS_A` `astropy.utils.iers.FROM_IERS_A_PREDICTION` `astropy.utils.iers.TIME_BEFORE_IERS_RANGE` `astropy.utils.iers.TIME_BEYOND_IERS_RANGE`

    Notes

    In normal usage, UT1-UTC differences are calculated automatically on the first instance ut1 is needed.

    Examples

    To check in code whether any times are before the IERS table range:

        >>> from astropy.utils.iers import TIME_BEFORE_IERS_RANGE
        >>> t = Time(['1961-01-01', '2000-01-01'], scale='utc')
        >>> delta, status = t.get_delta_ut1_utc(return_status=True)
        >>> status == TIME_BEFORE_IERS_RANGE
        array([ True, False], dtype=bool)

    To use an updated IERS A bulletin to calculate UT1-UTC (see also `astropy.utils.iers`):

        >>> from astropy.utils.iers import IERS_A, IERS_A_URL
        >>> from astropy.utils.data import download_file
        >>> t = Time(['1974-01-01', '2000-01-01'], scale='utc')
        >>> iers_a_file = download_file(IERS_A_URL,
        ...                             cache=True)
        Downloading ... [Done]
        >>> iers_a = IERS_A.open(iers_a_file)
        >>> t.delta_ut1_utc = t.get_delta_ut1_utc(iers_a)

    The delta_ut1_utc property will be used to calculate t.ut1; raises IndexError if any of the times is out of range.

  `max`(axis=None, out=None, keepdims=False)

    Maximum along a given axis.

    This is similar to `max()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used, and that corresponding attributes are copied.

    Note that the `out` argument is present only for compatibility with `np.max`; since `Time` instances are immutable, it is not possible to have an actual `out` to store the result in.

  `min`(axis=None, out=None, keepdims=False)

    Minimum along a given axis.

    This is similar to `min()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used, and that corresponding attributes are copied.

    Note that the `out` argument is present only for compatibility with `np.min`; since `Time` instances are immutable, it is not possible to have an actual `out` to store the result in.

  classmethod `now`()

    Creates a new object corresponding to the instant in time this method is called.

    Note

    “Now” is determined using the `utcnow` function, so its accuracy and precision is determined by that function. Generally that means it is set by the accuracy of your system clock.

    Returns:

    nowtime

    > A new `Time` object (or a subclass of `Time` if this is called from such a subclass) at the current time.

  `ptp`(axis=None, out=None, keepdims=False)

    Peak to peak (maximum - minimum) along a given axis.

    This is similar to `ptp()`, but adapted to ensure that the full precision given by the two doubles `jd1` and `jd2` is used.

    Note that the `out` argument is present only for compatibility with `ptp`; since `Time` instances are immutable, it is not possible to have an actual `out` to store the result in.

  `ravel`(*args, **kwargs)

    Return an instance with the time array collapsed into one dimension.

    Parameters are as for `ravel()`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape `(-1,)` to the shape attribute.

  `replicate`(format=None, copy=False)

    Return a replica of the Time object, optionally changing the format.

    If `format` is supplied then the time format of the returned Time object will be set accordingly, otherwise it will be unchanged from the original.

    If `copy` is set to `True` then a full copy of the internal time arrays will be made. By default the replica will use a reference to the original arrays when possible to save memory. The internal time arrays are normally not changeable by the user so in most cases it should not be necessary to set `copy` to `True`.

    The convenience method copy() is available in which `copy` is `True` by default.

    Parameters:

    format : str, optional

    > Time format of the replica.

    copy : bool, optional

    > Return a true copy instead of using references where possible.

    Returns:

    tm : Time object

    > Replica of this object

  `reshape`(*args, **kwargs)

    Returns a time instance containing the same data with a new shape.

    Parameters are as for `reshape()`. Note that it is not always possible to change the shape of an array without copying the data. If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute.

  `sidereal_time`(kind, longitude=None, model=None)

    Calculate sidereal time.

    Parameters:

    kind : str

    > `'mean'` or `'apparent'`, i.e., accounting for precession only, or also for nutation.

    longitude : `Quantity`, `str`, or `None`; optional

    > The longitude on the Earth at which to compute the sidereal time. Can be given as a `Quantity` with angular units (or an `Angle` or `Longitude`), or as a name of an observatory (currently, only `'greenwich'` is supported, equivalent to 0 deg). If `None` (default), the `lon` attribute of the Time object is used.

    model : str or `None`; optional

    > Precession (and nutation) model to use. The available ones are: - apparent: [u’IAU1994’, u’IAU2000A’, u’IAU2000B’, u’IAU2006A’] - mean: [u’IAU1982’, u’IAU2000’, u’IAU2006’] If `None` (default), the last (most recent) one from the appropriate list above is used.

    Returns:

    sidereal time : `Longitude`

    > Sidereal time as a quantity with units of hourangle

  `sort`(axis=-1)

    Return a copy sorted along the specified axis.

    This is similar to `sort()`, but internally uses indexing with `lexsort()` to ensure that the full precision given by the two doubles `jd1` and `jd2` is kept, and that corresponding attributes are properly sorted and copied as well.

    Parameters:

    axis : int or None

    > Axis to be sorted. If `None`, the flattened array is sorted. By default, sort over the last axis.

  `squeeze`(*args, **kwargs)

    Return a time instance with single-dimensional shape entries removed

    Parameters are as for `squeeze()`. All internal data are views of the data of the original.

  `swapaxes`(*args, **kwargs)

    Return a time instance with the given axes interchanged.

    Parameters are as for `swapaxes()`. All internal data are views of the data of the original.

  `take`(indices, axis=None, mode=u'raise')

    Return a Time object formed from the elements the given indices.

    Parameters are as for `take()`, except that, obviously, no output array can be given.

  `to_datetime`(timezone=None)

    Convert to (potentially timezone-aware) `datetime` object.

    If `timezone` is not `None`, return a timezone-aware datetime object.

    Parameters:

    timezone : {`tzinfo`, None} (optional)

    > If not `None`, return timezone-aware datetime.

    Returns:

    `datetime`

    > If `timezone` is not `None`, output will be timezone-aware.

  `transpose`(*args, **kwargs)

    Return a time instance with the data transposed.

    Parameters are as for `transpose()`. All internal data are views of the data of the original.