Code Reference

Client

class pyasassn.client.SkyPatrolClient(verbose=True)

Bases: object

The SkyPatrolClient allows users to interact with the ASAS-SN Sky Patrol photometry database.

This client enables users to use ADQL, cone searches, random samples, and catalog ID lookups on the input catalogs.

Queries to the input catalogs will either be returned as pandas DataFrames containing aggregate information on astronomical targets, or they will be returned as LightCurveCollections containing photometry data from all queried targets.

class InputCatalogs(schema, counts)

Bases: object

Data structure for holding metadata on ASAS-SN Sky Patrol’s input catalogs.

Stores input catalog names as well as their searchable columns and total number of targets.

catalog_names()

Get all the names of our available input catalogs

Returns

names of all input catalogs (list)

adql_query(query_str, download=False, save_dir=None, file_format='parquet', threads=1)

Query the ASAS-SN Sky Patrol Input Catalogs with an ADQL string. See README.md for more on accepted ADQL context and functions.

Parameters

• query_str – ADQL query string

• download – return full light curves if True, return catalog information if False

• save_dir – if set, then light curves will write to file as they are downloaded

• file_format – format to save light curves [‘parquet’, ‘pickle’, ‘csv’]

• threads – number of real threads to use for pulling light curves from server.

Returns

if ‘download’ if False; pandas Dataframe containing catalog information of targets; else LightCurveCollection

cone_search(ra_deg, dec_deg, radius, units='deg', catalog='master_list', cols=None, download=False, save_dir=None, file_format='parquet', threads=1)

Query the ASAS-SN Sky Patrol Input Catalogs for all targets within a cone of the sky. Does NOT return solar system targets (i.e. asteroids and coma).

Parameters

• ra_deg – right ascension of cone. accepts degree-decimal (float) or HH:MM:SS(.SS) sexagesimal (string)

• dec_deg – declination of cone. accepts degree/decimal as float or DD:MM:SS(.SS) sexagesimal (string)

• radius – radius in degrees of cone, float

• units – units for cone radius. ‘deg’: degree decimal ‘arcmin’: arcminutes ‘arcsec’ arcseconds

• catalog – which catalog are we searching

• cols – columns to return from the given input catalog; if None default = [‘asas_sn_id’, ‘ra_deg’, ‘dec_deg’]

• download – return full light curves if True, return catalog information if False

• save_dir – if set, then light curves will write to file as they are downloaded

• file_format – format to save light curves [‘parquet’, ‘pickle’, ‘csv’]

• threads – number of real threads to use for pulling light curves from server.

Returns

if ‘download’ if False; pandas Dataframe containing catalog information of targets; else LightCurveCollection

query_list(tar_ids, id_col='asas_sn_id', catalog='master_list', cols=None, download=False, save_dir=None, file_format='parquet', threads=1)

Query the ASAS-SN Sky Patrol Input Catalogs for all targets with the given identifiers. to view the available list of catalogs and identifiers see SkyPatrolClient.catalogs.

Most of our astronomical targets are in the stellar_main catalog, which has been pre-crossmatched to GaiaDR2, ATLAS Refcat2, SDSS, AllWISE, and Tess Input Catalog (TIC v8).

Thus searching for light curves with a list of Gaia IDs would require catalog=’stellar_main’, id_col=’gaia_id’. Our other input catalogs should be searched with id_col=’name’, or by columns giving alternative ids.

Parameters

• tar_ids – list of target ids for query; list

• id_col – the column on the given catalog to search against; string

• catalog – which catalog are we searching

• cols – columns to return from the given input catalog; if None default = [‘asas_sn_id’, ‘ra_deg’, ‘dec_deg’]

• download – return full light curves if True, return catalog information if False

• save_dir – if set, then light curves will write to file as they are downloaded

• file_format – format to save light curves [‘parquet’, ‘pickle’, ‘csv’]

• threads – number of real threads to use for pulling light curves from server.

Returns

if ‘download’ if False; pandas Dataframe containing catalog information of targets; else LightCurveCollection

random_sample(n, catalog='master_list', cols=None, download=False, save_dir=None, file_format='parquet', threads=1)

Get n random targets from the ASAS-SN Sky Patrol Input Catalogs.

Parameters

• n – number of targets to randomly sample

• catalog – which catalog are we searching

• cols – columns to return from the given input catalog; if None default = [‘asas_sn_id’, ‘ra_deg’, ‘dec_deg’]

• download – return full light curves if True, return catalog information if False

• save_dir – if set, then light curves will write to file as they are downloaded

• file_format – format to save light curves [‘parquet’, ‘pickle’, ‘csv’]

• threads – number of real threads to use for pulling light curves from server.

Returns

if ‘download’ if False; pandas Dataframe containing catalog information of targets; else LightCurveCollection

pyasassn.client.load_collection(save_dir, file_format='parquet')

Loads a LightCurveCollection from directory. Requires an index and light curve files saved from previous collection :param save_dir: path where collection is saved :param file_format: format of saved light curves :return: LightCurveCollection

