{ "cells": [ { "cell_type": "markdown", "id": "818f137f", "metadata": { "deletable": false, "editable": false }, "source": [ "# 1. Query tools\n", "\n", "This Section introduces three methods to query the ALMA archive:\n", "\n", "- [1.1 - Query by target name (alminer.target)](#1.1-Query-by-target-name)
\n", "- [1.2 - Query a catalog (alminer.catalog)](#1.2-Query-by-position)
\n", "- [1.3 - Query by ALMA keywords (alminer.keysearch)](#1.3-Query-by-ALMA-keywords)\n", "\n", "

General notes about the querying functions:

\n", "\n", "* All querying functions search the ALMA archive for public data by default. To include both public and proprietary data in the search, set *public=None*. Similarly, to search for only propietary data, set *public=False*. \n", "* All querying functions search the ALMA archive for both published and unpublished data. To include only unpublished data, set *published=False*.\n", "* The querying functions will by default print a summary of the observations, including a list of target names. For large queries, it is useful to turn this feature off in order to not have a long list of targets printed to screen. To turn off this feature, simply set *print_targets=False*.\n", "* The queried archive service is by default the Europeran one (ESO). Other services can be specified through the *tap_service* argument. Options are: ESO, NRAO, or NAOJ.\n", "* The queries return all possible observations in [PANDAS DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/frame.html) format that can be used to further narrow down your search as demonstrated in [Section 2](2_filter_explore.ipynb)." ] }, { "cell_type": "markdown", "id": "6d22e9b3", "metadata": { "deletable": false, "editable": false }, "source": [ "

Load libraries

" ] }, { "cell_type": "code", "execution_count": 1, "id": "15f044eb", "metadata": { "deletable": false, "editable": false }, "outputs": [], "source": [ "import alminer\n", "import pandas\n", "from astropy.io import ascii" ] }, { "cell_type": "markdown", "id": "a7fc0530", "metadata": { "deletable": false, "editable": false }, "source": [ "## 1.1 Query by target name\n", "\n", "The [alminer.target](../pages/api.rst#alminer.target) function allows one to query objects by name. This function uses the Astropy [SESAME resolver](http://cds.u-strasbg.fr/cgi-bin/Sesame) which searches multiple databases (Simbad, NED, VizieR) to obtain the coordinates of the object of interest, and then queries the ALMA archive for all observations that contain those coordinates (corresponding to the case of *point=True* which is the default). When *point=False*, the function will return all observations that overlap with a cone extending the position of interest and a search radius around it. The search radius is by default 1.0 arcminute, but can be modified using the *search_radius* keyword (in arcmin units). " ] }, { "cell_type": "markdown", "id": "2580a952", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.1.1: query two sources by name" ] }, { "cell_type": "code", "execution_count": 2, "id": "ee9c31b8", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.target results \n", "================================\n", "Target = Orion KL\n", "--------------------------------\n", "Number of projects = 23\n", "Number of observations = 38\n", "Number of unique subbands = 129\n", "Total number of subbands = 160\n", "18 target(s) with ALMA data = ['OMC1_NW', 'Orion-KL', 'orion_kl', 'BN-KL', 'OMC1_SE', 'Orion_KL_Field_3_North-west_Clump', 'BN', 'OrionKL', 'Orion', 'Orion_KL', 'orion-IRc2', 'OMC-1', 'ONC', 'Orion1', 'OMC-1_Region2', 'ONC_Mosaic', 'Orion_Source_I', 'Orion_BNKL_source_I']\n", "--------------------------------\n", "Target = AB Aur\n", "--------------------------------\n", "Number of projects = 3\n", "Number of observations = 3\n", "Number of unique subbands = 17\n", "Total number of subbands = 17\n", "3 target(s) with ALMA data = ['AB_Auriga', 'AB_Aur', 'ab_aurigae']\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.target(['Orion KL', \"AB Aur\"])" ] }, { "cell_type": "markdown", "id": "6d08b0fb", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.1.2: query a list of objects by name\n", "\n", "First create a catalog or a list of object names. In this example, the catalog `Sample_cat.dat` has the following content:\n", "```\n", " Name RA DEC \n", "------ -------- --------\n", "AB_Aur 73.9412 30.5511\n", "AK_Sco 253.6867 -36.8886\n", "AS_310 278.3383 -4.9683\n", "AS_470 324.0592 57.3586\n", "AS_477 328.1421 47.2289\n", "```\n", "\n", "Note that the column that is used is the *Name* column and the coordinates are ignored in this example." ] }, { "cell_type": "code", "execution_count": 3, "id": "ae9a2f06", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.target results \n", "================================\n", "Target = AB_Aur\n", "--------------------------------\n", "Number of projects = 3\n", "Number of observations = 3\n", "Number of unique subbands = 17\n", "Total number of subbands = 17\n", "3 target(s) with ALMA data = ['AB_Auriga', 'AB_Aur', 'ab_aurigae']\n", "--------------------------------\n", "Target = AK_Sco\n", "--------------------------------\n", "Number of projects = 3\n", "Number of observations = 3\n", "Number of unique subbands = 12\n", "Total number of subbands = 12\n", "2 target(s) with ALMA data = ['AK_Sco', 'HIP_82747']\n", "--------------------------------\n", "Target = AS_310\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n", "Target = AS_470\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n", "Target = AS_477\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n" ] } ], "source": [ "mylist = ascii.read(\"Sample_cat.dat\", header_start=0, data_start=1)\n", "myquery = alminer.target(mylist['Name'])" ] }, { "cell_type": "markdown", "id": "dc7aea14", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.1.3: include proprietary data" ] }, { "cell_type": "code", "execution_count": 4, "id": "a73792a2", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.target results \n", "================================\n", "Target = AB_Aur\n", "--------------------------------\n", "Number of projects = 6\n", "Number of observations = 10\n", "Number of unique subbands = 56\n", "Total number of subbands = 62\n", "3 target(s) with ALMA data = ['AB_Aur', 'AB_Auriga', 'ab_aurigae']\n", "--------------------------------\n", "Target = AK_Sco\n", "--------------------------------\n", "Number of projects = 4\n", "Number of observations = 4\n", "Number of unique subbands = 16\n", "Total number of subbands = 16\n", "2 target(s) with ALMA data = ['AK_Sco', 'HIP_82747']\n", "--------------------------------\n", "Target = AS_310\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n", "Target = AS_470\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n", "Target = AS_477\n", "--------------------------------\n", "No observations found.\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.target(mylist['Name'], public=None)" ] }, { "cell_type": "markdown", "id": "77c36fd8", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.1.4: account for mosaics\n", "\n", "The [alminer.target](../pages/api.rst#alminer.target) function will by default search whether any ALMA observations contain the target of interest's position. To search whether any ALMA observations overlap with a larger region of interest, one can set the argument *point=False* and provide a search radius in arcminutes using the *search_radius* argument. The search radius is by default 1.0 arcminute." ] }, { "cell_type": "code", "execution_count": 5, "id": "cf704c2d", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.target results \n", "================================\n", "Target = Orion KL\n", "--------------------------------\n", "Number of projects = 37\n", "Number of observations = 125\n", "Number of unique subbands = 312\n", "Total number of subbands = 576\n", "57 target(s) with ALMA data = ['OrionKL', 'Orion H2O maser outburst', 'OrionField1-1', 'OrionField2', 'OrionField1-2', 'f1', 'f7', 'f5', 'f8', 'f4', 'f3', 'orion_kl', 'Orion_Source_I', 'BN', 'f13', 'f11', 'f12', 'f10', 'f9', 'f15', 'f14', 'orion-IRc2', 'Orion_KL', 'OMC1_SE', 'BN-KL', 'OMC1_NW', 'f23', 'f16', 'OMC-1S', 'OrionKL-SV', 'OMC-1', 'OrionBullets', 'ONC', 'Orion_BNKL_source_I', 'OMC-1_Region5', 'OMC-1_Region1', 'Orion', 'OMC-1_Region2', 'HC602_HC606_HC608', 'GEMS28', 'HC672', 'ONC_Mosaic', 'OMC-1_Region3', 'OMC-1_Region4', 'Orion_KL_Field_1_Orion_Hot_Core', 'Orion_KL_Field_2_SMA1', 'Orion_KL_Field_3_North-west_Clump', 'Orion KL', 'Orion1', '101', '32', '104', '107', '71', 'Orion-KL', 'ORS-8', 'ORS-4']\n", "--------------------------------\n", "Target = AB Aur\n", "--------------------------------\n", "Number of projects = 3\n", "Number of observations = 3\n", "Number of unique subbands = 17\n", "Total number of subbands = 17\n", "3 target(s) with ALMA data = ['ab_aurigae', 'AB_Aur', 'AB_Auriga']\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.target(['Orion KL', \"AB Aur\"], point=False, search_radius=2.0)" ] }, { "cell_type": "markdown", "id": "06b514fe", "metadata": { "deletable": false, "editable": false }, "source": [ "## 1.2 Query by position\n", "\n", "The [alminer.conesearch](../pages/api.rst#alminer.conesearch) and [alminer.catalog](../pages/api.rst#alminer.catalog) functions can be used to directly query the ALMA archive by positions in the sky and a search radius around them. The right ascension and declinations must be given in units of degrees (ICRS). You can use the [Astropy coordinates package](https://docs.astropy.org/en/stable/coordinates/index.html) to convert your desired coordinates to degrees." ] }, { "cell_type": "markdown", "id": "de9df24d", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.2.1: query an object by its coordinates (RA, Dec)" ] }, { "cell_type": "code", "execution_count": 6, "id": "e365b54b", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "--------------------------------\n", "Number of projects = 24\n", "Number of observations = 77\n", "Number of unique subbands = 192\n", "Total number of subbands = 312\n", "9 target(s) with ALMA data = ['J1325-430', 'Centaurus_A', 'J1325-4301', 'CenA', 'Centaurus_a', '3FGL_J1325.4-4301', 'Centaurus A', 'NGC_5128', 'Cen_A']\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.conesearch(ra=201.365063, dec=-43.019112, point=False, search_radius=10.0)" ] }, { "cell_type": "markdown", "id": "8289ac60", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.2.2: query a catalog of objects by their coordinates (RA, Dec)\n", "\n", "Let's first import a catalog, for example the catalog of Spitzer YSOs in Orion from Megeath et al. (2009), and create a PANDAS DataFrame using rows 866 to 869 of this catalog. Then use the [alminer.catalog](../pages/api.rst#alminer.catalog) function to query the ALMA archive for each target in the DataFrame." ] }, { "cell_type": "code", "execution_count": 7, "id": "ae11e33b", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.catalog results\n", "================================\n", "Target = 866\n", "--------------------------------\n", "Number of projects = 1\n", "Number of observations = 1\n", "Number of unique subbands = 4\n", "Total number of subbands = 4\n", "1 target(s) with ALMA data = ['M12_866']\n", "--------------------------------\n", "Target = 867\n", "--------------------------------\n", "Number of projects = 1\n", "Number of observations = 1\n", "Number of unique subbands = 4\n", "Total number of subbands = 4\n", "1 target(s) with ALMA data = ['M12_867']\n", "--------------------------------\n", "Target = 868\n", "--------------------------------\n", "Number of projects = 2\n", "Number of observations = 2\n", "Number of unique subbands = 8\n", "Total number of subbands = 8\n", "1 target(s) with ALMA data = ['HOPS-172']\n", "--------------------------------\n" ] } ], "source": [ "Spitzer = ascii.read(\"Spitzer_sample.dat\", header_start=0, data_start=866, data_end=869)\n", "\n", "mycat = {\"Name\": Spitzer[\"Seq\"], \n", " \"RAJ2000\" : Spitzer[\"RA2000\"], \n", " \"DEJ2000\" : Spitzer[\"DEC2000\"]}\n", "\n", "mycat = pandas.DataFrame(mycat)\n", "\n", "myquery = alminer.catalog(mycat)" ] }, { "cell_type": "markdown", "id": "7fee6bc0", "metadata": { "deletable": false, "editable": false }, "source": [ "## 1.3 Query by ALMA keywords\n", "\n", "Query the ALMA archive for any [(string-type) keywords defined in ALMA TAP system](../pages/query_keywords.rst) using the [alminer.keysearch](../pages/api.rst#alminer.keysearch) function.\n", "\n", "The power of this function is in combining keywords. When multiple keywords are provided, they are queried using 'AND' logic, but when multiple values are provided for a given keyword, they are queried using 'OR' logic. If a given value contains spaces, its constituents are queried using 'AND' logic. Words encapsulated in quotation marks (either ' or \") are queried as phrases. For example,\n", "\n", " * `alminer.keysearch({\"proposal_abstract\": [\"high-mass star formation outflow disk\"]})`\n", "will query the archive for projects with the words \"high-mass\" AND \"star\" AND \"formation\" AND \"outflow\" AND \"disk\" in their proposal abstracts.\n", "
\n", "\n", " * `alminer.keysearch({\"proposal_abstract\": [\"high-mass\", \"star\", \"formation\", \"outflow\", \"disk\"]})`\n", "will query the archive for projects with the words \"high-mass\" OR \"star\" OR \"formation\" OR \"outflow\" OR \"disk\" in their proposal abstracts.\n", "
\n", "\n", " * `alminer.keysearch({\"proposal_abstract\": [\"'high-mass star formation' outflow disk\"]})`\n", " will query the archive for projects with the phrase \"high-mass star formation\" AND the words \"outflow\" AND \"disk\" in their proposal abstracts.\n", "
\n", "\n", " * `alminer.keysearch({\"proposal_abstract\": [\"star formation\"], \"scientific_category\":['Galaxy evolution']})`\n", "will query the archive for projects with the words \"star\" AND \"formation\" in their proposal abstracts AND projects that are within the scientific_category of 'Galaxy evolution'.\n", "\n", "\n", "
\n", "\n", "Note\n", "\n", "* Tables of ALMA [scientific categories](../pages/scientific_categories.rst) and [science keywords](../pages/science_keywords.rst) are provided on the sidebar. \n", "\n", "* For an overview, see [Appendix D of the ALMA Proposer’s\n", "Guide](https://almascience.eso.org/proposing/proposers-guide#section-63).\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "9bb7032a", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.3.1: query a list of ALMA target names that may not be in SIMBAD/NED/VizieR" ] }, { "cell_type": "code", "execution_count": 8, "id": "6eedc818", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.keysearch results \n", "================================\n", "--------------------------------\n", "Number of projects = 17\n", "Number of observations = 31\n", "Number of unique subbands = 121\n", "Total number of subbands = 191\n", "12 target(s) with ALMA data = ['GRB021004', 'G345.5', 'SPT0319-47', 'G345.5043+00.3480', 'G345.49+1.47', 'G345.50+0.35', 'G345.6487+0.0089', 'G345.01', 'G345.11', 'G345.0029-0.2241', 'G345.5+1.5', 'G345.144-00.216']\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.keysearch({'target_name': ['GRB021004','SPT0319-47', 'G345']})" ] }, { "cell_type": "markdown", "id": "f1fd0cdc", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.3.2: query a list of ALMA projects by their proposal IDs" ] }, { "cell_type": "code", "execution_count": 9, "id": "cc6fd2c9", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.keysearch results \n", "================================\n", "--------------------------------\n", "Number of projects = 2\n", "Number of observations = 16\n", "Number of unique subbands = 16\n", "Total number of subbands = 64\n", "16 target(s) with ALMA data = ['KMOS3DCOS4-24763', 'KMOS3DGS4-25151', 'KMOS3DCOS4-13701', 'KMOS3DCOS4-10347', 'KMOS3DCOS4-13174', 'KMOS3DCOS4-19680', 'KMOS3DCOS4-15813', 'KMOS3DCOS4-15820', 'KMOS3DU4-34138', 'KMOS3DU4-22227', 'KMOS3DU4-32147', 'KMOS3DU4-20547', 'KMOS3DGS4-11016', 'KMOS3DGS4-24110', 'KMOS3DGS4-27882', 'AK_Sco']\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.keysearch({'proposal_id': ['2015.1.00664.S', '2016.1.00204.S']})" ] }, { "cell_type": "markdown", "id": "1ec42450", "metadata": { "deletable": false }, "source": [ "### Example 1.3.3: query by words in the proposal abstract\n", "\n", "Query the ALMA archive for proposals that have the phrase 'high-mass star formation' AND the words 'outflow' AND 'disk', OR the phrase 'massive star formation' AND the words 'outflow' AND 'disk' - and do not print the long list of target names in the summary." ] }, { "cell_type": "code", "execution_count": 10, "id": "e8eb11ee", "metadata": { "deletable": false, "editable": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.keysearch results \n", "================================\n", "--------------------------------\n", "Number of projects = 14\n", "Number of observations = 59\n", "Number of unique subbands = 206\n", "Total number of subbands = 423\n", "Total number of targets with ALMA data = 29\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.keysearch({'proposal_abstract': ['\"high-mass star formation\" outflow disk', \n", " '\"massive star formation\" outflow disk']}, \n", " print_targets=False)" ] }, { "cell_type": "markdown", "id": "c62e26fc", "metadata": { "deletable": false }, "source": [ "### Example 1.3.4: query by combination of keywords\n", "\n", "Query the ALMA archive for proposals that have the phrase 'star formation' in their abstracts and correspond to the scientific category of 'Galaxy evolution'." ] }, { "cell_type": "code", "execution_count": 11, "id": "f99bb866", "metadata": { "deletable": false, "editable": false, "scrolled": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.keysearch results \n", "================================\n", "--------------------------------\n", "Number of projects = 245\n", "Number of observations = 2839\n", "Number of unique subbands = 3908\n", "Total number of subbands = 11687\n", "Total number of targets with ALMA data = 1763\n", "--------------------------------\n" ] } ], "source": [ "myquery = alminer.keysearch({'proposal_abstract': ['\"star formation\"'], \n", " 'scientific_category':['Galaxy evolution']}, print_targets=False)" ] }, { "cell_type": "markdown", "id": "54a93153", "metadata": { "deletable": false, "editable": false }, "source": [ "### Example 1.3.5: query for full polarization data" ] }, { "cell_type": "code", "execution_count": null, "id": "52e92df9", "metadata": { "deletable": false, "editable": false, "scrolled": true }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "================================\n", "alminer.keysearch results \n", "================================\n" ] } ], "source": [ "myquery = alminer.keysearch({'science_keyword':['\"disks around low-mass stars\"'], \n", " 'pol_states':['XY', 'YX']}, print_targets=False)" ] } ], "metadata": { "celltoolbar": "Edit Metadata", "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.9" }, "nbsphinx": { "execute": "never" } }, "nbformat": 4, "nbformat_minor": 5 }