ASAS-SN SkyPatrol client

The SkyPatrol pyasassn client allows users to query the ASAS-SN input catalog and retrieve light curves from our photometry database. These light curves are regularly updated with continuous photometry run on nightly images. Read the docs here.

Installation

The easiest way to get started is with pip, using Python 3.6+:

python -m pip install skypatrol

To build from source:

git clone https://github.com/asas-sn/skypatrol.git
pip3 install skypatrol/

Getting started

The SkyPatrolClient will automatically ping the server for the most recent catalog data, allowing us to query through different methods.

from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()
client.catalogs

Table Name: stellar_main
Num Columns: 47

Table Name: master_list
Num Columns: 4

Table Name: comets
Num Columns: 1

Table Name: swift
Num Columns: 56

Table Name: allwiseagn
Num Columns: 15

Table Name: mdwarf
Num Columns: 32

Table Name: milliquas
Num Columns: 21

Table Name: fermi
Num Columns: 67

Table Name: aavsovsx
Num Columns: 28

Table Name: morx
Num Columns: 38

Table Name: chandra
Num Columns: 516

Table Name: asteroids
Num Columns: 1

Main Catalog

The stellar_main catalog contains the bulk of our targets. It was built off of ATLAS REFCAT2 and contains GAIA, TESS, SDSS, and ALLWISE identifiers where available.

client.catalogs.stellar_main.head(15)

	col_names	dtypes
0	asas_sn_id	bigint
1	ra_deg	double
2	dec_deg	double
3	refcat_id	bigint
4	gaia_id	bigint
5	hip_id	string
6	tyc_id	string
7	tmass_id	string
8	sdss_id	string
9	allwise_id	string
10	tic_id	bigint
11	plx	float
12	plx_d	float
13	pm_ra	float
14	pm_ra_d	float

HEASARC Catalogs

The remaining catalogs were sourced from NASA's HEASARC archive. Each of these retains its original columnar data, though we have appended an asas_sn_id for all of them.

client.catalogs.aavsovsx.head(12)

	col_names	dtypes
0	asas_sn_id	bigint
1	ra_deg	double
2	dec_deg	double
3	source_number	bigint
4	name	string
5	variability_flag	bigint
6	lii	double
7	bii	double
8	variability_type	string
9	max_mag_type	double
10	max_mag_limit	string
11	max_mag	double

The Master List

The master_list contains asas_sn_ids coordinates and catalog sources for all of our targets. All of our catalogs are cross-matched on the master list with a 2-arcsecond cone.

client.catalogs.master_list

	col_names	dtypes
0	asas_sn_id	bigint
1	ra_deg	double
2	dec_deg	double
3	catalog_sources	array<string>

Cone Seach

Lets run a simple cone-search on the master list.

client.cone_search(ra_deg=270, dec_deg=88, radius=4, catalog='master_list')

	asas_sn_id	ra_deg	dec_deg	catalog_sources
0	8590494153	270.508480	84.120395	[stellar_main, tic]
1	8590493551	257.333476	84.119978	[stellar_main, tic]
2	8590494160	273.628334	84.120183	[stellar_main, tic]
3	8590494620	282.208531	84.120019	[stellar_main, tic]
4	8590493763	257.575614	84.119906	[stellar_main, tic]
...	...	...	...	...
82247	317828630672	272.518828	89.284092	[stellar_main, tic]
82248	317828630205	0.339976	89.284143	[stellar_main, tic]
82249	317828630428	142.968424	89.283984	[stellar_main, tic]
82250	317828630825	353.474920	89.284470	[stellar_main, tic]
82251	317828648971	71.616242	89.752714	[stellar_main, tic]

82252 rows × 4 columns

Random Curves

For whatever reason, if you are interested in random targets from a given catalog, we can give you those too.

client.random_sample(1000, catalog="aavsovsx")

	asas_sn_id	ra_deg	dec_deg	name
0	661427528626	11.36008	-88.53342	MASTER OT J004526.42-883200.3
1	17181143984	113.42148	-87.67768	WISE J073341.1-874039
2	17181129184	276.53493	-86.82375	ASASSN-V J182608.32-864925.1
3	661427528887	294.50733	-86.65919	ASASSN-14ft
4	1118197	313.27013	-85.89292	ASASSN-V J205304.83-855334.5
...	...	...	...	...
995	515397078518	265.46100	-41.78668	ASASSN-V J174150.64-414712.0
996	515397087473	210.81929	-41.72133	ASASSN-V J140316.63-414316.8
997	412316933534	8.80896	-41.72128	ASAS J003514-4143.2
998	515397087308	210.42030	-41.72102	SSS_J140141.0-414314
999	412316939243	106.25032	-41.72086	SSS_J070500.0-414314

1000 rows × 4 columns

