[{ALLOW edit EISMainUsers}]
[{ALLOW view Anonymous}]

!!! EIS CAT 

EIS_CAT is an IDL program for searching the EIS science data catalog, sometimes called the EIS As-Run database.  Science data can searched for in a number of different ways, including specifying complex search strings and graphically selecting regions of the Sun.  Once a particular FITS file is located, EIS_CAT will invoke the Quicklook software to help you analyze the data.  If you do not already have a local copy of the FITS file, then EIS_CAT will automatically download it to your workstation.

[{TableOfContents }]

!! EIS_CAT Basics

! Environment Variables and EIS_CAT

Before running EIS_CAT, it is important to make sure that your environment is properly configured.  Specifically EIS_CAT depends on envirament variables to access to the correct database.  If you are having problems running EIS_CAT then you may need to check and/or modify their settings.  


[{Table 

|ZDBASE_USER: |this environment variable points to a local copy of the database maintained by the user.

|ZDBASE_EIS: |this environment variable points to a local copy of the database maintained by the system administrator. 

|ZDBASE: |this environment variable points to the database currrently being accessed.  
}]

! Starting EIS_CAT

Since EIS_CAT is an IDL program, it must be run from within the IDL environment.  Starting EIS_CAT is easy.  Just type:

IDL> EIS_CAT

There are no useful keywords or other parameters that can passed to EIS_CAT via the command line.

Once EIS_CAT has been started, the EIS_CAT widget will appear.

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat1.jpg' align='center' }]

%%center 
''The EIS_CAT main window.''
%%

! Selecting A Database

After starting EIS_CAT, your fist task is to select a database to search.  EIS_CAT can use one of three different databases: An official local copy of the science data catalog, your personal local copy of the science data catalog, or a remote copy of the official science data catalog.  Unfortunately searching a remote database is currently disabled due to unresolved firewall issues.  The database is selected by chooseing one of the options in the drop down menu labeled ‘Database:’

Each menu option will be discussed briefly:

The official option selects the official local copy of the science data catalog.  The official copy is maintianed by the administrator of the host system and should provide up to date information about most studies that EIS has so far conducted.   Note that very recent observations may not be present in this database depending on how often your system administrator performs updates.

The user option selects a local copy of the science data catalog which is specific to your user account.  Provided that you perform updates on a regular basis, this copy should also provide up to date information about most studies that EIS has so far conducted.  Unfortunately setting up and maintaining a copy of the science catalog are issues beyond the scope of this document.  Please consult your system administrator or local expert if you need help in these areas.

The original option selects whichever database was being used when EIS_CAT was started.  Specifically, this option selects the database that the environment variable ZDBASE was pointing to when EIS_CAT was started.  Please see the section ‘Environment Variables and EIS_CAT for more information.

Once a database has been chosen, EIS_CAT will check to see if it can find the required database tables.  If  EIS_CAT is unable to find these tables, then a warning will be displayed in a pop up box informing the user of this situation.  In addition, the display portion of the EIS_CAT widget will be greyed out.  

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat3.jpg' align='center' }]

%%center 
''You can choose a database from the database droplist (upper right).''
%%

! Exiting EIS_CAT

Click on the ‘Exit’ menu option under the File menu to exit EIS_CAT.  Alternatively, you may close the EIS_CAT widget to exit EIS_CAT.

!! Searching and Displaying Results

The primary purpose of the EIS_CAT widget is to allow the user to search for EIS studies and rasters meeting specific search criteria.  EIS_CAT tries to make searching as intuitive as possible.  Searches are progressive, that is as you enter new search criterion, the search results are continously updated.

Press the ENTER key in order to update the search criterion.  EIS_CAT will then reread all the search conditions and execute a new search.   

Each search initially results in a list of studies of that match the search criterion.  The studies are displayed in the box labeled ‘MAIN AS-RUN ENTRIES’. Each study is displayed on a seperate line.   The in information about each study is organized into five columns:

[{Table 

|STUDY_ACRONYM	|The study Acronym

|ID  |An unique numerical identifier assigned to each study.  Currently based on the Timeline ID.

|DATE_OBSERVED  |The date and time of the first raster in the study.

|DESCRIPTION  |A brief description of the study.

|NOAA#  |The NOAA ID of the active region observed by the study (if an active region was observed by the study).  Some studies that observe active regions may not have this field filled in.

|TARGET |The target of the study.
}]

Left clicking with the mouse on any line displaying information about a study will result in a secondary search, this time for all the rasters which are part of that study and which also meet the search criterion.  

