Utilities and tutorials for accessing Gaia data using TAP
Project description
*Gaia* on TAP
=============
Python utilities and examples for accessing ESA Gaia data using Table Access Protocol (TAP).
Authors
=======
- Andrew R. Casey (Cambridge)
Installation
============
Install using `pip`:
````
pip install gaia-on-tap
````
Getting Started
===============
The `gaia.tap` package includes two main functions for accessing Gaia data: `query` and `cone_search`.
By default, both will return all retrieved sources as an `astropy.table.Table` object, so you can then
write the results to disk or do something useful with them.
Select stars around M67
-----------------------
````python
# Get all sources within 1 degree of M67
import astropy.coordinates as coord
from gaia.tap import cone_search
cluster = coord.SkyCoord.from_name("M67")
cluster_candidates = cone_search(cluster.ra.deg, cluster.dec.deg, 1.0)
````
Select hypervelocity star candidates in TGAS
--------------------------------------------
This doesn't treat the errors correctly, but it's a useful example to show what you can do:
````python
import gaia.tap
# Identify stars with tangential velocities exceeding 500 km/s, and reasonable parallaxes
hvs_candidates = gaia.tap.query(
""" SELECT *
FROM gaiadr1.tgas_source
WHERE parallax_error/parallax < 0.2
AND (4.74 * SQRT(POWER(pmra, 2) + POWER(pmdec, 2)))/parallax > 500 """)
````
Authenticate using your ESA/Gaia Archive credentials
----------------------------------------------------
If you have an account with the ESA/Gaia archive, you can include your credentials so that
you can upload or query private tables. This is done by having a file (e.g., `credentials.yaml`)
like:
````
username: acasey
password: my-super-awesome-password
````
And then in the code:
````python
import gaia
# Read in our credentials. You only have to do this once per Python session!
gaia.config.read("credentials.yaml")
# For any further queries use the authenticate flag, and the code will log you in automagically
sources = gaia.tap.query(" ... ", authenticate=True)
````
Upload a table to your local space on the ESA/Gaia archive
----------------------------------------------------------
If you want to upload a VOtable and use it for cross-matches through the ESA/Gaia archive:
````python
import gaia
# Read in our credentials.
gaia.config.read("credentials.yaml")
# Upload our table, which we will ask ESA/Gaia to call 'my_table'
gaia.tap.upload("my_table", "/local/path/to/your/table.votable")
# Now use it!
# (Ensure that you use the authenticate=True flag so that you can access your private tables)
xmatched_sources = tap.query(
""" SELECT *
FROM gaiadr1.gaia_source as gaia,
<YOUR_USERNAME>.my_table as my_table
WHERE 1=CONTAINS(
POINT('ICRS', my_table.ra, my_table.dec),
CIRCLE('ICRS', gaia.ra, gaia.dec, 1.5/3600)
)
""", authenticate=True)
````
Resources
=========
- [ESA Gaia TAP documentation](https://gea.esac.esa.int/archive/) -> Help -> Command-line access
- [Gaia ADQL cookbook](https://gaia.ac.uk/science/gaia-data-release-1/adql-cookbook)
- [GAVO ADQL cheat sheet](http://docs.g-vo.org/adqlref/adqlref.pdf)
- [Jo Bovy's `gaia_tools`](https://github.com/jobovy/gaia_tools)
- [TAP ADQL help on Vizier](http://tapvizier.u-strasbg.fr/adql/help.html)
=============
Python utilities and examples for accessing ESA Gaia data using Table Access Protocol (TAP).
Authors
=======
- Andrew R. Casey (Cambridge)
Installation
============
Install using `pip`:
````
pip install gaia-on-tap
````
Getting Started
===============
The `gaia.tap` package includes two main functions for accessing Gaia data: `query` and `cone_search`.
By default, both will return all retrieved sources as an `astropy.table.Table` object, so you can then
write the results to disk or do something useful with them.
Select stars around M67
-----------------------
````python
# Get all sources within 1 degree of M67
import astropy.coordinates as coord
from gaia.tap import cone_search
cluster = coord.SkyCoord.from_name("M67")
cluster_candidates = cone_search(cluster.ra.deg, cluster.dec.deg, 1.0)
````
Select hypervelocity star candidates in TGAS
--------------------------------------------
This doesn't treat the errors correctly, but it's a useful example to show what you can do:
````python
import gaia.tap
# Identify stars with tangential velocities exceeding 500 km/s, and reasonable parallaxes
hvs_candidates = gaia.tap.query(
""" SELECT *
FROM gaiadr1.tgas_source
WHERE parallax_error/parallax < 0.2
AND (4.74 * SQRT(POWER(pmra, 2) + POWER(pmdec, 2)))/parallax > 500 """)
````
Authenticate using your ESA/Gaia Archive credentials
----------------------------------------------------
If you have an account with the ESA/Gaia archive, you can include your credentials so that
you can upload or query private tables. This is done by having a file (e.g., `credentials.yaml`)
like:
````
username: acasey
password: my-super-awesome-password
````
And then in the code:
````python
import gaia
# Read in our credentials. You only have to do this once per Python session!
gaia.config.read("credentials.yaml")
# For any further queries use the authenticate flag, and the code will log you in automagically
sources = gaia.tap.query(" ... ", authenticate=True)
````
Upload a table to your local space on the ESA/Gaia archive
----------------------------------------------------------
If you want to upload a VOtable and use it for cross-matches through the ESA/Gaia archive:
````python
import gaia
# Read in our credentials.
gaia.config.read("credentials.yaml")
# Upload our table, which we will ask ESA/Gaia to call 'my_table'
gaia.tap.upload("my_table", "/local/path/to/your/table.votable")
# Now use it!
# (Ensure that you use the authenticate=True flag so that you can access your private tables)
xmatched_sources = tap.query(
""" SELECT *
FROM gaiadr1.gaia_source as gaia,
<YOUR_USERNAME>.my_table as my_table
WHERE 1=CONTAINS(
POINT('ICRS', my_table.ra, my_table.dec),
CIRCLE('ICRS', gaia.ra, gaia.dec, 1.5/3600)
)
""", authenticate=True)
````
Resources
=========
- [ESA Gaia TAP documentation](https://gea.esac.esa.int/archive/) -> Help -> Command-line access
- [Gaia ADQL cookbook](https://gaia.ac.uk/science/gaia-data-release-1/adql-cookbook)
- [GAVO ADQL cheat sheet](http://docs.g-vo.org/adqlref/adqlref.pdf)
- [Jo Bovy's `gaia_tools`](https://github.com/jobovy/gaia_tools)
- [TAP ADQL help on Vizier](http://tapvizier.u-strasbg.fr/adql/help.html)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
gaia-on-tap-0.1.7.tar.gz
(5.0 kB
view hashes)
Built Distributions
gaia_on_tap-0.1.7-py3.6.egg
(10.8 kB
view hashes)
gaia_on_tap-0.1.7-py2.7.egg
(10.6 kB
view hashes)