ZTF moving target checker for short object lists.

Written by Michael S. P. Kelley (University of Maryland), with contributions from Quan-Zhi Ye (IPAC/Caltech). Thanks to James Bauer, Dennis Bodewits, Tony Farnham, and Matthew Knight for some design comments.

If ZChecker is useful to you, please cite Kelley, M. S. P., Bodewits, D., Ye, Q. et al. 2019. ADASS XXVIII, ed. P. Teuben, M. Pound, B. Thomas, and E. Warner, ASP Conf. Ser., 471, 305.

ZChecker is licensed with the BSD 3-clause license. See LICENSE for details.

Support for ZChecker was provided by the NASA/University of Maryland/Minor Planet Center Augmentation through the NASA Planetary Data System Cooperative Agreement NNX16AB16A, NASA Near-Earth Objects Observations grant NNX15AD99G, and NASA Solar System Observations grant 80NSSC20K0673.

• Python 3.8+
• astropy v4
• sbsearch v0.1
• sbpy 0.3
• requests
• astroquery 0.4.6
• sqlite
• wget
• sep

• Montage and montage_wrapper, optional, for image reprojection with zproject
• oorb and its Python wrapper for Minor Planet Center Possible Comet Confirmation Page (PCCP) checking
• photutils 0.5+, sep for measuring photometry with zphot
• matplotlib for quick look plots with zphot

Create a file with your preferred locations for the database, log file, etc.. The file may be placed in the current directory (./zchecker.config) or in a user configuration directory ($HOME/.config/zchecker.config). If both exist, the former takes precedence. To see the file format and current allowed configuration parameters::

$ zchecker --help

...
{
"database": "/path/to/zchecker.db",
"log": "/path/to/zchecker.log",
"user": "IRSA account user name",
"password": "IRSA account password",
"cutout path": "/path/to/cutout/directory",
"cutout size": "5arcmin",
"stack path": "/path/to/stack/directory"
}

1. (Optional) Make a list of objects: objects.list.

2. Update local database with ephemerides, specifying objects through the list or on the command line::

   zchecker eph-update objects.list --start=YYYY-MM-DD --stop=YYYY-MM-DD

   zchecker eph-update "C/2017 Y1, C/2017 Y2" --start=YYYY-MM-DD --stop=YYYY-MM-DD

   Broad date ranges are best. Ephemerides can be updated as the orbital elements are refined.

3. Delete ephemerides from the database::

   zchecker eph-update --clean objects.list

   zchecker eph-update --clean objects.list --start=YYYY-MM-DD --stop=YYYY-MM-DD

   zchecker eph-update --clean "C/2017 Y1, C/2017 Y2" --start=YYYY-MM-DD --stop=YYYY-MM-DD

1. Update local database with ZTF observations from a single night::

   zchecker ztf-update --date=YYYY-MM-DD

   Over a range of nights:

   zchecker ztf-update --start=YYYY-MM-DD --stop=YYYY-MM-DD

   Or to simply check the last night::

   zchecker ztf-update

2. Summarize nights in the local database::

   zchecker list-nights

3. Get ephemerides for an object::

   zchecker eph-update 60558 --start=YYYY-MM-DD --stop=YYYY-MM-DD

4. Add/remove alternate name for object::

   zchecker update-object 60558 174P

   Remove it::

   zchecker remove-object 174P

   The primary designation will always be used for ephemerides.

   Experimental Rename object's primary designation::

   zchecker update-object --rename 'P/2000 S4' 'P/2019 K2'

   No cutout files, etc. will be updated, but new ones will use the new name.

5. Find observations of your targets from the last night::

   zchecker search

   For a specific date::

   zchecker search --date=YYYY-MM-DD

   Over a range of dates::

   zchecker search --start=YYYY-MM-DD --stop=YYYY-MM-DD

   For all dates in the local database::

   zchecker search --full

   For a subset of targets saved to the file subset.list::

   zchecker search subset.list --full

   For a subset of targets specified on the command line::

   zchecker search "C/2017 AB5" --full

   zchecker search "C/2017 Y1,C/2017 Y2" --full

   Using a different V magnitude limit::

   zchecker search "C/2017 Y1,C/2017 Y2" --full --vmax=18

6. Report previously found objects::

   zchecker list-found "C/2017 Y1,C/2017 Y2"

   For a specific date / date range::

   zchecker list-found --date=2018-11-01

   zchecker list-found --start=2018-11-01 --stop=2018-11-12

7. Clean the found object database and associated cutout files, if they exist::

   zchecker clean-found "C/2017 AB5"

   zchecker clean-found "C/2017 AB5" --start=YYYY-MM-DD --stop=YYYY-MM-DD

8. Download cutouts around each found target::

   zchecker download-cutouts

   For specific targets::

   zchecker download-cutouts "C/2017 Y1,C/2017 Y2"

   Use a different size::

   zchecker download-cutouts 6478 --size=20arcmin

9. ZChecker's database tracks files that have been downloaded, but accidents (and bugs) can happen. If so, verify and fix the downloaded file repository with::

   zchecker download-cutouts 'P/2011 S1' --missing

10. Reproject downloaded cutouts to align projected velocity vectors and comet-Sun vectors along the +x axis::

    zproject

    Use a different size::

    zproject --size=20arcmin

11. Make nightly and bi-weekly stacks by object::

    zstack

    Check integrity of stack archive and fix errors::

    zstack --clean-missing

12. Measure object photometry::

    zphot measure 46P

    Without an object name, zphot would measure all missing photometry.

13. Plot object photometry::

    zphot plot 46P

Cutouts around each object are downloaded to the cutouts directory specified in the configuration. Files are sorted into sub-directories by object name. Cutout file names are lower-case with the format: desg-yyyymmdd_hhmmss-rh-ztf.fits, where rh is the heliocentric distance with the prefix 'pre' or 'post' depending on which side of perihelion it is on (based on heliocentric radial velocity).

The FITS file format for cutouts:

If the SANGLE image is based on DIFF, the SANGLE extension header keyword DIFFIMG will be True.

Stack files are downloaded to the stacks directory specified in the configuration, organized by object name. File names are lower-case with the format: desg-yyyymmdd-rh-ztf-stack.fits:

The coma model is $r_h^{-4} \Delta^{-1}$ and the surface model $r_h^{-2} \Delta^{-2}$.

Summary of ZTF observations by night, as downloaded from IRSA.

Objects.

Objects.

Object ephemerides. The default time step is 1/day, with smaller time steps for objects closer to the Earth.

R-tree of object ephemerides.

Basic observation parameters.

R-tree of observations.

ZTF observation metadata.

Found objects and observation geometry at image mid-time.

There is a one-to-many mapping of stackid to foundid that should be preserved upon multiple runs of zstack.

flux, m, and merr are arrays of single-precision floats.

Photometry flags:

In sbsearch v0.1.2 and earlier, a bug allowed observations to be added twice. If the database only contains ZTF observations, the number of duplicates may be identified with:

SELECT COUNT() FROM obs LEFT JOIN ztf USING(obsid) WHERE pid IS NULL;