CALLHORIZONS Documentation

CALLHORIZONS is a Python 2.7 interface to access JPL HORIZONS ephemerides and orbital elements of Solar System bodies.

Installation

PIP

Using PIP, simply call:

pip install callhorizons

GitHub

Using git, simply clone the code from GitHub:

git clone https://github.com/mommermi/callhorizons

or, download and unpack the zip file with all the files from GitHub and then run from the callhorizons directory:

python setup.py install

How to Use It?

  1. import the module into your code:

    import callhorizons

  2. initialize a QUERY object with an objectname that is readable by the JPL HORIZONS website; this might be the target’s name:

    dq = callhorizons.query('Don Quixote')

    number:

    dq = callhorizons.query('3552')

    designation:

    dq = callhorizons.query('1983 SA')

    or packed designation:

    dq = callhorizons.query('J83S00A')

  3. set the time range of epochs that you want to query using:

    dq.set_epochrange('2016-02-27 03:20', '2016-02-28 05:20', '1h')

    where the order is start date and time, end date and time, and step size using YYYY-MM-DD HH:MM UT times, or set discrete times:

    dq.set_discreteepochs([2457446.177083, 2457446.182343])

    where up to 15 discrete epochs are provided in the form of a list of Julian Dates.

  4. query ephemerides for the given times for a given observatory code (here: 568, Mauna Kea):

    dq.get_ephemerides(568)

    or, obtain the target’s orbital elements:

    dq.get_elements()

The queried data are stored in the QUERY object and can be accessed easily:

dq.fields   # provide list of available target properties
dq['RA']    # access 'RA' for all epochs
dq[0]       # access all properties for the first epoch
dq.dates    # provide list of epochs

Queried data can also be filtered, e.g., based on airmass:

dq[dq['airmass'] < 1.5]

Orbital elements queried with CALLHORIZONS can be directly converted into PyEphem objects to calculate the ephemerides:

import ephem
dq.get_elements()
dq_pyephem = dq.export2pyephem()

For more information, see the Examples and the callhorizons reference.

Examples

  1. Find the hours on the night of 2015-10-25 (UT) if Centaur Echeclus is observable with airmass < 1.5 from Mauna Kea (observatory code: 568) during dark time:

    import callhorizons
echeclus = callhorizons.query('echeclus')
echeclus.set_epochrange('2015-10-25', '2015-10-26', '1h')
echeclus.get_ephemerides(568)
print echeclus[(echeclus['solar_presence'] != 'daylight') & (echeclus['airmass'] < 1.5)]['datetime']

    Note: you can also use HORIZONS’ own skip daylight function and set an airmass limit during the query:

    echeclus.get_ephemerides(568, skip_daylight=True, airmass_lessthan=1.5)
print echeclus['datetime']

  2. more examples will come in the future ... (what are you interested in?)

callhorizons

callhorizons module

CALLHORIZONS - a Python 2.7 interface to access JPL HORIZONS ephemerides and orbital elements.

This module provides a convenient python interface to the JPL HORIZONS system by directly accessing and parsing the HORIZONS website. Ephemerides can be obtained through get_ephemerides, orbital elements through get_elements. Function export2pyephem provides an interface to the PyEphem module.

michael.mommert (at) nau.edu, latest version: v0.9, 2016-02-27. This code is inspired by code created by Alex Hagen.

class callhorizons.query(targetname)[source]
__getitem__(key)[source]

provides access to query data

Parameters:

key : str/int

epoch index or property key
Returns:

query data according to key
__init__(targetname)[source]

Initialize query to Horizons

Parameters:

targetname : str

HORIZONS-readable target number, name, or designation
__len__()[source]

returns total number of epochs that have been queried

__module__ = 'callhorizons'
__repr__()[source]

returns brief query information

__str__()[source]

returns information on the current query as string

data

returns full data array (structured numpy.ndarray)

dates

returns list of epochs that have been queried (format ‘YYYY-MM-DD HH-MM-SS’)

dates_jd

returns list of epochs that have been queried (Julian Dates)

export2pyephem(center='500@10', equinox=2000.0)[source]

