Chapter 3 - StarView

3.1.1 What is StarView?

StarView is an astronomical database browser and research analysis tool. Developed in Java, it provides a user interface that runs on any Java enabled platform as a standalone application.

StarView has the ability to update itself when new versions are released. When a new version is available, the user will be asked if they wish to upgrade. For site installations, the user will be informed of potential upgrades. If the program will not run, it will exit after the warning. Please contact your administrator to have the upgrade run.

3.1.4 Site Installation

StarView can also be installed globally. The Update feature is disabled for users on a site installation. They will be asked to contact the site administrator.

To do a site installation, download the installer and run as instructed.The StarView.jar files should be not world writeable. Create a file called site_env.dat in the same directory as the StarView.jar file. The administrator can set several default preferences so the user does not need to. These are the mail server used by StarView and the path to a browser startup script (if a wrapper script is used to launch the browser) and the path to the browser binary.

A sample site_env.dat file might contain:

Subscribing to starview-update@stsci.edu, a low traffic email list, will keep you informed of upcoming StarView upgrades.  Send mail to majordomo[at]stsci.edu and please put the line "subscribe starview-update" in the body of your email message. We will only send out messages prior to upcoming releases to warn you of the upcoming update.

When you start StarView for the first time, you will be prompted to enter your SMTP server and email address in the Preferences. This screen is also an item in the Edit menu.

Using the preferences tab you can set your:

Preference Tab Table

The Archives tab allows you choose which archives StarView can use at startup. You may deselect archives that you do not need to reduce load time. Note changes do not go into effect until the program is restarted. If you re-enable an archive, you will have to restart for it to be available.

The StarView workspace has two main sections, the search area and the results area, and is similar to a web browser in layout.

Figure 5: Pull Down Menu

Across the top is the menu bar. The basic functions of the menus are as follows:

3.2.2 Search Area

Once a search form is loaded, the top half of StarView's workspace will look something like this:

You can type in the qualifiers into the fields at the right or populate them from another source using the buttons on the left. The tool bar at the top provides the tools for navigating through the search results.

3.2.3 Searches available

The Searches menu is located in the upper-left portion of your StarView workspace. Note the two dividers in the main pull-down.

Figure 9: HST Search Forms

3.2.4 Results Workspace

The result forms are displayed in the bottom half of your StarView. Multiple forms can be shown in this area. To bring a form to focus, click on its title bar within the results workspace or select it from the Window menu.

Figure 11: Search Results workspace with several forms loaded

The record count status displays the number of the record you currently have selected. If there is not a final count displayed ("95 of ...") that means there are more records to be retrieved. The default is to return the first 100 records at a time. To get the rest, simply scan until all records are retrieved.

You can sort the results by any available field by right-clicking the label and selecting Sort Data from the menu. You can also get more information on the database field by selecting the Help option. You can also retrieve this information by clicking the Info button in the Get Field column in the Qualifiers section of the interface.

Figure 14: Field Information window

On the left side of the workspace is a toolbar that contains StarView tools that you can use to work with the records returned in a search.

Figure 15: Search Results Toolbar

You can refine your search by entering qualifications into the Qualification column of the table above the search form. If you wish to get more information about a particular field, simply click on its Info button at the far right.

Qualifying Operators

There are several valid operators available in StarView.

• The mathematical operators are  < and  >
• The range operator is two periods:  0..360
• The and operator can be expressed by joining items with  & or ;
• The or operator can be expressed by separating items with  | or ,
• The not operator is !
• You can wildcard your qualifiers to search for pieces by using *  .  Please note that fields of logical type wild-text are automatically wildcarded. Filter field especially should be wildcarded, as should the targetname and target description fields, especially when searching for solar system objects.

Qualifier Data Types

All qualifiers can be entered using free-form text except for radius, RA, Dec, and datetime.  Here are the most popular database fields from the Hubble Data Archive at STScI and their expected formats.

Figure 18: Data Types

Valid Datetime Formats

In StarView there are many acceptable formats to use when qualifying on dates.  The default format is YYYY-MM-DD

In all cases, a year can be represented as two or four digits: 00 or 2000

The year, month and day are sufficient in any format to encompass the entire 24-hour period: 2001-08-17 or Aug 17 2001

If you'd like a range of days, use the range operator with your favorite format: 2001-03-23..2001-03-25.

Greater than and less than are also acceptable in each format:   >1999-02-13 or  >Feb 13, 1999

Examples:

1999-01-23 12:00:00.000 AM

01/23/1999 12:00:00.00 AM

Jan-23-1999 12:00:00.000 AM

Jan 23, 1999 12:00:00.000 AM - also acceptable without comma

