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
obs_idObservation IDstringObservation identifier, given by missionU24Z0101T, N4QF18030
..................
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=135
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
str7str4str7str12str4str13str8str13str54str50float64float64str8str16int64float64float64float64float64float64str70float64str4str3int64str132str63str81str16boolfloat64str9str9
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001008_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.64941375775460265.65301753472300.63600.02800.0SOSS background measurements60265.681967444479CAL--POLYGON 9.325091029 1.406134446 9.309028303 1.43963309 9.342821013 1.455643805 9.35890312 1.422164529mast:JWST/product/jw04479001008_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001008_03101_00001_nis_rateints.fitsPUBLICFalsenan192007020370480998
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001001_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.5837301234960265.58733390046300.63600.02800.0SOSS background measurements60265.667488314479CAL--POLYGON 9.350452979 1.418150502 9.334390429 1.451649271 9.368183444 1.467659722 9.384265372 1.434180319mast:JWST/product/jw04479001001_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001001_03101_00001_nis_rateints.fitsPUBLICFalsenan191961743370481010
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001006_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.6307826697960265.634386446756300.63600.02800.0SOSS background measurements60265.667604054479CAL--POLYGON 9.337523341 1.40174698 9.321460798 1.435245697 9.355253516 1.451256258 9.371335441 1.41777691mast:JWST/product/jw04479001006_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001006_03101_00001_nis_rateints.fitsPUBLICFalsenan191961741370481023
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479002008_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.7343440471160265.73794782408300.63600.02800.0SOSS background measurements60265.787048554479CAL--POLYGON 9.325091017 1.406134443 9.309028286 1.439633085 9.342820993 1.455643805 9.358903106 1.422164532mast:JWST/product/jw04479002008_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479002008_03101_00001_nis_rateints.fitsPUBLICFalsenan192102532370481028
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479002010_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.75285662812560265.75646040509300.63600.02800.0SOSS background measurements60265.778286954479CAL--POLYGON 9.320615514 1.393736439 9.304552697 1.427234998 9.338345138 1.443245893 9.354427339 1.409766703mast:JWST/product/jw04479002010_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479002010_03101_00001_nis_rateints.fitsPUBLICFalsenan192101873370481030
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479002003_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.69689148923560265.7004952662300.63600.02800.0SOSS background measurements60265.746203674479CAL--POLYGON 9.345977528 1.405752567 9.329915153 1.439251378 9.363708024 1.455261742 9.37978978 1.421782299mast:JWST/product/jw04479002003_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479002003_03101_00001_nis_rateints.fitsPUBLICFalsenan192022229370481031
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001009_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.6586811535960265.66228493056300.63600.02800.0SOSS background measurements60265.690648074479CAL--POLYGON 9.31663705 1.402128898 9.300574174 1.435627456 9.334366739 1.451638351 9.350448997 1.418159162mast:JWST/product/jw04479001009_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001009_03101_00001_nis_rateints.fitsPUBLICFalsenan192007022370481033
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001010_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.6679137461860265.67151752315300.63600.02800.0SOSS background measurements60265.698518454479CAL--POLYGON 9.320615515 1.39373645 9.304552703 1.427235011 9.338345146 1.443245901 9.354427342 1.409766709mast:JWST/product/jw04479001010_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001010_03101_00001_nis_rateints.fitsPUBLICFalsenan192007024370481038
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479002004_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.5744145795160265.57801835648300.63600.02800.0SOSS background measurements60265.668553084479CAL--POLYGON 9.354432351 1.409758728 9.33837033 1.443257722 9.372163444 1.4592677 9.388244845 1.425788073mast:JWST/product/jw04479002004_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479002004_03101_00001_nis_rateints.fitsPUBLICFalsenan191959981370481039
scienceJWSTCALJWSTNIRISS/IMAGEJWSTCLEAR;GR700XDInfraredECLIPTIC-RA00Calibration; External flat fieldjw04479001003_03101_00001_nis9.3443875000000021.4307027777777779imageEspinoza, Nestor260265.6021604707260265.60576424769300.63600.02800.0SOSS background measurements60265.667083264479CAL--POLYGON 9.345977518 1.405752619 9.329915147 1.439251431 9.363708019 1.455261792 9.379789772 1.421782347mast:JWST/product/jw04479001003_03101_00001_nis_trapsfilled.jpgmast:JWST/product/jw04479001003_03101_00001_nis_rateints.fitsPUBLICFalsenan191961744370481053
...................................................................................................
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14--jw01541001001_04101_00001-seg001_nis260.116173674233238.24216472053897spectrumEspinoza, Nestor259738.2978802893559738.5524864930618855.408600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.16189736 38.23724474 260.11337274 38.23745635 260.11348205 38.24618969 260.16201603 38.24597525 260.16189736 38.23724474mast:JWST/product/jw01541001001_04101_00001-seg001_nis_ramp.jpgmast:JWST/product/jw01541001001_04101_00001-seg001_nis_x1dints.fitsPUBLICFalsenan85700117371225133
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14Star; Exoplanet Systems; Exoplanets; F dwarfs; F starsjw01541001001_04101_00001-seg004_nis260.116177163084438.24215651109613spectrumEspinoza, Nestor259738.2978802893559738.5524864930618855.408600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.16190084 38.23723653 260.11337623 38.23744814 260.11348554 38.24618148 260.16201952 38.24596704 260.16190084 38.23723653mast:JWST/product/jw01541001001_04101_00001-seg004_nis_ramp.jpgmast:JWST/product/jw01541001001_04101_00001-seg004_nis_x1dints.fitsPUBLICFalsenan85700141371225200
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14Star; Exoplanet Systems; Exoplanets; F dwarfs; F starsjw01541001001_02101_00002-seg001_nis260.1161771627305438.24215651192892imageEspinoza, Nestor259738.2620806944559738.2620912268540.954600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.117045344 38.242630644 260.116929825 38.241464963 260.115456996 38.241551067 260.11557248 38.24271685mast:JWST/product/jw01541001001_02101_00002-seg001_nis_cal.jpgmast:JWST/product/jw01541001001_02101_00002-seg001_nis_cal.fitsPUBLICFalsenan85700160371225256
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14Star; Exoplanet Systems; Exoplanets; F dwarfs; F starsjw01541001001_02101_00001-seg001_nis260.1161771627286638.24215651193334imageEspinoza, Nestor259738.2612162559738.261226782410.954600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.116957169 38.242674819 260.116841675 38.241509137 260.115368843 38.241595221 260.115484303 38.242761006mast:JWST/product/jw01541001001_02101_00001-seg001_nis_cal.jpgmast:JWST/product/jw01541001001_02101_00001-seg001_nis_cal.fitsPUBLICFalsenan85700178371225300
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14Star; Exoplanet Systems; Exoplanets; F dwarfs; F starsjw01541001001_04101_00001-seg003_nis260.116177163084438.24215651109613spectrumEspinoza, Nestor259738.2978802893559738.5524864930618855.408600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.16190084 38.23723653 260.11337623 38.23744814 260.11348554 38.24618148 260.16201952 38.24596704 260.16190084 38.23723653mast:JWST/product/jw01541001001_04101_00001-seg003_nis_ramp.jpgmast:JWST/product/jw01541001001_04101_00001-seg003_nis_x1dints.fitsPUBLICFalsenan85700237371225426
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14--jw01541001001_04101_00001-seg002_nis260.116173674233238.24216472053897spectrumEspinoza, Nestor259738.2978802893559738.5524864930618855.408600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.16189736 38.23724474 260.11337274 38.23745635 260.11348205 38.24618969 260.16201603 38.24597525 260.16189736 38.23724474mast:JWST/product/jw01541001001_04101_00001-seg002_nis_ramp.jpgmast:JWST/product/jw01541001001_04101_00001-seg002_nis_x1dints.fitsPUBLICFalsenan85700224371225559
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredHAT-P-14Star; Exoplanet Systems; Exoplanets; F dwarfs; F starsjw01541001001_04102_00001-seg001_nis260.116177163368638.242156510427485imageEspinoza, Nestor259738.5539086689859738.55835982639329.64600.02800.0NIRISS Sensitivity and Stability for Transiting Exoplanet Observations59774.85416661541COM--POLYGON 260.071038142 38.249479213 260.119374977 38.246710174 260.118514171 38.23802336 260.070180892 38.24078268mast:JWST/product/jw01541001001_04102_00001-seg001_nis_ramp.jpgmast:JWST/product/jw01541001001_04102_00001-seg001_nis_rateints.fitsPUBLICFalsenan85700205371225649
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredCD-38-2551Star; G starsjw02113005001_04103_00001-seg001_nis94.33630544130956-38.32344481509817imageEspinoza, Nestor260216.252828391260216.257597488424329.64600.02800.0Exploring the morning and evening limbs of a transiting exoplanet60582.576261422113GO--POLYGON 94.343963285 -38.287739716 94.342226315 -38.325776892 94.331128864 -38.325424225 94.332859637 -38.287385839mast:JWST/product/jw02113005001_04103_00001-seg001_nis_ramp.jpgmast:JWST/product/jw02113005001_04103_00001-seg001_nis_rateints.fitsEXCLUSIVE_ACCESSFalsenan178895888373900829
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredCD-38-2551Star; G starsjw02113005001_04101_00001-seg001_nis94.33630544945105-38.3234448051187spectrumEspinoza, Nestor260215.7743559722260215.774483148155.494600.02800.0Exploring the morning and evening limbs of a transiting exoplanet60582.584108712113GO--POLYGON 94.38208655 -38.32834702 94.33350101 -38.32815311 94.33361111 -38.31941977 94.38219434 -38.31961642 94.38208655 -38.32834702mast:JWST/product/jw02113005001_04101_00001-seg001_nis_ramp.jpgmast:JWST/product/jw02113005001_04101_00001-seg001_nis_x1dints.fitsEXCLUSIVE_ACCESSFalsenan178895938373900895
scienceJWSTCALJWSTNIRISS/SOSSJWSTCLEAR;GR700XDInfraredCD-38-2551Star; G starsjw02113-o005_t001_niriss_clear-gr700xd-substrip25694.33630544540856-38.32344481007381spectrumEspinoza, Nestor360215.7568526273260216.2504900925932810.168600.02800.0Exploring the morning and evening limbs of a transiting exoplanet60582.963425882113GO--POLYGON 94.38208655 -38.32834702 94.33350101 -38.32815311 94.3336111 -38.31941978 94.38219433 -38.31961643 94.38208655 -38.32834702--mast:JWST/product/jw02113-o005_t001_niriss_clear-gr700xd-substrip256_x1dints.fitsEXCLUSIVE_ACCESSFalsenan188165781373903106

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'])
{'NIRISS/IMAGE', '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'])
{'NIRISS/IMAGE', 'NIRISS/SOSS', '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'])
({'1512', '1541'}, {'NIRISS/IMAGE', '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