Call JPL HORIZONS website to obtain orbital elements based on the provided targetname, epochs, and center code and create a PyEphem (http://rhodesmill.org/pyephem/) object. This function requires PyEphem to be installed.

Parameters:

center : str

center body (default: 500@10 = Sun)

equinox : float

equinox (default: 2000.0)

Examples

>>> import callhorizons
>>> import numpy
>>> import ephem

>>> ceres = callhorizons.query('Ceres')
>>> ceres.set_epochrange('2016-02-23 00:00', '2016-02-24 00:00', '1h')
>>> ceres_pyephem = ceres.export2pyephem()

>>> nau = ephem.Observer() # setup observer site
>>> nau.lon = -111.653152/180.*numpy.pi
>>> nau.lat = 35.184108/180.*numpy.pi
>>> nau.elevation = 2100 # m
>>> nau.date = '2015/10/5 01:23' # UT 
>>> print 'next rising: %s' % nau.next_rising(ceres_pyephem[0])
>>> print 'next transit: %s' % nau.next_transit(ceres_pyephem[0])
>>> print 'next setting: %s' % nau.next_setting(ceres_pyephem[0])
fields

returns list of available properties for all epochs

get_elements(center='500@10')[source]

Call JPL HORIZONS website to obtain orbital elements based on the provided targetname, epochs, and center code. For valid center codes, please refer to http://ssd.jpl.nasa.gov/horizons.cgi

Parameters:

center : str

center body (default: 500@10 = Sun)

Examples

>>> ceres = callhorizons.query('Ceres')
>>> ceres.set_epochrange('2016-02-23 00:00', '2016-02-24 00:00', '1h')
>>> print ceres.get_elements(), 'epochs queried'
The queried properties and their definitions are:
Property Definition
targetname official number, name, designation [string]
H absolute magnitude in V band (float, mag)
G photometric slope parameter (float)
datetime_jd epoch Julian Date (float)
e eccentricity (float)
p periapsis distance (float, au)
a semi-major axis (float, au)
incl inclination (float, deg)
node longitude of Asc. Node (float, deg)
argper argument of the perifocus (float, deg)
Tp time of periapsis (float, Julian Date)
meananomaly mean anomaly (float, deg)
trueanomaly true anomaly (float, deg)
period orbital period (float, Earth yr)
Q apoapsis distance (float, au)
get_ephemerides(observatory_code, airmass_lessthan=99, solar_elongation=(0, 180), skip_daylight=False)[source]

Call JPL HORIZONS website to obtain ephemerides based on the provided targetname, epochs, and observatory_code. For a list of valid observatory codes, refer to http://minorplanetcenter.net/iau/lists/ObsCodesF.html

Parameters:

observatory_code : str/int

observer’s location code according to Minor Planet Center

airmass_lessthan : float

maximum airmass (optional, default: 99)

solar_elongation : tuple

permissible solar elongation range (optional, deg)

skip_daylight : boolean

crop daylight epoch during query (optional)

Examples

>>> ceres = callhorizons.query('Ceres')
>>> ceres.set_epochrange('2016-02-23 00:00', '2016-02-24 00:00', '1h')
>>> print ceres.get_ephemerides(568), 'epochs queried'
The queried properties and their definitions are:
Property Definition
targetname official number, name, designation [string]
H absolute magnitude in V band (float, mag)
G photometric slope parameter (float)
datetime epoch date and time (str, YYYY-MM-DD HH:MM:SS)
datetime_jd epoch Julian Date (float)
solar_presence information on Sun’s presence (str)
lunar_presence information on Moon’s presence (str)
RA target RA (float, J2000.0)
DEC target DEC (float, J2000.0)
RA_rate target rate RA (float, arcsec/s)
DEC_rate target RA (float, arcsec/s, includes cos(DEC))
AZ Azimuth meas East(90) of North(0) (float, deg)
EL Elevation (float, deg)
airmass target optical airmass (float)
magextinct V-mag extinction due airmass (float, mag)
V V magnitude (comets: total mag) (float, mag)
illumination fraction of illuminated disk (float)
EclLon heliocentr. ecl. long. (float, deg, J2000.0)
EclLat heliocentr. ecl. lat. (float, deg, J2000.0)
r heliocentric distance (float, au)
r_rate heliocentric radial rate (float, km/s)
delta distance from the observer (float, au)
delta_rate obs-centric radial rate (float, km/s)
lighttime one-way light time (float, s)
elong solar elongation (float, deg)
elongFlag app. position relative to Sun (str)
alpha solar phase angle (float, deg)
sunTargetPA PA of Sun->target vector (float, deg, EoN)
velocityPA PA of velocity vector (float, deg, EoN)
GlxLon galactic longitude (float, deg)
GlxLat galactic latitude (float, deg)
RA_3sigma 3sigma pos. unc. in RA (float, arcsec)
DEC_3sigma 3sigma pos. unc. in DEC (float, arcsec)
set_discreteepochs(discreteepochs)[source]

Set a list of discrete epochs, epochs have to be given as Julian Dates

Parameters:

discreteepochs : list

list of floats or strings, maximum length: 15
Returns:

None

Examples

>>> import callhorizons
>>> ceres = callhorizons.query('Ceres')
>>> ceres.set_discreteepochs([2457446.177083, 2457446.182343])

If more than 15 epochs are provided, the list will be cropped to 15 epochs.

set_epochrange(start_epoch, stop_epoch, step_size)[source]

Set a range of epochs, all times are UT

Parameters:

start_epoch : str

start epoch of the format ‘YYYY-MM-DD [HH-MM-SS]’

stop_epoch : str

final epoch of the format ‘YYYY-MM-DD [HH-MM-SS]’

step_size : str

epoch step size, e.g., ‘1d’ for 1 day, ‘10m’ for 10 minutes...
Returns:

None

Examples

>>> import callhorizons
>>> ceres = callhorizons.query('Ceres')
>>> ceres.set_epochrange('2016-02-26', '2016-10-25', '1d')

Note that dates are mandatory; if no time is given, midnight is assumed.

Indices and tables