Note
Go to the end to download the full example code.
Performing a Vizier Query#
The most simple example of a query in ATK is a Vizier query. In this tutorial, data will be retrieved from GALEX for a single target (for guidance on working with multiple targets simultaneously, see here after following these tutorials).
Queries of any kind use the query() tool, which can be imported as follows:
from ATK import query
or:
from ATK.Tools import query
Setting a Target#
The first step in performing a query is to set a target, which can be done in a few different ways. In this example, query() will be used to retrieve GALEX data for van Maanen’s Star.
Stars with Gaia DR3 data can be targeted by their Source ID:
target = 2552928187080872832
The target’s coordinates can be used directly by creating an astropy
SkyCoord:
A
Targetobject can be created explicitly, either from a Gaia source ID or from the star’s coordinates:
from ATK.Models import Target
target = Target.from_id(2552928187080872832)
Note
Passing a Target explicitly may seem unnecessary at first, but it offers a key advantage in queries that simultaneously target multiple stars.
Performing a Query#
With a target set (in this case via the star’s coordinates), a Vizier query can now be performed:
Note
By default, ATK supports queries via aliases to the following Vizier catalogues:
Gaia -
gaiaPan-STARRS -
panstarrsSkyMapper -
skymapperGALEX -
galexROSAT -
rosatSDSS -
sdssWISE -
wise2MASS -
2masseROSITA -
erosita
To utilise any other Vizier catalogue, enter its catalogue ID (e.g. "I/355/gaiadr3" for Gaia DR3). A full tutorial on extending query() to work with any Vizier catalogue (including automatic proper motion correction) can be found here.
The query() tool returns a DataSet, which contains key details of the request along with any returned data.
To see the structure of the returned DataSet, its show() method can be called. This prints it to the terminal in a human-readable format (this also applies to any other ATK data structure). Passing show_types=True to show() forces the printing of all attribute data types. This will be used throughout these tutorials when a structure is seen for the first time:
galex_query.show(show_types=True)
<Empty DataSet>
.kind (str): vizier
.targets (list): 12.291° 5.389° (icrs, 2000-01-01T00:00:00.000, 3.0″)
.exception (bool): False
.data (list): <empty list>
Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()
The majority of the returned DataSet’s attributes are immediately clear, but there are a couple details to note:
targetslists everyATK.Models.Targetof the search as they were entered (coordinates, frame and epoch).exceptionstates whether any exceptions were encountered. IfexceptionisTrue, then the query encountered something unexpected. The most common cause of this is that service being utilised (in this case Vizier) is experiencing downtime.
Any returned data is stored in the DataSet’s data attribute. Unfortunately, targeting van Maanen’s Star with its coordinates has returned an empty DataSet.
Instead the star can be targeted via its Gaia Source ID:
<Record DataSet>
.kind: Record
.targets: 2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 3.0″)
.exception: False
.data:
<galex (II/335/galex_ais) Record>
survey: galex
catalogue: II/335/galex_ais
correction: full
search_pos: 12.294° 5.384° (icrs, 2006-08-01T00:00:00.000)
table:
(astropy.Table)
RAJ2000: [12.293] °
DEJ2000: [5.384] °
Name: [GALEX J004910.4+052300]
objid: [6380239640935270574]
phID: [6380239640934219776]
Cat: [AIS]
RAfdeg: [12.328] °
DEfdeg: [5.431] °
FUVexp: [216.0] s
NUVexp: [216.0] s
GLON: [121.884] °
GLAT: [-57.484] °
tile: [50265]
img: [801]
sv: [25]
r.fov: [0.058] °
Obs: [1]
b: [1]
E(B-V): [0.026000000536441803] mag
Sp?: [0]
chkf: [0]
FUVmag: [nan] mag
e_FUVmag: [nan] mag
NUVmag: [18.189] mag
e_NUVmag: [0.03700000047683716] mag
FUV.a: [nan] mag
e_FUV.a: [nan] mag
NUV.a: [-1.891] mag
e_NUV.a: [0.03700000047683716] mag
FUV.4: [nan] mag
e_FUV.4: [nan] mag
NUV.4: [-1.785] mag
e_NUV.4: [0.039] mag
FUV.6: [nan] mag
e_FUV.6: [nan] mag
NUV.6: [-1.892] mag
e_NUV.6: [0.038] mag
Fafl: [0]
Nafl: [2]
Fexf: [0]
Nexf: [0]
Fflux: [nan] µJy
e_Fflux: [nan] µJy
Nflux: [192.502] µJy
e_Nflux: [6.567] µJy
FXpos: [nan] pix
FYpos: [nan] pix
NXpos: [1998.98] pix
NYpos: [1809.01] pix
Fima: [nan] pix
Nima: [3.711] pix
Fr: [nan] °
Nr: [0.002] °
nS/G: [0.984000027179718]
fS/G: [0.0]
nell: [0.04500000178813934]
fell: [nan]
nPA: [-19.420000076293945] °
e_nPA: [-23.059999465942383] °
fPA: [nan] °
e_fPA: [nan] °
Fnr: [13.0] pix
F3r: [85.0] pix
Nar: [3.5]
Narms: [0.001] °
Nbrms: [0.001] °
Far: [nan]
Farms: [nan] °
Fbrms: [nan] °
NUVw: [161.3000030517578] s
FUVw: [207.1999969482422] s
Prob: [nan]
Sep: [nan] ″
Nerr: [0.4699999988079071] ″
Ferr: [nan] ″
Ierr: [nan] ″
Nperr: [0.05000000074505806] ″
Fperr: [nan] ″
CV: [C]
G: [0]
N: [1]
primid: [6380239640935270400]
groupid: [6380239640935270574]
Gd: [0]
Nd: [1]
primidd: [6380239640935270400]
groupidd: [6380239640935270574]
groupTot: [6380239640935270574]
OName: [N]
Size: [nan] pix
Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()
Targeting van Maanen’s Star in this way has utilised Gaia’s astrometry to correct the position of our search for proper motion before it is executed. Without increasing the query radius, we have retrieved GALEX data for van Maanen’s Star.
Using the Returned Data#
A ATK.Models.DataSet store any returned data as a list of containers matching the kind of data that was requested. Since this tutorial performed a Vizier query for one target, the returned DataSet contains a single Record:
galex_entry = galex_query.data[0]
<galex (II/335/galex_ais) Record>
As with any ATK object, show() can be used to see its structure:
galex_entry.show(show_types=True)
<galex (II/335/galex_ais) Record>
.survey (str): galex
.catalogue (str): II/335/galex_ais
.correction (str): full
.search_pos (astropy.SkyCoord): 12.294° 5.384° (icrs, 2006-08-01T00:00:00.000)
.table:
(astropy.Table)
RAJ2000: [12.293] °
DEJ2000: [5.384] °
Name: [GALEX J004910.4+052300]
objid: [6380239640935270574]
phID: [6380239640934219776]
Cat: [AIS]
RAfdeg: [12.328] °
DEfdeg: [5.431] °
FUVexp: [216.0] s
NUVexp: [216.0] s
GLON: [121.884] °
GLAT: [-57.484] °
tile: [50265]
img: [801]
sv: [25]
r.fov: [0.058] °
Obs: [1]
b: [1]
E(B-V): [0.026000000536441803] mag
Sp?: [0]
chkf: [0]
FUVmag: [nan] mag
e_FUVmag: [nan] mag
NUVmag: [18.189] mag
e_NUVmag: [0.03700000047683716] mag
FUV.a: [nan] mag
e_FUV.a: [nan] mag
NUV.a: [-1.891] mag
e_NUV.a: [0.03700000047683716] mag
FUV.4: [nan] mag
e_FUV.4: [nan] mag
NUV.4: [-1.785] mag
e_NUV.4: [0.039] mag
FUV.6: [nan] mag
e_FUV.6: [nan] mag
NUV.6: [-1.892] mag
e_NUV.6: [0.038] mag
Fafl: [0]
Nafl: [2]
Fexf: [0]
Nexf: [0]
Fflux: [nan] µJy
e_Fflux: [nan] µJy
Nflux: [192.502] µJy
e_Nflux: [6.567] µJy
FXpos: [nan] pix
FYpos: [nan] pix
NXpos: [1998.98] pix
NYpos: [1809.01] pix
Fima: [nan] pix
Nima: [3.711] pix
Fr: [nan] °
Nr: [0.002] °
nS/G: [0.984000027179718]
fS/G: [0.0]
nell: [0.04500000178813934]
fell: [nan]
nPA: [-19.420000076293945] °
e_nPA: [-23.059999465942383] °
fPA: [nan] °
e_fPA: [nan] °
Fnr: [13.0] pix
F3r: [85.0] pix
Nar: [3.5]
Narms: [0.001] °
Nbrms: [0.001] °
Far: [nan]
Farms: [nan] °
Fbrms: [nan] °
NUVw: [161.3000030517578] s
FUVw: [207.1999969482422] s
Prob: [nan]
Sep: [nan] ″
Nerr: [0.4699999988079071] ″
Ferr: [nan] ″
Ierr: [nan] ″
Nperr: [0.05000000074505806] ″
Fperr: [nan] ″
CV: [C]
G: [0]
N: [1]
primid: [6380239640935270400]
groupid: [6380239640935270574]
Gd: [0]
Nd: [1]
primidd: [6380239640935270400]
groupidd: [6380239640935270574]
groupTot: [6380239640935270574]
OName: [N]
Size: [nan] pix
Available Methods: .from_dataframe(), .from_table(), .show(), .to_dataframe(), .to_hdu(), .to_table()
Along with the survey and the returned data, the returned Record has the following attributes:
correctionstates the degree of proper motion correction that was achieved. Afullcorrection indicates that the system has valid Gaia proper motion and distance, and so a complete 3-dimensional correction was performed. Apartialcorrection occurs when the star has an invalid distance and so correction is purely angular on the sky - this is still fine in essentially all cases. Ifcorrectionisnone, no correction was performed - either because the star has invalid proper motion in Gaia, or because ATK does not know the median epoch of the requested survey (more on this later).search_posgives the actual position (coordinates, frame and epoch) of the search as it was performed. In this case, the coordinates of the target have been corrected from Gaia’s epoch of January 2016 to GALEX’s median epoch of August 2006.
A Record stores its data as an astropy Table. Any parameter can therefore be extracted from a catalogue (in this case the GALEX Near-UV magnitude) as follows:
nuv_mag = galex_entry.table["NUVmag"][0]
np.float64(18.1889)
Note
Vizier queries to Gaia will always return exactly one row when targeting a star via a valid Gaia Source ID. Any other search combination will return all rows within the query radius.
Configuring a Query#
The arguments that can be passed to query() depend on the kind of data that is being requested. Vizier queries do not have many optional arguments, but one example is the radius, which defaulted to 3 arcseconds above. The best way to override this is to set the radius explicity using astropy.units:
<Record DataSet>
.kind: Record
.targets: 2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 2.0′)
.exception: False
.data:
<galex (II/335/galex_ais) Record>
survey: galex
catalogue: II/335/galex_ais
correction: full
search_pos: 12.294° 5.384° (icrs, 2006-08-01T00:00:00.000)
table:
(astropy.Table)
RAJ2000: [12.293, 12.301, 12.28] °
DEJ2000: [5.384, 5.396, 5.4] °
Name: [GALEX J004910.4+052300, GALEX J004912.2+052345, GALEX J004907.2+052359]
objid: [6380239640935270574, 6380239640937367784, 6380239640935270689]
phID: [6380239640934219776, 6380239640934219776, 6380239640934219776]
Cat: [AIS, AIS, AIS]
RAfdeg: [12.328, 12.328, 12.328] °
DEfdeg: [5.431, 5.431, 5.431] °
FUVexp: [216.0, 216.0, 216.0] s
NUVexp: [216.0, 216.0, 216.0] s
GLON: [121.884, 121.898, 121.86] °
GLAT: [-57.484, -57.471, -57.467] °
tile: [50265, 50265, 50265]
img: [801, 801, 801]
sv: [25, 25, 25]
r.fov: [0.058, 0.044, 0.057] °
Obs: [1, 1, 1]
b: [1, 3, 1]
E(B-V): [0.026000000536441803, 0.026000000536441803, 0.026000000536441803] mag
Sp?: [0, 0, 0]
chkf: [0, 0, 0]
FUVmag: [nan, 22.348, nan] mag
e_FUVmag: [nan, 0.469, nan] mag
NUVmag: [18.189, 20.931, 22.001] mag
e_NUVmag: [0.03700000047683716, 0.18000000715255737, 0.32199999690055847] mag
FUV.a: [nan, 3.528, nan] mag
e_FUV.a: [nan, 0.469, nan] mag
NUV.a: [-1.891, 0.851, 1.921] mag
e_NUV.a: [0.03700000047683716, 0.18000000715255737, 0.32199999690055847] mag
FUV.4: [nan, 3.329, nan] mag
e_FUV.4: [nan, 0.39, nan] mag
NUV.4: [-1.785, 0.929, 2.194] mag
e_NUV.4: [0.039, 0.162, 0.353] mag
FUV.6: [nan, 3.379, nan] mag
e_FUV.6: [nan, 0.587, nan] mag
NUV.6: [-1.892, 0.928, 1.942] mag
e_NUV.6: [0.038, 0.23, 0.488] mag
Fafl: [0, 256, 0]
Nafl: [2, 275, 19]
Fexf: [0, 0, 0]
Nexf: [0, 0, 16]
Fflux: [nan, 4.178, nan] µJy
e_Fflux: [nan, 1.803, nan] µJy
Nflux: [192.502, 15.403, 5.747] µJy
e_Nflux: [6.567, 2.549, 1.704] µJy
FXpos: [nan, 1981.06, nan] pix
FYpos: [nan, 1837.95, nan] pix
NXpos: [1998.98, 1981.21, 2030.82] pix
NYpos: [1809.01, 1838.77, 1847.96] pix
Fima: [nan, 5.721, nan] pix
Nima: [3.711, 7.477, 9.315] pix
Fr: [nan, 0.002, nan] °
Nr: [0.002, 0.003, 0.004] °
nS/G: [0.984000027179718, 0.9760000109672546, 0.9660000205039978]
fS/G: [0.0, 0.9940000176429749, 0.0]
nell: [0.04500000178813934, 0.3179999887943268, 0.5509999990463257]
fell: [nan, 0.474, nan]
nPA: [-19.420000076293945, 6.619999885559082, -79.36000061035156] °
e_nPA: [-23.059999465942383, 7.25, -78.62999725341797] °
fPA: [nan, -58.38, nan] °
e_fPA: [nan, -58.37, nan] °
Fnr: [13.0, 7.199999809265137, 9.300000190734863] pix
F3r: [85.0, 2.0999999046325684, 7.300000190734863] pix
Nar: [3.5, 3.5, 3.5]
Narms: [0.001, 0.001, 0.001] °
Nbrms: [0.001, 0.001, 0.0] °
Far: [nan, 4.709, nan]
Farms: [nan, 0.001, nan] °
Fbrms: [nan, 0.0, nan] °
NUVw: [161.3000030517578, 147.89999389648438, 161.3000030517578] s
FUVw: [207.1999969482422, 195.8000030517578, 208.8000030517578] s
Prob: [nan, 0.732, nan]
Sep: [nan, 0.97, nan] ″
Nerr: [0.4699999988079071, 0.7200000286102295, 1.6299999952316284] ″
Ferr: [nan, 1.42, nan] ″
Ierr: [nan, 1.23, nan] ″
Nperr: [0.05000000074505806, 0.28999999165534973, 0.6299999952316284] ″
Fperr: [nan, 0.26, nan] ″
CV: [C, C, C]
G: [0, 0, 0]
N: [1, 1, 1]
primid: [6380239640935270400, 6380239640937367552, 6380239640935270400]
groupid: [6380239640935270574, 6380239640937367784, 6380239640935270689]
Gd: [0, 0, 0]
Nd: [1, 1, 1]
primidd: [6380239640935270400, 6380239640937367552, 6380239640935270400]
groupidd: [6380239640935270574, 6380239640937367784, 6380239640935270689]
groupTot: [6380239640935270574, 6380239640937367784, 6380239640935270689]
OName: [N, N, N]
Size: [nan, nan, nan] pix
Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()
Note
While a default radius of 3 arcseconds is reasonable for a modern optical telescope, for other workloads it may be preferrable to work at a different spatial resolution. To accomodate this, most of the core defaults in ATK are configurable via a config file. See here for details.
Download this Tutorial
Total running time of the script: (0 minutes 2.004 seconds)