Multi-Target Queries

All tasks in ATK (including all of those showcased in previous tutorials) are designed to work modularly with multiple targets. A target matching system is used to internally link each input target (whether that be a Gaia source ID, a Target or a SkyCoord) to the data that it returns.

Performing a Multi-Target Query

A multi-target query can be performed by passing multiple targets to query(). An example of a multi-target Vizier query for two targets - van Maanen’s star and Hu Leo, a cataclysmic variable - is shown below:

from ATK import query

targets = [2552928187080872832, 587316166180416640]
galex_query = query("vizier", targets=targets, survey="gaia")
galex_query.show()

<Record DataSet>

.kind:      Record
.targets:   2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 3.0″), 587316166180416640 | 141.185° 8.031° (icrs, 2016-01-01T00:00:00.000, 3.0″)
.exception: False
.data:
      <gaia (I/355/gaiadr3) Record>
            survey:     gaia
            catalogue:  I/355/gaiadr3
            correction: full
            search_pos: 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000)
            table:
                  (astropy.Table)
                        DR3Name: [Gaia DR3 2552928187080872832]
                        RA_ICRS: [12.297] °
                        DE_ICRS: [5.377] °
                        SolID:   [1636148068921376768]
                        Source:  [2552928187080872832]


      <gaia (I/355/gaiadr3) Record>
            survey:     gaia
            catalogue:  I/355/gaiadr3
            correction: full
            search_pos: 141.185° 8.031° (icrs, 2016-01-01T00:00:00.000)
            table:
                  (astropy.Table)
                        DR3Name: [Gaia DR3 587316166180416640]
                        RA_ICRS: [141.185] °
                        DE_ICRS: [8.031] °
                        SolID:   [1636148068921376768]
                        Source:  [587316166180416640]



Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()

Note

The returned Record objects have been truncated here for clarity.

Accessing Multi-Target Data

The returned DataSet contains two Record objects. These could be extracted by pulling them out of the data attribute:

van_maanen, hu_leo = galex_query.data

But this can easily produce unexpected results if no data is returned for one or more of the targets.

Instead, the DataSet’s split() method should be used. split() takes one or more valid targets (with each target being a Gaia source ID, a Target, or an astropy SkyCoord) and returns a split of the DataSet which only contains that target’s data.

Splitting by ID

Since Gaia source IDs were used in this example, these can be passed to split():

van_maanen_2 = galex_query.split(2552928187080872832, inplace=False)
van_maanen_2.show()

<Record DataSet>

.kind:      Record
.targets:   2552928187080872832 | 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000, 3.0″)
.exception: False
.data:
      <gaia (I/355/gaiadr3) Record>
            survey:     gaia
            catalogue:  I/355/gaiadr3
            correction: full
            search_pos: 12.297° 5.377° (icrs, 2016-01-01T00:00:00.000)
            table:
                  (astropy.Table)
                        DR3Name: [Gaia DR3 2552928187080872832]
                        RA_ICRS: [12.297] °
                        DE_ICRS: [5.377] °
                        SolID:   [1636148068921376768]
                        Source:  [2552928187080872832]



Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()

The returned DataSet contains only the requested target in its targets attribute, and only the corresponding Record in its data attribute.

Note

inplace = False tells split() to act on and return a copy of the DataSet - leaving the original unchanged.

Splitting by Coordinates

Equivalently, an astropy SkyCoord can be passed to split(). This returns a split of the original DataSet which only contains data corresponding to input positions (i.e. the uncorrected coordinates that were provided to query() by the user) that fall within a given radius:

import astropy.units as u
from astropy.coordinates import SkyCoord

coord = SkyCoord(141.185, 8.031, unit="deg", frame="icrs")
hu_leo = galex_query.split(coord, inplace=False, radius = 5 * u.arcsec)
hu_leo.show()

<Record DataSet>

.kind:      Record
.targets:   587316166180416640 | 141.185° 8.031° (icrs, 2016-01-01T00:00:00.000, 3.0″)
.exception: False
.data:
      <gaia (I/355/gaiadr3) Record>
            survey:     gaia
            catalogue:  I/355/gaiadr3
            correction: full
            search_pos: 141.185° 8.031° (icrs, 2016-01-01T00:00:00.000)
            table:
                  (astropy.Table)
                        DR3Name: [Gaia DR3 587316166180416640]
                        RA_ICRS: [141.185] °
                        DE_ICRS: [8.031] °
                        SolID:   [1636148068921376768]
                        Source:  [587316166180416640]



Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()

Note

In queries that target stars with their Gaia source IDs (like the one performed here), splitting via a SkyCoord isn’t particularly useful. However, it is worth noting that the input positions of the stars in this case would be those given by Gaia DR3.

Splitting by Target

Finally, a Target can be passed to split(). This enables exact matching without the need of a radius, and is therefore preferable if a Gaia source ID isn’t available:

from ATK.Models import Target

coord_1 = SkyCoord(12.2912, 5.3886, unit="deg", frame="icrs")  # van Maanen's Star
coord_2 = SkyCoord(141.1853, 8.0308, unit="deg", frame="icrs")  # Hu Leo
targets = [Target.from_coord(coord_1), Target.from_coord(coord_2)]

gaia_query = query("vizier", targets=targets, survey="gaia")

hu_leo = gaia_query.split(targets[1], inplace=False)
hu_leo.show()

<Record DataSet>

.kind:      Record
.targets:   141.185° 8.031° (icrs, 2000-01-01T00:00:00.000, 3.0″)
.exception: False
.data:
      <gaia (I/355/gaiadr3) Record>
            survey:     gaia
            catalogue:  I/355/gaiadr3
            correction: none
            search_pos: 141.185° 8.031° (icrs, 2000-01-01T00:00:00.000)
            table:
                  (astropy.Table)
                        DR3Name: [Gaia DR3 587316166180416640]
                        RA_ICRS: [141.185] °
                        DE_ICRS: [8.031] °
                        SolID:   [1636148068921376768]
                        Source:  [587316166180416640]



Available Methods: .add(), .apply(), .from_target(), .merge(), .open(), .plot(), .save(), .show(), .split(), .store()

Download this Tutorial