Please note:  Not every raster which is part of a study will be displayed.  Only those rasters which meet the search criterion will be displayed.  For example suppose a study contains a number of rasters spread over a fairly wide region of the solar disk.  However, part of the search criterion is to search for rasters whose center is within 50 arcseconds of sun center (see ‘Graphical Searches’ to learn how to do this).  Only those rasters which meet this narrow search criterion will be displayed.

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat2.jpg' align='center' }]

%%center 
''EIS_CAT displays studies in the upper box labeled MAIN AS_RUN ENTRIES and rasters in the lower box labeled RASTER-LEVEL AS-RUN ENTRIES.''
%%

Rasters are displayed in the box labeled ‘RASTER LEVEL AS-RUN ENTRIES’.  Each raster is displayed on a seperate line.  The information about each raster is organized in six columns:

[{Table 

|TIMELINE_ID: |An unique numerical identifier assigned to each study.  Currently based on the Timeline ID.

|DATE_OBSERVED:	|The date and time of the first observation in the raster.

|FITS FILE: |The name of the FITS file containing the level 0 data for this raster.

|XCEN: |The center of the raster along the X axis in arcseconds.

|YCEN: |The center of the raster along the Y axis in arcseconds.

|DUR: |The duration of the raster in seconds.
}]

! Selecting the Download Location for FITS Files.

You can select the subdirectory where FITS files will be stored once they are downloaded to your local machine.  If you know the exact path you wish to use to download FITS files, you may enter this path into text box labeled ‘Download FITS file to:’.  Once you press the return key, the existence of this directory will be checked.  If the directory exists, it will then be used as the new target directory for downloaded FITS files.  Otherwise the previous target directory will be restored.

Another way to change the subdirectory where FITS files will be stored is to click on the ‘Browse’ button.  Clicking the ‘Browse’ button brings up a dialog box which will allow you to graphically browse the file system.  If you wish to create a new subdirectory, you can do that by clicking on the button labeled ‘Make New Folder’ in the dialog box.

! Downloading a FITS File.

Once you have identified a raster that you are interested in, you may download the FITS file with the data for this raster to your local machine.  Left click on the raster of interest in the box labeled ‘Raster-Level As-Run Entries’ to select that raster.  Once you have selected a raster, click on the button labeled ‘Download FITS File’ to download that file to your local machine.  Alternatively, you may select the menu option ‘Download FITS File …’ from the ‘Quicklook’ top level menu or simply double click on the raster you are interested in.

If you try to download file that already exists on your local system, EIS_CAT will put up dialog box informing you that the file already exist.  You will then be required to confirm that you would like to continue with the download.

The selected file will then be downloaded to your local machine from a repository.  
 
! Starting the Quicklook Software

The Quicklook Software may be started from within EIS_CAT.  Left click on the raster of interest in the box labeled ‘Raster-Level As-Run Entries’ to select that raster.  Once you have selected a raster, click on the button labeled ‘Run Quicklook Program’.  Alternatively, you may select the menu option ‘Start Quicklook …’ from the ‘Quicklook’ top level menu.

If the FITS file is not available locally, EIS_CAT will automatically try to  download it from the nearest archive over the internet (provided that an internet connection is available).  If the FITS file can not be located or no archive is available, then a warning will be displayed in a pop-up box stating that the requested file can not be found.

! Sorting Results By Time

The search results can be sorted in either ascending or descending order.  When displaying search results in ascending order, studies will be sorted so that the study with the earliest start time will be at the top of the display window while the study that was performed most recently will be at the bottom of the display window.  

Displaying search results in descending order is just the opposite.  When displaying results in descending order, studies will be sorted so that most recent study will be at the top of the display window while the study with the earliest start time will be at the bottom.

Use the mouse to click on the radio button labeled ‘Ascending’ to sort the search results in ascending order.  Click on the radio button labeled ‘Descending’ to sort the search results in descending order.
 
! Printing the Search Results

In order to get a hard copy of  the current search results, select the ‘Print Search Results …’ menu option from the ‘File’ top level menu.  A dialog box will then appear that will allow you to select which printer you wish to use as well as set options specific to that printer.

If your current search results include rasters, then those will be included in the printout.  Otherwise the printout will only show the studies returned by the latest search.

! Saving Your Search Results as a Text File

In addition to printing your current search results, you can also save your search results to text file.  Select the ‘Save Search Results As …’ menu option from the ‘File’ top level menu. A dialog box will then appear that will allow you to select where you wish to save text file as well as what to name it.  

! Resetting All Search Parameters

