Cross Correlation Search Help

Use the Cross Correlation Search form to search the MAST Archive by object name or position. Names or coordinates can be specified in the "target name" form element. Multiple values can be entered in a comma-separated list. List of targets or coordinates can also be uploaded from the file upload form. Search radii for each mission can be specified individually.

The first 'n' entries for each selected mission are displayed in order of target, where 'n' is specified in the "maximum rows" field on the search form (default = 10). The mission name is a link to the mission search form to allow retrieving remaining entries for that particular mission and target. You can also mark data for retrieval and display previews from the results page.

This interface can retrieve data either to the archive staging area or directly to the destination you specify, so you can retrieve proprietary data (if you're priveleged to do so). To allow you to safely enter a destination username and password, we use the same security mechanism as many commercial sites.

Local File Name
The name of a local file containing a table or list of either coordinates or targets names to be uploaded to the server and used to query the database. The file must be an ASCII text file with either one entry per line (i.e., a target name or set of coordinates), or in a table separated with one of the allowed delimiters, with targets or RA and Dec values in the designated columns. Coordinates may be in serveral formats including sexigesimal and decimal degrees.

The search script will perform a database search for each target, or set of coordinates, contained in the uploaded list. If a resolver error occurs, the search will abort and the compiled results displayed. By default, up to 10 rows will be displayed for each file entry, but this can be increased using the "Maximum records per Target" entry. If the output is requested in CSV or Excel spreadsheet format, a blank line will be used to distinguish the results of one target search from another. VOTable format incorporates separate RESOURCE tags for each database query.

Use the other form entries to specify field delimiters, RA, DEC, or Target column numbers (when the file contains a table of values), and file contents (target names or coordinates). The browse button allows users to seach local directories to locate files.

Warning: since uploading long lists can take a while to run, uploaded files are currently limited to 5,000 entries.

File Contents
Specifies whether the local file to be uploaded contains coordinates, target names, or data IDs. By default, coordinates are assumed.

RA Column Number
The column number containing either the Right Ascension target name, or data ID (depending on how file_contents is set). The default is to assume the first column contains the RA value.

Dec Column Number
The column number containing the Declnation. The default is to assume the second column contains the DEC value.

Column Delimiter
The character used to delimit table entries in the uploaded file. Allowed values include tabs( ), commas(,), vertical bar (|), or semi-colons(;). The default is to assume tabs are the delimiters.

Target Name
The name(s) or coordinates of the astronomical objects you want to search for. Multiple targets can be specified as a comma-separated list. Examples of valid names include gam Gem, NGC 1068, JUPITER, and hd 45677. Valid coordinate formats include 09 55 33.2 +69 03 55, 09 55 +69 03, or decimal degrees such as 148.9 69.062 (Note: do not use commas between RA and Dec.) Coordinate ranges and other formats can be specified in the separate RA and Dec form elements.

Warning: specifying long lists and many missions will require more processing time.

The Target Name is used in combination with the Resolver Field. If the SIMBAD or NED Resolver options are chosen, then coordinates returned from these services are used to perform the search.

You do NOT have to use the resolver. Choose the "Don't resolve" option to perform string searches on the object name in the database.

When you search on the object name in the database (i.e. without using the name resolver), case will be ignored. The object name will not be wildcarded at the front and back automatically (that's so if you innocently enter IO, you don't match things like ORION). You can however wildcard the object name using * (for example, *IO*). You can also enter a comma-separated list; for example, *JUP*,*SAT* would match object names containing either JUP or SAT.

Resolver
The name resolver you want to use, if you want to resolve an object into its coordinates. You can resolve an object name either before a search, or you can redraw the form with the resolved coordinates in place. You can also elect not to resolve the object name when doing the search, and search the database on the object name instead.

The resolver services that may be chosen are NED and SIMBAD. NED is the NASA Extragalactic Database at Caltech in Pasadena, California, and SIMBAD is the Set of Identifications, Measurements, and Bibliography for Astronomical Data at the Centre de Données astronomiques in Strasbourg, France. The object name will be sent to the chosen resolver, which will send back the coordinates. (If the object name is not recognized by the resolver, or there is some other problem with the SIMBAD or NED services, then the search form will be redrawn with an error message at the top.) These coordinates will then be used to search the database, along with whatever other query qualifications you have given.

You may also choose the "Don't resolve" option. This will allow string searches to be performed on the object.

We recommend that you use object name resolution to find observations of specific objects in the database. This is the most reliable way to look up observations, because the observer could have given any object name at all (for example, NGC1976 instead of M42, or PARALLEL-FIELD). However, if you do know the object name that the observer used, you can select Don't resolve, in which case the object name will not be resolved into coordinates, but will be used as a search qualification in the database. (This will happen only when you press the Search button.)

The SIMBAD and NED object name resolvers can resolve only fixed objects; they cannot compute the positions of moving objects (planets, comets, etc.). To find moving objects, try selecting the appropriate object class, entering an object name that could match what you're looking for, and selecting Don't resolve for the name resolver. NED is an extragalactic database, and generally won't resolve object names within the Milky Way galaxy.

To perform a search for a moving target or find entries listed under a specific target name, choose the "Do Not Resolve" option from the resolver menu and enter a target name for the search (e.g. for Jupiter you might enter "*JUP*"). Note wild cards are allowed. Moving targets could also be found using the "category" option available on most MAST search pages.

Right Ascension, Declination
The Right Ascension and Declination values in either decimal degrees or sexagesimal notation. If single values are entered, a cone search is performed using the specified search radius (default = 3 arcminutes).

You may also enter ranges of right ascension or declination, using the ".." operator. For example, you can enter 21h 51m .. 21h 52m for the right ascension, and 28 51 .. 29 51 for the declination. Comparators can also be used, i.e. ">", ">=", "<", "<=". For example, "> 85" as a declination value will return all observations with declination larger than 85 degrees. (Note when ranges of coordinates are specified the search radius will be ignored. Also, searches on ranges can be quite time consuming.)

Coordinate values may be specified using a number of formats. Examples of accepted values include: 

    Decimal Degrees
       	185.63325 29.8959861111111
 
    Hours, minutes and Seconds
        12 22 31.98      29 53 45.55
        12h22m31.98s     29d53m45.55s
        12:22:31.98     +29:53:45.55
        12h22'31.98"     29d53'45.55"
        12h 22m 31.98s   29d 53m 45.55s
        12h 22' 31.98"   29d 53' 45.55"
        12h 22' 31.98"  -29d 53' 45.55"
        12h22'31".98    -29d53'45".55
        12h22m31s.98    -29o53m45s.55
        12h 22' 31".98  -29d 53' 45".55
     
    Hours/Degrees and Minutes (no seconds)
        12 22     29 53
        12h22m   +29d53m
        12h22m    29d53m
        12:22m    29:53m
        12h22'    29d53'
        12h 22m   29d 53m
        12h 22'   29d 53'
        12h 22'  -29d 53'

    The RA may be given in decimal degrees by indicating
    a D or d after the degrees:
        12d 22m   29d 53m
Spacing is not important, as long as the value is unambiguous, and that you can delimit the hours/degrees, minutes, and (optional) seconds with letters, colons, spaces, or any character that's not a digit or a decimal point.

Radius
The radius of the search box around the RA and Dec, in floating-point arcminutes (e.g., 5.0). You should be careful about giving too restrictive a search radius since (for some missions) the coordinates of the object were given by the Guest Observer, and may not reflect the precise pointing of the instrument at the time of the observation.

The search routine computes the angular separation between each result dataset and the search center so this really is a circular radius. (Results are generally sorted on the angular separation by default.) Note a range may also be specified so, for example, to search for all observations between 2 and 8 arcminutes from the center of a galaxy, just enter 2 .. 8 for the radius.

Equinox
The equinox of the RA and Dec you have entered, either B1900, B1950 or J2000. This only applies to the input coordinates. The coordinates displayed in the search results will depend on the mission database and the selected output columns. (Note: all MAST missions include J2000 coordinates as default output columns.)

If you enter a target name and use either the SIMBAD or NED name resolver, the equinox will be set to J2000.

Missions/Instruments
Select the set of missions/HST instruments to be included in the cross correlation search. The Mark/Unmark buttons can be used to help select the various missions. For large searches, it is safer (and faster!) to unmark all the missions and search only 1 or 2. Running a large search on all missions may significantly decrease response time.

Radii
The search radius in arcminutes, specified individually for each mission/HST instrument. Defaults are given as shown on search form. Note when outputting results in VOTable format, specifying a radius of 0 will return a VOTable XML file listing the fields available for that mission.

Output Columns
This form element allows you to choose the columns to be displayed and their order, for the search results. A set of columns that are commonly requested has been chosen as a default.

You remove output columns by highlighting the column to be removed and then clicking on the remove button to the right of the output columns list.

You may determine the order of columns by highlighting a column and then clicking the up or down buttons to the right of the list of chosen output columns.

You may also add more columns to the list, either singly or all at once. To add individual columns, select the desired column from the pull down menu beneath the list of chosen output columns, then click the add button. The column will be added to the bottom of the output column list. To add all the available columns, click the "add all" button.

Note the output column form element has its own reset button to restore the list of output columns to the values initially displayed when the page was drawn. The reset button at the top of the form is used to reset the other form elements. Clicking the "clear form" button will restore the original defaults to all isections of the form.

One warning, the amount of memory required for a search is proportional to the number of columns requested. For large requests, users may want to reduce the number of output columns to the minimum required.

Suppress Null Result Message
By default, when using "file upload mode", the message "No Records Found Matching Query" (or for non-html output, "no rows found") is displayed for each entry with no search results. Clicking this button will prevent these messages from appearing which may be useful for reducing output from large search results.

Verb
Verb is an integer parameter used by the VO community for specifying the amount of output returned for a given search request. It is only available when retrieving data as a web service but works with every MAST service. Setting verb=3 in a search request is equivalent to specifying "add all" from a search form; it will return all the available columns in the output not just the standard default fields. Currently setting verb to any other value has no effect.

Sort output by:
Choose how you want the output rows sorted. You can select up to three fields to sort on. The rows will be sorted in the order of the first sort field; if two rows have the same sort field, they will be sorted in order of the second sort field, and so on. Default sort fields may be listed, but any field from the pulldown list can be used. Specifying multiple sort fields may increase executon time. If you prefer no sorting, you can specify "null" for all 3 fields. This may speed up the query, but results will be displayed in the order in which they were originally stored in the database table.

For each field, you can select that the rows be sorted in reverse order on that field by selecting the reverse checkbox. For example, you can sort the rows with the most recent observations first by selecting Observation Date for the first sort field and selecting the reverse checkbox next to it.

One word of caution: the selected sort field can change the search results when the query finds more rows than are displayed ( i.e, when the number of found rows exceeds the value of "maximum records"). For example, for a search on a particular coordinate that finds 5,000 entries, if the search is sorted on exposure time and 1,001 rows are to be displayed (the default), then the 1,001 shortest exposures from the 5,000 found entries will be displayed which may not include the entries closest to the desired position. (It is a good idea to always sort on "ang_sep" for target or coordinate searches).

Display Coordinates
Specifies the format for displaying the primary equatorial (i.e., RA and Dec) coordinates. The options include: Any other coordinate fields contained in the searched mission catalog will be displayed in their original format.

Maximum Records
This value specifies the maximum number of rows returned in a single query. For the standard mission search forms, the current default is 1,001, but values from 1 to 25,001 are allowed. For the file upload forms in which multiple targets, data ID's, or coordinates can be specified, the default is set to 20 rows per file entry, with allowed values ranging from 1 to 5,000.

Note when displayed as HTML, the latest search scripts will display 100 records per page. Links to the additional pages are shown on the results page. This paging feature however does require javascript to be turned on.

Users should be cautioned about retrieving a large number of records (i.e., > 10,000 - 15,000) in HTML format. This can cause memory problems for the browser (particulrly Safari) and prevent javascript commands from functioning. It may also cause the browser to freeze and require restarting. Using the output format options which download results in a file can reduce the problem.

Another option for large requests is to use "Casjobs". Casjobs requires requesting a user name and password, and submitting queries in SQL, but it allows users to submit large search results and save them online. For Kepler, the link ito Casjobs is http://mastweb.stsci.edu/kplrcasjobs/. For other missions, check the Search_Retrieve page in the left gutter.

When queries are submitted as a web service, the default number of rows returned is 2,000, but any value is allowed when max_rows is specified as a query parameter. (See the MAST Web services page for more information.)

Records per page
This parameter controls the number of records displayed per web page. By default, 100 rows or records are displayed per HTML page. Therefore if 400 records are returned, links to 4 pages will be displayed at the top and bottom of the results table. The paging feature however uses javascript, so if javascript is turned off, paging won't work and only the rows shown on the first page can be displayed. This is one reason why increasing the default value may be helpful. The current limit is 1000 rows per page which is recommended for large requests. Note this value is ignored when output formats other than HTML are selected.

Make Rows Distinct
Selecting this checkbox will restrict the display to only rows in which every output column value for a given row is unique. This option is primarily useful when only a small number of columns are displayed (i.e., using the "remove" button to remove default output columns) and when the selected columns have duplicate values. Including columns which already have unique values (e.g. Kepler ID or Data ID) will make the "Distinct" option ineffective.

As an example, a IUE or FUSE user might want to create a list of unique target names for a specific object class/category. He or she would specify the desired object class, select only "object Class" and "target name" for the output columns, click the "Make Rows Distinct" button, then click "Search".

Note that for some missions, columns such as RA, Dec and Magnitude were frequently defined by the observer and often have different values for the same target. If columns such as these are chosen as output columns, there will often be more than one row listed per object name.

Output Format
You may choose any of the following formats for displaying/storing search results. If you are using a browser (e.g., Firefox, etc) to submit a query from a MAST web form, the formats labelled "File: ..." offer a way to download results directly to your local computer. Choose any of the other format options if you want to display the results in the browser, or if you are submitting the request from a program (see MAST web services).

Note: If no entries are found for an entry a "no entries found" message is written in the selected format and the program continues. In all cases, error conditions will cause the database search to abort.