astro plan:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroplan v0.7 »
- Reference/API »
- Observer

# Observer

class `astroplan.``Observer`(**func_kwargs)

  Bases: `object`

  A container class for information about an observer’s location and environment.

  Examples

  We can create an observer at Subaru Observatory in Hawaii two ways. First, locations for some observatories are stored in astroplan, and these can be accessed by name, like so:

      >>> from astroplan import Observer
      >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii")

  To find out which observatories can be accessed by name, check out `get_site_names`.

  Next, you can initialize an observer by specifying the location with `EarthLocation`:

      >>> from astropy.coordinates import EarthLocation
      >>> import astropy.units as u
      >>> location = EarthLocation.from_geodetic(-155.4761*u.deg, 19.825*u.deg,
      ...                                        4139*u.m)
      >>> subaru = Observer(location=location, name="Subaru", timezone="US/Hawaii")

  You can also create an observer without an `EarthLocation`:

      >>> from astroplan import Observer
      >>> import astropy.units as u
      >>> subaru = Observer(longitude=-155.4761*u.deg, latitude=19.825*u.deg,
      ...                   elevation=0*u.m, name="Subaru", timezone="US/Hawaii")

  Parameters
    location `EarthLocation`

      The location (latitude, longitude, elevation) of the observatory.

    timezone str or `datetime.tzinfo` (optional)

      The local timezone to assume. If a string, it will be passed through `pytz.timezone()` to produce the timezone object.

    name str

      A short name for the telescope, observatory or location.

    latitude float, str, `Quantity` (optional)

      The latitude of the observing location. Should be valid input for initializing a `Latitude` object.

    longitude float, str, `Quantity` (optional)

      The longitude of the observing location. Should be valid input for initializing a `Longitude` object.

    elevation `Quantity` (optional), default = 0 meters

      The elevation of the observing location, with respect to sea level. Defaults to sea level.

    pressure `Quantity` (optional)

      The ambient pressure. Defaults to zero (i.e. no atmosphere).

    relative_humidity float (optional)

      The ambient relative humidity.

    temperature `Quantity` (optional)

      The ambient temperature.

    description str (optional)

      A short description of the telescope, observatory or observing location.

  Methods Summary

  `altaz`(time[, target, obswl, grid_times_targets]) | Get an `AltAz` frame or coordinate.
  `astropy_time_to_datetime`(astropy_time) | Convert the `Time` object `astropy_time` to a localized `datetime` object.
  `at_site`(site_name, **kwargs) | Initialize an `Observer` object with a site name.
  `datetime_to_astropy_time`(date_time) | Convert the `datetime` object `date_time` to a `Time` object.
  `is_night`(time[, horizon, obswl]) | Is the Sun below `horizon` at `time`?
  `local_sidereal_time`(time[, kind, model]) | Convert `time` to local sidereal time for observer.
  `midnight`(time[, which, n_grid_points]) | Time at solar midnight.
  `moon_altaz`(time[, ephemeris]) | Returns the position of the moon in alt/az.
  `moon_illumination`(time) | Calculate the illuminated fraction of the moon.
  `moon_phase`([time]) | Calculate lunar orbital phase.
  `moon_rise_time`(time[, which, horizon, …]) | Returns the local moon rise time.
  `moon_set_time`(time[, which, horizon, …]) | Returns the local moon set time.
  `noon`(time[, which, n_grid_points]) | Time at solar noon.
  `parallactic_angle`(time, target[, …]) | Calculate the parallactic angle.
  `sun_altaz`(time) | Returns the position of the Sun in alt/az.
  `sun_rise_time`(time[, which, horizon, …]) | Time of sunrise.
  `sun_set_time`(time[, which, horizon, …]) | Time of sunset.
  `target_hour_angle`(time, target[, …]) | Calculate the local hour angle of `target` at `time`.
  `target_is_up`(time, target[, horizon, …]) | Is `target` above `horizon` at this `time`?
  `target_meridian_antitransit_time`(time, target) | Calculate time at the antitransit of the meridian.
  `target_meridian_transit_time`(time, target[, …]) | Calculate time at the transit of the meridian.
  `target_rise_time`(time, target[, which, …]) | Calculate rise time.
  `target_set_time`(time, target[, which, …]) | Calculate set time.
  `tonight`([time, horizon, obswl]) | Return a time range corresponding to the nearest night
  `twilight_evening_astronomical`(time[, which, …]) | Time at evening astronomical (-18 degree) twilight.
  `twilight_evening_civil`(time[, which, …]) | Time at evening civil (-6 degree) twilight.
  `twilight_evening_nautical`(time[, which, …]) | Time at evening nautical (-12 degree) twilight.
  `twilight_morning_astronomical`(time[, which, …]) | Time at morning astronomical (-18 degree) twilight.
  `twilight_morning_civil`(time[, which, …]) | Time at morning civil (-6 degree) twilight.
  `twilight_morning_nautical`(time[, which, …]) | Time at morning nautical (-12 degree) twilight.

  Methods Documentation

  `altaz`(time, target=None, obswl=None, grid_times_targets=False)

    Get an `AltAz` frame or coordinate.

    If `target` is None, generates an altitude/azimuth frame. Otherwise, calculates the transformation to that frame for the requested `target`.

    Parameters
      time `Time` or other (see below)

        The time at which the observation is taking place. Will be used as the `obstime` attribute in the resulting frame or coordinate. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `FixedTarget`, `SkyCoord`, or list (optional)

        Celestial object(s) of interest. If `target` is `None`, returns the `AltAz` frame without coordinates.

      obswl `Quantity` (optional)

        Wavelength of the observation used in the calculation.

      grid_times_targets: bool (optional)

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules. Useful for grid searches for rise/set times etc.

    Returns
      `AltAz`

        If `target` is `None`, returns `AltAz` frame. If `target` is not `None`, returns the `target` transformed to the `AltAz` frame.

    Examples

    Create an instance of the `AltAz` frame for an observer at Apache Point Observatory at a particular time:

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> from astropy.coordinates import SkyCoord
        >>> apo = Observer.at_site("APO")
        >>> time = Time('2001-02-03 04:05:06')
        >>> target = SkyCoord(0*u.deg, 0*u.deg)
        >>> altaz_frame = apo.altaz(time)

    Now transform the target’s coordinates to the alt/az frame:

        >>> target_altaz = target.transform_to(altaz_frame)

    Alternatively, construct an alt/az frame and transform the target to that frame all in one step:

        >>> target_altaz = apo.altaz(time, target)

  `astropy_time_to_datetime`(astropy_time)

    Convert the `Time` object `astropy_time` to a localized `datetime` object.

    Timezones localized with pytz.

    Parameters
      astropy_time `Time`

        Scalar or list-like.

    Returns
      `datetime`

        Localized datetime, where the timezone of the datetime is set by the `timezone` keyword argument of the `Observer` constructor.

    Examples

    Convert an astropy time to a localized `datetime`:

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii")
        >>> astropy_time = Time('1999-12-31 06:00:00')
        >>> print(subaru.astropy_time_to_datetime(astropy_time))
        1999-12-30 20:00:00-10:00

  classmethod `at_site`(site_name, **kwargs)

    Initialize an `Observer` object with a site name.

    Extra keyword arguments are passed to the `Observer` constructor (see `Observer` for available keyword arguments).

    Parameters
      site_name str

        Observatory name, must be resolvable with `get_site_names`.

    Returns
      `Observer`

        Observer object.

    Examples

    Initialize an observer at Kitt Peak National Observatory:

        >>> from astroplan import Observer
        >>> import astropy.units as u
        >>> kpno_generic = Observer.at_site('kpno')
        >>> kpno_today = Observer.at_site('kpno', pressure=1*u.bar, temperature=0*u.deg_C)

  `datetime_to_astropy_time`(date_time)

    Convert the `datetime` object `date_time` to a `Time` object.

    Timezones localized with pytz. If the `date_time` is naive, the implied timezone is the `timezone` structure of `self`.

    Parameters
      date_time `datetime` or list-like
    Returns
      `Time`

        Astropy time object (no timezone information preserved).

    Examples

    Convert a localized `datetime` to a `Time` object. Non-localized datetimes are assumed to be UTC. <Time object: scale=’utc’ format=’datetime’ value=1999-12-31 06:00:00>

        >>> from astroplan import Observer
        >>> import datetime
        >>> import pytz
        >>> subaru = Observer.at_site("Subaru", timezone="US/Hawaii")
        >>> hi_date_time = datetime.datetime(2005, 6, 21, 20, 0, 0, 0)
        >>> subaru.datetime_to_astropy_time(hi_date_time)
        <Time object: scale='utc' format='datetime' value=2005-06-22 06:00:00>
        >>> utc_date_time = datetime.datetime(2005, 6, 22, 6, 0, 0, 0,
        ...                                   tzinfo=pytz.timezone("UTC"))
        >>> subaru.datetime_to_astropy_time(utc_date_time)
        <Time object: scale='utc' format='datetime' value=2005-06-22 06:00:00>

  `is_night`(time, horizon=<Quantity 0. deg>, obswl=None)

    Is the Sun below `horizon` at `time`?

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating day/night (i.e., -6 deg horizon = civil twilight, etc.)

      obswl `Quantity` (optional)

        Wavelength of the observation used in the calculation

    Returns
      sun_below_horizon bool or np.ndarray(bool)

        `True` if sun is below `horizon` at `time`, else `False`.

    Examples

    Is it “nighttime” (i.e. is the Sun below `horizon`) at Apache Point Observatory at 2015-08-29 18:35 UTC?

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time("2015-08-29 18:35")
        >>> apo.is_night(time)
        False

  `local_sidereal_time`(time, kind='apparent', model=None)

    Convert `time` to local sidereal time for observer.

    This is a thin wrapper around the `sidereal_time` method.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      kind{‘mean’, ‘apparent’} (optional)

        Passed to the `kind` argument of `sidereal_time`

      model str or `None`; optional

        The precession/nutation model to assume - see `sidereal_time` for more details.

    Returns
      `Longitude`

        Local sidereal time.

  `midnight`(time, which='nearest', n_grid_points=150)

    Time at solar midnight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which noon relative to the present `time` would you like to calculate

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields midnight time precisions better than one minute.

    Returns
      `Time`

        Time at solar midnight

  `moon_altaz`(time, ephemeris=None)

    Returns the position of the moon in alt/az.

    Parameters
      time `Time` or other (see below)

        This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object).

      ephemeris str, optional

        Ephemeris to use. If not given, use the one set with `astropy.coordinates.solar_system_ephemeris.set` (which is set to ‘builtin’ by default).

    Returns
      altaz `SkyCoord`

        Position of the moon transformed to altitude and azimuth

    Examples

    Calculate the altitude and azimuth of the moon at Apache Point Observatory:

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time("2015-08-29 18:35")
        >>> altaz_moon = apo.moon_altaz(time)
        >>> print("alt: {0.alt}, az: {0.az}".format(altaz_moon))
        alt: -63.72706397691421 deg, az: 345.3640380598265 deg

  `moon_illumination`(time)

    Calculate the illuminated fraction of the moon.

    Parameters
      time `Time` or other (see below)

        This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object).

    Returns
      float

        Fraction of lunar surface illuminated

    Examples

    How much of the lunar surface is illuminated at 2015-08-29 18:35 UTC, which we happen to know is the time of a full moon?

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time("2015-08-29 18:35")
        >>> apo.moon_illumination(time)
        array([ 0.99972487])

  `moon_phase`(time=None)

    Calculate lunar orbital phase.

    For example, phase=pi is “new”, phase=0 is “full”.

    Parameters
      time `Time` or other (see below)

        This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object).

    Returns
      moon_phase_angle float

        Orbital phase angle of the moon where pi corresponds to new moon, zero corresponds to full moon.

    Examples

    Calculate the phase of the moon at 2015-08-29 18:35 UTC. Near zero radians corresponds to a nearly full moon.

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site('APO')
        >>> time = Time('2015-08-29 18:35')
        >>> apo.moon_phase(time)
        <Quantity [ 0.03317537] rad>

  `moon_rise_time`(time, which='nearest', horizon=<Quantity 0. deg>, n_grid_points=150)

    Returns the local moon rise time.

    Compute time of the next/previous/nearest moon rise, where moon rise is defined as the time when the moon transitions from altitudes below `horizon` to above `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which moon rise relative to the present `time` would you like to calculate.

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields rise time precisions better than one minute.

  `moon_set_time`(time, which='nearest', horizon=<Quantity 0. deg>, n_grid_points=150)

    Returns the local moon set time.

    Compute time of the next/previous/nearest moon set, where moon set is defined as the time when the moon transitions from altitudes below `horizon` to above `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which moon set relative to the present `time` would you like to calculate.

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating set/set times (i.e., -6 deg horizon = civil twilight, etc.)

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields set time precisions better than one minute.

  `noon`(time, which='nearest', n_grid_points=150)

    Time at solar noon.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which noon relative to the present `time` would you like to calculate

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields noon time precisions better than one minute.

    Returns
      `Time`

        Time at solar noon

  `parallactic_angle`(time, target, grid_times_targets=False)

    Calculate the parallactic angle.

    Parameters
      time `Time`

        Observation time.

      target `FixedTarget` or `SkyCoord` or list

        Target celestial object(s).

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

    Returns
      `Angle`

        Parallactic angle.

    Notes

    The parallactic angle is the angle between the great circle that intersects a celestial object and the zenith, and the object’s hour circle [1].

    1

      https://en.wikipedia.org/wiki/Parallactic_angle

  `sun_altaz`(time)

    Returns the position of the Sun in alt/az.

    Parameters
      time `Time` or other (see below)

        This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object).

      ephemeris str, optional

        Ephemeris to use. If not given, use the one set with `astropy.coordinates.solar_system_ephemeris.set` (which is set to ‘builtin’ by default).

    Returns
      altaz `SkyCoord`

        Position of the sun transformed to altitude and azimuth

  `sun_rise_time`(time, which='nearest', horizon=<Quantity 0. deg>, n_grid_points=150)

    Time of sunrise.

    Compute time of the next/previous/nearest sunrise, where sunrise is defined as when the Sun transitions from altitudes below `horizon` to above `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunrise relative to the present `time` would you like to calculate.

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields rise time precisions better than one minute.

    Returns
      `Time`

        Time of sunrise

    Examples

    Calculate the time of the previous sunrise at Apache Point Observatory:

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time('2001-02-03 04:05:06')
        >>> sun_rise = apo.sun_rise_time(time, which="previous")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(sun_rise))
        ISO: 2001-02-02 14:02:50.554, JD: 2451943.08531

  `sun_set_time`(time, which='nearest', horizon=<Quantity 0. deg>, n_grid_points=150)

    Time of sunset.

    Compute time of the next/previous/nearest sunset, where sunset is defined as when the Sun transitions from altitudes below `horizon` to above `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunset relative to the present `time` would you like to calculate

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields set time precisions better than one minute.

    Returns
      `Time`

        Time of sunset

    Examples

    Calculate the time of the next sunset at Apache Point Observatory:

        >>> from astroplan import Observer
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time('2001-02-03 04:05:06')
        >>> sun_set = apo.sun_set_time(time, which="next")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(sun_set))
        ISO: 2001-02-04 00:35:42.102, JD: 2451944.52479

  `target_hour_angle`(time, target, grid_times_targets=False)

    Calculate the local hour angle of `target` at `time`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

    Returns
      hour_angle `Angle`

        The hour angle(s) of the target(s) at `time`

  `target_is_up`(time, target, horizon=<Quantity 0. deg>, return_altaz=False, grid_times_targets=False)

    Is `target` above `horizon` at this `time`?

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      return_altaz bool (optional)

        Also return the ‘~astropy.coordinates.AltAz’ coordinate.

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

    Returns
      observable boolean or np.ndarray(bool)

        True if `target` is above `horizon` at `time`, else False.

    Examples

    Are Aldebaran and Vega above the horizon at Apache Point Observatory at 2015-08-29 18:35 UTC?

        >>> from astroplan import Observer, FixedTarget
        >>> from astropy.time import Time
        >>> apo = Observer.at_site("APO")
        >>> time = Time("2015-08-29 18:35")
        >>> aldebaran = FixedTarget.from_name("Aldebaran")
        >>> vega = FixedTarget.from_name("Vega")
        >>> apo.target_is_up(time, aldebaran)
        True
        >>> apo.target_is_up(time, [aldebaran, vega])
        array([ True, False], dtype=bool)

  `target_meridian_antitransit_time`(time, target, which='nearest', grid_times_targets=False, n_grid_points=150)

    Calculate time at the antitransit of the meridian.

    Compute time of the next/previous/nearest antitransit of the `target` object.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunrise relative to the present `time` would you like to calculate

      grid_times_targets bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields rise time precisions better than one minute.

    Returns
      `Time`

        Antitransit time of target

    Examples

    Calculate the meridian anti-transit time of Rigel at Keck Observatory:

        >>> from astroplan import Observer, FixedTarget
        >>> from astropy.time import Time
        >>> time = Time("2001-02-03 04:05:06")
        >>> target = FixedTarget.from_name("Rigel")
        >>> keck = Observer.at_site("Keck")
        >>> rigel_antitransit_time = keck.target_meridian_antitransit_time(
        ...     time, target, which="next")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(rigel_antitransit_time))
        ISO: 2001-02-03 18:40:29.761, JD: 2451944.27812

  `target_meridian_transit_time`(time, target, which='nearest', grid_times_targets=False, n_grid_points=150)

    Calculate time at the transit of the meridian.

    Compute time of the next/previous/nearest transit of the `target` object.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunrise relative to the present `time` would you like to calculate

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields rise time precisions better than one minute.

    Returns
      `Time`

        Transit time of target

    Examples

    Calculate the meridian transit time of Rigel at Keck Observatory:

        >>> from astroplan import Observer, FixedTarget
        >>> from astropy.time import Time
        >>> time = Time("2001-02-03 04:05:06")
        >>> target = FixedTarget.from_name("Rigel")
        >>> keck = Observer.at_site("Keck")
        >>> rigel_transit_time = keck.target_meridian_transit_time(time, target,
        ...                                                        which="next")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(rigel_transit_time))
        ISO: 2001-02-03 06:42:26.863, JD: 2451943.77948

  `target_rise_time`(time, target, which='nearest', horizon=<Quantity 0. deg>, grid_times_targets=False, n_grid_points=150)

    Calculate rise time.

    Compute time of the next/previous/nearest rise of the `target` object, where “rise” is defined as the time when the `target` transitions from altitudes below the `horizon` to above the `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunrise relative to the present `time` would you like to calculate

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields rise time precisions better than one minute.

    Returns
      `Time`

        Rise time of target

    Examples

    Calculate the rise time of Rigel at Keck Observatory:

        >>> from astroplan import Observer, FixedTarget
        >>> from astropy.time import Time
        >>> time = Time("2001-02-03 04:05:06")
        >>> target = FixedTarget.from_name("Rigel")
        >>> keck = Observer.at_site("Keck")
        >>> rigel_rise_time = keck.target_rise_time(time, target, which="next")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(rigel_rise_time))
        ISO: 2001-02-04 00:51:23.330, JD: 2451944.53569

  `target_set_time`(time, target, which='nearest', horizon=<Quantity 0. deg>, grid_times_targets=False, n_grid_points=150)

    Calculate set time.

    Compute time of the next/previous/nearest set of `target`, where “set” is defined as when the `target` transitions from altitudes above `horizon` to below `horizon`.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      target `SkyCoord`, `FixedTarget`, or list

        Target celestial object(s)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which sunset relative to the present `time` would you like to calculate

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (i.e., -6 deg horizon = civil twilight, etc.)

      grid_times_targets: bool

        If True, the target object will have extra dimensions packed onto the end, so that calculations with M targets and N times will return an (M, N) shaped result. Otherwise, we rely on broadcasting the shapes together using standard numpy rules.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields set time precisions better than one minute.

    Returns
      `Time`

        Set time of target.

    Examples

    Calculate the set time of Rigel at Keck Observatory:

        >>> from astroplan import Observer, FixedTarget
        >>> from astropy.time import Time
        >>> time = Time("2001-02-03 04:05:06")
        >>> target = FixedTarget.from_name("Rigel")
        >>> keck = Observer.at_site("Keck")
        >>> rigel_set_time = keck.target_set_time(time, target, which="next")
        >>> print("ISO: {0.iso}, JD: {0.jd}".format(rigel_set_time))
        ISO: 2001-02-03 12:29:34.768, JD: 2451944.02054

  `tonight`(time=None, horizon=<Quantity 0. deg>, obswl=None)

    Return a time range corresponding to the nearest night

    This will return a range of `Time` corresponding to the beginning and ending of the night. If in the middle of a given night, return times from `now` until the nearest `sun_rise_time`

    Parameters
      time `Time` (optional), default = `now`

        The start time for tonight, which is allowed to be arbitrary. See description above for behavior

      horizon `Quantity` (optional), default = zero degrees

        Degrees above/below actual horizon to use for calculating rise/set times (e.g., -6 deg horizon = civil twilight, etc.)

      obswl `Quantity` (optional)

        Wavelength of the observation used in the calculation

    Returns
      times `Time`

        A tuple of times corresponding to the start and end of current night

  `twilight_evening_astronomical`(time, which='nearest', n_grid_points=150)

    Time at evening astronomical (-18 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate. Default is nearest.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of twilight

  `twilight_evening_civil`(time, which='nearest', n_grid_points=150)

    Time at evening civil (-6 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate. Default is nearest.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of twilight

  `twilight_evening_nautical`(time, which='nearest', n_grid_points=150)

    Time at evening nautical (-12 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate. Default is nearest.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of twilight

  `twilight_morning_astronomical`(time, which='nearest', n_grid_points=150)

    Time at morning astronomical (-18 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of twilight

  `twilight_morning_civil`(time, which='nearest', n_grid_points=150)

    Time at morning civil (-6 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate. Default is nearest.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of sunset

  `twilight_morning_nautical`(time, which='nearest', n_grid_points=150)

    Time at morning nautical (-12 degree) twilight.

    Parameters
      time `Time` or other (see below)

        Time of observation. This will be passed in as the first argument to the `Time` initializer, so it can be anything that `Time` will accept (including a `Time` object)

      which{‘next’, ‘previous’, ‘nearest’}

        Choose which twilight relative to the present `time` would you like to calculate. Default is nearest.

      n_grid_points int (optional)

        The number of grid points on which to search for the horizon crossings of the target over a 24 hour period, default is 150 which yields twilight time precisions better than one minute.

    Returns
      `Time`

        Time of twilight