Query Lists

If you have a list of external identifiers you can query our catalogs using these. For the stellar_main catalog, use the id_col parameter. For other catalogs you can search by name.

my_tic_ids = [6658326, 46783395, 1021890]
client.query_list(my_tic_ids, catalog='stellar_main', id_col='tic_id')

	asas_sn_id	ra_deg	dec_deg
0	309238124040	329.260377	-8.035864
1	335007699083	97.045759	18.214838
2	335007693701	81.164422	18.222147

my_vso_id = 'ASASSN-V J182608.32-864925.1'
client.query_list(my_vso_id, catalog='aavsovsx')

	asas_sn_id	ra_deg	dec_deg	name
0	17181129184	276.53493	-86.82375	ASASSN-V J182608.32-864925.1

ADQL Queries

We have inculded a custom ADQL parser. That will allow users to query targets using this familiar SQL-like language. First, take note how we can use this to perform a cone-search.

query = """
SELECT 
 * 
FROM stellar_main 
WHERE DISTANCE(ra_deg, dec_deg, 270, -88) <= 5.1
"""
client.adql_query(query)

	asas_sn_id	ra_deg	dec_deg	refcat_id	gaia_id	hip_id	tyc_id	tmass_id	sdss_id	allwise_id	...	pstarrs_r_mag_contrib	pstarrs_i_mag	pstarrs_i_mag_d	pstarrs_i_mag_chi	pstarrs_i_mag_contrib	pstarrs_z_mag	pstarrs_z_mag_d	pstarrs_z_mag_chi	pstarrs_z_mag_contrib	nstat
0	1094902	14.059417	-89.846361	180140594164367	4611690901807713792	None	None	None	None	None	...	1	16.174999	0.100	0.00	1	15.810000	0.100	0.00	1	0
1	1099017	182.038926	-89.804971	231820389264035	5764625115221143040	None	None	None	None	None	...	1	17.544001	0.100	0.00	1	17.448000	0.100	0.00	1	0
2	1105675	309.260296	-89.743042	303092602958351	6341076010576210432	None	None	None	None	None	...	33	12.147000	0.021	0.03	33	11.933000	0.100	0.01	1	0
3	1109079	39.243573	-89.709996	340392435728006	4611694161685666944	None	None	None	None	None	...	1	17.083000	0.100	0.00	1	16.879000	0.100	0.00	1	0
4	1110860	281.009406	-89.701636	352810094058038	6341087418009385600	None	None	None	None	None	...	33	16.521000	0.100	0.00	1	16.492001	0.100	0.00	1	0
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
245123	77310219747	256.853379	-83.001130	8392568533788677	5773920596978196224	None	None	None	None	None	...	41	16.059000	0.022	3.28	41	15.903000	0.028	0.00	9	1
245124	77310248925	260.635568	-82.997364	8402606355683196	5773744258504279552	None	None	None	None	None	...	1	16.035999	0.090	0.02	1	15.943000	0.090	0.00	1	0
245125	266288894288	276.533820	-82.974527	8432765338190601	6359213240854465280	None	None	None	None	None	...	41	16.825001	0.053	0.36	9	16.875000	0.024	1.32	9	0
245126	77310240409	278.626894	-82.946876	8462786268933782	6359204964453699328	None	None	None	None	None	...	9	16.986000	0.025	0.31	9	16.709000	0.046	0.43	9	0
245127	77310268049	263.648603	-82.935546	8472636486037378	5773736699361849344	None	None	None	None	None	...	9	17.495001	0.059	0.46	9	17.431000	0.025	0.25	9	0

245128 rows × 47 columns

JOINS

Since we have cross matched all of our catalogs. We can use ADQL to explore targets accross catalogs.

query = """
SELECT 
 asas_sn_id,
 chandra.name AS c_name,
 swift.name AS s_name  
FROM chandra 
JOIN swift USING(asas_sn_id) 
"""
client.adql_query(query)

	asas_sn_id	c_name	s_name
0	661430542782	2CXO J165358.5-395225	GROJ1655-40
1	661430564327	2CXO J174544.4-285744	GALACTICCENTER
2	661430563309	2CXO J174538.4-285744	GALACTICCENTER
3	661430490720	2CXO J132524.3-430110	CenA
4	661430501688	2CXO J140304.7+541924	PTF11kly
...	...	...	...
472	661430562283	2CXO J174532.1-290054	GALACTICCENTER
473	661430562286	2CXO J174545.7-290054	GALACTICCENTER
474	661430561004	2CXO J174547.5-290053	GALACTICCENTER
475	661430562813	2CXO J174547.4-290052	GALACTICCENTER
476	661430468363	2CXO J121900.0+472049	NGC4258

477 rows × 3 columns

Complex Searches

