Source¶

The Source class provides functionality to explore and analyse an astrophysical source as found in the VAST Pilot Survey or a detected using the VAST Pipeline. Source instances are returned by the Query.find_sources() method and the Pipeline.get_source() method. With a Source instance it is possible to:

• view the individual measurements from each epoch that make up the source,
• plot a lightcurve,
• create postage stamps of the measurements and save as FITS or PNG files,
• create kvis annotation files or DS9 region files,
• calculate the η and V variability metrics,
• load image data from other surveys for the source location,
• search SIMBD or the NASA/IPAC Extragalactic Database (NED) for counterparts to the source,
• and query the CSIRO ASKAP Science Data Archive (CASDA) for other ASKAP observations containing the source.

Using the Source Component¶

Initialising a Source Instance¶

If a Source instance is required to be initialised then the first step is to import the Source class as demonstrated below.

from vasttools.source import Source

Source Initialisation Options¶

A number of arguments are required to initialise a Source instance. Those that are required are described below, along with an example.

coord
The SkyCoord object representing the the position of the source.

name
The string name of the source.

epochs
A list of the epochs (as strings). Must be the same length as the number of measurements. The values can be arbitrary for a pipeline created Source.

fields
A list of the field names (as strings). Must be the same length as the number of measurements. This is mainly for Source instances created by using the Query component, and while required, the values can be arbitrary for a pipeline created Source.

stokes
The stokes value of the source: I, V, U or Q.

primary_field
The primary field of the source. For pipeline created Source objects this can be entered as None.

crossmatch_radius
The crossmatch radius used to construct the source, as a astropy.coordinates.Angle instance. For pipeline created Source objects this can be entered as None.

measurements
The dataframe of individual measurements for the source. This can either be the search output from the Query or the measurements dataframe of the source from the VAST Pipeline.

base_folder
For Query produced sources this is the base directory of where the image data can be found relating to the source. The standard VAST Pilot Survey data release structure is assumed (refer to Configuration & Data Access).

import astropy.units as u

from vasttools.source import Source
from astropy.coordinates import Angle, SkyCoord


my_coord = SkyCoord("21h29m45.29s -04d29m11.9s")
source_name = "PSR J2129-04"
source_epochs = ['1', '2', '3', '4']
source_fields = ['field_1', 'field_1', 'field_2', 'field_1']
source_stokes = 'I'
source_primary_field = 'field_1'
crossmatch_radius = Angle(5.0 * u.arcsec)
source_base_folder = "path/to/source/images/"

my_source = Source(
    source_coord,
    source_name,
    source_epochs,
    source_fields,
    source_stokes,
    source_primary_field,
    source_crossmatch_radius,
    measurements_df,  # the measurements dataframe.
    source_base_folder,
)

Source Attributes¶

A Source instance contains several useful attributes.

The two most commonly accessed attributes are:

Source.coord¶

The right ascension and declination coordinates of the source as a SkyCoord object.

my_source.coord
# output:
<SkyCoord (ICRS): (ra, dec) in deg
    (322.43870833, -4.48663889)>

Source.measurements¶

Access to the measurements dataframe of the source.

my_source.measurements

Available Source Methods¶

The following methods are available with the Source instance.

calc_eta_and_v_metrics¶

Code reference.

Calculates the η and V variability metrics. By default the peak flux is used.

eta, v = my_source.calc_eta_and_v_metrics()

calc_eta_metric¶

Code reference.

Calculates the η variability metric. By default the peak flux is used.

eta = my_source.calc_eta_metric()

calc_v_metric¶

Code reference.

Calculates the V variability metric. By default the peak flux is used.

v = my_source.calc_v_metric()

casda_search¶

Code reference.

Uses the astoquery CASDA Queries service to perform a search of the CSIRO ASKAP Science Data Archive (CASDA) for all ASKAP observations that contain the respective source. By default a 20 arcsecond radius is used and unreleased data is included. Results are returned as an astropy table. None will be returned if there are no results.

casda_results = my_source.casda_search()

get_cutout_data¶

Code reference.

This method fetches the cutout data that is required to generate the postage stamps and additional overlays. The cutout data is stored in a dataframe as the attribute Source.cutout_df.

my_source.get_cutout_data()

make_png¶

Code reference.

The main method that generates all the PNG images that is called by other methods. Note that this method can only produce a single epoch at a time, and the required argument is the index of the observation to plot. The result is returned a matplotlib.pyplot.figure instance. There are a wide variety of options that can style the output plot, please refer to the Code Reference to view them all.

my_source.make_png(size=Angle(30 * u.arcsec), force=True)

my_source.make_png(0)

By default the axis labels will measure the offset from the central coordinate. However users can instead choose to use absolute coordinates by setting the offset_axes argument to False.

my_source.make_png(0, offset_axes=False)

Example png output

Offset coordinates

