Wildcard Handling with Astroquery.mast#


Learning Goals#

By the end of this tutorial, you will:

  • Use the wildcards available for astroquery.mast.Observations criteria queries

  • Broaden and refine astroquery.mast.Observations criteria queries

  • Fully utilize the instrument_name criteria, especially for JWST queries

  • Query for moving targets using target ephemeris and time criteria such as t_min and t_max

Introduction#

This Notebook demonstrates the use of wildcards in astroquery.mast.Observations criteria queries. The use of wildcards is encouraged for certain criteria types (namely, string object types) to ensure your query returns all results.

We will demonstrate 3 use-cases for wildcards when doing criteria queries and emphasize certain criteria where wildcard usage is highly encouraged, particularly for JWST queries. We will also use the last example to demonstrate the use of value ranges when working with float object criteria types.

The workflow for this notebook consists of:

  • Wildcard overview with astroquery.mast.Observations

    1. Wildcard Search with instrument_name

    2. Wildcard Search with instrument_name and proposal_id

    3. Wildcard Search a Time-sensitive Object with target_name and t_min

  • Resources

Imports#

import astropy.units as u
import matplotlib.pyplot as plt

from astropy.coordinates import SkyCoord
from astropy.table import Table, unique, vstack
from astropy.time import Time
from astroquery.mast import Observations

Wildcards with astroquery.mast.Observations#

The use of wildcards when making astroquery.mast.Observations queries can help ensure you retrieve all observations without leaving anything out. The available wildcards are % and *: % replaces a single character, while * replaces more than one character preceding, following, or in between the existing characters, depending on its placement. See the Observation Criteria Queries section in the astroquery.mast documentation for more information on the wildcards.

Wildcards are only available for certain criteria. string type objects accept wildcards, but float, integer, or any other objects do not accept wildcards.

Users may call the get_metadata method to see the list of query criteria and their data types. The criteria listed as string objects under the Data Type column are criteria that can be called with wildcards:

