diff options
Diffstat (limited to 'noao/astutil/doc/obs.hlp')
| -rw-r--r-- | noao/astutil/doc/obs.hlp | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/noao/astutil/doc/obs.hlp b/noao/astutil/doc/obs.hlp new file mode 100644 index 00000000..4b5a8a88 --- /dev/null +++ b/noao/astutil/doc/obs.hlp @@ -0,0 +1,390 @@ +.help observatory Jan92 noao +.ih +NAME +observatory -- Examine and set observatory parameters +.ih +USAGE +observatory command obsid [images] +.ih +PARAMETERS +.ls command = "list" (set|list|images) +Command option which is one of "set", "list", or "images". The set command +sets the default observatory task parameters for the specified +observatory. The list command lists the observatory parameters for the +specified observatory but does not modify the task parameters. The images +command lists the observatory parameters for a list of images. The list +and images commands examine and verify the observatory parameters applied +by other tasks using the observatory database facility. +.le +.ls obsid = "?" +Observatory identification to be set, listed, or used as the default for +images without the OBSERVAT keyword. The observatory ID is one of those in +the database (case ignored), the special string "observatory" to default to +the environment variable "observatory" or the \fIobservatory.observatory\fR +parameter, "obspars" to select the parameters in the \fBobservatory\fR +task, or "?" to list the observatories defined in the database. +.le +.ls images +List of images to be examined with the "images" command. The images are +checked for the OBSERVAT keyword to determine the observatory parameters +to be listed, otherwise the observatory given by \fIobsid\fR is used. +.le +.ls verbose = no +Verbose output? Because there are a number of different ways in which +observatory information is determine this option prints detailed +information on how the observatory database and parameters are +ultimately selected. +.le + +.ls observatory +The default observatory used by tasks which use the special +observatory identification "observatory". The value is one of the +observatory names in the observatory database (case ignored) +or the special value "obspars" to select the parameters defined in this +task. There is no default to force users to set it at least once. +.le +.ls name +Observatory name. +.le +.ls longitude +Observatory longitude given in degrees west. +.le +.ls latitude +Observatory latitude in degrees. Positive latitudes are north and negative +latitudes are south. +.le +.ls altitude +Observatory altitude in meters above sea level. +.le +.ls timezone +Observatory time zone. The time zone is the number of hours west of +Greenwich or the number of hours to be added to local time to obtain +Greenwich time. +.le +.ih +ENVIRONMENT VARIABLES +.ls obsdb +This variable selects the observatory database. If not defined it defaults +to noao$lib/obsdb.dat. +.le +.ls observatory +This variable selects the observatory entry whenever a task uses the +observatory name "observatory". If not defined the value of the task +parameter \fIobservatory.observatory\fR is used. +.le +.ih +IMAGE HEADER KEYWORDS +The observatory identification for images is first sought under the +image header keyword OBSERVAT. This always takes precedence over any +other means of defining the observatory. +.ih +DESCRIPTION + +OBSERVATORY PARAMETERS IN THE NOAO PACKAGE + +Some astronomical data reduction and analysis tasks perform +computations requiring information about where the data was observed. +For example a number of \fBnoao\fR tasks make corrections for the +airmass. Generally they look for an airmass in the image header and +if it is not present they attempt to compute it from other image header +parameters. The information about time and telescope coordinates +of the observation are often in the image header but the observatory +latitude is not. The task must get this information somehow. + +Prior to IRAF V2.10 tasks generally had explicit parameters, such as +latitude, with default values pointing (using parameter redirection) to +the parameter of the same name in the \fBobservatory\fR task. The +user was required to know the values of the observatory parameters and +manually change them for data from different observatories. In V2.10 +an observatory database has been implemented. Observatory parameters +are stored in a simple text file and tasks obtain observatory related +parameters by specifying an observatory identification. + +In general the information about the observatory should be directly +associated with the image data. Unless stated otherwise in the +description of a task, tasks which require observatory information +will first look for the image header keyword OBSERVAT. The value of +this keyword is the observatory identification used to index the +observatory database. The task will then look up any observatory +parameters it needs in the observatory database. Data from +observatories that support this keyword will, therefore, always use the +correct observatory parameters without user intervention. All +observatories which export FITS image data are urged to adopt the +OBSERVAT keyword (a keyword recommended by the FITS standard). + +For image data which do not identify the observatory in this way +and in tasks which do not operate on images (such as astronomical +calculator tools), the observatory must be specified by the user. +Most tasks provide an "observatory" parameter which either directly +selects the observatory or use special values for defining the +observatory with an environment variable or the parameters +from the \fBobservatory\fR task. + +An observatory is specified by the identification name used in the +observatory database. The names in the database may be listed using +the \fBobservatory\fR task as described below. If the desired observatory +is not in the database a user may copy/create their own database and +select it with the environment variable "obsdb", modify the standard +database if allowed (any changes to the distributed version should +be forwarded to iraf$noao.edu), or use the special observatory name +"obspars". The last option directly uses the parameters in the +\fBobservatory\fR task which can be set to any values using the normal +parameter editing mechanism. + +The default value for the observatory parameter in a task is generally +"observatory". This special name directs the task to look first +for the environment variable of the same name and then at the +\fIobservatory\fR parameter of the \fBobservatory\fR task. The environment +variable allows users or sites to set the default observatory in their +login files and site defaults. Also it is simple to change the +default observatory either with a \fBreset\fR command or the +\fBobservatory\fR command. + +The observatory database is selected by the environment variable +"obsdb". The default when the variable is not defined is the +\fBnoao\fR package library database file "noao$lib/obsdb.dat". The use +of an environment variable allows users to permanently change the +default database in the OS environment (when IRAF has access to it such +as in UNIX systems) or in the startup IRAF environment as set in the +"login.cl" or "loginuser.cl" files. One can, of course, change it +during a session with the set or reset commands. For sites which want +to customize the observatory mechanism the environment variables can +also be set and changed in the files "hlib$zzsetenv.def", +"noao$lib/zzsetenv.def", and the template login file "hlib$login.cl". + +An observatory database file consist of a simple list of keyword=value +pairs with arbitrary whitespace allowed. An observatory entry begins +with the observatory keyword and extends to the next observatory +keyword or the end of the file. The observatory identification should +be the same as the string used in the OBSERVAT image header parameter +for data from that observatory. The default file noao$lib/obsdb.dat +begins as follows: + +.nf +# Observatory Parameters. Taken from the Almanac. +# +# Observatories wishing to be added or make changes in the default +# distributed database should send information to iraf@noao.edu. + +observatory = "kpno" + name = "Kitt Peak National Observatory" + longitude = 111:36.0 + latitude = 31:58.8 + altitude = 2120. + timezone = 7 + +observatory = "ctio" + <etc> +.fi + +In summary, access to observatory parameters is now done by referencing +the image header keyword OBSERVAT and, if not defined, determine the +observatory name from a task parameter. The environment variables +"observatory" and "obsdb" can be set by the user to select alternate +observatories and observatory database files. For data without an +observatory entry the observatory can be set to "obspars" or the user +may make their own observatory database. + +THE OBSERVATORY TASK + +The \fBobservatory\fR task serves a number of functions. It may be used to +examine the observatory database, verify the observatory parameters which +will be used by other tasks, particularly those operating on images, set +the default observatory if not defined by other means, set observatory +parameters explicitly, especially when there is no observatory database +entry, and as a parameter set for tasks which explicitly reference +observatory parameters. The \fBverbose\fR parameter also provides a +detailed check of the steps used to determine the observatory database, +observatory identification, and observatory parameters. + +The \fIcommand\fR parameter takes the values "set", "list", or "images". +The \fIobsid\fR parameter supplies the observatory identification and the +\fIimages\fR parameter is used to specify a list of images for the "images" +command. The parameters are query parameters and so may be either queried +or simply typed on the command line. + +The "set" command prints the observatory parameters for the specified +observatory and sets many of these in the \fBobservatory\fR task +parameters. This command is used to set the default observatory parameters +for tasks where images are not used, the images do not contain the +observatory id, or direct references to specific parameters with parameter +redirection (for example ")observatory.latitude") are used. + +The "list" command is similar to the "set" command except the task parameters +are not modified. It is used to list observatory parameters. It is also +use with the special observatory identifications to list the entries in +an observatory database and verify the observatory to be used by +tasks which do not operate on images. The special value "?" lists +the entries in the database. The special value "observatory" lists +the observatory defined by the "observatory" environment variable or +that given by the \fIobservatory.observatory\fR parameter. The special +value "obspars" simply lists the observatory task parameters. + +The "images" command lists the observatory information applicable to +one or more images. In particular, the observatory identification is +first sought in OBSERVAT image header keyword and, if not found, the +\fIobsid\fR parameter is used. Often the default observatory is +"observatory" to follow the same search path used by other tasks. + +The \fIverbose\fR parameter prints additional detailed information. It +prints the database used and whether it is selected by default +(noao$lib/obsdb.dat) or by the "obsdb" environment variable. When the +observatory is defined as "observatory" it indicates whether the +observatory is defined by the environment variable "observatory" or by the +observatory task. When listing images it prints the OBSERVAT keyword or +the default observatory assigned. + +For observatories not in a database the name, latitude, longitude, +altitude, and time zone parameters may be set using \fBeparam\fR. +The observatory id must be set to "obspars" in this case. +These parameters will then be referenced by other tasks in which +the observatory is specified as "obspars". This allows arbitrary +observatory parameters to be set without creating or modifying +an observatory database. However, it is advisable to create a +local database and also send the observatory information to the +IRAF group at NOAO for inclusion in the default database. +.ih +EXAMPLES +1. List the observatory entries in the database: + +.nf + cl> observatory list ? v+ + Using default observatory database: noao$lib/obsdb.dat + + default: Kitt Peak National Observatory + kpno: Kitt Peak National Observatory + ctio: Cerro Tololo Interamerican Observatory + eso: European Southern Observatory + lick: Lick Observatory + mmt: Whipple Observatory + cfht: Canada-France-Hawaii Telescope + lapalma: Roque de los Mucachos, La Palma +.fi + +2. Set the observatory parameters for Cerro Tololo: + +.nf + cl> observatory set ctio + Observatory parameters for Cerro Tololo... + observatory = ctio + timezone = 5 + altitude = 2215. + latitude = -30:09.9 + longitude = 70:48.9 + name = 'Cerro Tololo Interamerican Observatory' + cl> lpar observatory + command = "set" Command (set|list|images) + argument = ctio Observatory or images + (observatory = "ctio") Observatory identification + (name = "Cerro Tololo...") Observatory name + (longitude = 70.815) Observatory longitude (degrees) + (latitude = -30.165) Observatory latitude (degrees) + (altitude = 2215.) Observatory altitude (meters) + (timezone = 4) Observatory time zone + (verbose = no) Verbose output? + (mode = "q") +.fi + +3. Set the observatory parameters to use the environment variable +"observatory" and verify it. + +.nf + cl> set observatory=cfht + cl> observatory list observatory + Observatory parameters for Canada-France-Hawaii Telescope + observatory = cfht + timezone = 10 + altitude = 4215 + latitude = 19:49.6 + longitude = 155:28.3 + name = 'Canada-France-Hawaii Telescope' +.fi + +4. Change the default observatory database and verify verbosely: + +.nf + cl> set observatory="sco" + cl> set obsdb="/local/iraf/obsdb.dat" + cl> type obsdb$ + # Local Observatory Parameters. + + observatory = "sco" + name = "Small College Observatory" + longitude = 100:20.0 + latitude = 35:58.8 + altitude = 212. + timezone = 6 + cl> observ set observatory v+ + Using database defined by 'obsdb' environment variable: + /tmp/test/obsdb.dat + Using obs... defined by 'obs...' environment variable: sco + Using observatory parameters for database entry: sco + Observatory parameters for Small College Observatory + observatory = sco + timezone = 6 + altitude = 212. + latitude = 35:58.8 + longitude = 100:20.0 + name = 'Small College Observatory' +.fi + +5. List the observatory assigned to some images with a default observatory +determined either by the "observatory" environment variable or that set +in the observatory task. + +.nf + cl> observ images observatory dev$pix,demoobj1 + Observatory parameters for Small College Observatory + observatory = sco + timezone = 6 + altitude = 212. + latitude = 35:58.8 + longitude = 100:20.0 + name = 'Small College Observatory' + Images: dev$pix (default observatory) + Observatory parameters for Kitt Peak National Observatory + observatory = kpno + timezone = 7 + altitude = 2120. + latitude = 31:58.8 + longitude = 111:36.0 + name = 'Kitt Peak National Observatory' + Images: demoobj1 (OBSERVAT keyword) + +.fi + +6. Set explicit observatory parameters: + +.nf + cl> epar observatory + <set observatory parameters> + cl> observ list obspars + Observatory parameters for North Pole + observatory = obspars + timezone = 0 + altitude = 0. + latitude = 90. + longitude = 0. + name = 'North Pole' +.fi + +7. Use observatory parameters in expressions: + +.nf + cl> observ set kpno + Observatory parameters for Kitt Peak National Observatory + observatory = kpno + timezone = 7 + altitude = 2120. + latitude = 31:58.8 + longitude = 111:36.0 + name = 'Kitt Peak National Observatory' + cl> = observ.lat + 31.98 + cl> = sin (3.14159/180 * observ.lat) + 0.52962280742153 +.fi +.ih +SEE ALSO +Tasks in astutil, imred, onedspec, and twodspec. +.endhelp |