Note

Download the full notebook for this tutorial here

MAST query and download tools for coronagraphic datasets

SpaceKLIP includes some simple query tools for searching available coronagraphic datasets in MAST.

These are intended for, for instance, determining if there are PSF or background observations from other programs that may be useful in reducing a given science dataset.

Finding available PSF reference or background observations

Let’s see what’s available for NIRCam F356W. This returns a table of all observations, including science obs, PSF reference obs, and background obs (for MIRI).

This output is a bit long; We’ll show next how to filter that to particular kinds of data.

[1]:

import spaceKLIP

table = spaceKLIP.mast.query_coron_datasets('NIRCam', 'F356W')

print(f"Found {len(table)} total rows. Here's the first few:")
table[:5]

Found 34 total rows. Here's the first few:

[1]:
Table length=5
visit_idstart timefiltercoronmsktargnameobslabeldurationnumdthptprogramtitlepi_name
str12str16str5str9str22str54float64int64int64str75str20
V013860010012022-07-29 22:01F356WMASKA335R* phi CenNIRCam 335R - REF83.42691386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860020012022-07-30 01:13F356WMASKA335RHD 116434NIRCam 335R - Roll 1617.94611386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860030012022-07-30 03:16F356WMASKA335RHD 116434NIRCam 335R - Roll 2617.94611386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V011840150012022-09-06 00:00F356WMASKA335RLP 944-20LP 944-20 roll 1846.84411184A NIRCam Coronagraphic Imaging Survey of Nearby Young M DwarfsSchlieder, Joshua
V011840160012022-09-06 01:43F356WMASKA335RLP 944-20LP 944-20 roll 2846.84411184A NIRCam Coronagraphic Imaging Survey of Nearby Young M DwarfsSchlieder, Joshua

The columns in the above provide information on the observation overall (visit number, date and time, instrument settings, etc), the target and observation label, the duration in seconds and number of dither points used, and which APT program these data are from.

Let’s see what PSF references are available in MIRI F1550C.

[2]:

spaceKLIP.mast.query_coron_datasets('MIRI', 'F1550C', kind='REF')

[2]:
Table length=15
visit_idstart timefiltercoronmsktargnameobslabeldurationnumdthptprogramtitlepi_name
str12str16str6str9str23str42float64int64int64str80str21
V010450690012022-06-13 17:35F1550C4QPM_1550HD 922094QPM - F1550C774.40691045MIRI Coronagraphic PSF Characterization, Radial Transmission and 4QPM TransitionDicken, Daniel
V010370100012022-06-18 15:04F1550C4QPM_1550HD 1631134QPM - F1550C2299.4991037MIRI Coronagraphic Contrast RatiosBoccaletti, Anthony
V010370110012022-06-18 21:13F1550C4QPM_1550HD 162989Ref 1 deg F1550C2299.4991037MIRI Coronagraphic Contrast RatiosBoccaletti, Anthony
V013860070012022-07-17 20:48F1550C4QPM_1550* phi CenMIRI 1550C - REF459.70691386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V010450880012022-07-19 10:02F1550C4QPM_1550HD 922094QPM - F1550C2299.4951045MIRI Coronagraphic PSF Characterization, Radial Transmission and 4QPM TransitionDicken, Daniel
V013860270012022-08-02 17:02F1550C4QPM_1550HD 140986MIRI F1550C - REF1726.89451386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V011930040012022-10-21 18:48F1550C4QPM_1550* 19 PsAFomalhautPSF-1550C202.2991193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V011940160012022-11-08 15:17F1550C4QPM_1550HD 218261REF 1550C239.9291194Characterization of the HR 8799 planetary system and planet searchBeichman, Charles A.
V014110080012022-12-13 08:54F1550C4QPM_1550* alf PicAlpha Pic - 1550 4QPM PSF725.99151411Coronagraphy of the Debris Disk Archetype Beta PictorisStark, Chris
V012410410012023-03-10 19:02F1550C4QPM_1550HD 49518Ref HR 2562 - F1550C357.12351241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.
V022430060012023-07-03 14:08F1550C4QPM_1550V* DI TucDITuc F1550C2724.44352243A direct detection of the closest Jupiter analog with JWST/MIRIMatthews, Elisabeth C
V014130090012023-07-15 22:40F1550C4QPM_1550HD 190360HD 190360 F1550 (PSF star)293.84891413MIRI coronagraphy of the Cold Substellar Companion GJ 758 BPueyo, Laurent
V016180070012023-07-27 04:34F1550C4QPM_1550dr3-5859405804986931200offset star for eps Mus. Position A. Obs 22971.79291618Searching Our Closest Stellar Neighbor for Planets and Zodiacal EmissionBeichman, Charles A.
V011930240012023-08-18 21:39F1550C4QPM_1550HD 169305VegaPSF-1550C206.84491193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V012410210012023-09-19 14:11F1550C4QPM_1550HD 222389Ref kappa And - F1550C199.65351241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.

And similarly for background observations:

[3]:

spaceKLIP.mast.query_coron_datasets('MIRI', 'F1550C', kind='BKG')