Observations.get_metadata("observations")
Table length=34
Column NameColumn LabelData TypeUnitsDescriptionExamples/Valid Values
str21str25str7str10str72str116
intentTypeObservation TypestringWhether observation is for science or calibration.Valid values: science, calibration
obs_collectionMissionstringCollectionE.g. SWIFT, PS1, HST, IUE
provenance_nameProvenance NamestringProvenance name, or source of dataE.g. TASOC, CALSTIS, PS1
instrument_nameInstrumentstringInstrument NameE.g. WFPC2/WFC, UVOT, STIS/CCD
projectProjectstringProcessing projectE.g. HST, HLA, EUVE, hlsp_legus
filtersFiltersstringInstrument filtersF469N, NUV, FUV, LOW DISP, MIRROR
wavelength_regionWavebandstringEnergy BandEUV, XRAY, OPTICAL
target_nameTarget NamestringTarget NameEx. COMET-67P-CHURYUMOV-GER-UPDATE
target_classificationTarget ClassificationstringType of targetEx. COMET;COMET BEING ORBITED BY THE ROSETTA SPACECRAFT;SOLAR SYSTEM
..................
s_regions_regionstringICRS ShapeSTC/S FootprintWill be ICRS circle or polygon. E.g. CIRCLE ICRS 17.71740689 -58.40043015 0.625
jpegURLjpegURLstringPreview Image URLhttps://archive.stsci.edu/hst/previews/N4QF/N4QF18090.jpg
distanceDistance (")floatarcsecAngular separation between searched coordinates and center of obsevation
obsidProduct Group IDintegerDatabase identifier for obs_idLong integer, e.g. 2007590987
dataRightsData RightsstringData Rightsvalid values: public,exclusive_access,restricted
mtFlagMoving TargetbooleanMoving Target FlagIf True, observation contains a moving target, if False or absent observation may or may not contain a moving target
srcDenNumber of Catalog ObjectsfloatNumber of cataloged objects found in observation
dataURLData URLstringData URL
proposal_typeProposal TypestringType of telescope proposalEg. 3PI, GO, GO/DD, HLA, GII, AIS
sequence_numberSequence NumberintegerSequence number, e.g. Kepler quarter or TESS sector

Case 1: Wildcard Search with instrument_name#

For our first example we will search for all NIRISS observations taken by a certain proposal/program PI. Our two query criteria are proposal_pi and instrument_name, which are both string object criteria. As such, both can be wildcarded for ease of use.

In fact, it is sometimes necessary to use wildcards when searching on instrument_name. Both HST and JWST use instrument configurations in this field to allow for more precise advanced searches (e.g. NIRISS/IMAGE and STIS/FUV-MAMA). When performing a “generic” search, you must include a wildcard or these more detailed results will be excluded.

We will demonstrate this by looking at the results for the query below:

observations = Observations.query_criteria(proposal_pi="Espinoza, Nestor",
                                           instrument_name="NIRISS*")
observations
Table masked=True length=234
intentTypeobs_collectionprovenance_nameinstrument_nameprojectfilterswavelength_regiontarget_nametarget_classificationobs_ids_ras_decdataproduct_typeproposal_picalib_levelt_mint_maxt_exptimeem_minem_maxobs_titlet_obs_releaseproposal_idproposal_typesequence_numbers_regionjpegURLdataURLdataRightsmtFlagsrcDenobsidobjID
str7str4str7str12str4str13str8str14str54str50float64float64str10str16int64float64float64float64float64float64str70float64str4str3int64str132str80str81str16boolfloat64str9str9
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210h_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.66172463738659688.665328414354300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.079361272 19.219997306 124.088204918 19.256195264 124.126749247 19.247627141 124.117926871 19.211434025mast:JWST/product/jw01541005001_0210h_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210h_00001_nis_rateints.fitsPUBLICFalsenan79661376733199805
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210v_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.6981105285959688.70171430556300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.070680154 19.221940542 124.079522008 19.258138913 124.118067242 19.249572589 124.109246657 19.213379062mast:JWST/product/jw01541005001_0210v_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210v_00001_nis_rateints.fitsPUBLICFalsenan79661402733199880
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210b_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.64615131562559688.64975509259300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.080801154 19.213559815 124.089644763 19.249757705 124.128187507 19.241189289 124.119365169 19.20499624mast:JWST/product/jw01541005001_0210b_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210b_00001_nis_rateints.fitsPUBLICFalsenan79661433733199936
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210p_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.68251202164559688.68611579861300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.072120417 19.215503156 124.080962242 19.251701457 124.119505889 19.243134834 124.110685335 19.206941375mast:JWST/product/jw01541005001_0210p_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210p_00001_nis_rateints.fitsPUBLICFalsenan79661458733199999
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210n_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.67732165127459688.68092542824300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.075014085 19.214855403 124.083856539 19.25105356 124.122399877 19.242486306 124.113578694 19.206292991mast:JWST/product/jw01541005001_0210n_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210n_00001_nis_rateints.fitsPUBLICFalsenan79661490733200051
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210t_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.6929068248959688.696510601854300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.073573871 19.221292827 124.082416316 19.257491062 124.12096125 19.248924145 124.112140074 19.212730753mast:JWST/product/jw01541005001_0210t_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210t_00001_nis_rateints.fitsPUBLICFalsenan79661522733200120
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_0210x_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.7032890355359688.7068928125300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.069953497 19.219045681 124.078795054 19.255244082 124.117339642 19.246677893 124.108519354 19.210484334mast:JWST/product/jw01541005001_0210x_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_0210x_00001_nis_rateints.fitsPUBLICFalsenan79661542733200173
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_02101_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.6200654128559688.623669189816300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.08369426 19.212911861 124.092538264 19.249109658 124.131080754 19.240540834 124.122258022 19.204347878mast:JWST/product/jw01541005001_02101_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_02101_00001_nis_rateints.fitsPUBLICFalsenan79661575733200230
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDECLIPTIC-RA80Calibration; External flat fieldjw01541005001_02103_00001_nis124.1008916666666819.23126111111111imageEspinoza, Nestor259688.6253868943359688.6289906713300.63600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 124.084421799 19.215806744 124.093266409 19.252004442 124.131809472 19.243435191 124.122986133 19.207242333mast:JWST/product/jw01541005001_02103_00001_nis_trapsfilled.jpgmast:JWST/product/jw01541005001_02103_00001_nis_rateints.fitsPUBLICFalsenan79661598733200276
...................................................................................................
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512003001_02101_00004_nis261.217877705017460.43078853297545imageEspinoza, Nestor259996.0052950347259996.0053034606460.6834600.05000.0SOSS Wavelength and Trace59996.223321791512CAL--POLYGON 261.218583699 60.430047681 261.216374892 60.430470734 261.217218009 60.431553546 261.219427079 60.431130459mast:JWST/product/jw01512003001_02101_00004_nis_cal.jpgmast:JWST/product/jw01512003001_02101_00004_nis_cal.fitsPUBLICFalsenan117933686737830022
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512003001_02101_00001_nis261.2178777049690660.43078853295712imageEspinoza, Nestor259995.9988854050959995.998893831020.6834600.05000.0SOSS Wavelength and Trace59996.223692111512CAL--POLYGON 261.218608459 60.430036846 261.216399664 60.430459912 261.217242807 60.43154272 261.219451865 60.431119619mast:JWST/product/jw01512003001_02101_00001_nis_cal.jpgmast:JWST/product/jw01512003001_02101_00001_nis_cal.fitsPUBLICFalsenan117933667737830036
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDBD+60-1753Star; A dwarfsjw01512003001_03101_00001_nis261.2178777050360.43078853298023imageEspinoza, Nestor259996.00690887731659996.007036053245.494600.02800.0SOSS Wavelength and Trace59996.067997671512CAL--POLYGON 261.252812005 60.462625558 261.225202062 60.427083893 261.208742612 60.430236211 261.236320034 60.465785632mast:JWST/product/jw01512003001_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw01512003001_03101_00001_nis_rateints.fitsPUBLICFalsenan117933687737830047
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDBD+60-1753Star; A dwarfsjw01512003001_03102_00001_nis261.217877705046160.430788532986334imageEspinoza, Nestor259996.0078354861159996.01037900463164.82600.02800.0SOSS Wavelength and Trace59996.063171291512CAL--POLYGON 261.252812349 60.462625738 261.225202494 60.427084057 261.208743037 60.430236364 261.23632037 60.465785803mast:JWST/product/jw01512003001_03102_00001_nis_trapsfilled.jpgmast:JWST/product/jw01512003001_03102_00001_nis_rateints.fitsPUBLICFalsenan117933688737830059
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512002001_02101_00001_nis261.217877704834360.43078853290603imageEspinoza, Nestor259995.9810135763959995.9810220023140.6834600.05000.0SOSS Wavelength and Trace59996.181759251512CAL--POLYGON 261.218611229 60.43003597 261.216402689 60.430459359 261.217246483 60.431542043 261.219455287 60.431118619mast:JWST/product/jw01512002001_02101_00001_nis_cal.jpgmast:JWST/product/jw01512002001_02101_00001_nis_cal.fitsPUBLICFalsenan117933629738677988
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512002001_02101_00004_nis261.217877704882460.43078853292429imageEspinoza, Nestor259995.9874009722259995.987409398150.6834600.05000.0SOSS Wavelength and Trace59996.181331011512CAL--POLYGON 261.218583741 60.430047673 261.216375205 60.430471068 261.217219012 60.43155375 261.219427811 60.43113032mast:JWST/product/jw01512002001_02101_00004_nis_cal.jpgmast:JWST/product/jw01512002001_02101_00004_nis_cal.fitsPUBLICFalsenan117933631738677997
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512002001_02101_00003_nis261.2178777048472460.43078853291094imageEspinoza, Nestor259995.9827313541759995.982739780090.6834600.05000.0SOSS Wavelength and Trace59996.182430511512CAL--POLYGON 261.218450695 60.430086083 261.216242156 60.430509478 261.217085963 60.43159216 261.219294765 60.43116873mast:JWST/product/jw01512002001_02101_00003_nis_cal.jpgmast:JWST/product/jw01512002001_02101_00003_nis_cal.fitsPUBLICFalsenan117933632738678003
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDBD+60-1753Star; A dwarfsjw01512002001_03101_00001_nis261.2178777048951660.4307885329291imageEspinoza, Nestor259995.9890244444559995.989151620375.494600.02800.0SOSS Wavelength and Trace59996.022870341512CAL--POLYGON 261.25283293 60.462620181 261.22520026 60.427082814 261.208742825 60.430237693 261.236342987 60.465782822mast:JWST/product/jw01512002001_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw01512002001_03101_00001_nis_rateints.fitsPUBLICFalsenan117933633738678016
scienceJWSTCALJWSTNIRISS/SOSSJWSTF480MINFRAREDBD+60-1753Star; A dwarfsjw01512002001_02101_00002_nis261.217877704840760.430788532908466imageEspinoza, Nestor259995.9818661689859995.981874594910.6834600.05000.0SOSS Wavelength and Trace59996.183055561512CAL--POLYGON 261.218488089 60.429982383 261.216279555 60.430405777 261.217123358 60.431488459 261.219332154 60.43106503mast:JWST/product/jw01512002001_02101_00002_nis_cal.jpgmast:JWST/product/jw01512002001_02101_00002_nis_cal.fitsPUBLICFalsenan117933634738678023
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDINFRAREDBD+60-1753Star; A dwarfsjw01512002001_03102_00001_nis261.2178777049112560.4307885329352imageEspinoza, Nestor259995.9899510648259995.99249458333164.82600.02800.0SOSS Wavelength and Trace59996.023379561512CAL--POLYGON 261.25283321 60.46262025 261.225200729 60.427082848 261.208743277 60.430237705 261.236343249 60.46578287mast:JWST/product/jw01512002001_03102_00001_nis_trapsfilled.jpgmast:JWST/product/jw01512002001_03102_00001_nis_rateints.fitsPUBLICFalsenan117933635738678034

Our query returned many NIRISS observations led by the PI Dr. Espinoza. Let’s get all the unique values under the instrument_name column to see what our * wildcard picked up.

set(observations['instrument_name'])
{np.str_('NIRISS/IMAGE'), np.str_('NIRISS/SOSS')}

Our observations have the advanced labeling; had we simply set instrument_name = "NIRISS", we would have missed several observations. For more details on this advanced labeling, see the JWST Instrument Names page.

A note of caution: There is such a thing as too many wildcards#

You can be too generous with the wildcards, so be sure to exercise caution in their use. Too much ambiguity can lead to unintended results. Let’s take a look at our example below.

observations = Observations.query_criteria(proposal_pi='Espinoza, Nestor',
                                           instrument_name='NIR*') # Surely only one instrument begins with 'NIR'
set(observations['instrument_name'])
{np.str_('NIRISS/IMAGE'), np.str_('NIRISS/SOSS'), np.str_('NIRSPEC/SLIT')}

This query returns NIRSPEC/SLIT observations in addition to the NIRISS ones, which is not what we intended.

Case 2: Wildcard Search with instrument_name and proposal_id#

Let’s add an additional string criterion and wildcard into the mix. We’ll do this with the proposal_id field which, despite its numeric content, is encoded as a string.

Let’s query for a four digit proposal/program IDs that begin with 15.

observations = Observations.query_criteria(proposal_pi='Espinoza, Nestor',
                                           instrument_name='NIRISS*',
                                           proposal_id=['15%%']) # Only a four digit result will match this

set(observations['proposal_id']), set(observations['instrument_name'])
({np.str_('1512'), np.str_('1541')},
 {np.str_('NIRISS/IMAGE'), np.str_('NIRISS/SOSS')})

Resources#

The following is a list of resources that were referenced throughout the tutorial, as well as some additional references that you may find useful:

Citations#

If you use any of astroquery’s tools for published research, please cite the authors. Follow this link for more information about citing astroquery:

About This Notebook#

If you have comments or questions on this notebook, please contact us through the Archive Help Desk e-mail at archive@stsci.edu.

Author: Jenny V. Medina
Keywords: astroquery, wildcards, moving target
Last Updated: Jun 2023