Light Curve Tools

class pyasassn.utils.LightCurve(pandas_obj, meta)

Bases: object

Object for analysing and visualizing ASAS-SN Sky Patrol light curves.

find_period(frequency, power, best_frequency=None, plot=True, figsize=(12, 8), savefile=None, include_poor_images=False, include_non_det=False)

Find the period of the light curve given the power spectrum produced by lomb_scargle. Also produces a phase-folded plot of the light curve.

Parameters

• frequency – frequency from lomb_scargle()

• power – power from lomb_scargle()

• best_frequency – peak frequency for phase folding the light curve

• plot – if True, then the function also produces a plot of the phase-folded light curve

• figsize – size of the plot

• savefile – file name to save the plot; if None plot will be directly displayed

• include_poor_images – whether or not to include images of poor or unknown quality; defaults to False

• include_non_det – whether or not to include non-detection events in analysis; defaults to False

Returns

period of the light curve

lomb_scargle(fit_mean=True, center_data=True, nterms=1, normalization='standard', minimum_frequency=0.001, maximum_frequency=25, method='auto', samples_per_peak=5, nyquist_factor=5, plot=True, figsize=(12, 8), savefile=None, include_poor_images=False, include_non_det=False)

Thin wrapper around the astropy LombScargle utility to determine frequency and power spectra of the given light curve. Default values work for most variable sources.

Parameters

• fit_mean – if True, include a constant offset as part of the model at each frequency. This can lead to more accurate results, especially in the case of incomplete phase coverage.

• center_data – if True, pre-center the data by subtracting the weighted mean of the input data. This is especially important if fit_mean = False

• nterms – number of terms to use in the Fourier fit

• normalization – Normalization to use for the periodogram.

• minimum_frequency – If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

• maximum_frequency – If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

• method –

  specify the lomb scargle implementation to use. Options are:

  • ‘auto’: choose the best method based on the input

  • ‘fast’: use the O[N log N] fast method. Note that this requires evenly-spaced frequencies: by default this will be checked unless assume_regular_frequency is set to True.

  • ‘slow’: use the O[N^2] pure-python implementation

  • ‘cython’: use the O[N^2] cython implementation. This is slightly faster than method=’slow’, but much more memory efficient.

  • ‘chi2’: use the O[N^2] chi2/linear-fitting implementation

  • ‘fastchi2’: use the O[N log N] chi2 implementation. Note that this requires evenly-spaced frequencies: by default this will be checked unless assume_regular_frequency is set to True.

  • ‘scipy’: use scipy.signal.lombscargle, which is an O[N^2] implementation written in C. Note that this does not support heteroskedastic errors.

• samples_per_peak – The approximate number of desired samples across the typical peak

• nyquist_factor – The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

• plot – if True, then the function also produces a plot of the power spectrum.

• figsize – size of the plot.

• savefile – file name to save the plot; if None plot will be directly displayed

• include_poor_images – whether or not to include images of poor or unknown quality; defaults to False

• include_non_det – whether or not to include non-detection events in analysis; defaults to False

Returns

power, frequency and the astropy LombScargle object

plot(figsize=(12, 8), savefile=None, include_poor_images=False)

Plots the given light curve with error bars.

Parameters

• figsize – size of the plot

• savefile – file name to save the plot; if None plot will be directly displayed

• include_poor_images – whether or not to include images of poor or unknown quality; defaults to False

Returns

void

save(filename, file_format='parquet')

Save the light curve to csv.

Parameters

• filename – filename to save this light curve.

• file_format – file format of saved objects [‘parquet’, ‘csv’, ‘pickle’]

Returns

void

class pyasassn.utils.LightCurveCollection(data, catalog_info, id_col)

Bases: object

Object for storing and analysing ASAS-SN Sky Patrol light curves. Returned by any SkyPatrolClient query where download=True

apply_function(func, col='mag', include_non_det=False, include_poor_images=False)

Apply a custom aggregate function to all light curves in the collection.

Parameters

• func – custom aggregate function

• col – column to apply aggregate function; defaluts to ‘mag’

• include_non_det – whether or not to include non-detection events in analysis; defaults to False

:param include_poor_images whether or not to include images of poor or unknown quality; defaults to False :return: pandas Dataframe with results

itercurves()

Generator to iterate through all light curves in the collection.

Returns

a generator that iterates over the collection

save(save_dir, file_format='parquet', include_index=True)

Saves entire light curve collection to a given directory.

Parameters

• save_dir – directory name

• file_format – file format of saved objects [‘parquet’, ‘csv’, ‘pickle’]

• include_index – whether or not to save index (catalog_info)

Returns

filenames

stats(include_non_det=False, include_poor_images=False)

Calculate simple aggregate statistics on the collection. Gets the mean and stddev magnitude for each curve as well as the total number of epochs observed.

Parameters

• include_poor_images – whether or not to include images of poor or unknown quality; defaults to False

• include_non_det – whether or not to include non-detection events in analysis; defaults to False

Returns

pandas Dataframe with results