How to ... Use PanStamps to download images within a given time-window

How to ... Use PanStamps to download images within a given time-window

Panstamps was originally designed to download all warp or stacked images found to overlap a given sky-position. This is fine if your objects remain fixed at the same location in the sky, i.e *they don't move*! For moving objects, alongside spatially filtering the panstarrs images we want downloaded, we also require a temporal filter. We need to be able to request images at a given sky-position that were taken within a given time range.

Panstamps was originally designed to download all warp or stacked images found to overlap a given sky-position. This is fine if your objects remain fixed at the same location in the sky, i.e they don’t move! For moving objects, alongside spatially filtering the panstarrs images we want downloaded, we also require a temporal filter. We need to be able to request images at a given sky-position that were taken within a given time range.

For example, I have a moving target that I know is at the position \(\alpha\)=189.1960991, \(\delta\)=28.2374845 (12:36:47.06 +28:14:14.944) at MJD=55246.63228. If I trigger panstamps and ask for all the images at the location:

> panstamps -f --width=4 --downloadFolder=~/Desktop/movers warp 189.1960991 28.2374845

I end up with 103 FITS images. On closer inspection I only really want two of the images:

> ls | grep 55246.63
warp_g_ra189.196099_dec28.237485_mjd55246.63198_arcsec240_skycell1972.009.fits
warp_g_ra189.196099_dec28.237485_mjd55246.63892_arcsec240_skycell1972.009.fits

If we open these two images we find the target at the expected location1:

warp 1 warp 2

This is great, we have the data we wanted … but we didn’t want the 101 extra images downloaded just to get these 2. Now however, with a few tweaks to panstamps, we can pass in an optional time-window to filter the images by. The command-line usage for panstamps is now:

Usage:
    panstamps [options] [--width=<arcminWidth>] [--filters=<filterSet>] [--settings=<pathToSettingsFile>] [--downloadFolder=<path>] (warp|stack) <ra> <dec> [<mjdStart> <mjdEnd>]

    -h, --help                              show this help message
    -f, --fits                              download fits (default on)
    -F, --nofits                            don't download fits (default off)
    -j, --jpeg                              download jepg (default off)
    -J, --nojpeg                            don't download jepg (default on)
    -c, --color                             download color jepg (default off)
    -C, --nocolor                           don't download color jepg (default on)
    -a, --annotate                          annotate jpeg (default true)
    -A, --noannotate                        don't annotate jpeg (default false)
    -t, --transient                         add a small red circle at transient location (default false)
    -T, --notransient                       don't add a small red circle at transient location (default true)
    -g, --greyscale                         convert jpeg to greyscale (default false)
    -G, --nogreyscale                       don't convert jpeg to greyscale (default true)
    -i, --invert                            invert jpeg colors (default false)
    -I, --noinvert                          don't invert jpeg colors (default true)
    --width=<arcminWidth>                   width of image in arcsec (default 1)
    --filters=<filterSet>                   filter set to download and use for color image (default gri)
    --downloadFolder=<path>                 path to the download folder, relative or absolute (folder created where command is run if not set)
    --settings=<pathToSettingsFile>         the settings file

    ra                                      right-ascension in sexagesimal or decimal degrees
    dec                                     declination in sexagesimal or decimal degrees
    mjdStart                                the start of the time-window within which to select images
    mjdEnd                                  the end of the time-window within which to select images

Notice the new mjdStart and mjdEnd optional parameters. So now I can run:

panstamps -Fj --width=4 --filters=gri --downloadFolder=~/Desktop/movers warp 189.1960991 28.2374845 55246.63 55246.64

to return only the 2 images I want. Nice.

For up-to-date panstamps documentation, with install and usage instructions, see Read the Docs.


  1. although in the second warp the source is partially hidden by the pixel mask  ↩