 |
 |
 |
PyRAF Programmer's Guide |  |
|
|
|
|
PyRAF Programmer's Guide | |
|
One of the strengths of IRAF is the way it handles task parameters.
The very useful IRAF commands lparam, dparam, eparam, unlearn
are available in PyRAF with the same syntax.
One significant difference is that
eparam brings up a GUI parameter editor,
rather than the IRAF text-based parameter editor.
This section describes parameter files and in-memory parameter lists,
the copy of a par file in the uparm directory,
and a few useful methods for handling parameters and par files.
Not every task has a parameter file,
as was mentioned earlier
(that was in the section on foreign tasks,
but other tasks may lack parameter files as well).
For a task that does have parameters,
there is a template parameter file (or a CL script file)
that specifies the default values, the types, and other information.
This file is typically found in the package directory,
has root name equal to the task name,
and has extension ``.par'' (or ``.cl'').
There is another copy of that parameter file
in the user's uparm directory,
which by default is a subdirectory of the user's IRAF home directory.
This copy is what is deleted when unlearn is used.
After running eparam on a task,
or after successfully executing the task,
the copy in the uparm directory will be updated (or created, if necessary)
to reflect the values set using eparam
or specified when the task was run
(but see below for further details).
The name of the file in the uparm directory is somewhat garbled
(``scrunched,'' in PyRAF terminology).
The file name begins with the first two characters of the package
that contains the task, followed by the last character of the package name
(or just the package name if it is less than or equal to three characters).
The rest of the root name is the first five characters of the task name
and the last character of the task name
(or just the task name if it is less than or equal to six characters).
The extension is .par.
This scheme dates back to the 1980's,
when file names on some operating systems were severely limited in length.
For example, the uparm file names for imcopy and imtranspose are
imlimcopy.par and immimtrae.par respectively
(these tasks are in the imutil and imgeom subpackages of images).
PyRAF uses the same template and uparm parameter files, and there can also be in-memory copies of the parameters for a task. In the PyRAF code these parameter lists are called the _defaultParList, the _runningParList and the _currentParList. The default par list is what you have after a task is unlearned; the parameter values are copied from the template par file. The running par list is the set that is used when a task is run, i.e. it would include values assigned on the command line. If the task completes successfully, the running par list will be copied to the current par list and to the uparm copy of the parameter file (but see below). The current par list contains updates after running a task or by direct assignment to the parameters, e.g. using eparam. The current par list generally (but not always) agrees with the uparm file.
It was stated above that the uparm copy of the parameter file will be updated after a task runs successfully. This is not always true. This section describes the conditions under which the uparm file will or will not be updated, and which parameter values will be modified.
If a task is executed using Python syntax,
then the uparm copy of the par file will not be updated
(unless the special boolean keyword _save=1 was specified).
This is the case regardless of whether the task
is run interactively or in a Python script.
On the other hand, if a task is run interactively using
the ordinary command-line syntax that looks like IRAF's ``command mode,''
then query/learn parameters (mode="ql" or "al")
will be updated in the uparm file;
hidden parameters will not normally be updated.
When using Python syntax, if _save=1 is specified
then query/learn parameters will be updated in the uparm file,
i.e. the uparm update behavior is the same as when using command mode.
Except for the _save keyword,
this is intended to closely emulate
the way IRAF handles updating the uparm file.
The significant difference is that
PyRAF either updates the uparm file or not
depending on the syntax (IRAF's command mode vs. Python syntax).
IRAF updates the uparm file if the task was run interactively,
and it does not update the uparm file
if the task was invoked from a script
or was run as a background job.
Running a task in command mode normally does not result in
hidden parameters (mode="h") being updated in the uparm file.
Parameters may be set explicitly,
either by direct assignment (e.g. iraf.imstat.fields="mean")
or by calling the setParam() method.
Doing so does not update the uparm file immediately;
however, if the task is subsequently run in command mode,
the values thus set will be updated in the uparm file,
and this is so even if the parameters are hidden.
There are two simple ways to get an entire parameter list
updated in the uparm copy of the par file,
regardless of whether the parameters are query or hidden.
One way is to run eparam and click on ``Save'';
in this case all the parameters in the uparm file will be set
to the values shown by eparam.
The other way, which can conveniently be used in a script,
is to call the saveParList() method for the task.
In PyRAF, IRAF tasks are IrafTask (or related) objects.
Four of the most useful methods of this class are described below.
The IRAF CL syntax for printing the value of a task parameter is,
for example, print (fxheader.fits_file),
or =fxheader.fits_file.
A parameter may be set using similar syntax,
fxheader.fits_file = "xyz.fits".
A similar syntax works in Python, too:
print iraf.fxheader.fits_file,
iraf.fxheader.fits_file = "xyz.fits".
The PyRAF methods getParam() and setParam()
serve a similar purpose,
and they allow more control over prompting (for query parameters),
data type of the returned value,
and access to the ``p_'' fields (described below).
The first argument to getParam() and setParam()
is qualifiedName,
which in its simplest form is a parameter name.
The ``qualified'' aspect means that the parameter
may be qualified with a package name, task name, or field,
with the various parts separated by periods.
The parameter name may include an array index in brackets
if the parameter is an array.
If a package name is specified, then a task name must be given;
otherwise, the package would appear to be a task name.
You may be wondering why one would give a task name,
when these methods are already associated with an IRAF task object.
The answer is that you can access the parameters of any loaded task this way.
For example, print iraf.imcopy.getParam("fxheader.fits_file")
and print iraf.fxheader.getParam("fits_file")
are equivalent.
To get the value of a parameter in the task's package,
precede the parameter name with the ``_.'' qualifier;
for example, print iraf.imcopy.getParam("_.version")
prints the version parameter in the imutil package par file.
The fields are referred to as ``parameter attributes''
in the IRAF help page (type phelp parameters).
The fields are
p_name, p_value, p_default, p_xtype, p_type, p_prompt,
p_filename, p_minimum, p_maximum, p_mode.
In IRAF there is also a p_length, which is a maximum string length,
but in PyRAF this is not needed and is not included.
Note that for string and (in PyRAF) integer parameters,
p_minimum is used for the list of allowed values; for example:
The calling sequence for getParam() is
getParam(qualifiedName, native=0, mode=None, exact=0, prompt=1).
The value will be gotten from the running par list if that is defined,
or the current par list if that is defined,
or the default par list.
The value returned is by default a string;
specifying native=1 gives the value in the native type of the parameter.
Minimum matching is supported unless exact=1 was specified.
The default prompt=1 means that the current value will be printed
to the terminal window,
and the user will have the option to specify a new value.
The calling sequence for setParam() is
setParam(qualifiedName, newvalue, check=1, exact=0).
The value will be set in the running parameter list if that is defined,
or the current par list if that is defined.
Values set don't typically appear in
the copy of the file in the uparm directory
until after the task has been run successfully.
The parameter fields that may be set are
p_value, p_prompt, p_filename, p_minimum, p_maximum, p_mode.
The default exact=0 means that minimum matching is supported,
but exact can be set to 1 to require an exact match.
The default check=1 means that the specified parameter value
will be compared with the minimum and maximum allowed values
(or the choice list, for a string),
and a value that is out of range will not be accepted.
However, sometimes one wants to give an out-of-range value,
e.g. for testing how the task deals with it,
and that can be done by specifying check=0.
saveParList(filename=None)
writes the current parameter list to filename,
or to the file in the uparm directory if filename was not specified.
The format of such a file is a standard IRAF parameter file.
Parameters can be restored from a file using setParList(),
with the file specified using the special keyword ParList.
The keyword value can be either a file name or an IrafParList object.
If a file name is given, the filename extension must be .par.
An alternative is to specify the special keyword ParList
when running the task.
--> # Save the parameters to the file hedit.par.
--> # Restore the parameters from the file, and then run hedit.
--> # Alternatively, restore parameters from saved file
--> # and run hedit in one call.
|
|
|
PyRAF Programmer's Guide | |
|
 | Questions or comments? Contact help@stsci.edu Documented updated on |