Observer¶

class
astroplan.
Observer
(location=None, timezone=u'UTC', name=None, latitude=None, longitude=None, elevation=<Quantity 0.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: 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 metersThe 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
objectastropy_time
to a localizeddatetime
object.at_site
(site_name, **kwargs)Initialize an Observer
object with a site name.datetime_to_astropy_time
(date_time)Convert the datetime
objectdate_time
to aTime
object.is_night
(time[, horizon, obswl])Is the Sun below horizon
attime
?local_sidereal_time
(time[, kind, model])Convert time
to local sidereal time for observer.midnight
(time[, which])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, **kwargs)Returns the local moonrise time. moon_set_time
(time, **kwargs)Returns the local moonset time. noon
(time[, which])Time at solar noon. parallactic_angle
(time, target[, ...])Calculate the parallactic angle. 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
attime
.target_is_up
(time, target[, horizon, ...])Is target
abovehorizon
at thistime
?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)[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 requestedtarget
.Parameters: time :
Time
or other (see below)target :
FixedTarget
,SkyCoord
, or list; defaults toNone
(optional)obswl :
Quantity
(optional)Wavelength of the observation used in the calculation.
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. Useful for grid searches for rise/set times etc.
Returns: 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('20010203 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
objectastropy_time
to a localizeddatetime
object.Timezones localized with pytz.
Parameters: astropy_time :
Time
Scalar or listlike.
Returns: Localized datetime, where the timezone of the datetime is set by the
timezone
keyword argument of theObserver
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('19991231 06:00:00') >>> print(subaru.astropy_time_to_datetime(astropy_time)) 19991230 20:00:0010: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 (seeObserver
for available keyword arguments).Parameters: site_name : str
Observatory name, must be resolvable with
get_site_names
.Returns: 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
objectdate_time
to aTime
object.Timezones localized with pytz. If the
date_time
is naive, the implied timezone is thetimezone
structure ofself
.Parameters: date_time :
datetime
or listlikeReturns: Astropy time object (no timezone information preserved).
Examples
Convert a localized
datetime
to aTime
object. Nonlocalized datetimes are assumed to be UTC. <Time object: scale=’utc’ format=’datetime’ value=19991231 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=20050622 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=20050622 06:00:00>

is_night
(time, horizon=<Quantity 0.0 deg>, obswl=None)[source]¶ Is the Sun below
horizon
attime
?Parameters: time :
Time
or other (see below)horizon :
Quantity
(optional), default = zero degreesDegrees 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)
Examples
Is it “nighttime” (i.e. is the Sun below
horizon
) at Apache Point Observatory at 20150829 18:35 UTC?>>> from astroplan import Observer >>> from astropy.time import Time >>> apo = Observer.at_site("APO") >>> time = Time("20150829 18:35") >>> apo.is_night(time) False

local_sidereal_time
(time, kind=u'apparent', model=None)[source]¶ 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)kind : {‘mean’, ‘apparent’} (optional)
Passed to the
kind
argument ofsidereal_time
model : str or
None
; optionalThe precession/nutation model to assume  see
sidereal_time
for more details.Returns: Local sidereal time.

midnight
(time, which=u'nearest')[source]¶ Time at solar midnight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which noon relative to the present
time
would you like to calculateReturns: Time at solar midnight

