.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_tutorials/getting_started/data_query.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_tutorials_getting_started_data_query.py: .. role:: bolditalic :class: bolditalic ######################### 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 :doc:`here <../multiple_targets/multi_target_query>` after following these tutorials). | Queries of any kind use the :func:`~ATK.Tools.query` tool, which can be imported as follows: .. GENERATED FROM PYTHON SOURCE LINES 15-19 .. code-block:: Python from ATK import query .. GENERATED FROM PYTHON SOURCE LINES 32-33 or: .. GENERATED FROM PYTHON SOURCE LINES 33-36 .. code-block:: Python from ATK.Tools import query .. GENERATED FROM PYTHON SOURCE LINES 37-47 | | 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, :func:`~ATK.Tools.query` will be used to retrieve GALEX data for `van Maanen's Star `_. | 1. Stars with Gaia DR3 data can be targeted by their Source ID: .. GENERATED FROM PYTHON SOURCE LINES 47-50 .. code-block:: Python target = 2552928187080872832 .. GENERATED FROM PYTHON SOURCE LINES 51-54 | 2. The target's coordinates can be used directly by creating an astropy :class:`~astropy.coordinates.SkyCoord`: .. GENERATED FROM PYTHON SOURCE LINES 54-59 .. code-block:: Python from astropy.coordinates import SkyCoord target = SkyCoord(12.2912, 5.3886, unit="deg", frame="icrs") .. GENERATED FROM PYTHON SOURCE LINES 60-63 | 3. A :class:`~ATK.Models.Target` object can be created explicitly, either from a Gaia source ID or from the star's coordinates: .. GENERATED FROM PYTHON SOURCE LINES 63-68 .. code-block:: Python from ATK.Models import Target target = Target.from_id(2552928187080872832) .. GENERATED FROM PYTHON SOURCE LINES 69-76 .. code-block:: Python from ATK.Models import Target from astropy.coordinates import SkyCoord coord = SkyCoord(12.2912, 5.3886, unit="deg", frame="icrs") target = Target.from_coord(coord) .. GENERATED FROM PYTHON SOURCE LINES 77-80 .. note:: Passing a :class:`~ATK.Models.Target` explicitly may seem unnecessary at first, but it offers a key advantage in queries that simultaneously target :doc:`multiple stars <../multiple_targets/multi_target_query>`. .. GENERATED FROM PYTHON SOURCE LINES 82-88 | | Performing a Query ==================== With a target set (**in this case via the star's coordinates**), a `Vizier `_ query can now be performed: .. GENERATED FROM PYTHON SOURCE LINES 88-92 .. code-block:: Python target = SkyCoord(12.2912, 5.3886, unit="deg", frame="icrs") galex_query = query("vizier", targets=target, survey="galex") .. GENERATED FROM PYTHON SOURCE LINES 93-108 | .. note:: By default, ATK supports queries via aliases to the following `Vizier `_ catalogues: .. include:: supported_aliases.rst To utilise any other :doc:`Vizier <../extension/vizier>` catalogue, enter its catalogue ID (e.g. ``"I/355/gaiadr3"`` for Gaia DR3). A full tutorial on extending :func:`~ATK.Tools.query` to work with any `Vizier `_ catalogue (including automatic proper motion correction) can be found :doc:`here <../extension/vizier>`. | **The** :func:`~ATK.Tools.query` **tool returns a** :class:`~ATK.Models.DataSet`, which contains key details of the request along with any returned data. **To see the structure of the returned** :class:`DataSet `, its :meth:`~ATK.Models.DataSet.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 :meth:`~ATK.Models.DataSet.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: .. GENERATED FROM PYTHON SOURCE LINES 108-111 .. code-block:: Python galex_query.show(show_types=True) .. rst-class:: sphx-glr-script-out .. code-block:: none .kind (str): vizier .targets (list): 12.291° 5.389° (icrs, 2000-01-01T00:00:00.000, 3.0″) .exception (bool): False .data (list): Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store() .. GENERATED FROM PYTHON SOURCE LINES 115-130 | The majority of the returned :class:`~ATK.Models.DataSet`'s attributes are immediately clear, but there are a couple details to note: - :attr:`~ATK.Models.DataSet.targets` lists every :class:`ATK.Models.Target` of the search **as they were entered** (coordinates, frame and epoch). - :attr:`~ATK.Models.DataSet.exception` states whether any exceptions were encountered. If :attr:`~ATK.Models.DataSet.exception` is ``True``, 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 :class:`~ATK.Models.DataSet`'s :attr:`~ATK.Models.DataSet.data` attribute. **Unfortunately, targeting van Maanen's Star with its coordinates has returned an empty** :class:`~ATK.Models.DataSet`. | Instead the star can be targeted via its Gaia Source ID: .. GENERATED FROM PYTHON SOURCE LINES 130-135 .. code-block:: Python target = 2552928187080872832 galex_query = query("vizier", targets=target, survey="galex") galex_query.show() .. rst-class:: sphx-glr-script-out .. code-block:: none .kind: Record .targets: 2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 3.0″) .exception: False .data: 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() .. GENERATED FROM PYTHON SOURCE LINES 139-149 | **Targeting van Maanen's Star in this way has utilised Gaia's astrometry to correct the position of our search for proper motion** :bolditalic:`before` **it is executed. Without increasing the query radius, we have retrieved GALEX data for van Maanen's Star.** | | Using the Returned Data ======================= A :class:`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 :class:`~ATK.Models.DataSet` contains a single :class:`~ATK.Models.Record`: .. GENERATED FROM PYTHON SOURCE LINES 149-152 .. code-block:: Python galex_entry = galex_query.data[0] .. rst-class:: sphx-glr-script-out .. code-block:: none .. GENERATED FROM PYTHON SOURCE LINES 156-159 | As with any ATK object, :meth:`~ATK.Models.Record.show` can be used to see its structure: .. GENERATED FROM PYTHON SOURCE LINES 159-162 .. code-block:: Python galex_entry.show(show_types=True) .. rst-class:: sphx-glr-script-out .. code-block:: none .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() .. GENERATED FROM PYTHON SOURCE LINES 166-179 | Along with the ``survey`` and the returned data, the returned :class:`~ATK.Models.Record` has the following attributes: - :attr:`~ATK.Models.Record.catalogue` shows the ID of the requested :attr:`~ATK.Models.Record.survey` in Vizier. - :attr:`~ATK.Models.Record.correction` states the degree of proper motion correction that was achieved. A ``full`` correction indicates that the system has valid Gaia proper motion and distance, and so a **complete 3-dimensional correction** was performed. A ``partial`` correction 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. If :attr:`~ATK.Models.Record.correction` is ``none``, **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). - :attr:`~ATK.Models.Record.search_pos` gives 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 :class:`~ATK.Models.Record` stores its data as an astropy :class:`~astropy.table.Table`. Any parameter can therefore be extracted from a catalogue (in this case the GALEX Near-UV magnitude) as follows: .. GENERATED FROM PYTHON SOURCE LINES 179-183 .. code-block:: Python nuv_mag = galex_entry.table["NUVmag"][0] .. rst-class:: sphx-glr-script-out .. code-block:: none np.float64(18.1889) .. GENERATED FROM PYTHON SOURCE LINES 187-199 | .. 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 :func:`~ATK.Tools.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 :mod:`astropy.units`: .. GENERATED FROM PYTHON SOURCE LINES 200-208 .. code-block:: Python from ATK import query import astropy.units as u target = 2552928187080872832 galex_query = query("vizier", targets=target, survey="galex", radius=2*u.arcmin) galex_query.show() .. rst-class:: sphx-glr-script-out .. code-block:: none .kind: Record .targets: 2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 2.0′) .exception: False .data: 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() .. GENERATED FROM PYTHON SOURCE LINES 212-217 | .. 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 :doc:`here <../configuration/config>` for details. .. GENERATED FROM PYTHON SOURCE LINES 220-225 | | | .. rubric:: Download this Tutorial .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 2.004 seconds) .. _sphx_glr_download_auto_tutorials_getting_started_data_query.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: data_query.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: data_query.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: data_query.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_