Keck Observatory Archive (KOA) Tutorial: Moving Object Searches in PyKOA

PyKOA Version January 2023: Version 1.7.2

The Keck Observatory Archive (KOA) contains tens of thousands of observations of solar system objects. This notebook shows how to use the PyKOA Python client to seach KOA in time and space for public and protected observations of solar system objects. It is the Python analog of the the Moving Object Search Service (MOSS) available through the KOA web page at https://koa.ipac.caltech.edu.

Installation

PyKOA can be installed from PyPI:

pip install pykoa
or if already installed: pip install --upgrade pykoa

For displaying PNG images below (3. Display The PNG files), copy the https://koa.ipac.caltech.edu/UserGuide/PyKOA/notebooks/mossdisputil.py file into the same directory as this notebook. The mossdisputil.py utility uses the plotting environment dash and jupyter_dash. See https://dash.plotly.com/workspaces/using-dash-in-jupyter-and-workspaces The following modules are needed and can be installed via pip if not already in your python environment:

pip install dash
pip install jupyter_dash
pip install plotly
pip install astropy
pip install panda
pip install skimage

Requirements

Requires Python 3.6 (or above), plus table read and write functions from Astropy. We have tested with Astropy 4.0.1. We recommend using the Anaconda Python distribution.

from pykoa.koa import Koa
from astropy.table import Table, Column
import json
import glob
import os
module_path = os.path.abspath(os.path.join('.'))

Search for Solar System Objects: Koa.query_moving_object

The Koa.query_moving_object method in PyKOA supports searches for observations of an asteroid, comet, planet, or satellite by NAIF ID (SPK-ID), or by manually entering the orbital elements.

NAIF IDs:

NAIF IDs (SPK-IDs) are unique identifiers of solar system objects, found using the JPL Small-Body Database Browser https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html#/.