The default search criteria is to display all of the studies that have been performed in the past two weeks.  When EIS_CAT is started, it will perform an intitial search based on this creteria.  If at any time you wish to return to the default search criteria, simply select the ‘Reset All Search Parameters’ menu option from the ‘Search’ top level menu.

! Repeating a Search

It is possible to repeat a search without changing any of the search parameters.  In order to repeat a search, select the ‘Relist Current Search’ menu option from the ‘Search’ top level menu.  In general, it will not be necessary to do this.
 
! Searching By Time

The most basic way of searching the science data catalog is by time.  All searches include a time component, although it can be set to length of the mission (or even longer).

The time range for a seach is entered by using the boxes labeled ‘Start Time’ and ‘Stop Time’

Enter the beginning of the time range to perform the search over in the box labeled ‘Start Time’.  Enter the end of the time range  enter in the box labled ‘Stop Time’.  Press the ‘ENTER’ key in order to display studies which fall within the selected time range.

All times are specified relative to UTC and in twenty four hour format.  Times can include date and time (including millisecond) or simply date.   

Here are some examples of acceptable time formats.

[{Table 

|21-July-2010 15:32:30 |3:32:30 PM on July 21, 2010

|2010/3/15 11:00 |11:00 AM on March 15, 2010

|2010-Jul-1 |12:00 AM on July 1, 2010
}]

! Searching by Study Acronym

You may search for studies based on study acronym.  Click the radio button labeled ‘Use Study Acronym:’ in order to enable searches based on study acronym.  The text box to the right of the label ‘Use Study Acronym:’ will become active.  Enter the study acronym that you are interested in into this box.  After hitting the return key, all studies that match the search string and that fall with the selected time interval will be displayed.

In addition to searching on an entire study acronym, you may search on just part of it.  Any studies that have a study acronym containing the search text as a substring will be selected.  For instance, entering the string “SY” as a study acronym will yield studies with the acronyms “SYNOP006” and “SYNOP005_A”.

Note that searches based on a study acronym are case insensitive.  “Synop”, “SYNOP”, and “synop” will each produce equivalent results.

! Searching by Active Region Number

You may also search for studies based on NOAA active region number.  Click the radio button labeled ‘On Active Region Number:’ in order to enable searches based on active region number.  The text box to the right of the label ‘On Active Region Number’ will become active.  Enter the active region number that you are interested in into this box.  After hitting the return key, all studies that have this active region as their target will be displayed.

Note that not studies run on active region identified by a NOAA active region number will have this information recorded in the database.  Therefore it is possible that a search for a particular NOAA active region number will not yield all of the studies of interest. 

! Searching by HOP Number

Hinode joint instrument studies are tracked by HOP (Hinode operation plan) numbers.  You may search for studies that run in support of a particular HOP.  Click the radio button labeled ‘With HOP number:’ in order to enable searches based on HOP numbers.  The text box to the right of the label ‘With HOP number:’ will become active.  Enter the HOP number that you are interested in into this box.  After hitting the return key, all studies that were run in support of this HOP will be displayed.

! Interaction of Search Terms

Search terms are additive.  That is, if you search on more than one field, the search will display only results that satisfy all of the search terms.  For instance, searching on active region number and study acronym will yield studies that satisfy both of these search terms.  In addition, all searches include a time interval as specified by the text boxes labeled ‘Start Time:’ and ‘Stop Time:”.


!! Advanced Types of Searches

It is possible perform searches based on any (or any combination) of database fields.  This is done by using the advanced search tool.  In addition, you can also perform database searches for studies performed on a specific region of the sun by graphically selecting that region.  Finally, if you interested in a specific wavelength (or set of wavelengths) you may search for studies that include those wavelengths using the wavelength search tool.

! The Graphical Search Tool

The graphical search tool is used to select studies based on pointing.  It allows you to graphically select a region of the sun and then search for studies that were pointed at this region.

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat6.jpg' align='center' }]

%%center 
''The Graphical Search Tool.''
%%

In order to start the graphical search tool, select the “Graphical Search Tool …” menu option form the “Search” top level menu.  A dialog box that implements the graphical search tool will then appear.

The main area of the dialog box is a graphical depiction of the Sun.  The solar disk is marked with longitude and latitude lines in ten degree intervals.

Select regions of the Sun by using your mouse.  For this purpose, it is best to have a 3 button mouse.  

Click the left button and drag the mouse in order to create an initial selection rectangle.  One corner will be fixed where you initially click the mouse while the opposite corner will follow the mouse location.

You may change the position of the selection rectangle by clicking on the rectangle with the center mouse button and then dragging the rectangle to a new position. 

