Observer#

class astroplan.Observer(location=None, timezone='UTC', name=None, latitude=None, longitude=None, elevation=<Quantity 0. m>, pressure=None, relative_humidity=None, temperature=None, description=None)[source]#

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:
locationEarthLocation

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

timezonestr or datetime.tzinfo (optional)

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

namestr

A short name for the telescope, observatory or location.

latitudefloat, str, Quantity (optional)

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

longitudefloat, str, Quantity (optional)

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

elevationQuantity (optional), default = 0 meters

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

pressureQuantity (optional)

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

relative_humidityfloat (optional)

The ambient relative humidity.

temperatureQuantity (optional)

The ambient temperature.

descriptionstr (optional)

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

Attributes Summary

elevation

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

latitude

The latitude of the observing location, derived from the location.

longitude

The longitude of the observing location, derived from the 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.

Attributes Documentation

elevation#

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

latitude#

The latitude of the observing location, derived from the location.

longitude#

The longitude of the observing location, derived from the location.

Methods Documentation

altaz(time, target=None, obswl=None, grid_times_targets=False)[source]#

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:
timeTime 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)

targetFixedTarget, SkyCoord, or list (optional)

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

obswlQuantity (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)[source]#

Convert the Time object astropy_time to a localized datetime object.

Timezones localized with pytz.

Parameters:
astropy_timeTime

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)[source]#

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_namestr

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)[source]#

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_timedatetime 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)[source]#

Is the Sun below horizon at time?

Parameters:
timeTime 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)

horizonQuantity (optional), default = zero degrees

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

obswlQuantity (optional)

Wavelength of the observation used in the calculation

Returns:
sun_below_horizonbool 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)[source]#

Convert time to local sidereal time for observer.

This is a thin wrapper around the sidereal_time method.

Parameters:
timeTime 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

modelstr 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)[source]#

Time at solar midnight.

Parameters:
timeTime 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_pointsint (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)[source]#

Returns the position of the moon in alt/az.

Parameters:
timeTime 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).

ephemerisstr, 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:
altazSkyCoord

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)[source]#

Calculate the illuminated fraction of the moon.

Parameters:
timeTime 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)[source]#

Calculate lunar orbital phase.

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

Parameters:
timeTime 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_anglefloat

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)[source]#

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:
timeTime 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.

horizonQuantity (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_pointsint (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)[source]#

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:
timeTime 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.

horizonQuantity (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_pointsint (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)[source]#

Time at solar noon.

Parameters:
timeTime 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_pointsint (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, kind='mean', model=None)[source]#

Calculate the parallactic angle.

Parameters:
timeTime

Observation time.

targetFixedTarget 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.

kindstr

Argument to the sidereal_time function, which may be either 'mean' or 'apparent', i.e., accounting for precession only, or also for nutation.

modelstr or None; optional

Precession (and nutation) model to use in the call to sidereal_time, see docs for that method for details.

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].

sun_altaz(time)[source]#

Returns the position of the Sun in alt/az.

Parameters:
timeTime 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).

ephemerisstr, 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:
altazSkyCoord

Position of the sun transformed to altitude and azimuth

sun_rise_time(time, which='nearest', horizon=<Quantity 0. deg>, n_grid_points=150)[source]#

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:
timeTime 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.

horizonQuantity (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_pointsint (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)[source]#

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:
timeTime 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

horizonQuantity (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_pointsint (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)[source]#

Calculate the local hour angle of target at time.

Parameters:
timeTime 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)

targetSkyCoord, 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_angleAngle

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)[source]#

Is target above horizon at this time?

Parameters:
timeTime 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)

targetSkyCoord, FixedTarget, or list

Target celestial object(s)

horizonQuantity (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_altazbool (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:
observableboolean 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)[source]#

Calculate time at the antitransit of the meridian.

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

Parameters:
timeTime 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)

targetSkyCoord, 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_targetsbool

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_pointsint (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)[source]#

Calculate time at the transit of the meridian.

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

Parameters:
timeTime 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)

targetSkyCoord, 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_pointsint (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)[source]#

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:
timeTime 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)

targetSkyCoord, FixedTarget, or list

Target celestial object(s)

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

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

horizonQuantity (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_pointsint (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)[source]#

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:
timeTime 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)

targetSkyCoord, FixedTarget, or list

Target celestial object(s)

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

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

horizonQuantity (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_pointsint (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)[source]#

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:
timeTime (optional), default = now

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

horizonQuantity (optional), default = zero degrees

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

obswlQuantity (optional)

Wavelength of the observation used in the calculation

Returns:
timesTime

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

twilight_evening_astronomical(time, which='nearest', n_grid_points=150)[source]#

Time at evening astronomical (-18 degree) twilight.

Parameters:
timeTime 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_pointsint (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)[source]#

Time at evening civil (-6 degree) twilight.

Parameters:
timeTime 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_pointsint (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)[source]#

Time at evening nautical (-12 degree) twilight.

Parameters:
timeTime 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_pointsint (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)[source]#

Time at morning astronomical (-18 degree) twilight.

Parameters:
timeTime 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_pointsint (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)[source]#

Time at morning civil (-6 degree) twilight.

Parameters:
timeTime 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_pointsint (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)[source]#

Time at morning nautical (-12 degree) twilight.

Parameters:
timeTime 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_pointsint (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