Absolute coordinates

ned_search¶

Code reference.

Uses the astoquery NED Queries service to perform a search of the NASA/IPAC Extragalactic Database (NED) for possible counterparts to the source. By default a 20 arcsecond radius is used for the search. Results are returned as an astropy table. None will be returned if there are no results.

ned_results = my_source.ned_search()

plot_lightcurve¶

Code reference.

A method that returns a plot of the source lightcurve. The result is returned a matplotlib.pyplot.figure instance. There are a wide variety of options that can style the output plot, please refer to the Code Reference to view them all.

my_source.plot_lightcurve()

Example lightcurve output

save_all_ann¶

Code reference.

A method to save the kvis annotation files for all epochs. Refer to the method write_ann for saving the annotation file for an individual epoch. The target source and all surrounding sources are included. The files will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_all_ann()

save_all_fits_cutouts¶

Code reference.

A method to save the cutouts (or postage stamps) of each epoch as individual FITS files. Refer to the method save_fits_cutout for saving the FITS of an individual epoch. The FITS files will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_all_fits_cutouts(size=Angle(30 * u.arcsec), force=True)

my_source.save_all_fits_cutouts()

save_all_png_cutouts¶

Code reference.

A method to save the cutouts (or postage stamps) of each epoch as individual png files. Refer to the method save_png_cutout for saving the png for an individual epoch. The png files will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_all_png_cutouts(size=Angle(30 * u.arcsec), force=True)

my_source.save_all_png_cutouts()

save_all_reg¶

Code reference.

A method to save the DS9 region files for all epochs. Refer to the method write_reg for saving the region file for an individual epoch. The target source and all surrounding sources are included. The files will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_all_reg()

save_fits_cutout¶

Code reference.

A method to save the cutout (or postage stamp) of a single observation in the FITS format. The required argument is the zero-based index of the observation to be saved. Refer to the code reference for all other available options. The file will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_fits_cutout(0, size=Angle(30 * u.arcsec), force=True)

my_source.save_fits_cutout(0)

save_png_cutout¶

Code reference.

A method to save the cutout (or postage stamp) of a single observation as a png image. The required argument is the zero-based index of the epoch to be saved. Refer to the code reference for all other available options. The file will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.save_png_cutout(0, size=Angle(30 * u.arcsec), force=True)

my_source.save_png_cutout(0)

Example png output

show_all_png_cutouts¶

Code reference.

A method to produce a single image containing all the cutouts of the source, i.e. those from each epoch, displayed. Refer to the code reference for all other available options. The result is returned a matplotlib.pyplot.figure instance.

my_source.show_all_png_cutouts(size=Angle(30 * u.arcsec), force=True)

all_cutouts_plot = my_source.show_all_png_cutouts()

Example png output

show_png_cutout¶

Code reference.

A method to produce the cutout (or postage stamp) of a single observation as a png image. The required argument is the zero-based index of the observation to be saved. Refer to the code reference for all other available options. The result is returned a matplotlib.pyplot.figure instance.

my_source.show_png_cutout(0, size=Angle(30 * u.arcsec), force=True)

my_cutout = my_source.show_png_cutout(0)

Example png output

simbad_search¶

Code reference.

Uses the astoquery SIMBAD Queries service to perform a search of SIMBD for possible counterparts to the source. By default a 20 arcsecond radius is used for the search. Results are returned as an astropy table. None will be returned if there are no results.

simbad_results = my_source.simbad_search()

skyview_contour_plot¶

Code reference.

Uses the astroquery Skyview Queries service to download and display a cutout from an available external survey and overlay contours of the source from the selected observation. The list of available surveys is shown on the linked page for the astroquery Skyview service. The required arguments are the zero-based index of the observation to plot and the survey to query for a cutout image. Contours are adjustable using the contour_levels argument, which defines the sigma levels of contours to use. Refer to the Code Reference for full details on the arguments available. The result is returned a matplotlib.pyplot.figure instance.

my_source.skyview_contour_plot(0, 'WISE 3.4', size=Angle(30 * u.arcsec), force=True)

wise_3_4_contour_epoch6x = my_source.skyview_contour_plot(0, 'WISE 3.4')

Example png output

write_ann¶

Code reference.

Saves the kvis annotation file equal to the generated cutout size for the provided observation. The target source and all surrounding sources are included. Refer to the Code Reference for information on all the arguments. The file will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.write_ann(0)

write_measurements¶

Code reference.

A convenience method to save the measurements dataframe (i.e. Source.measurements) to a file. The file will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.write_measurements()

write_reg¶

Code reference.

Saves the ds9 region file of the generated cutout size for the provided observation. The target source and all surrounding sources are included. Refer to the Code Reference for information on all the arguments. The file will be saved to the directory specified by the argument outdir in the instancing of the Source. If this was not provided the default location is the current directory.

my_source.write_reg(0)