You may change the size of the selection rectangle by clicking near a corner of the selection rectangle with the left mouse button.  Drag the corner to change the size of the selection rectangle, the opposite corner of the rectangle remains fixed.  

If you need clear the selection rectangle and start over, click the right mouse button anywhere on the display.   

Beneath solar graphic is four text fields labeled “X Center”, “Y Center”, “X Length”, and “Y Length”.  The text fields labeled “X Center” and “Y Center” display the X and Y coordinate of the center of the selection rectangle in arc seconds.  The text fields labeled “X Length” and “Y Length” display the width and height of the selection rectangle in arc seconds.

Once you are happy with the size and position of the selection rectangle, you may initiate a search by left clicking on the button labeled “Apply” at the bottom of the dialog box.  A search will be generated that selects any study that has a raster that is pointed within the selection rectangle.

If you are happy with the search results, then left click on the button labeled “Cancel” to close the graphical search tool and get rid of the dialog box.  Otherwise you may alter the search rectangle and then rerun the search.  Left clicking on the “Reset” button has the same effect clicking on the display with the right mouse button -- that is it will remove the search rectangle.

You may be able to get solar image from your favorite observatory to use as a background image for this program.  Left click on the button labeled “Select Background Image” in order to bring up the SHOW_SYNOP tool.  SHOW_SYNOP will to allow search the repositories of solar 

! Advanced Database Search

The advanced search tool allows you to search a database based on any combination of fields.  This can be done with the assistance of graphical widget or by directly entering a search string.  In order to start the advanced search tool, select the “Advanced Search Tool .,..” menu option from the “Search” top level menu.  A dialog box that implements the advanced search tool will then appear.  

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat4.jpg' align='center' }]

%%center 
''The Advanced Database Search Tool.''
%%

__Selecting a Database To Search On__

In order to use the advanced search tool, you must first select the database to search on.  EIS_CAT supports searches on two database tables.  These are described below:

The EIS_MAIN table contains information about each study run on EIS.  EIS studies consist of a defined set of observations (rasters) designed to support a scientific objective.  Each entry in this table contains high level information about the study, such as the science objective of the study and who the author is.

The EIS_EXPERIMENT table contains information about each raster run on EIS.  Each raster contains the data from a specific observation stored as a FITS file.  Each entry in this table contains detailed and specific information about the raster.

Click on the radio button next to the database table you wish to search on.

__Searching Using the Advance Search Widget__

You may perform searches using the advanced search widget.  This widget provides graphical controls that allow you to explicitly tailor each parameter of your search.  Using this widget allows you perform very complex searches without having to master any special syntax or search language.

In order to use this widget, click on the radio button labeled “Select individual database fields from the list below …”.  This option is enabled by default when you first start this tool.

__Selecting Database Fields__

The next step in constructing your search is to select which database fields you wish to search on.   In the middle of the widget is list box that contains a list of every field in the currently selected database table.  The title of the list box is also the name of the currently selected database table.

The list box contains both the name of each field and, to its right, a brief description of that field.  Select a field of interest by right clicking on the line in the list box containing the field name.  A scroll bar on the right side of the list box will allow you to scroll through all of fields that are part of the database table.  The selected field will now be highlighted.  Now right click on the button labeled ‘Select’ which is to the right of the list box in order to add that field to search.   

__Choosing Selection Operators__

After you have added a field to the search, the field name along with a drop list and a text box will appear at the bottom of the list of database fields.  Together these are used to specify a selection rule.  A search will return (select) all of the records in a table that satisfy all of its rules.

Note: each rule in a search must specify a unique field.  It is not possible share a field between multiple rules.

In general, a selection rule takes the following form: 

~[field name~] ~[selection operator~] ~[target~]

Here are some examples:

XCEN  > 0	Select all rasters with XCEN greater than 0.

RAST_ID = 14	Select all rasters that use raster ID 14.

Use the drop list to choose the selection operator to use with this field.  The chosen operator will be displayed between the field name and the text box.  Enter value to use as the target of the search in the text box.  

For selection operators are available.  Each one is described below:

[{Table 

| = |The search returns database records where the value of the field is equal to the target. 

| > |The search returns database records where the value of the field is greater than the target.

| < |The search returns database records where the value of the field is less than the target.

| << |This selection operator requires two targets.  When selected, two text boxes will appear with the field name between them.  This search returns database records where the value of the field is between the value entered in the text box to the left of the field name (target 1) and the value entered to in the text box to the right of the field name (target 2).
}]

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat5.jpg' align='center' }]

