Atlas - A General Collection Search Service
Introduction and Instructions
Many of the datasets served by IRSA in the future will consist of collections of images, source tables, spectra, or light curves, often covering a particular region of the sky. Atlas is a single CGI program which can be used to search any such collection in a general and uniform manner and present the search results on a web page.
The user interfaces for all the data sets served through Atlas are similar. Each Atlas Data Collection Homepage has a short description of the data set, along with any documentation and links for further information. Generally an all-sky image (or local region of the sky) is presented at the top of the collection home page in black and white. Typically this all-sky image is a 12 um superposition using the IRAS Sky Survey Atlas (ISSA) "plates"/images, unless noted otherwise, with a resolution of 0.5 degrees. The color overlays on this sky image are the footprints (positions) of the areas covered by that data set collection. Image data are usually displayed as red rectangles overlaid on the sky, yellow dots indicate source lists, and red (or cyan) dots represent spectra. The coordinate system, if displayed, is usually depicted in blue.
A description of how to use Atlas (search for data within a collection) is described below. In brief, you search for data at single or mutiple positions location on the sky. For single input, the software determines which ISSA (or alternate background) at that requested position and brings up a window containing that plate/image. Within that image (again with the ISSA plate as a background) you will see overlaid icons showing where there are data products within the IRSA holding for the collection/mission you are searching. These products will appear as symbols (circles, rectangles) overlaid and these symbols will have a one-to-one correspondence to the entries to the table of products listed on that results page. For multi-object searching, using Table Upload, a summary of the results sets is presented on the results page; from there, you can click on individual results pages and/or download scripts to get the results file(s).
How to use this service:
There are three methods for retrieving data through Atlas. You may either click on the image (all-) sky map within an area shown to contain data, or enter a single coordinate (or astronomical object name) in the "Single Object" field, or enter a file name with a table of coordinates (or astronomical object names) in the "Table Upload" field.
If using the image map for searching, keep in mind that the pixel resolution of an all-sky image is 0.5 degrees; if you require a higher degree of precision you should use the coordinate search method. If entering a position (single or multi-object table upload file), the location information can take the form of coordinates in a variety of formats (see the examples at the bottom of main panel), or can be an object name. If it is the latter, first NED and then SIMBAD are checked to attempt name resolution; once the name is resolved, the celestial coordinates of that object are used for the search query.
Examples of valid input coordinates are provided for each of the Atlas data services, in a variety of coordinate systems. Each example coordinate is separated by a "|" character. Only one is necessary as input in the "Single Object" field (or in the multi-object table listing using "Table Upload"), without the "|" character. The default coordinate system is (RA DEC) Equatorial J2000, in decimal degrees (1st example below).
EXAMPLES OF INPUT
In the 2nd example above, "Local Equatorial J2000 (Equ)" is also known as "sexigesimal" (hours, minutes, seconds; degrees, minutes, seconds). The abbreviation "eq" and "Equ" stands for equinox of the coordinate system; typically equinox is "J2000" (which is the default when the user does not enter the equinox) and of course could also be "B1950", etc.
Multi-Object searching can be performed by selecting the "Table Upload" button and then entering the name of a table on your local file system which contains a list of coordinates or astronomical object names.
Most of IRSA's services allow users to enter single objects or coordinates into a web form, or they can upload a file containing multiple objects and coordinates. The latter method is called "Table Upload," for which IRSA accepts four ASCII table formats:
- IPAC ASCII Column-Aligned (Download template)
- Comma-Separated Values (CSV) or Comma-Delimited (Download template)
- Tab-Delimited (Download template)
- A Simple List of Objects (such as astronomical source names) (Download template)
There are two ways to ensure your tables will work with IRSA's services:
- Run your tables through IRSA's Table Reformat and Validation tool to identify possible errors.
- Read and follow the Using Tables With IRSA Services help document to learn and troubleshoot table formats, including:
- Detailed descriptions of the four acceptable table formats
- A description of how sexagesimal and Galactic coordinates are handled by IRSA services
- Best practices for creating tables
- Troubleshooting solutions for common error messages
- ASCII file with simple name listing
- IPAC table format using object names
- IPAC table format with ra dec positions as well as source names
- IPAC table format with mixture of coord types
- tab-delimited table of positions as well as source names
- comma-delimited table of positions as well as source names
Search Size Constraints
For Atlas data collections which include images, the "Size" search field is adjustable. It is given in degrees; the permitted maximum search size is listed, and is typically 12.5 degrees; Table 1 below lists all the maximum search-sizes for all Atlas collections, in the third column. [The current upper limits is due to the fact that the results are displayed as overlays on background 'sky' images; these background images have a fixed size, the largest being 12.5 square degrees, corresponding to one ISSA "plate".] If you specify a box "Size" larger than the allowed maximum, the results will only have the data which fall within the maximum allowed search size. Background images are discussed in more detail below.
The checkbox "Images must cover coordinate" allows the user to choose to search for only those images whose footprint on the sky covers the exact input coordinate. If unchecked, all images which overlap the given search area, as determined by location and box size, will be returned. When checked, the results will show only those data whose footprints overlap the specified input search coordinate.
For Atlas data services which have catalogue or spectral information, the "Source Search Radius" field is provided and can be adjusted for searching. This is a cone search, using a radius where the units can be adjusted using a drop-down menu. The maximum allowed search radius is listed for each collectiontion and is typically 6.25 degrees.
Next to the "Source Seach Radius" field is the checkbox "Search whole region". When checked, the search for catalogue and spectral information is done using the "Size" box search (or 12.5 degrees when "Size" is not on available); note that the "Source Seach Radius" value is ignored in this case. When the checkbox is not checked, then the "Source Seach Radius" value is used for the radius of the cone search.
If searching by location rather than clicking on the sky map, hit the "Submit" button to submit the request.
Multi-Object Search Results
When performing a Multi-Object search, using Table Upload, the search results are returned in a summary table. The table shows the positions of each requested source (ra and dec in decimal degrees); the number of images (N_images), catalog sources (N_srcs) and spectra (N_spectra) results returned for that location; a link to the HTML search results page (Result_Link) for each source; the Data Tag associated with the results (for publication); links to data download scripts (Download_Script) for each results set (includes images, catalogs, spectra). The Status column will indicate "ERROR" if a problem was found while searching for data for that source, else "OK" is returned. Note, an empty set of results (no images, catalogs, or spectra found) is a valid result, and therefore "OK" is returned when the search did not find an error.
A Download a script with ALL the results for all sources is also available; this is a contatination of the download scripts listed below per source, as one master script. Download scripts use unix GNU tool 'wget' for bulk downloads. [WGET HELP]
Clicking a Result_Link brings up a single object search results page; this page is identical to the result if a "Single Object" was used in the search form for that same position. Please see the section below on Single Object Search Results for information on individual source search results.
For reference, the user's table is available. Note, IRSA adds ra and dec coordinates for each source in decimal degrees, if these columns are not provided. The table is also reformatted to IPAC Table Format, if it is not already uploaded as such. The order of the user table sources and the results table summary are the same; the "cnt" (counter) column is the row number of the input user table.
Single Object Search Results
If no data are found for the selected area, a "NOTIFICATION" page is returned stating that the collection does not have data within the input search parameters. Hit the 'Back' button on your browser to return to the search page and try again with different search criteria. If you see a 'NOTIFICATION' after doing a coordinate search, it is likely that there are no datasets from this Atlas collection for your data-point, or your search Size and/or Radius is too small to have found the object. Broaden the search by increasing the Size of the search box and/or radius, or by de-selecting the "Images must cover coordinate" checkbox.
On the results page, data which matched the search criteria will be listed in tabular form as well as rendered on a background of the area you have selected. The selected coordinate will be displayed as the green crosshairs; images found are depicted as red rectangles, source tables and spectra are small yellow and red (or cyan) circles/squares, and the coordinate system is in blue. All the data points displayed are listed in the tables of the output page. Any source/spectral tables found are listed first, followed by images. There is a one-to-one correspondence to the entries in the results tables and the footprints on the sky image (note that multiple overlays for the exact same position will look as one overlay). You can download any of the images listed, retrieve spectra when they are available, or display that image, table, etc by sending it to OASIS, using the OASIS applet viewer.
Images can be saved to disk if you click on the To disk link under the "download" column. Save the background image displayed in the results overlay by clicking on "Background Image: Download" link. The metadata associated with the results is also available for viewing or downloading. Clicking on "Image Metadata: Download" will retrieve an ascii IPAC-format image metadata table, which can be saved from the browser. Each set of results (image, catalog, spectra, metadata and background data) is explained in more detail below.
Table 1 below lists the source of the background images and their characteristics. Most of the background data come from either the IRSA ISSA or 2MASS image collections. The ISSA images are 12.5 square degrees, which are a good size to use as background images since they are quite large. 2MASS images have been created using the j-band 2MASS data, with the Montage mosaic engine, and should be used for visualization only.
For most of the Atlas data collections the results are displayed on a background which is the same size as the requested search size. This allows the user to view the entire requested search area, with the data results overlayed. However, for some Atlas collections visualization of the search results is made clearer by having a larger background size compared to the requested search size. For these data collections, Atlas has a set "background scaling factor" to display the results; the background size is equal to the search size times the background factor. The scaling factors for all collections are also listed Table 1. The Atlas search results page lists the background factor in the lower right of the overlay image, near the 'Background Image' download option.
|Atlas Collection Name||Background Dataset Name||Maximum Allowed Search-Size/Background-Size (deg)||Background Scaling Factor|
|COSMOS||COSMOS Subaru mosaics (B=blue, V=green, i=red); COSMOS front page & OASIS download is SDSS 'i' band||2.0||2.0|
|COSMOS_INT||COSMOS Subaru mosaics (B=blue, V=green, i=red); COSMOS front page & OASIS download is SDSS 'i' band||2.0||2.0|
|SAGE||SAGE front page uses the MIPS 70um SAGE full mosaic; search results are 3-color SAGE MIPS mosaics (24um=blue, 70um=green, 160um=red)||7.0||1.0|
|FIDEL||FIDEL front page and search results page use the FIDEL MIPS data as backdrops: 24um MIPS images for EGS and ECDFS fields, and 70um MIPS image for the GOODS-N field.||0.6||1.5|
ISSA backgrounds have a minimum size of 0.25 degrees.
Data Tag associated with the search results are indicated on each single source results web page. Authors may include data tags returned by IRSA and other data providers in their papers through the AASTeX 5.2 "\dataset" macro.
Bulk Download of data is also available from the results pages, using a wget script. For more information on wget, click here. The script contains a list of all the images, catalogs, and/or spectra returned in the search results.
Image results are displayed as red rectagles on the background sky image; they are also individually presented in the "Listing of Image Results". The RA and DEC center position and size of the fits image axes are listed in this table, along with possible other information about the fits file, such as the band, filter, telescope, instrument, when available. You can download each fits file by clicking on the "To disk" link at each entry under the "dowload" column. You can also view that same fits file in the IRSA JAVA visualization tool by clicking on the "To OASIS" link at each row under the "download" column. A summary of all the image metadata can be found by clicking on the "Image Metadata: Download" link under the sky map of results. That same image metadata can also be viewed in OASIS if you hit the OASIS button in that same area. A description of each column in the metadata can be found by clicking on the "column key" link within the metadata section. The key can also be found at the head of the "Listing of Image Results"; or, you can click on the column names in that table listing.
Catalog results are in the "Listing of Source Table Results" section. Depending on the number of sources found in the search region, if under 3000, these source positions (RA,DEC) are marked typically as yellow symbols on the background sky map. The link is usually the name of the results table file, sometimes called sources.tbl. You have a choice of clicking on the name of the table link to get the table, or clicking on the OASIS button to send the file to the visualization tool. If you click on the source table name link, it will present the html table version of the source list file. In some source table results, that table will contain further links within the results source list, which lead you to find these data in atlernate archives (i.e., the Scrapbook). Back on the results page, if you click on the OASIS button next to the source table listing, that source table will be sent to the IRSA JAVA visualization tool OASIS. A description of each column in the catalog can be found by clicking on the "Column Key" link within the row, under the "Column key" column.Spectra metadata results, along with catalogs, are also in the "Listing of Source Table Results" section. The sky position (RA, DEC) of each spectrum is marked typically as red or cyan symbols on the background sky map. The link is usually the name of the results metadata table file. You have a choice of clicking on the name of the table link to get the spectra metadata, or clicking on the OASIS button to send the file to the visualization tool. If you click on the table name link, it will present the html table version of the file. Each spectrum/row will contain information regarding that target, as well as links to various formats of the spectrum itself. The spectral formats vary depending on what was given to IRSA by the data provider; we have spectra in the following formats within the various collections: ascii with IPAC header, ascii without IPAC header, xml, postscript, gif, png and fits. Download any of the results spectra by clicking on the link of the data format you prefer and saving it to disk. Some spectra can also be viewed by the IRSA JAVA visualization PlotApplet by clicking on "Plot" or "OASIS" links. A description of each column in the spectra metadata file can be found by clicking on the "Column Key" on the Atlas search results page, under the "Column key" column.
The results page also contains another search form, which can be used to fine-tune the original search or start a completely new search. Zoom in and out by specifying a smaller or larger search "Size"/"Radius", and then re-submitting the request.