Object IDs can be ambiguous, and are resolved in this priority of object types: planets, natural satellites, asteroids, comets. If a name is given that resolves to more than one object (e.g. 'Io' can be Jupiter's moon Io or the asteroid 85 Io), then an informational message is provided giving the possible options.

Koa.query_moving_object method parameters for queries on public data:

Parameter	Description	Required(R)/Optional(O)	Values	Default	Notes
Instrument	Keck Instrument Name	R	...	...	...
object	Object name	R	...	...	...
naifid	NAIF_ID of object	R	...	...	R required if object name is ambiguous
startdate	Start date	R	...	...	...
enddate	End date of observations	O	...	current date	...
outdir	Path to output files	R	...	...	...
outfile	JSON Output file name	R	...	...	...
datatype	data types to be output	O	image/spec/both	both	...
graphoption	Images of paths	O	0/1	1	0/1=(no)images showing trajectory
orbitalinput	Orbital Elements	O	0/1	0	0/1=no orbital elements
debugfile	Name of debug file	O	...	...	useful in troubleshooting

Example 1: Discovering, Downloading and Visualizing NIRSPEC observations of Pluto

This example illustrates four queries that return the metadata for observations of Pluto (NAIF ID = 999) made with NIRSPEC between Jan 1 1995 and Sept 20 2022, parse the metadata to create metadata tables for image and spectroscopic data, and download PNG files of the tracks of Pluto across the sky; and then download the science and calibration files and visualize the PNG files.

1. Discover metadata and create metadata table (JSON format), create tables of image and spectroscopic metadata (IPAC ASCII column-delimited format), and download the PNG files, which show the trajectory of the object overlaid in the footprints of the KOA data. All the results can be found in the output directory "nirspec_pluto"

Koa.query_moving_object(instrument='nirspec', \
                        object='pluto', \
                        naifid='999', \
                        startdate='1995-01-01', \
                        enddate='2022-09-20', \
                        outdir='./nirspec_pluto', \
                        outfile='nirspec_pluto.json', \
                        debugfile='./nirspec_moss.debug')

submitting request...
result metafile list written to ./nirspec_pluto/nirspec_pluto.json
Start downloading 4 metadata tables and their associated graph PNG files you requested;
please check your outdir: ./nirspec_pluto for  progress.
4 metadata tables and 48 graph PNG files downloaded.

2a: Download the NIRSPEC image data

Ths example downloads the NIRSPEC science and calibration image files, and the quick-look reduced files (if available). The example downloads two records wortth of data to speed-up the example.

Koa.download ('./nirspec_pluto/nirspec_pluto_im.tbl',
    'ipac', \
    './nirspec_pluto_data', \
    start_row=1000, \
    end_row=1001, \
    calibfile=1, \
    lev1file=1 )

Start downloading 2 koaid data you requested;
please check your outdir: ./nirspec_pluto_data for  progress ....
No level 1 data found for koaid: [NC.20010407.46191.fits]
No associated calibration list for NC.20010407.46191.fits
No level 1 data found for koaid: [NC.20010407.46206.fits]
No associated calibration list for NC.20010407.46206.fits

A total of 2 new lev0 FITS files downloaded.
2 new lev1 list downloaded.
0 new lev1 files downloaded.
0 new calibration list downloaded.
0 new calibration FITS files downloaded.

2b: Download the NIRSPEC spectroscopic data

Ths example downloads the NIRSPEC science and calibration spectroscopic files files, and the quick-look extracted files (if available). The example downloads two records worth of data to speed-up the example.

Koa.download ('./nirspec_pluto/nirspec_pluto_spec.tbl',
    'ipac', \
    './nirspec_pluto_data', \
    start_row=1000, \
    end_row=1001, \
    calibfile=1, \
    lev1file=1 )

Start downloading 2 koaid data you requested;
please check your outdir: ./nirspec_pluto_data for  progress ....

A total of 2 new lev0 FITS files downloaded.
2 new lev1 list downloaded.
164 new lev1 files downloaded.
2 new calibration list downloaded.
112 new calibration FITS files downloaded.

3. Display The PNG files

The PNG files show the intersection of the path of Pluto on the footprints of the NIRSPEC data. In the cell below, run the app.run_server with mode='external' and a port number; e.g. 8876. You will see a message such as 'Dash app running on http://your-hostname:8876' where 8876 is the local port number you selected. If you don't specify a port, the default will be port=8050; if, however, that port is being used elsewhere, the operation will fail. Make sure you have mossdisputil.py installed in the same directory as this notebook. It installs Dash and configures the plotting environment.

The code returns a URL: click it to see a tablation of the PNG images. Click the "pngfile" cell, the image will be shown on the right side of the HTML page. The tables are scrollable, so you can view all the metadata columns by just scrolling to the right.

You can also run the app.run_server with mode='inline', then the graph will be shown inside the Jupyter page, but is likely to be cramped and is not recommended.

from mossdisputil import mossDisputil

def tblDisp (impath, specpath, pngdir, **kwargs):

    debug = 0
    
    if debug:
        print (f'Enter tblDisp: impath= {impath:s}')
        print (f'specpath= {specpath:s}')
        print (f'pngdir= {pngdir:s}')
        
    mossdisp = None
    try:
        mossdisp = mossDisputil (impath, specpath, pngdir)
    except Exception as e:
        msg = 'Failed to initialize mossDisputil: ' + str(e)
        print (msg)
        return
    
    app = mossdisp.setup_mossapp()
 
    app.run_server (mode='external', port=8876)


if __name__=="__main__":

    import sys

    tblDisp ('./nirspec_pluto/nirspec_pluto_im_graph.tbl', \
        './nirspec_pluto/nirspec_pluto_spec_graph.tbl', \
        './nirspec_pluto/png')

Dash app running on http://127.0.0.1:8876/

Example 2: Discovering, Downloading and Visualizing NIRC2 observations of Pallas

This example is similar to example 1. Because Pallas is identified unambiguously by SPK, there is no need to include a NAIF ID.

Koa.query_moving_object(instrument='nirc2', \
                        object='pallas', \
                        startdate='1995-01-01', \
                        outdir='./nirc2_pallas', \
                        outfile='nirc2_pallas.json' )

submitting request...
result metafile list written to ./nirc2_pallas/nirc2_pallas.json
Start downloading 2 metadata tables and their associated graph PNG files you requested;
please check your outdir: ./nirc2_pallas for  progress.
2 metadata tables and 6 graph PNG files downloaded.

The query returns no spectroscopic observations, so in the call to display the images in the below, enter 'None' for the filename of the spectroscopic metadata:

tblDisp ('./nirc2_pallas/nirc2_pallas_im.tbl', \
            None, \
         './nirc2_pallas/png')

  from mossdisputil import mossDisputil

def tblDisp (impath, specpath, pngdir, **kwargs):

    debug = 0
    
    if debug:
        print (f'Enter tblDisp: impath= {impath:s}')
        print (f'specpath= {specpath:s}')
        print (f'pngdir= {pngdir:s}')
        
    mossdisp = None
    try:
        mossdisp = mossDisputil (impath, specpath, pngdir)
    except Exception as e:
        msg = 'Failed to initialize mossDisputil: ' + str(e)
        print (msg)
        return
    
    app = mossdisp.setup_mossapp()
 
    #app.run_server (mode='inline', debug=True)
    app.run_server (mode='external', port=8876)

if __name__=="__main__":

    import sys

    tblDisp ('./nirc2_pallas/nirc2_pallas_im.tbl', \
                None, \
             './nirc2_pallas/png')
         


    

Dash app running on http://127.0.0.1:8876/

Example 3: Discovering observation of Lutetia with manual input of orbital parameters

Input the orbital parameters as follows

Parameter	Description	Units
Object	object name	N/A
ec	orbital eccentricity	N/A
epoch	epoch	JD
om	longitude of ascending node	deg
w	argument of perihelion	deg
inc	inclination	deg
For a comet:
qr	perihelion distance	AU
tp	perihelion Julian date	JD
For an asteriod:
a	semi-major axis	AU
m0	mean anomaly	deg

Koa.query_moving_object ( \
    instrument = 'nirc2', \
    object = 'lutetia', \
    startdate = '1995-01-01', \
    outdir ='./nirc2_lutetia', \
    outfile = 'lutetia_orbital.json', \
    orbitalinput = 1, \
    ec = '0.164587024192538', \
    epoch = '2457800.500000', \
    om = '80.88034501826424', \
    w = '250.0144262431933', \
    inc = '3.06376292337028', \
    a = '2.434292642077133', \
    m0 = '136.722830835853' )

submitting request...
result metafile list written to ./nirc2_lutetia/lutetia_orbital.json
Start downloading 2 metadata tables and their associated graph PNG files you requested;
please check your outdir: ./nirc2_lutetia for  progress.
2 metadata tables and 9 graph PNG files downloaded.

Example 4: Accessing protected data

The next query shows how PIs can login with their KOA credentials, assigned when the dat thta were acquired, and access their protected data. The example is a query for public data to show the syntax. At the prompts, please login with your KOA supplied credentials to access your protected data. While logged in, you can access all public data as well. Koa.login creates a cookie file, tapcookie.txt, which you should include in your queries.

Koa.login ('./tapcookie.txt')

Koa.query_moving_object(instrument='nirspec', \
                        object='pluto', \
                        naifid='999', \
                        startdate='1995-01-01', \
                        enddate='2022-09-20', \
                        outdir='./nirspec_pluto_prop', \
                        outfile='nirspec_pluto.json', \
                        cookiepath='./tapcookie.txt')

---

Visit KOA at https://koa.ipac.caltech.edu

Please acknowledge the use of KOA by including this text in your publications: "This research has made use of the Keck Observatory Archive (KOA), which is operated by the W. M. Keck Observatory and the NASA Exoplanet Science Institute (NExScI), under contract with the National Aeronautics and Space Administration."

Please also acknowledge the PI(s) of datasets that have been obtained through KOA.

The Keck Observatory Archive (KOA) is a collaboration between the NASA Exoplanet Science Institute (NExScI) and the W. M. Keck Observatory (WMKO). NExScI is sponsored by NASA's Exoplanet Exploration Program, and operated by the California Institute of Technology in coordination with the Jet Propulsion Laboratory (JPL).

Need help? Submit your questions to the KOA Help Desk