astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v0.3 »
- Astronomical Coordinate Systems (`astropy.coordinates`) »
- Angle

# Angle

class `astropy.coordinates.angles.``Angle`

  Bases: `astropy.units.quantity.Quantity`

  One or more angular value(s) with units equivalent to radians or degrees.

  An angle can be specified either as an array, scalar, tuple (see below), string, `Quantity` or another `Angle`.

  The input parser is flexible and supports a variety of formats:

      Angle('10.2345d')
      Angle(['10.2345d', '-20d'])
      Angle('1:2:30.43 degrees')
      Angle('1 2 0 hours')
      Angle(np.arange(1, 8), unit=u.deg)
      Angle(u'1°2′3″')
      Angle('1d2m3.4s')
      Angle('-1h2m3s')
      Angle((-1, 2, 3), unit=u.deg)  # (d, m, s)
      Angle(10.2345 * u.deg)
      Angle(Angle(10.2345 * u.deg))

  Parameters:

  angle : array, scalar, Quantity, Angle

  > The angle value. If a tuple, will be interpreted as `(h, m s)` or `(d, m, s)` depending on `unit`. If a string, it will be interpreted following the rules described above.

  > If `angle` is a sequence or array of strings, the resulting values will be in the given `unit`, or if None is provided, the unit will be taken from the first given value.

  unit : `UnitBase`, str, optional

  > The unit of the value specified for the angle. This may be any string that `Unit` understands, but it is better to give an actual unit object. Must be an angular unit.

  dtype : ~numpy.dtype, optional

  > See `Quantity`.

  copy : bool, optional

  > See `Quantity`.

  Raises:

  `~astropy.units.core.UnitsError` :

  > If a unit is not provided or it is not an angular unit.

  Attributes Summary

  `dms` | The angle’s value in degrees, as a `(d, m, s)` tuple (read-only property).
  `hms` | The angle’s value in hours, as a `(h, m, s)` tuple (read-only property).
  `hour` | The angle’s value in hours (read-only property).

  Methods Summary

  `format`(*args, **kwargs) | Deprecated since version 0.3.
  `is_within_bounds`([lower, upper]) | Check if all angle(s) satisfy `lower <= angle < upper` If `lower` is not specified (or `None`) then no lower bounds check is performed.
  `to_string`([unit, decimal, sep, precision, ...]) | A string representation of the angle.
  `wrap_at`(wrap_angle[, inplace]) | Wrap the Angle object at the given `wrap_angle`.

  Attributes Documentation

  `dms`

    The angle’s value in degrees, as a `(d, m, s)` tuple (read-only property).

  `hms`

    The angle’s value in hours, as a `(h, m, s)` tuple (read-only property).

  `hour`

    The angle’s value in hours (read-only property).

  Methods Documentation

  `format`(*args, **kwargs)

    Deprecated since version 0.3: Use to_string instead.

  `is_within_bounds`(lower=None, upper=None)

    Check if all angle(s) satisfy `lower <= angle < upper`

    If `lower` is not specified (or `None`) then no lower bounds check is performed. Likewise `upper` can be left unspecified. For example:

        >>> from astropy.coordinates import Angle
        >>> import astropy.units as u
        >>> a = Angle([-20, 150, 350] * u.deg)
        >>> a.is_within_bounds('0d', '360d')
        False
        >>> a.is_within_bounds(None, '360d')
        True
        >>> a.is_within_bounds(-30 * u.deg, None)
        True

    Parameters:

    lower : str, Angle, angular Quantity, None

    > Specifies lower bound for checking. This can be any object that can initialize an Angle object, e.g. ‘180d’, 180 * u.deg, or Angle(180, unit=u.deg).

    upper : str, Angle, angular Quantity, None

    > Specifies upper bound for checking. This can be any object that can initialize an Angle object, e.g. ‘180d’, 180 * u.deg, or Angle(180, unit=u.deg).

    Returns:

    is_within_bounds : bool

    > True if all angles satisfy `lower <= angle < upper`

  `to_string`(unit=None, decimal=False, sep=u'fromunit', precision=None, alwayssign=False, pad=False, fields=3, format=None)

    A string representation of the angle.

    Parameters:

    units : `UnitBase`, optional

    > Specifies the units. Must be an angular unit. If not provided, the unit used to initialize the angle will be used.

    decimal : bool, optional

    > If True, a decimal respresentation will be used, otherwise the returned string will be in sexagesimal form.

    sep : str, optional

    > The separator between numbers in a sexagesimal representation. E.g., if it is ‘:’, the result is “12:41:11.1241”. Also accepts 2 or 3 separators. E.g., `sep='hms'` would give the result “12h41m11.1241s”, or sep=’-:’ would yield “11-21:17.124”. Alternatively, the special string ‘fromunit’ means ‘dms’ if the unit is degrees, or ‘hms’ if the unit is hours.

    precision : int, optional

    > The level of decimal precision. If `decimal` is True, this is the raw precision, otherwise it gives the precision of the last place of the sexagesimal representation (seconds). If `None`, or not provided, the number of decimal places is determined by the value, and will be between 0-8 decimal places as required.

    alwayssign : bool, optional

    > If `True`, include the sign no matter what. If `False`, only include the sign if it is negative.

    pad : bool, optional

    > If `True`, include leading zeros when needed to ensure a fixed number of characters for sexagesimal representation.

    fields : int, optional

    > Specifies the number of fields to display when outputting sexagesimal notation. For example:

    > > - fields == 1: `'5d'`
    > > - fields == 2: `'5d45m'`
    > > - fields == 3: `'5d45m32.5s'`

    > By default, all fields are displayed.

    format : str, optional

    > The format of the result. If not provided, an unadorned string is returned. Supported values are:

    > - ‘latex’: Return a LaTeX-formatted string
    > - ‘unicode’: Return a string containing non-ASCII unicode characters, such as the degree symbol

    Returns:

    strrepr : str

    > A string representation of the angle.

  `wrap_at`(wrap_angle, inplace=False)

    Wrap the Angle object at the given `wrap_angle`.

    This method forces all the angle values to be within a contiguous 360 degree range so that `wrap_angle - 360d <= angle < wrap_angle`. By default a new Angle object is returned, but if the `inplace` argument is `True` then the Angle object is wrapped in place and nothing is returned.

    For instance:

        >>> from astropy.coordinates import Angle
        >>> import astropy.units as u
        >>> a = Angle([-20.0, 150.0, 350.0] * u.deg)

        >>> a.wrap_at(360 * u.deg).degree  # Wrap into range 0 to 360 degrees
        array([ 340.,  150.,  350.])

        >>> a.wrap_at('180d', inplace=True)  # Wrap into range -180 to 180 degrees
        >>> a.degree
        array([ -20.,  150.,  -10.])

    Parameters:

    wrap_angle : str, Angle, angular Quantity

    > Specifies a single value for the wrap angle. This can be any object that can initialize an Angle object, e.g. ‘180d’, 180 * u.deg, or Angle(180, unit=u.deg).

    inplace : bool

    > If `True` then wrap the object in place instead of returning a new Angle

    Returns:

    out : Angle or None

    > If `inplace is False` (default), return new Angle object with angles wrapped accordingly. Otherwise wrap in place and return None.