 |
 |
|
|
|
 |
MAST's goal is to make searches and data discovery as convenient as possible for users. In CasJobs/Kepler this means to expand the functionality and holdings visible from the Enhanced Target Search page. Using CasJobs entails scripting in the SQL language. For those not familiar with SQL, we make available Sample queries on the Query page that we'll show you presently. You can expand a Sample to match the needs of your own special request or come to us by email to help you with it. Here are circumstances for which you would need CasJobs and not be able to carry out your work on the Target Search form alone:
The Kepler Colors tables provides access to colors and stars not given in the KIC. It has been made possible by teams of astronomers who have obtained telescope ground-based observations of the Kepler field. See the MAST Acknowledgments page for credits.
The Enhanced Target Search form was inaugurated with the addition of the UKIRT J-magnitude and GALEX satellite datasets (consisting of NUV and FUV surveys of the sky). During 2012 and beyond MAST expects to add at least three different ground-based surveys of all or part of the Kepler observed sky area. MAST will develop CasJobs in parallel with new additions to the Enhanced form.
The Kepler Colors table, is named keplerObjectSearchWithColors it is an amalgam of several catalogs - the most obvious one is the KIC. To find it once you are logged in to Casjobs, click on the DB tab in the upper menu and click on the "Kepler" tables context tab. "keplerObjectSearchWithColors" in the upper right of the myDB Casjobs page. (Below we may use DB an myDB interchangeably.) The tables will appear in the long list to the left. (As noted in Section 2, the two tables used for the Kepler-GALEX crossmatch are also found in this list.) The GALEX entries are those updated from the Kepler-GALEX Xmatch GoldStandard table, updated for the GALEX General Release 7 (GR7). Other catalogs consulted are the 2MASS (point and extended), the UKIRT Catalog of J magnitudes observed and supplied by Dr. Phil Lucas, the UBV catalog published by Everett et al. (2012), and the Kepler Isaac Newton Telescope Survey (KIS) published by Greiss et al. (2012). The UKIRT catalog lists J-band magnitudes fainter than the 2MASS catalogs - it is complete down to about J_IRT = 18, and as such lists by far more than any objects in ground-based surveys of the Kepler field. It includes many objects not in the KIC. Because Dr. Lucas recommended against including objects fainter than J_IRT = 20.0, MAST has excluded these faint objects in its tables that draw from the original Lucas catalog. Again on Dr. Lucas' recommendation, the MAST tables do not include objects brighter than J_IRT = 10.0 either because of detector saturation. Even fainter objects cannot matched to any of MAST mission catalogs. The IRT goes the faintest of any than J = 20.0 because beyond this limit detections are unreliable. of our matched catalogs to date. Thus other than for bright objects it is the most comprehensive. On the other hand, for the faint objects it alone records there is no other information useable for identification of the objects other than the IRT ID number provided by the Lucas catalog and the IRT determined coordinates. Still, among all the catalogs it provides the most useful indicator (jClass_IRT) of whether an object is point-like or extended - at least in the IR. The keplerObjectSearchWithColors table contains some 10.4 million objects if one includes the UKIRT catalog of J magnitudes constructed by Dr. Phil Lucas.
Other information of possible interest is the search radius used for these between the KIC positions and those of other catalogs:
| GALEX: | 2.5″ | UBV: | 1.5″ |
| KIS: | 1.0″ | 2MASS: | 1.0″ |
| UKIRT: | 1.0″ | SDSS: | 1.0″ |
Again, some vocabulary: let's define the knobs needed to navigate the CasJobs site, both to stage a query and download results to your machine. The topmost panel of links is referred to as the (top) gutter. Appearing below the gutter are a horizontal row of buttons on certain pages such as the Query or MyDB page. On the left these are called Recent, Clear, and on the right Syntax, Plan, Quick, and Submit. Clicking on buttons in the button or gutter row takes the user to a new CasJobs page or to an extension of the current page - or initiates an action such as a query (request) to CasJobs. Dropdown menus allow the user to select of several possible choices. Examples are provided by the Sample button. The Context drop down menu gives a list of tables that are available in the system or your own user-created database. Also, open boxes permit the user to enter text such as the Table or Task Name box and, in the large box, the SQL query itself.
During the execution of these steps it is crucial to keep track of which table you are using: consulting the kepler crossmatch table, e.g. KGMatch, or your own mydb.myTable. This is done from the Context menu. Get used to flipping back and forth between these two context options. The most typical mistake running CasJobs queries is failing to reset the Context selection.
(b) Select Query in the top gutter (see previous para for vocabulary).
(c) Select preferred item in Samples menu (see previous para for vocabulary).
The easiest way to do this is to mouse over the descriptions of the various
samples. Then select your favorite one. For example, Sample Query #1, which
returns results only on KIC objects in the Kepler field, should read:
Digression: Are our targets on or off the detector CCDs? The query from
the specified table can include objects from the KIC catalog that are not
on the CCDs unless you have specified otherwise. Objects from other catalogs
(UKIRT, UBV, KIS) are guaranteed to lie at least 4 pixels from the physical edge
of the detector for at least 1 season. If you want objects that are safely
within the perimeters of the CCD detectors be sure to append to the sample
query the condition "where kct_num_seasons > N", where N = 0, 1, 2, 3.
Also notice the "kct_distance_N". We point out carefully that this kct
(Kepler Characteristics Table) parameter comes from the project and is
distance in CCD pixels to the closest CCD edge, as measured from the
pixel of the project's extraction area nearest that edge. These are
the same quantities given from searches on the Kepler Target Search form.
However, the so-called "kct_distance" of an object found in another catalog is
not determined by the project. Rather it is
(d) Take a quick peek at the results of this query.
Click on the Quick button to the right. Within a few seconds you should get
a message in green: "Query complete!" If a red one appears, make sure
you've really set the context to kepler or check the SQL syntax.
At this stage you shouldn't have tampered with this syntax, so errors in
syntax are not likely to be the problem.
(e) Now add a SQL phrase specifying a new table that you will be creating
in your own myDB area. Type into the query e.g. "into
mydb.myTable_listout" before the "from keplerObjectSearchWithColors"
segment of the query. You may enter the same name into the "Table optional"
box above the query box for clarity to yourself, but this is optional.
When your query is successfully completed, a new table named "myTable_listout"
(in this example) will appear in the table "Name" list under the DB context.
(f) Rerun the query by clicking on Submit.
This action will take you to a "'My Query' Details" page with a tab in the
upper right that is initially marked "Ready" in yellow. These crossmatch
queries run over a small database, so within several seconds this tab
will convert to blue (Finished) or red (Failed). You can also
see the status of a running query by clicking on History in the top gutter.
This query status gives you a sometimes helpful error message (as it also
does on the "'My Query Details" page).
Generally this is the quickest way of discovering if a job run under
Submit has been executed successfully. Please examine the returned column
names. In most or all cases, these names are those used elsewhere on
MAST pages. If you have questions about their meanings, contact us
as usual at archive@stsci.edu .
(a) Go to your newly created myTable.
This is done by clicking myDB in the top gutter, selecting MyDB in the
menu download. If you decide you want to delete this table for some
reason click on the check box in front of your listed table and click
on the "All Selected..." tab. This will allow you to make the deletion.
(b) Select your myTable for download. Click on the link to
your table. This will take you to a "myTable_listout" page, where
you can click on Download in the row of tabs under the page title.
c) On the new page select your table download format.
Users typically download CSV as format so they can play with their
table in Excel or convert it to ascii on their own machines.
d) Download the table.
This is a two-step process. First, click on the Go button. Since the
table may or may not be converted instantaneously, so repeat the
process after several seconds. So, second, mark it
for download either by refreshing the browser page or by clicking
on Output in the gutter. Either action will cause a new row to
appear under the Available Output listing. Click on the yellow
Download link after the current timestamp and download the CSV
table in the manner that your computer/browser lets you do (e.g.,
by clicking on the right mouse button to "Download Linked file").
When you download your table, fields from the keplerObjectSearchWithColors
table will be listed. CasJobs does not allow you to add fields beyond
these shown in the listed tables. The definitions of these
fields and their ranges can be found on the results help pages
located within the individual MAST/mission sites.
Suppose you want to find all the fields, including the color g-i
from the KIC for stars with magnitudes g =12-12.5 and, according to
the UKIRT catalog the infrared magnitude J shows no flaws, blends, etc.
The first condition is met by forming the KIC (Sloan) color g-i
from the magnitudes g and i in the SQL query and selecting
only those targets for which jppErrBits_IRT = 0.
Now here is our Sample Query #2:
In this case we have formed a new column named "iminusz" for the
difference of two KIC magnitudes, i - z, for this color.
Again, this example returns only KIC entries the Kepler field since only KIC
objects have observed ("non-null") i and z magnitudes.
Purely to get fancy in this example, we also stipulate that we will avoid
objects that are blends, and we do this by making use of the UKIRT catalog's
jppErrBits_IRT = 0 condition to insure we have no nearby image blends, at
least in the J band region of the IR spectrum. Likewise, we specify that
the UKIRT project considered the found targets to be stars. We have included
all the fields in the keplerObjectSearchWithColors and added the new one,
i_minus_z. We note parenthetically that column names cannot be defined
containing arithmetic symbols (i.e. this column can't be renamed "i-z").
Notes:
In the previous paragraph we slipped in the concept of a MAST universal
identifier (ktswcKey, and
herewith, MasterRA and MasterDec). These are object identifications and
coordinates that are immutable - until keplerObjectSearchWithColors is updated
- and serve the function of assigning groups of objects coordinates assigned
to coordinates found from surveys that MAST has given the highest precedence
according to an arbitrary ordering scheme. MAST's order of precedence
is: KIC, UKIRT, UBV, KIS, and GALEX. This is simply MAST's way of assigning
a set of standard coordinates to a particular object. In later additions
such as for Sloan and PanStarrs will appear within this scheme. The KIC
survey will always be first in the precedence chain, and GALEX the last.
We also note that ktswcKey in CasJobs is called "Table Key" in the
MAST/Kepler Target Search form.
The user is free to extend and download these results.
Note that the k_kis magnitude need not be specified as "not null"
because this condition is already covered by "not null" for
the rha_kis index.
Step 1B: Downloading the table created from your dry run
Step 2: Run the modified query you tailor, or a
more detailed query (to be called Sample Query #2)
We recommend that you order your output by adding a phrase
like order by kepler_kic_id or "ktswckey" to be sure that
you specified an ordered list.
This will save you a lot of heartache in the end. If you omit an order
specification, SQL will retrieve rows in its own random order.
Sample Query #3, Run a query to get color dependent errors between
KIC and KIS:
There is a color dependence on the magnitudes (and associated)
colors between KIC and KIS (part of this is because they are based on
different magnitude systems). Let's print out arbitrarily the first 1000
rows giving the delta_g = g - g_kis (where g is the KIC g magnitude)
with the KIC g-r magnitude, and order them by their KIC ID numbers.
We'll put the colors in the myDB area in a new table called
kickis_gr_colors. Sample Query #3 reads:
select top 1000 kic_kepler_id,id_kis,g,gr,gr_kis,(g-g_kis) as delta_g
into kickis_gr_colors
from keplerObjectSearchWithColors
where gr is not null and g_kis is not null
order by kic_kepler_id
Sample Query #4, Find Planetary Nebula (PN) by KIS Hα color cuts:
KIC and KIS:
Viitronen et al. (2009, A&A, 504, 291) has found a zone in the
(r-i)_kis vs. rHα color plane (where rHα is the Hα index
formed between the r and Hα KIS magnitudes; see eqn. a in this
paper). The "PN zone" in the (r-i)_kis vs. rHα 2-color diagram
is given as rHα > 0.25∗(r-i)_kis + 1.9 in magnitudes.
Sample Query #4 requests a list of object satisfying this
condition with r_kis magnitudes between 12 and 14. (Make sure you
run it as "Submit" and not "Quick", as it will time out in 60 seconds,
and make sure your Context is set to kepler). Sample Query #4 reads:
select id_kis,r_kis,rha_kis,r_kis - i_kis as ri_kis
from keplerObjectSearchWithColors
where r_kis between 12 and 14
and rha_kis is not null and i_kis is not null
and rha_kis > 0.25*(r_kis-i_kis) + 1.9
order by id_kis
Queries #5 and 6, Run queries on previously uploaded
target lists:
Suppose you want to run a simple query on a list of KIC object identifiers.
Our Sample Query #5 enables this capability. The query assumes a single
column list of KIC identifier values. Note that the first line of the input
list should give a column title; in our example we refer to your
arbitrary (single word) name as "kic_kepler_id". Note that one can run target
list uploads on the MAST/Kepler Target Search form as well,
but the list returned through the CasJobs tool is more flexible.
Open by clicking the Import menu tab in CasJobs and follow instructions. Here you will need to set the format as Comma/Space/Tab Separate and type the same root name of the file in the open box that you're uploading to your CasJobs myDB area. Also set the "Import into..." menu table to "New Table". Finally, click the "Choose file" button and select the file from your computer desktop. Clicking on Import will upload the file to the myDB list of tables. If you make a mistake the file or which to recreate it for any reason, you can go to your DB via the "myDB" tab, drop the first creation, and restart a new upload.
Sample #5: Do a SQL join of your imported table with the Kepler
Colors Table
Here, arbitrarily we will ask for KIS and UBV magnitudes for a list of
KIC objects that we just uploaded and output them to your DB area again
under the name mykic_list. We'll also request the KIC coordinates,
kic_ra and kic_dec, and each of the UBV and KIS magnitudes that now
reside in the kepler database table keplerObjectSearchWithColors, and
we'll order them by KIC number. We well execute a SQL "inner join" to draw
parameters from both your DB table and the Colors Table, and we'll give the
two context names "m" and "k" (arbitrarily, for mydb and kepler) as aliases.
The output will go into your DB area as a file you name "mykic_list_out".
Reset the Context to MyDB. Sample Query #5 then looks like this:
select k.kic_kepler_id,k.kic_ra,k.kic_dec,k.u_ubv,
k.b_ubv,k.v_ubv,k.u_kis,k.g_kis,k.r_kis,k.i_kis
from kepler.keplerObjectSearchWithColors as k
into mydb.mykic_list_out
inner join mykic_list as m on k.kic_kepler_id = m.kic_kepler_id
order by k.kic_kepler_id
If the query is short we recommend running the query first under "Quick" and excluding the "into" line. Once ready, add this line and run under "Submit". In this example we have elected to include only certain rows by naming them explicitly, and preceded by the alias prefix "k." (note the dot).
Sample Query #6: Do a search with the "Neighbors" tool on objects
on your imported table against the Colors Table. Then join all the results
from this table to the common objects in the Colors Table and save a final
table containing all the columns for these objects from both tables.
:
The idea here is to add the Neighbors tool in CasJobs to your query. In our example we start by uploading a file (we've just discussed how to do this) with only arbitrary ra's and dec's, which we'll assume to be on the Kepler field. The ra's and dec's won't necessarily match nearby KIC targets (they're arbitrary). Furthermore, you can if you wish add other fields to your uploaded list, but in our example we won't use them. But Neighbors requires that the input table contain two fields named stictly "ra" and "dec" (lowercase). We provide an example of a working upload file of coordinates HERE. The query will run by using the Colors Table and a previously imported file now called sampleUpLoadList in your DB area.
Create a "neighbors" file:
Next we create a neighbors file that will include any objects in
the Colors Table (keplerObjectSearchWithColors). One you upload the
file to your DB area, click on the file, the context to kepler
(this will join your table with keplerObjectSearchWithColors behind the
scenes), and the "find neighbors within" box to some convenient value,
like 0.04'. Next, name the output table; in this example we'll choose
the name "sampleUploadList_Neighbors".
Finally, click on the Go button.
If the run is successful, the new Neighbors table will be listed in
your list of myDB tables.
What are the contents of this table? It contains 4 columns. Columns 1 and 2
are your input "ra" and "dec". Column 3 is "search_ID" (a running index
corresponding to the rows in your sampleUploadList file), and
Column 4 is "matched_ID". The matched_ID is synonymous with our
universal MAST identifier, ktswcKey, defined above.
In general the results will fall into one of three cases: (1) a single match
to an object in the Colors Table,
(2) more than one match, and (3) no matches. In our example sampleUpLoadList
file we provide, the first row exemplifies case (1) and
rows 2-3 case (2). No entry -- case (3) --
is given for search_id = 9 because that object's coordinates,
(298.165, 44.824, are not within 0.04' of any objects in the Colors Table.
Finally, we will run the Sample Query #6 as the "inner join" of all columns from
both the Colors Table and the sampleUpLoadList_Neighbors table in
the the myDB area. So the Context should be set to kepler and
the reference to context myDB should refer to *Neighbors file with the
prefix "mydb". Ultimately, Sample Query #6 becomes:
select m.matched_id as mytargetid, m.ra as myra, m.dec as mydec,
m.search_id as mySearch_id, m.matched_id, k.*
into mydb.sample_FinalWithNeighbors
from mydb.sampleUploadList_Neighbors as m
inner join keplerObjectSearchWithColors as k
on m.matched_id=k.ktswckey
The results are the DB table list under the name sample_FinalWithNeighbors.
This table consists of all the matched rows
from the run through the Neighbors tool and all columns from both the
Colors Table and sampleUploadList_Neighbors table.
All surveys have accidental "detections" known as artifacts and take steps to identify against them. The best defense is to find detections in more than one filter of a survey, or better, to find them among different surveys. (Any source found only in one band of GALEX should probably not be trusted.) Here are some steps taken by add-on optical and IR surveys to mitigate against artifacts.
Object Morphology: star/extended classifications:
Most projects have made some attempt to compute star/galaxy classifications.
One rule of thumb for the Kepler field is that objects fainter than
Kp = 18-19 are galaxies or QSOs. The KIC has a field
Star/Gal_ID (borrowed from the USNO Cat B) for this purpose. However,
because it was borrowed mainly from a variety of photographic catalogs,
its accuracy cannot always be trusted. MAST recommends that newer optical
or IR surveys as given in the following be used instead.