Query¶

The Query component of VAST Tools is used to query the VAST Pilot Survey data directly.

The base function of a Query is to search the VAST Pilot catalogues for source matches to the queried positions. If no source is found in an epoch then the upper limit or forced fit measurement is returned. In full, the Query component as the ability to:

• determine whether provided coordinates are in the VAST Pilot survey, and if so, which field(s) the source present in (no data required),
• find source matches to provided coordinates,
• perform forced fit and upper limit measurements
• attempt to construct a lightcurve for the source,
• create postage stamps for sources, with overlays and save as fits or png files,
• search stokes V data,
• search for planets and the Sun and Moon.

Using the Query Component¶

Code reference.

A Query instance can be imported from vasttools.query:

from vasttools.query import Query

from vasttools.query import Query

if __name__ == '__main__':
    my_query = Query(source_names=["PSR J2129-04"])
    my_query.find_sources()

Constructing a Query¶

The Query is defined on the initialisation of the instance. In other words, when the Query is first defined all the desired Query arguments must be entered so the Query is initialised correctly.

For example, the code below demonstrates how to create a Query object that will use the RA and Dec coordinate 21:29:45.29 -04:29:11.9 to perform a search.

from vasttools.query import Query
from astropy.coordinates import SkyCoord

my_coord = SkyCoord("21h29m45.29s -04d29m11.9s")

my_query = Query(coords=my_coord)

See the following section for details on how to enter coordinates or how to instead use object names as the coordinate input.

Entering the Coordinates to Query¶

Coordinates passed to the coords parameter in the Query object must be entered as an astropy SkyCoord object. The SkyCoord object can be a singular coordinate or contain multiple coordinates.

from vasttools.query import Query
from astropy.coordinates import SkyCoord

coords_list = ["21h29m45.29s -04d29m11.9s", "21h18m50.70s -57d38m42.5s"]

my_coord = SkyCoord(coords_list)

my_query = Query(coords=my_coord)

The source_names parameter can be used to enter names of the sources alongside the coordinates. The future results of the query will then be accessible using these source names. If not source names are provided then they will be automatically named using the degrees representation of the coordinates in the format ra_dec.

from vasttools.query import Query
from astropy.coordinates import SkyCoord

coords_list = ["21h29m45.29s -04d29m11.9s", "21h18m50.70s -57d38m42.5s"]
my_source_names = ["PSR J2129-04", "SN 2012dy"]

my_coord = SkyCoord(coords_list)

my_query = Query(coords=my_coord, source_names=my_source_names)

It is also possible to only define the source_names parameter. If this is done then the Query will use the CDS SIMBAD service to attempt to fetch the coordinates for the requested sources.

from vasttools.query import Query
from astropy.coordinates import SkyCoord

my_source_names = ["PSR J2129-04", "SN 2012dy"]

my_query = Query(source_names=my_source_names)

Crossmatching Options¶

There are two options that control how the crossmatching to the VAST catalogues is performed.

crossmatch_radius
This is the radius, in arcsec, to which a VAST Pilot source is considered a match to the search coordinate.

max_sep
The maximum distance, in degrees, from the centre of an individual beam (36 beams make up an ASKAP tile) to determine if a match is possible. This defaults to 1.5 degrees.

search_around_coordinates All matches within the crossmatch_radius are returned instead of just the closest matched component or island.

Data Selection Options¶

These Query keyword arguments control the data that is used to perform the query or the data returned.

epochs
A list of epochs or a comma-separated string of epochs to search. Do not use zero padded values when entering the epochs. The values all and all-vast are also valid, selecting all RACS & VAST data or just VAST data, respectively.

The pilot survey used an x to designate an epoch that was only partially observed. This can be supplied, but is not necessary.

my_query = Query(..., epochs="1,2,6x,8,9")

my_query = Query(..., epochs=["1","2","6x","8","9"])

my_query = Query(..., epochs=[1,2,6,8,9])

stokes
Select which Stokes parameter data to search in. Valid entries are I, V, Q and U.

use_tiles
Switch to using the catalogues and images TILE type instead of the COMBINED. The default is to use the TILE type. Refer to this wiki page for an explanation on the two types (askap-vast GitHub membership required to access).

use_islands
Query the island catalogues produced by the selavy source finder instead of the component catalogues (default).

matches_only
Only return results that have a source match. I.e. no forced fit or upper limit measurements will be returned.

search_all_fields Return all data available at the source location. If not selected, only the data associated with the best (i.e. closest) field will be returned.

corrected_data and post_processed_data Use the corrected data (astrometric corrections applied, only available for the pilot survey) or the post-processed data (astrometric corrections and cropping applied, along with the use of compressed images). The default is now to use the post-processed data moving forward.

Planet Search¶

Planets are included in the Query search by using the planets keyword argument.

planets A python list of planets to include in the Query search. Valid entries are: mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, sun and moon.

my_query = Query(..., planets=["jupiter", "moon"])

RMS & Forced Fits¶

These Query arguments control the RMS estimation and forced fitting.