23 Jan, 1999 12:00:00.000 AM - also acceptable without comma

23-Jan-1999 12:00:00.000 AM

NOT Valid:

01-23-99

Valid Coordinate Formats

Figure 19: Valid Coordinate formats

Once you have found the data you are looking for, you can mark the data you wish to retrieve using the Mark button for individual datasets, or the Mark All to retrieve all the records returned by the search.

To mark multiple datasets, click on them while holding down the Control key, and then use the Mark button.

Right-clicking the dataset name and selecting "Fetch Entry" from the menu will also select the dataset for retrieval.

Figure 20: Right-click menu on dataset name

Selecting data for retrieval brings up a retrieval window that acts as a shopping cart. in the list are will be added as "marked."

Save Datasets

You can also take the datasets in your retrieval list and save them to an external file. You can save all of them, or just the ones that are marked. These can be uploaded at another time using Add Datasets.

Purge Unmarked and Clear

Purge Unmarked will delete all unmarked datasets from the list. Clear will remove everything from the list.

Submitting a Request

Once you have finalized your list, press Submit.

3.3.2 Retrieval Options

In the Retrieval Configuration Options window, you enter your archive user name and password, destination information and file selection.

If you are retrieving public data, you can use the anonymous retrieval method. This uses anonymous as the user id and your email as the password.

You can chose to have your data delivered via ftp, sftp, placed on the staging area or, in the case of HST only, written to CD or DVD. FUSE data cannot be retrieved to hard media. You can also choose to have the data gzipped.

If you chose ftp or sftp, you will be prompted to provide the user name, user password, host name, and directory to which you want data. This information is encrypted in the submission and the password is not stored in the user preferences.

HST

The following options are available for retrieving HST science data:

Figure 25: HST Retrieval File Options

On the Fly Reprocessing (OTFR) is available for ACS, STIS, WFPC2 and NICMOS

FUSE

The following options are available for retrieving FUSE science data:

Figure 27: FUSE Retrieval File Options

Show Override Options (Expert)

Reference files can be retrieved through a couple different methods. When you are retrieving science data, the "Used" or "Best" reference file checkboxes on the retrieval options page will provide the relevant data.

You can also retrieve reference files independent of the science data with which they are associated. On the Calibration and OTFR forms, the reference files are displayed. If you right-click the file name, you will be presented with a menu where one of the options is "Fetch Entry". This will place that reference file in the Retrieval list.

Once you've reached the Retrieval Configurations screen, you will need to select the Show Override option and enter the dataset's extension. If the dataset was listed as IPPPSSOOT_XXX.FITS, the extension is the XXX portion of the name.

Suppose you want to find what observations were made by ACS or WFPC2 of M82, in the F814W filter and retrieve some to the archive staging area.

First, load a quick search.

To get the coordinates, select Coords and enter M82.
Press Resolve.

This loads the coordinates into the search fields for RA and Dec.

Figure 30: Quick Search, fields entered

Next, designate the instruments as WFPC2, ACS and the filter as F814W. Since you are searching for ACS data as well, it is important to wildcard the filter fields.

Hit Search

You can also display the results in a table:

Figure 32 Quick Search Results Table

The Proposal Abstract, Instrument Info and Calibration Info buttons will launch searches using just the datasets selected in the Search Result form or table. Use them to quickly get more information than is available on the Quick Search form.

Figure 33: Search Results with Abstract Search shown

For this search, all potential previews are images, so the button reflects this. If spectra were available, it would look like

If there are papers that have been linked to the data, clicking on the References button will open a listing in a browser.

The DSS button will open up an image from the Digitized Sky Survey in the preferred image browser.

Figure 35: DSS Image

Select data you would like to retrieve using either the mark buttons at the top, or by right clicking on the dataset name and selecting Fetch Entry or Mark Datasets. You can also use control-M on a highlighted dataset.

In the Retrieval list, marked data is indicated by the check in the left column. Hit Submit.

On the retrieval options page, type in your archive username and password. If you don't have an account, you can click the New Account button to get one. You must have an authorized account to retrieve proprietary data; however, public data can be retrieved using anonymous as the user id and your email address as the password.

Select Archive FTP Staging as the destination and Not Compressed for the Compression option.

For the type of data requested, the default is the OTFR /Calibrated option. To retrieve the raw data as well, select Uncalibrated in addition to the Calibrated/OTFR option.

Figure 37: Retrieval Options

When all options are set, hit Done to complete. StarView will verify the supplied parameters and respond with a request id.

When your request is complete, an email will be sent detailing the location of the data and how to retrieve it.

3.5 - Saving and Refining a Search

