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 asteroid’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')
    

    You can also query major bodies (planets and moons) and spacecraft. This is a little bit trickier, since there are no clear naming conventions for these objects, causing ambiguities (see the Horizons documentation for a discussion). Assume that we want to select Jupiter’s moon Io, we would could use the following line:

    io = callhorizons.query('Io', smallbody=False)
    

    Please note the flag smallbody=False, which is necessary here. However, this line will cause an error when one tries to obtain ephemerides or orbital elements: ValueError: Ambiguous target name; check URL: http://ssd.jpl.nasa.gov/.... Calling the provided URL explains the problem. Horizons selects all known objects that contain the letters io. In order to unambiguously refer to Jupiter’s moon Io, one has to use the provided ID number, which is 501. Hence, one should use:

    io = callhorizons.query(501, smallbody=False)
    

    Every target listed in Horizons provides an ID number, allowing for unambiguous identification. If there is ambiguity - or if the target is not in the Horizons database - CALLHORIZONS will raise a ValueError and provide the URL with explanations. Spacecraft can be selected the same way, also requiring the smallbody=False flag.

  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
dq.query    # show URL to query Horizons

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()

Once ephemerides or orbital elements have been queried, the URL with which HOrizons has been called can be listed:

print dq.query

This is especially useful for debugging and finding out why a query might have failed.

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