no_rms Set to True to not make background rms measurements for each requested position per epoch.

forced_fits When set to True a forced fit will be produced at each queried location in each requested epoch where possible.

forced_cluster_threshold Passed to the cluster_threshold parameter in forced_phot.

forced_allow_nan Passed to the allow_nan parameter in forced_phot.

Checking Settings¶

Once the Query has been defined the settings can be checked by viewing the Query.settings attribute as demonstrated below.

my_coords = SkyCoord([206.058966, 319.711250, 322.438710], [0.278384, -57.645140, -4.486640], unit=(u.deg, u.deg))
my_source_names = ["1AXG J134412+0016", "SN 2012dy", "PSR J2129-0429"]

my_query = Query(
    coords=my_coords,
    source_names=my_source_names,
    matches_only=True, 
    epochs="all-vast", 
    crossmatch_radius=10., 
    output_dir='source-search-example-output', 
    base_folder='/import/ada1/askap/PILOT/release'
)

my_query.settings

{'epochs': ['1', '2', '3x', '4x', '5x', '6x', '7x', '8', '9', '10x', '11x'],
 'stokes': 'I',
 'crossmatch_radius': <Angle 10. arcsec>,
 'max_sep': 1.5,
 'islands': False,
 'tiles': False,
 'no_rms': False,
 'matches_only': True,
 'search_around': False,
 'sort_output': False,
 'forced_fits': False,
 'output_dir': 'source-search-example-output',
 'search_all_fields': False,}

Running a Query¶

The query does not automatically run once initialised. There are two methods available to launch the query that are detailed below. See the following section for details on how to use the results from each method.

find_fields¶

This method will only locate the fields that the contains the queried sources/coordinates. The results will be saved to the attribute fields_df in the form of a pandas dataframe.

my_query.find_fields()

find_sources¶

This method will build upon find_fields and perform the source crossmatching from the selavy catalogues. The results will be stored in the attribute .results, in the format of a pandas series containing vasttools.source.Souce objects with the source name as the key.

my_query.find_sources()

Using the Query Results¶

find_fields Results¶

Each row in the results dataframe, saved to Query.fields_df, represents the result of the queried source for a particular epoch. For example, if the source PSR J2129-04 should be present in 5 epochs there will be 5 row. The columns of the dataframe are:

• name The name of the source/coordinate queried.
• ra The right ascension of the source/coordinate in degrees.
• dec The declination of the source/coordinate in degrees.
• skycoord The SkyCoord representation of the coordinate.
• stokes The stokes parameter of this field.
• fields The complete list of fields the source can be found in.
• primary_field Which VAST Pilot field is considered the main field of the source. Defined by being the field where the source is the closest to the respective fields centre.
• epoch The epoch this row is for.
• field The best field for this epoch (may not be the primary field if that field is not present in the epoch).
• sbid The ASKAP SBID of the field observation.
• dateobs The date and time of the observation.
• planet Set to True if the source/coordinate is a planet that has been requested to search for.

These results can be written to a file by using the Query.write_find_fields() method.

find_sources Results¶

The find_sources method creates VAST Tools Source objects for each queried coordinate/source and saves these to a pandas Series object that is accessible as Query.results. Below shows an example of what a results series looks like when find_sources has completed.

name
1AXG J134412+0016    <vasttools.source.Source object at 0x7f181dea4...>
SN 2012dy            <vasttools.source.Source object at 0x7f182938d...>
PSR J2129-0429       <vasttools.source.Source object at 0x7f182938d...>
Name: name, dtype: object

To access a specific source of the results, the source name is used as a key as demonstrated below.

my_query.results['SN 2012dy']

Please now refer to the Source page of this documentation to learn more about vasttools.source.Source objects, which details how to produce lightcurves, postage stamps and more.

Forced Fits Results¶

If forced fits has been used in the query these results will be placed in the measurements attribute of the Source object (refer to here for more details). The following columns will be added:

• f_island_id An id to the forced extraction island given by forced_phot.
• f_component_id An id to the forced extraction component given by forced_phot.
• f_ra_deg_cont The right ascension coordinate of the extraction in degrees.
• f_dec_deg_cont The declination coordinate of the extraction in degrees.
• f_flux_peak The measured peak flux of the extraction in mJy/beam.
• f_flux_peak_err The error of the measured peak flux.
• f_flux_int The measured integrated flux of the extraction in mJy. Note this should be equal to the peak flux.
• f_flux_int_err The error of the integrated flux.
• f_chi_squared_fit The \(\chi^{2}\) value of the fit.
• f_rms_image The rms at the measured position as calculated by forced_phot in mJy.
• f_maj_axis The major axis of the Gaussian used in arcsec.
• f_min_axis The minor axis of the Gaussian used in arcsec.
• f_pos_ang The position angle of the Gaussian used in degrees.

find_sources script¶

VAST Tools provides the script find_sources that can be accessed from the command line. It is a script that allows for the use of the Query functionality but in a command line environment. This is most useful for large queries that would be non-ideal to perform in a notebook environment. See the find_sources documentation page for full details.