CALLHORIZONS 0.9 documentation

# 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)
  `__getitem__`(key)

    provides access to query data

    Parameters: | key : str/int epoch index or property key
    Returns: | query data according to key

  `__init__`(targetname)

    Initialize query to Horizons

    Parameters: | targetname : str HORIZONS-readable target number, name, or designation

  `__len__`()

    returns total number of epochs that have been queried

  `__module__` = 'callhorizons'
  `__repr__`()

    returns brief query information

  `__str__`()

    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)

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

    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)

    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)

    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)

    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

- Index
- Module Index
- Search Page