Lets say we were searching for white dwarfs that crossmatched in the VSO catalog.

query = """
SELECT 
  asas_sn_id,
  gaia_id,
  pstarrs_g_mag,
  (gaia_mag - (5 * LOG10(plx) - 10)) AS g_mag_abs, 
  name 
FROM stellar_main 
JOIN aavsovsx USING(asas_sn_id)
WHERE 1=1
 AND pstarrs_g_mag < 14 
 AND (gaia_mag - (5 * LOG10(plx) - 10)) > 10
 AND (gaia_b_mag - gaia_r_mag) < 1.5 
"""
client.adql_query(query)

	asas_sn_id	gaia_id	pstarrs_g_mag	g_mag_abs	name
0	81666	5775496815616520960	11.407	19.708543	ASAS J170324-7937.2
1	118602	5785843769793058048	10.258	16.563561	ASAS J142524-7758.4
2	588857	1055430973963102848	11.696	15.816850	NSV 5012
3	728404	2286601456945437952	8.677	16.979321	V0462 Cep
4	882997	2296982083661854592	13.810	25.175794	WISE J211009.8+791037
...	...	...	...	...	...
86597	652835029334	5923382022937143680	13.345	24.216244	ASASSN-V J171026.75-553046.2
86598	652835270742	5894443632805934976	9.793	17.875823	HD 127021
86599	652835624417	5334925216491199360	12.149	24.397192	GDS_J1142208-613045
86600	661425088337	5258317985093107072	11.683	21.799361	IV Car
86601	661425544613	5335409796224181376	11.922	22.474754	ASASSN-V J114927.29-601925.8

86602 rows × 5 columns

Downloading Curves

Any of the previous functions can take mode='download_curves' as a parameter to download the lightcurves coresponding to these targets.

The client will return a LightCurveCollection object which can be used for further analysis and plotting.

# Should take about 1-2 minutes
lcs = client.adql_query(query, mode="download_curves", threads=2)
lcs.data

	jd	flux	flux_err	mag	mag_err	limit	fwhm	asas_sn_id	cam
0	2.458829e+06	20.342858	0.088424	13.129036	0.004725	17.286221	1.44	8590141875	bC
1	2.458799e+06	18.665619	0.087248	13.222460	0.005081	17.300755	1.43	8590141875	bC
2	2.458828e+06	19.152875	0.076590	13.194481	0.004347	17.442213	1.46	8590141875	bC
3	2.458486e+06	20.587438	0.018324	13.116060	0.000967	18.995069	1.66	8590141875	bC
4	2.458676e+06	19.333177	0.089922	13.184308	0.005056	17.267982	1.50	8590141875	bC
...	...	...	...	...	...	...	...	...	...
67	2.458767e+06	11.306272	0.104996	13.766767	0.010094	17.099706	2.09	627065865626	bF
68	2.458735e+06	11.481891	0.097641	13.750032	0.009243	17.178560	2.05	627065865626	bF
69	2.458728e+06	11.532006	0.087781	13.745303	0.008274	17.294142	1.98	627065865626	bF
70	2.458690e+06	8.161064	0.085658	14.120699	0.011409	17.320725	1.98	627065865626	bF
71	2.458608e+06	11.419176	0.054434	13.755979	0.005181	17.812959	1.45	627065865626	bF

10357650 rows × 9 columns

lcs.stats()

	mean_mag	std_mag	epochs
asas_sn_id
6722	13.713655	0.143119	557
7205	9.354485	0.433855	243
10138	11.980529	0.032530	410
12702	13.071251	0.166151	547
15055	12.448167	0.345866	235
...	...	...	...
661425547786	13.487700	0.105852	137
661425547969	13.287609	0.141784	54
661425548441	13.690842	0.124418	157
661425548470	11.917627	0.024326	143
661425548591	13.108276	0.067760	157

86539 rows × 3 columns

lightcurve = lcs[15055]
lightcurve.meta

	asas_sn_id	gaia_id	pstarrs_g_mag	g_mag_abs	name
67265	15055	5784674881551467392	12.351	24.402487	BV Cha

lightcurve.plot()

client.adql_query("SELECT * FROM aavsovsx WHERE asas_sn_id = 15055")

	asas_sn_id	ra_deg	dec_deg	source_number	name	variability_flag	lii	bii	variability_type	max_mag_type	...	min_mag_system	epoch	epoch_flag	period_limit	period	period_flag	ref_bibcode_1	ref_bibcode_2	ref_bibcode_others	class
0	15055	195.58829	-79.75731	9336	BV Cha	0	303.438856	-16.896307	CWB	NaN	...	V	2451872.85	None	None	1.23804	None	1963VeSon...6....1H	2009yCat....102025S	None	2900

1 rows × 28 columns

darthoctopus/skypatrol