This page contains Jupyter Notebooks to programatically access the ALMA Science Archive. The notebooks interact through Virtual Observatory standards with ALMA's ObsCore Table Access Protocol (TAP) service.
Queries in TAP are written in the SQL-like Astronomical Data Query Language (ADQL). ADQL queries include spatial queries as well as operations on other properties/columns of the database. This also allows the user detailed control over the returned columns.
In these Jupyter notebook we will exemplify some of the most common queries. For this we will be using the astropy affiliated PyVO client, which is interoperable with other valid TAP services from other observatories.
Install the required software with
pip3 install jupyterlab matplotlib pandas sklearn
pip3 install --upgrade --pre astroquery
download the Jupyter Notebooks
wget https://almascience.org/alma-data/archive/archive-notebooks/alma-science-archive-notebooks.tgz -O - | tar -xz
cd alma-science-archive-notebooks
and start the notebook server
jupyter-lab
You can modify the code in the cells and run each cell with "Shift+Enter". An introduction to Jupyter Notebooks can be found here.
Python 3.6 users, run: pip3 --upgrade astropy==4.1
If you experience problems with these notebooks, please contact us through the ALMA Helpdesk.
Throughout the notebooks we will access the ALMA ObsCore TAP service using:
import pyvo
import pandas as pd
service = pyvo.dal.TAPService("https://almascience.eso.org/tap") # for the EU ALMA TAP service
# service = pyvo.dal.TAPService("https://almascience.nao.ac.jp/tap") # for the EA ALMA TAP service
# service = pyvo.dal.TAPService("https://almascience.nrao.edu/tap") # for the NA ALMA TAP service
Here some examples of the use of ADQL:
Find all ALMA observations where the footprint of the observation (stored in the VO column 's_region') intersects with our search circle where RA, Dec and the search radius are given in decimal degrees:
query = f"""
SELECT *
FROM ivoa.obscore
WHERE INTERSECTS(CIRCLE('ICRS',201.365063,-43.019112,0.006),s_region)=1
"""
result = service.search(query)
output = result.to_table().to_pandas()
The output has been directly converted into a pandas dataframe. For simplicity, we only display the first 5 rows.
pd.set_option('display.max_columns', None)
output.head(5)
| access_url | access_format | proposal_id | data_rights | gal_longitude | gal_latitude | obs_publisher_did | obs_collection | facility_name | instrument_name | obs_id | dataproduct_type | calib_level | target_name | s_ra | s_dec | s_fov | s_region | s_resolution | t_min | t_max | t_exptime | t_resolution | em_min | em_max | em_res_power | pol_states | o_ucd | band_list | em_resolution | authors | pub_abstract | publication_year | proposal_abstract | schedblock_name | proposal_authors | sensitivity_10kms | cont_sensitivity_bandwidth | pwv | group_ous_uid | member_ous_uid | asdm_uid | obs_title | type | scan_intent | science_observation | spatial_scale_max | bandwidth | antenna_arrays | is_mosaic | obs_release_date | spatial_resolution | frequency_support | frequency | velocity_resolution | obs_creator_name | pub_title | first_author | qa2_passed | bib_reference | science_keyword | scientific_category | lastModified | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | http://almascience.org/aq?member_ous_id=uid://... | text/html | 2011.0.00008.SV | Public | 309.512363 | 19.416239 | ADS/JAO.ALMA#2011.0.00008.SV | ALMA | JAO | ALMA | uid://A002/X259150/X157 | cube | 2 | Centaurus A | 201.360719 | -43.020553 | 0.058089 | Polygon ICRS 201.401254 -43.032096 201.401354 ... | 1.023315 | 55784.795689 | 55785.043473 | 344.261 | 344.261 | 0.001221 | 0.001231 | 251315.70776 | /XX/YY/ | phot.flux.density;phys.polarization | 6 | 306.959997 | Azeez, Jazeel H.; Abidin, Zamri Z.; Hwang, C. ... | Centaurus A, with its gas-rich elliptical host... | 2014 | Science Verification (SV) is the process by wh... | CenA mosaic | 13.319542 | 0.432702 | 1.663192 | uid://A002/X259150/X157 | uid://A002/X2762c7/X132 | Science verification observation of Centaurus A | SV | TARGET WVR | T | 9.714115 | 1.875000e+09 | A004:DV07 A008:DV09 A009:DA41 A011:DV12 A015:D... | T | 2016-06-24T14:02:07.000 | 1.023315 | [229.20..231.08GHz,976.56kHz,13.2mJy/beam@10km... | 238.261613 | 1183.847494 | observatory, ALMA | ALMA Observations of the Physical and Chemical... | Azeez, Jazeel H. Israel, F. P. McCoy, Mark | T | 2014A&A...562A..96I 2017AdAst2017E...6A 2017Ap... | Galactic centres/nuclei, Active Galactic Nucle... | Active galaxies | 2021-09-30T16:34:41.133 | ||
| 1 | http://almascience.org/aq?member_ous_id=uid://... | text/html | 2011.0.00008.SV | Public | 309.512363 | 19.416239 | ADS/JAO.ALMA#2011.0.00008.SV | ALMA | JAO | ALMA | uid://A002/X259150/X157 | cube | 2 | Centaurus A | 201.360719 | -43.020553 | 0.058089 | Polygon ICRS 201.401254 -43.032096 201.401354 ... | 1.023315 | 55784.795689 | 55785.043473 | 344.261 | 344.261 | 0.001212 | 0.001221 | 253235.70776 | /XX/YY/ | phot.flux.density;phys.polarization | 6 | 306.959997 | Azeez, Jazeel H.; Abidin, Zamri Z.; Hwang, C. ... | Centaurus A, with its gas-rich elliptical host... | 2014 | Science Verification (SV) is the process by wh... | CenA mosaic | 13.283133 | 0.432702 | 1.663192 | uid://A002/X259150/X157 | uid://A002/X2762c7/X132 | Science verification observation of Centaurus A | SV | TARGET WVR | T | 9.714115 | 1.875000e+09 | A004:DV07 A008:DV09 A009:DA41 A011:DV12 A015:D... | T | 2016-06-24T14:02:07.000 | 1.023315 | [229.20..231.08GHz,976.56kHz,13.2mJy/beam@10km... | 238.261613 | 1183.847494 | observatory, ALMA | ALMA Observations of the Physical and Chemical... | Azeez, Jazeel H. Israel, F. P. McCoy, Mark | T | 2014A&A...562A..96I 2017AdAst2017E...6A 2017Ap... | Galactic centres/nuclei, Active Galactic Nucle... | Active galaxies | 2021-09-30T16:34:41.133 | ||
| 2 | http://almascience.org/aq?member_ous_id=uid://... | text/html | 2011.0.00008.SV | Public | 309.512363 | 19.416239 | ADS/JAO.ALMA#2011.0.00008.SV | ALMA | JAO | ALMA | uid://A002/X259150/X157 | cube | 2 | Centaurus A | 201.360719 | -43.020553 | 0.058089 | Polygon ICRS 201.401254 -43.032096 201.401354 ... | 1.023315 | 55784.795689 | 55785.043473 | 344.261 | 344.261 | 0.001297 | 0.001308 | 236599.53752 | /XX/YY/ | phot.flux.density;phys.polarization | 6 | 306.959997 | Azeez, Jazeel H.; Abidin, Zamri Z.; Hwang, C. ... | Centaurus A, with its gas-rich elliptical host... | 2014 | Science Verification (SV) is the process by wh... | CenA mosaic | 13.238502 | 0.432702 | 1.663192 | uid://A002/X259150/X157 | uid://A002/X2762c7/X132 | Science verification observation of Centaurus A | SV | TARGET WVR | T | 9.714115 | 1.875000e+09 | A004:DV07 A008:DV09 A009:DA41 A011:DV12 A015:D... | T | 2016-06-24T14:02:07.000 | 1.023315 | [229.20..231.08GHz,976.56kHz,13.2mJy/beam@10km... | 238.261613 | 1183.847494 | observatory, ALMA | ALMA Observations of the Physical and Chemical... | Azeez, Jazeel H. Israel, F. P. McCoy, Mark | T | 2014A&A...562A..96I 2017AdAst2017E...6A 2017Ap... | Galactic centres/nuclei, Active Galactic Nucle... | Active galaxies | 2021-09-30T16:34:41.133 | ||
| 3 | http://almascience.org/aq?member_ous_id=uid://... | text/html | 2011.0.00008.SV | Public | 309.512363 | 19.416239 | ADS/JAO.ALMA#2011.0.00008.SV | ALMA | JAO | ALMA | uid://A002/X259150/X157 | cube | 2 | Centaurus A | 201.360719 | -43.020553 | 0.058089 | Polygon ICRS 201.401254 -43.032096 201.401354 ... | 1.023315 | 55784.795689 | 55785.043473 | 344.261 | 344.261 | 0.001287 | 0.001297 | 238519.53752 | /XX/YY/ | phot.flux.density;phys.polarization | 6 | 306.959997 | Azeez, Jazeel H.; Abidin, Zamri Z.; Hwang, C. ... | Centaurus A, with its gas-rich elliptical host... | 2014 | Science Verification (SV) is the process by wh... | CenA mosaic | 13.354480 | 0.432702 | 1.663192 | uid://A002/X259150/X157 | uid://A002/X2762c7/X132 | Science verification observation of Centaurus A | SV | TARGET WVR | T | 9.714115 | 1.875000e+09 | A004:DV07 A008:DV09 A009:DA41 A011:DV12 A015:D... | T | 2016-06-24T14:02:07.000 | 1.023315 | [229.20..231.08GHz,976.56kHz,13.2mJy/beam@10km... | 238.261613 | 1183.847494 | observatory, ALMA | ALMA Observations of the Physical and Chemical... | Azeez, Jazeel H. Israel, F. P. McCoy, Mark | T | 2014A&A...562A..96I 2017AdAst2017E...6A 2017Ap... | Galactic centres/nuclei, Active Galactic Nucle... | Active galaxies | 2021-09-30T16:34:41.133 | ||
| 4 | http://almascience.org/aq?member_ous_id=uid://... | text/html | 2011.0.00010.S | Public | 309.515914 | 19.417224 | ADS/JAO.ALMA#2011.0.00010.S | ALMA | JAO | ALMA | uid://A002/X327408/X217 | cube | 2 | CenA | 201.365063 | -43.019112 | 0.007385 | Circle ICRS 201.365063 -43.019112 0.003692 | 1.330912 | 55950.253573 | 55950.305961 | 1512.000 | 1512.000 | 0.001360 | 0.001366 | 451534.98200 | /XX/YY/ | phot.flux.density;phys.polarization | 6 | 614.023326 | McCoy, Mark; Ott, Jürgen; Meier, David S.; Mul... | Centaurus A, with its gas-rich elliptical host... | 2017 | Centaurus A with its host NGC5128 is the most ... | CenA 13CO, C18O, HNCO, H2CO COMP | Impellizzeri, Violette; Peck, Alison; Walter, ... | 1.398342 | 0.061695 | 0.852892 | uid://A002/X327408/X217 | uid://A002/X383b50/Xc45 | The Physics and Chemisty of Gas in Centaurus A... | S | TARGET | T | 12.599759 | 9.375000e+08 | A002:PM02 A004:DV04 A009:DA43 A011:DV12 A013:D... | F | 2015-02-12T13:48:59.000 | 1.330912 | [217.59..218.53GHz,488.28kHz,1.4mJy/beam@10km/... | 219.025328 | 663.940713 | Ott, Juergen | ALMA Observations of the Physical and Chemical... | McCoy, Mark | T | 2017ApJ...851...76M | Active Galactic Nuclei (AGN)/Quasars (QSO), Me... | Active galaxies | 2021-09-30T16:34:41.133 |
The ALMA TAP table contains 63 columns with the following column names and units:
print(*sorted([f"{fieldname:28s} {result.getdesc(fieldname).unit if result.getdesc(fieldname).unit else ''}" for fieldname in result.fieldnames]), sep='\n')
access_format access_url antenna_arrays asdm_uid authors band_list bandwidth GHz bib_reference calib_level cont_sensitivity_bandwidth mJy/beam data_rights dataproduct_type em_max m em_min m em_res_power em_resolution m facility_name first_author frequency GHz frequency_support GHz gal_latitude deg gal_longitude deg group_ous_uid instrument_name is_mosaic lastModified member_ous_uid o_ucd obs_collection obs_creator_name obs_id obs_publisher_did obs_release_date obs_title pol_states proposal_abstract proposal_authors proposal_id pub_abstract pub_title publication_year pwv mm qa2_passed s_dec deg s_fov deg s_ra deg s_region deg s_resolution deg scan_intent schedblock_name science_keyword science_observation scientific_category sensitivity_10kms mJy/beam spatial_resolution arcsec spatial_scale_max arcsec t_exptime s t_max d t_min d t_resolution s target_name type velocity_resolution m / s
The query returns all ALMA observations where the footprint (s_region) intersects with the search circle specified by RA, Dec and the search radius, all in decimal degrees. Compared to the example above, the result table has now a much smaller width as only the target name, RA and Dec have been requested.
query = f"""
SELECT target_name, s_ra, s_dec
FROM ivoa.obscore
WHERE INTERSECTS(CIRCLE('ICRS',201.365063,-43.019112,0.006),s_region)=1
"""
output = service.search(query).to_table().to_pandas()
pd.set_option('display.max_columns', None)
output.head(5)
| target_name | s_ra | s_dec | |
|---|---|---|---|
| 0 | Centaurus A | 201.360719 | -43.020553 |
| 1 | Centaurus A | 201.360719 | -43.020553 |
| 2 | Centaurus A | 201.360719 | -43.020553 |
| 3 | Centaurus A | 201.360719 | -43.020553 |
| 4 | CenA | 201.365063 | -43.019112 |