{
"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",
"
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",
"