%%center 
''A selection rule to select rasters based on the value of XCEN.''
%%

You may specify as many rules as you wish.   Simply select a new field from the list of fields and left click on the “Select” button.  Alternatively, if you decide you do not wish to use a rule, you may delete all of the current rules by clicking on left click button labeled “Clear Items”.  Unfortunately you cannot delete a single rule.

Once you are satisfied with you current rule set, you may initiate a search by left clicking button labeled “Apply” at the bottom of the dialog box.  Studies satisfying the search criterion will be displayed.  If you are not satisfied with the search results, you change the values you have entered as targets in any search rule.  Left click again on the button labeled “Apply” to initiate a new search with the updated rule set.

Once you are happy results of a search, left click on the button label “Cancel” to close the advanced search tool and get rid of the dialog box.

__Entering Your Search Query Directly into EIS_CAT__

If you know the syntax used to create UiT database queries, you may enter a query directly into EIS_CAT.  

As with using the advanced search tool, first select which database table you wish to search.  Then click on the radio button labeled “OR enter a search string to query the database:”.  Left click on the Apply button to execute the search.  Studies satisfying the search criterion will be displayed.

Once you are happy results of a search, left click on the button label “Cancel” to close the advanced search tool and get rid of the dialog box.

! Searching By Wavelength

It is possible to search for studies that observe a particular wavelength or an interval of wavelengths.  To search by wavelength, select the “Search by Line/Wavelength …” menu option form the “Search” top level menu.  A dialog box that implements the wavelength searches tool will then appear.

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat7.jpg' align='center' }]

%%center 
''The Wavelength Search Tool.''
%%


On the left side of the widget is a list box labeled “Available Lines”.  This list box contains all of the available wavelengths along with the line name associated with each wavelength.  On the right side of the widget is a list box labeled “Selected Lines” containing all of the wavelengths that have been selected as part of the current search.  

To begin searching by wavelength, highlight the wavelength you are interested in from the list box labeled “Available Lines”.  You may highlight a wavelength by left clicking on it with your mouse.  Multiple contiguous wavelengths may be highlighted by holding down the shift key while left clicking on a second wavelength.   All the lines between the first and second wavelengths will be highlighted.

You may narrow your choice of wavelengths by selecting a range of wavelengths to display.  To do this, click on the checkbox labeled “Select values to display”.   Enter the minimum wavelength that you are interested in the text box labeled “Minimum Wavelength”.  Enter the maximum wavelength that you are interested in the text box labeled “Maximum Wavelength”.  Hitting the return key will modify the list box labeled “Available Lines” so that only wavelengths within the specified range will be displayed.  Note that this will not modify the wavelengths displayed in the list box labeled “Selected Lines”.

Once you have highlighted a wavelength (or wavelengths) that you are interested in searching on, you can add it to the list of selected wavelengths by left clicking on the button labeled “>>”.  The highlighted wavelength (or wavelengths) will be moved from the list box labeled “Available Lines” to the list box labeled “Selected Lines”.    You may repeat this operation as many times as you wish.

[{Image src='http://hyperion.nascom.nasa.gov/misc/eiscat8.jpg' align='center' }]

%%center 
''Selected wavelengths are moved from list labeled 'Available Lines' to the list labeled 'Selected Lines'.''
%%

If you decide that you wish to remove a wavelength from a search, highlight that wavelength (or wavelengths) in the list box labeled “Selected Lines” then left click on the button labeled “<<”.  The highlighted wavelength (or wavelengths) will be moved from the list box labeled “Selected Lines” to the list box labeled “Available Lines”.  

Once you are happy with the wavelengths you have selected, left click on the button labeled “OK” to initiate the search.  The dialog box will disappear and EIS_CAT will display all the studies in the specified time interval that include any of the selected wavelengths.  If you wish to abort the search, you may left click on the button labeled “Cancel” to close the dialog box without initiating a search.

! Saving Search Parameters

You may save your current search for later use.  To save a search, as opposed to the search results, select the “Save Search Parameters …” menu option from the “Search” top level menu.  A dialog box will then be displayed that will allow you to choose a file name and directory to store your search in.  Searches are saved as text files, so you may edit them if you wish.

! Executing a Search using Saved Search Parameters

Once you have saved a search, you may re-execute that search over a new time interval, possibly including studies that were not available when you first created your search.

To execute a previously save search, select the “Load New Search Parameters …” menu option from the “Search” top level menu.  A dialog box will then be displayed that will allow you to navigate to and select a previously saved search.  Once you have selected the search of your choice, the search will be executed over the currently selected time interval.