moon_altaz
(time, ephemeris=None)[source]¶ Returns the position of the moon in alt/az.
Parameters: time :
Time
or other (see below)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("20150829 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: time :
Time
or other (see below)Returns: float
Fraction of lunar surface illuminated
Examples
How much of the lunar surface is illuminated at 20150829 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("20150829 18:35") >>> apo.moon_illumination(time) array([ 0.99972487])

moon_phase
(time=None)[source]¶ Calculate lunar orbital phase.
For example, phase=2*pi is “new”, phase=0 is “full”.
Parameters: time :
Time
or other (see below)Returns: moon_phase_angle : float
Orbital phase angle of the moon where 2*pi corresponds to new moon, zero corresponds to full moon.
Examples
Calculate the phase of the moon at 20150829 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('20150829 18:35') >>> apo.moon_phase(time) <Quantity [ 0.03317537] rad>

moon_rise_time
(time, **kwargs)[source]¶ Returns the local moonrise time.
The default moonrise returned is the next one to occur.
Parameters: time :
Time
or other (see below)Keywords : str, optional
previous next

moon_set_time
(time, **kwargs)[source]¶ Returns the local moonset time.
The default moonset returned is the next one to occur.
Parameters: time :
Time
or other (see below)Keywords : str, optional
previous next

noon
(time, which=u'nearest')[source]¶ Time at solar noon.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which noon relative to the present
time
would you like to calculateReturns: Time at solar noon

parallactic_angle
(time, target, grid_times_targets=False)[source]¶ Calculate the parallactic angle.
Parameters: time :
Time
Observation time.
target :
FixedTarget
orSkyCoord
or listTarget 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: 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 [R5].
[R5] https://en.wikipedia.org/wiki/Parallactic_angle

sun_rise_time
(time, which=u'nearest', horizon=<Quantity 0.0 deg>)[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 abovehorizon
.Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunrise relative to the present
time
would you like to calculate.horizon :
Quantity
(optional), default = zero degreesDegrees above/below actual horizon to use for calculating rise/set times (i.e., 6 deg horizon = civil twilight, etc.)
Returns: 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('20010203 04:05:06') >>> sun_rise = apo.sun_rise_time(time, which="previous") >>> print("ISO: {0.iso}, JD: {0.jd}".format(sun_rise)) ISO: 20010202 14:02:50.554, JD: 2451943.08531

sun_set_time
(time, which=u'nearest', horizon=<Quantity 0.0 deg>)[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 abovehorizon
.Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunset relative to the present
time
would you like to calculatehorizon :
Quantity
(optional), default = zero degreesDegrees above/below actual horizon to use for calculating rise/set times (i.e., 6 deg horizon = civil twilight, etc.)
Returns: 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('20010203 04:05:06') >>> sun_set = apo.sun_set_time(time, which="next") >>> print("ISO: {0.iso}, JD: {0.jd}".format(sun_set)) ISO: 20010204 00:35:42.102, JD: 2451944.52479

target_hour_angle
(time, target, grid_times_targets=False)[source]¶ Calculate the local hour angle of
target
attime
.Parameters: time :
Time
or other (see below)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget 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.0 deg>, return_altaz=False, grid_times_targets=False)[source]¶ Is
target
abovehorizon
at thistime
?Parameters: time :
Time
or other (see below)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget celestial object(s)
horizon :
Quantity
(optional), default = zero degreesDegrees 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 abovehorizon
attime
, else False.Examples
Are Aldebaran and Vega above the horizon at Apache Point Observatory at 20150829 18:35 UTC?
>>> from astroplan import Observer, FixedTarget >>> from astropy.time import Time >>> apo = Observer.at_site("APO") >>> time = Time("20150829 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=u'nearest', grid_times_targets=False)[source]¶ 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)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget celestial object(s)
which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunrise relative to the present
time
would you like to calculategrid_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: Antitransit time of target
Examples
Calculate the meridian antitransit time of Rigel at Keck Observatory:
>>> from astroplan import Observer, FixedTarget >>> from astropy.time import Time >>> time = Time("20010203 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: 20010203 18:40:29.761, JD: 2451944.27812

target_meridian_transit_time
(time, target, which=u'nearest', grid_times_targets=False)[source]¶ 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)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget celestial object(s)
which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunrise relative to the present
time
would you like to calculategrid_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: 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("20010203 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: 20010203 06:42:26.863, JD: 2451943.77948

target_rise_time
(time, target, which=u'nearest', horizon=<Quantity 0.0 deg>, grid_times_targets=False)[source]¶ Calculate rise time.
Compute time of the next/previous/nearest rise of the
target
object, where “rise” is defined as the time when thetarget
transitions from altitudes below thehorizon
to above thehorizon
.Parameters: time :
Time
or other (see below)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget celestial object(s)
which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunrise relative to the present
time
would you like to calculatehorizon :
Quantity
(optional), default = zero degreesDegrees 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.
Returns: 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("20010203 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: 20010204 00:51:23.330, JD: 2451944.53569

target_set_time
(time, target, which=u'nearest', horizon=<Quantity 0.0 deg>, grid_times_targets=False)[source]¶ Calculate set time.
Compute time of the next/previous/nearest set of
target
, where “set” is defined as when thetarget
transitions from altitudes abovehorizon
to belowhorizon
.Parameters: time :
Time
or other (see below)target : coordinate object (i.e.
SkyCoord
,FixedTarget
) or listTarget celestial object(s)
which : {‘next’, ‘previous’, ‘nearest’}
Choose which sunset relative to the present
time
would you like to calculatehorizon :
Quantity
(optional), default = zero degreesDegrees 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.
Returns: 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("20010203 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: 20010203 12:29:34.768, JD: 2451944.02054

tonight
(time=None, horizon=<Quantity 0.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 fromnow
until the nearestsun_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 degreesDegrees 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=u'nearest')[source]¶ Time at evening astronomical (18 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculate. Default is nearest.Returns: Time of twilight

twilight_evening_civil
(time, which=u'nearest')[source]¶ Time at evening civil (6 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculate. Default is nearest.Returns: Time of twilight

twilight_evening_nautical
(time, which=u'nearest')[source]¶ Time at evening nautical (12 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculate. Default is nearest.Returns: Time of twilight

twilight_morning_astronomical
(time, which=u'nearest')[source]¶ Time at morning astronomical (18 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculateReturns: Time of twilight

twilight_morning_civil
(time, which=u'nearest')[source]¶ Time at morning civil (6 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculate. Default is nearest.Returns: Time of sunset

twilight_morning_nautical
(time, which=u'nearest')[source]¶ Time at morning nautical (12 degree) twilight.
Parameters: time :
Time
or other (see below)which : {‘next’, ‘previous’, ‘nearest’}
Choose which twilight relative to the present
time
would you like to calculate. Default is nearest.Returns: Time of twilight