[3]:
Table length=27
visit_idstart timefiltercoronmsktargnameobslabeldurationnumdthptprogramtitlepi_name
str12str16str6str9str21str37float64int64int64str91str22
V013860300012022-07-18 02:42F1550C4QPM_1550N/AMIRI 1550C - Target BG3609.34111386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860310012022-07-18 04:53F1550C4QPM_1550N/AMIRI 1550C - REF BG459.70611386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860360012022-08-02 19:57F1550C4QPM_1550N/AMIRI F1550C - Target BG3741.88411386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860370012022-08-02 22:29F1550C4QPM_1550N/AMIRI F1550C - REF BG1726.89411386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V011930050012022-10-21 19:43F1550C4QPM_1550* 19 PsAFomalhautPSF-1550C-background202.2911193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V011930100012022-10-21 22:42F1550C4QPM_1550FOMALHAUT-F1550C-BACKFomalhaut-F1550C-background914.37911193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V011940110012022-11-08 10:18F1550C4QPM_1550N/A1550C - Target Bkg4322.62921194Characterization of the HR 8799 planetary system and planet searchBeichman, Charles A.
V011940180012022-11-08 16:18F1550C4QPM_1550N/A1550C - REF Bkg239.9221194Characterization of the HR 8799 planetary system and planet searchBeichman, Charles A.
V014060300012022-11-29 05:12F1550C4QPM_1550HD 1616171550-BGND508.12221406Verification of the MIRI Coronagraphic Target AcquisitionHines, Dean C.
V014110010012022-12-13 00:10F1550C4QPM_1550N/ABeta Pic Background - 1550 4QPM1331.18321411Coronagraphy of the Debris Disk Archetype Beta PictorisStark, Chris
V014110090012022-12-13 10:17F1550C4QPM_1550N/AAlpha Pic Background - 1550 4QPM PSF725.99121411Coronagraphy of the Debris Disk Archetype Beta PictorisStark, Chris
V012410330012023-03-10 15:05F1550C4QPM_1550HR 2562 BackgroundHR 2562 Bckgr - F1550C1199.11921241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.
V012410440012023-03-10 20:22F1550C4QPM_1550HD 49518 BackgroundRef HR 2562 Bckgr - F1550C357.12321241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.
V012770210012023-05-16 20:26F1550C4QPM_1550HD 106906 backgroundHD106906 Bkg 1500C960.39821277Coronographic Observations of Young Exoplanets and Spectroscopic Observations of ROSS 458 CLagage, Pierre-Olivier
V022430010012023-07-03 00:54F1550C4QPM_1550N/ABG_dituc F1550C2724.44322243A direct detection of the closest Jupiter analog with JWST/MIRIMatthews, Elisabeth C
V022430020012023-07-03 03:33F1550C4QPM_1550N/ABG_epsindi F1550C3922.36322243A direct detection of the closest Jupiter analog with JWST/MIRIMatthews, Elisabeth C
V012770160012023-07-04 12:41F1550C4QPM_1550GJ 504 backgroundGJ504 Bkg 1550C239.9221277Coronographic Observations of Young Exoplanets and Spectroscopic Observations of ROSS 458 CLagage, Pierre-Olivier
V014130040012023-07-15 18:41F1550C4QPM_1550GJ-758-BackgroundGJ 758 F1550 roll 1 BACKGROUND864.04621413MIRI coronagraphy of the Cold Substellar Companion GJ 758 BPueyo, Laurent
V014130100012023-07-15 23:49F1550C4QPM_1550HD-190360-BACKGROUNDHD 190360 F1550 (PSF star) BACKGROUND293.84821413MIRI coronagraphy of the Cold Substellar Companion GJ 758 BPueyo, Laurent
V016180020012023-07-26 08:51F1550C4QPM_1550N/Aeps Mus Position A BACKGROUND2971.79221618Searching Our Closest Stellar Neighbor for Planets and Zodiacal EmissionBeichman, Charles A.
V016180040012023-07-26 14:18F1550C4QPM_1550N/AAlpha Cen A F1550 - BACKGROUND9287.3621618Searching Our Closest Stellar Neighbor for Planets and Zodiacal EmissionBeichman, Charles A.
V016180060012023-07-26 23:00F1550C4QPM_1550N/AAlpha Cen A F1550 - BACKGROUND9287.3621618Searching Our Closest Stellar Neighbor for Planets and Zodiacal EmissionBeichman, Charles A.
V016180080012023-07-27 12:52F1550C4QPM_1550N/Aoffset star for eps Mus. BACKGROUND2971.79221618Searching Our Closest Stellar Neighbor for Planets and Zodiacal EmissionBeichman, Charles A.
V011930250012023-08-18 22:39F1550C4QPM_1550HD 169305VegaPSF-1550C-background206.84421193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V011930300012023-08-19 02:01F1550C4QPM_1550VEGA-F1550C-BACKVega-1550C-background915.81721193Coronagraphic Imaging of Young Planets and Debris Disk with NIRCam and MIRIBeichman, Charles A.
V012410130012023-09-19 10:25F1550C4QPM_1550kappa And Backgroundkappa And Bckgr - F1550C899.27921241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.
V012410240012023-09-19 15:22F1550C4QPM_1550HD 222389 BackgroundRef kappa And Bckgr - F1550C199.65321241MIRI Coronagraphic Imaging of exoplanetsRessler, Michael E.

