Tools

Contains the main tools for data fetching, plotting and analysis in ATK.

AstroToolkit.Tools.query(kind, source/pos, check_exists, **kwargs)[source]

Returns a data structure of a given type from a given survey. Accepted types are:

  • data: returns catalogue data as listed in Vizier

  • bulkdata: returns data from all supported catalogues (including user-defined aliases)

  • reddening: returns reddening from a supported survey

  • lightcurve: returns light curve data from a supported survey

  • image: returns image data from a supported survey

  • hrd: returns Gaia Hertzsprung-Russell diagram data

  • sed: returns spectral energy distribution data from all supported surveys

  • spectrum: returns spectrum data from a supported survey


The type of query to be performed is chosen via the ‘kind’ parameter:

Parameters:

kind (str) – Type of query to perform, as listed above

query() requires additional parameters depending on the kind of query being performed, and returns different data structures in each case.


Data Queries

Parameters:

  • survey (str) – Target survey, from supported surveys

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • radius (float, optional) – Search radius in arcseconds, default given by query_data_radius config key

  • check_exists (bool, optional) – Path to check for existing data. If a file is found, data is generated without having to run a query. If a file is not found, query will go ahead and the resulting data will be saved to the requested Path for future executions. Defaults to None (i.e. this functionality is disabled)

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

DataStruct


Bulkdata Queries

Parameters:

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • radius (float, optional) – Search radius in arcseconds, default given by query_bulkdata_radius config key

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

DataStruct

Return type:

class


Reddening Queries

Parameters:

  • survey (str) –

    Target survey, from:

    • stilism - requires source input, doesn’t accept a radius

    • gdre - accepts source or pos input

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • radius (float, optional) – Search radius in arcseconds, default given by query_reddening_radius config key

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

DataStruct


Light Curve Queries

Parameters:

  • survey (str) – Target survey, from supported surveys

  • radius – Search radius in arcseconds, default given by query_lightcurve_radius config key

  • raw (bool, optional) – Return raw data with no filtering, defaults to False

  • username – ATLAS username, only required in ATLAS queries. Default given by query_lightcurve_atlas_username config key

  • password (str, optional) – ATLAS password, only required in ATLAS queries. Default given by query_lightcurve_atlas_password config key

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

LightcurveStruct


Image Queries

Parameters:

  • survey (str) – Target survey, from supported surveys

  • size – Size of image in arcseconds, default given by query_image_size config key

  • size – float, optional

  • band (str, optional) – All required image bands as a single string (see supported bands). E.g. ‘grizy’ for all panstarrs bands. Defaults to ‘g’

  • overlays (list<str>, optional) – Required detection overlays. Accepts any data survey or light curve survey

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Note: use ‘gaia_lc’ for Gaia light curve overlays, and ‘gaia’ for gaia detection overlays

The default band in the detection overlay of a given survey is the that which is listed first in ATKOverlays.yaml (see the tutorial on defining image overlays and the ATKoverlay command-line tool). If you wish to use multiple bands from a single survey, detections can instead be requested using a dictionary.

E.g. to request an overlay that includes all Gaia magnitudes:

overlays={'gaia':['phot_g_mean_mag','phot_bp_mean_mag','phot_rp_mean_mag']}
Returns:

ImageStruct


HRD Queries

Parameters:

  • sources (list<int>) – List of target Gaia DR3 sources

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

HrdStruct


SED Queries

Parameters:

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • radius (float, optional) – Search radius in arcseconds, default given by query_sed_radius config key

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

SedStruct


Spectrum Queries

Parameters:

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • survey (str) – Target survey, from supported surveys

  • radius (float, optional) – Search radius in arcseconds, default given by query_spectrum_radius config key

  • retry (int, optional) – Re-attempt query if no data is returned. This can help to ensure that no data is missed due to e.g. brief server interruptions when performing queries for a large number of targets. Defaults to 1 (i.e. only one attempt is made).

Returns:

SpectrumStruct


AstroToolkit.Tools.correctpm(source/pos, **kwargs)[source]

Corrects coordinates for proper motion between times or supported surveys.

Parameters:

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

Note: Additional parameters are required depending on whether a source or pos is used:


Source Input

Requires one of:

Parameters:

  • target_survey (str) – any supported survey

  • target_time (list<int>) – target time in format [year,month]

Pos Input

Requires:

Parameters:

  • input_time (list<int>) – epoch of supplied coordinates in format [year,month]

  • target_time (list<int>) – target time in format [year,month]

  • pmra (float) – proper motion in right ascension in mas/yr

  • pmdec (float) – proper motion in declination in mas/yr

or

Parameters:

  • input_survey (str) – any supported survey

  • target_survey (str) – any supported survey

  • pmra (float) – proper motion in right ascension in mas/yr

  • pmdec (float) – proper motion in declination in mas/yr

Returns:

[right ascension, declination] in degrees

Return type:

list<int>


AstroToolkit.Tools.readdata(fname)[source]

Reads data from a local file created by ATK, recreating the original data structure. If no file name is provided, a file dialogue will open in which a file may be selected.

Parameters:

fname (str, optional) – name of file from which to read

Returns:

ATK Data Structure


AstroToolkit.Tools.search(kind, source/pos, *)[source]

Searches for a given target in Vizier or SIMBAD.

Parameters:

  • kind (str) – where to search for target, from ‘vizier’, ‘simbad’

  • source (int) – Target GAIA DR3 Source ID

  • pos (list<float>) – Position [right ascension, declination] in degrees

  • radius (float, optional) – Search radius in arcseconds, default given by search_radius config key

Returns:

None


AstroToolkit.Tools.readfits(fname, columns)[source]

Reads columns from a .fits file.

Parameters:

  • fname (str) – name of file from which to read

  • columns (list<str>) – names of column(s) to read

Returns:

Returned column data. E.g. if [ra, dec] requested, returns [[ra], [dec]]

Return type:

list<list>


AstroToolkit.Tools.deg2hms(pos)[source]

Converts coordinates in degrees to HMS±DMS format.

Parameters:

pos (list<float>) – Position [right ascension, declination] in degrees

Returns:

coordinates in HMS±DMS format

Return type:

str


AstroToolkit.Tools.hms2deg(identifier)[source]

Converts coordinates in HMS±DMS format to degrees.

Parameters:

pos (str) – position of target in HMS±DMS format, i.e. HHMMSS.SS…±DDMMSS.SS…

Returns:

[right ascension, declination] in degrees

Return type:

list<float>