3.5.1 - Saving and Uploading

You can also save the search parameters to a file that can later be uploaded into another search form.

If you want to save the results of your search to a file, you can use the Export button The default format is a tab-delineated file with one record per row.

Figure 39: Export Results to File

You can also save the file in other formats by selecting Format, above the Save and Cancel options.

Figure 40: Format Options

On the Format screen, check the "Use Custom ASCII Table Format Options" checkbox to change the delimiters between records and fields. You can also have text fields surrounded by the same delimiters.

Table 2: Delimiters

The default is for records to be separated by a carriage return, fields by a tab, and nothing surrounding the text fields.

If you click on the "Include Fields" checkbox, you can arrange to save only selected fields. The default is all fields displayed on the form. The "View Fields As" checkbox allows you to display either the database fieldname or the form label in the Available fields column.

Double click on a fieldname listed in the Available Fields column or select it and use the right arrow to move it into the Selected Fields column. You can use the left arrow to remove a field and the up and down arrows to arrange the order.

If you select the source "From a file", a file selection menu will appear. The file needs to be a tab separated listing of results, with each new row a list of results from a given field. Loading the file will display the field data in the "Available Fields" column.

Figure 42: File of results to be imported into Cross Qualification

Once you have selected the source and destination, you can select the fields in each for cross qualification. To select a field, click on the field in the "Available Fields" column and then on the arrow pointing to the right. Double clicking the field will also add it to the "Selected Fields column."

You can change the order of the fields using the up and down arrows. The order of the source's fields needs to match the order of the destination's.

Once you've selected all the fields, click the X-Qualify button This will port the results from the source into the destination search form, and bring it into focus. Click Search.

Figure 43: XQual Results

If you wish to save the text of the query used in a search, select Save SQL from the file menu.

3.6 More Complex Example

To save the results, you will need to export them. Select the export button.

If you don't want to export every field listed on the screen, choose Format in the file chooser before proceeding.

On the format screen, select the fields you wish to save. If you wish to re-use these results in StarView at a later date (as in this example,) leave the "Use Custom ASCII Table Format Option" unchecked. Check the "Include Fields" box and select the fields you wish to export, by either double-clicking them or selecting them on the left and using the arrow to push them into the box on the right. In this example, the chosen fields are Dataset Name, Target Name, Proposal ID, Instrument and Release Date.

Give the file a name and save it. Here we will call it export_results.txt. Please note that if you intend to import the results later using cross qualification, you will need to edit the file to 50 lines or less.

To view OTFR information about the results, you will need to use Cross Qualification. First, bring up the ACS OTFR Search. This will give you information on the ACS datasets saved earlier. If you still have the Quick Search with the results available, you could Cross Qualify from that form to the ACS OTFR form. In this example, we'll use the results exported to export_results.txt.

Push theX-Qual button Cross Qualify in the Tools menu.

Under "Query Results from:" choose "A File" and select the exported results file from earlier, export_results.txt.

Under "Mapped to Query", select the ACS OTFR search.

Figure 46: Cross Qualify from a file

The first line in Available Fields in the "From" section is the dataset name. Double click on that line to push it to the list of selected fields. Under "Mapped to" find "Dataset Name" in the list of available fields and double click on it.

Press the X-Qualify arrow. The names of the datasets have been pushed into the dataset name qualifying field on the ACS OTFR form.

Figure 47: Cross Qualification

Now select search to view results. If you have more than 50 qualifiers, there will be an error. You will need to edit your file or the list in the qualifying screen to have less than 50.

Figure 48: ACS OTFR Search results

You can also save the sql used in the query to a text file. This might be useful if you needed to know all the database names of the fields to construct custom searches.

3.7 Building a New Search or Modifying an Existing Search

3.7.1 Custom Query Generator Tool

The Custom Query Generation Tool is a database browser that is used to create and modify search forms. It allows you to add fields from the available MAST databases.

To create a completely new search from scratch, select a blank form from the Searches menu. This will start up the database browser.

To edit an existing form, load the form and click on the button reading Static. It will change to Edit. You can then start the tool by selecting Custom Query Generator from the View menu.

Figure 49: Custom Query Generator

The Custom Query Generator Tool has three main sections.

To add fields, the form must first be in Edit mode. This is done by toggling the Static button at the bottom of the form to Edit. Clicking on a fieldname, either from the database tree or the results of the string search will add it to the search form.

To format or delete a field in a form, right click on the field label

Figure 56: Field Edit Menu

Properties allows you to change the field label, the size of the label and the size of the display box.

Figure 57: Properties

Delete Component will remove the field from the form.

Sort and Help work as they do in Static mode.