Available search keywords

You can also query by program ID number, filter, coronagraph mask name, and for NIRCam also channel name SW/LW.

[4]:

spaceKLIP.mast.query_coron_datasets('NIRCam', program=1386, filt='F444W', kind='SCI')

[4]:
Table length=2
visit_idstart timefiltercoronmsktargnameobslabeldurationnumdthptprogramtitlepi_name
str12str16str5str9str9str20float64int64int64str70str14
V013860020012022-07-30 01:13F444WMASKA335RHD 116434NIRCam 335R - Roll 1617.94611386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha
V013860030012022-07-30 03:16F444WMASKA335RHD 116434NIRCam 335R - Roll 2617.94611386High Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTHinkley, Sasha

Retrieving filenames

Note that the above by default does not return filenames, nor indeed individual exposures. Each row summarizes one observation, even though there are often multiple dithered exposures per observation.

Set the return_filenames option to return filenames. This will also return more exhaustive metadata in additional table columns as well, compared to the default shorter summary output.

[7]:

spaceKLIP.mast.query_coron_datasets('NIRCam', program=1386, filt='F444W', kind='SCI', return_filenames=True)

[7]:
Table masked=True length=2
filenameproductLevelkindfiltercoronmsktargnamedurationeffexptmeffinttmexp_typebkgdtargbstrtimeis_psfnexposurnframesnintsnumdthptobs_idobslabelpi_nameprogramsubarraytemplatetitlevisit_idvisitstavststart_mjdisRestricted
str47str2bytes3str5str9str9float64float64float64str9str1float64str1int64int64int64int64str26str20str14int64str11str28str70str12str10float64bool
jw01386002001_0310a_00001_nrcalong_calints.fits2bSCIF444WMASKA335RHD 116434617.946615.767307.88352NRC_CORONf59790.1298299529f8821V01386002001P000000000310ANIRCam 335R - Roll 1Hinkley, Sasha1386SUB320A335RNIRCam Coronagraphic ImagingHigh Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTV01386002001SUCCESSFUL59790.05121913194False
jw01386003001_0310a_00001_nrcalong_calints.fits2bSCIF444WMASKA335RHD 116434617.946615.767307.88352NRC_CORONf59790.21375087909f8821V01386003001P000000000310ANIRCam 335R - Roll 2Hinkley, Sasha1386SUB320A335RNIRCam Coronagraphic ImagingHigh Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTV01386003001SUCCESSFUL59790.13650497685False

Set the level option to uncal or rate if you want the filenames for those data products instead.

[8]:

spaceKLIP.mast.query_coron_datasets('NIRCam', program=1386, filt='F444W', kind='SCI', return_filenames=True,
                                    level='uncal')

[8]:
Table masked=True length=2
filenameproductLevelkindfiltercoronmsktargnamedurationeffexptmeffinttmexp_typebkgdtargbstrtimeis_psfnexposurnframesnintsnumdthptobs_idobslabelpi_nameprogramsubarraytemplatetitlevisit_idvisitstavststart_mjdisRestricted
str45str2bytes3str5str9str9float64float64float64str9str1float64str1int64int64int64int64str26str20str14int64str11str28str70str12str10float64bool
jw01386002001_0310a_00001_nrcalong_uncal.fits1bSCIF444WMASKA335RHD 116434617.946615.767307.88352NRC_CORONf59790.1298299529f8821V01386002001P000000000310ANIRCam 335R - Roll 1Hinkley, Sasha1386SUB320A335RNIRCam Coronagraphic ImagingHigh Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTV01386002001SUCCESSFUL59790.05121913194False
jw01386003001_0310a_00001_nrcalong_uncal.fits1bSCIF444WMASKA335RHD 116434617.946615.767307.88352NRC_CORONf59790.21375087909f8821V01386003001P000000000310ANIRCam 335R - Roll 2Hinkley, Sasha1386SUB320A335RNIRCam Coronagraphic ImagingHigh Contrast Imaging of Exoplanets and Exoplanetary Systems with JWSTV01386003001SUCCESSFUL59790.13650497685False

Downloading data

The download_files function can be used to download from MAST the filenames in a given query results table.

[9]:

table = spaceKLIP.mast.query_coron_datasets('NIRCam', program=1386, filt='F444W', kind='SCI', return_filenames=True,
                                    level='uncal')

spaceKLIP.mast.download_files(table)

 DOWNLOAD SUCCESSFUL: ./jw01386002001_0310a_00001_nrcalong_uncal.fits
 DOWNLOAD SUCCESSFUL: ./jw01386003001_0310a_00001_nrcalong_uncal.fits

A MAST API token can be provided by the environment variable $MAST_API_TOKEN to enable download of exclusive-access data.

Set the outputdir parameter if you want the files downloaded somewhere other then the current working directory.

If the files already have been downloaded, they will by default be ignored. Set overwrite=True to redownload, or exists_ok=False to raise an exception if such files already exist.

[ ]: