/skypatrol

The ASAS-SN Sky Patrol python client

Primary LanguagePythonGNU General Public License v3.0GPL-3.0



Tests Docs

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()

png

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