astwro.pydaophot¶
The astwro.pydaophot
module provides an interface to the command line tools of Peter B. Stetson daophot and allstar
Daphot/Allstar opt-configuration files¶
The module provides various options to indicate the location of following daophot configuration files:
daophot.opt
allstar.opt
photo.opt
Routines searches the following locations in the order provided:
- parameter – constructors of
Daophot
andAllstar
objects and some routines, have parameters to indicate the location of opt-files (e.g. the daophotopt parameter of theDaophot
constructor). Also script’s command line parameters (e.g.gapick --photo-opt
) are passed as arguments to appropriate routines. - working directory – if working directory of script process (not to be confused with
Daophot
object’s working directory - runner directory!) contains opt file, this file will be used. - astwro.cfg – the astwro configuration files contains section [files] where location of the opt files can be specified.
- default files – if module cannot locate opt file in locations below, uses the default file located in [astwro path]/pydaophot/config.
Note, that the presented order of searching means, that e.g. the working directory daophot.opt file have priority over another one provided in astwro.cfg.
Files and directories¶
Paths¶
To distinguish between the working directory of the python program and the working directory of the underlying daophot process, the following naming convention is used:
- runner directory is the working directory of the underlying daophot process.
This directory accessible by the
Daophot[Allstar].dir.path
property. - working directory is current working directory of python program
as obtained by
os.getcwd()
.
Runner directory¶
- Each
Daophot
[1] object maintains it’s own runner directory. - If directory is not specified in constructor, the temporary directory is created.
[1] | All information below applies to Allstar as well |
The runner directory is accessible by the Daophot[Allstar].dir.path
property.
Daophot
’s runner directory is the working directory of daophot program.
Specifying the file patch¶
For all command methods (FInd()
, PHotometry()
, …)
parameters that refer to files
follow the rules described below. Understanding those rules is especially important to
distinguish whether the file in runner directory or another directory is addressed.
- All filenames without path prefix, addresses the runner directory files.
- Files with absolute path prefix (that is, starting with /), are… absolute addressed files as expected.
- Files with relative (but not empty) path prefix, are relative to working directory.
- Files with patch prefix starting with ~ (tilde) are relative to the user’s home directory.
In other words, file pathnames are fairly standard and reltive to script working directory, with exception than lack of path prefix indicates file in runner directory.
During operation, all files has representation in runner directory, and underlying daophot processes only works on the files in that directory. It’s implemented by creating symbolic link in runner directory for the input files and copying the output files from runner directory into destination directories if such external output file is requested.
Runner directory file names¶
To avoid filename conflicts, the name of link/file in the runner directory created for external file consists of:
- hash of absolute pathname and
- original filename.
Input files¶
Due to the limited length of directory paths maintained by the daophot program, for all filepaths provided to
Daophot
object, the symbolic link is created in runner directory, and this link is given to the daophot process instead
of the original filename. Existing symbolic links of the same name are overwritten (because name is generated
from absolute patch it’s not a problem at all).
Output files¶
For output files, when the filename contains path component, daophot is instructed to output into the runner directory file, then, after daophot terminates, this file(s) are copied to the path specified by the user.
Warning
The output files, existing in runner directory, are deleted on queuing command. This can lead to unexpected
behaviour in "batch"
mode, when mixing input/output files. Consider following example:
d.mode = 'batch'
d.GRoup(psf_file='i.psf') # preexisting i.psf (input)
d.PSf(psf_file='i.psf') # deletes i.psf (output)
d.run() # GROUP will miss i.psf and fail
Note
In the batch mode, the copying occurs after execution of all commands in queue. This can have consequences when using the external file as an output of one command and input of further one. Usually everything should be fine, since the filenames generated for runner directory are deterministic as described above.
In the following example
from astwro.pydaophot import Daophot
from astwro.sampledata import fits_image
d = Daophot(image=fits_image())
d.mode = 'batch'
d.FInd(starlist_file='~/my.coo')
d.PHotometry(stars_file='~/my.coo')
d.run()
FInd()
command instruct daophot to output into file 1b7afb3.my.coo in runner directory.
PHotometry()
command will read file 1b7afb3.my.coo from runner directory.
After all 1b7afb3.my.coo will
be copied to ~/my.coo. Sometimes it’s easier to work explicitly on the files inside the runner directory :
from astwro.pydaophot import Daophot
from astwro.sampledata import fits_image
d = Daophot(image=fits_image(), batch=True)
d.FInd() # equiv: d.FInd(starlist_file='i.coo')
d.PHotometry() # equiv: d.PHotometry(starlist_file='i.coo')
d.run()
d.copy_from_runner_dir('i.coo', '~/my.coo')
User can also get patch to this file without copying
d.file_from_runner_dir('i.coo')
or, without specifying names at all
d.FInd_result.starlist_file
Operation modes - batch and parallel execution¶
The execution regime of daophot commands depends on Daophot
’s operation mode
(this applies to any runner subclassing the Runner
class).
Operation modes¶
Property Daophot.mode
(type: str) indicates operation mode:
"normal"
(default) - Every command method (FInd()
,PHotometry()
, …) blocks until the underlying daophot process completes processing. That is intuitive behaviour. Every command is executed by brand new daophot process, which terminates once the command execution is finished.The
ATtach()
andOPtions()
commands are not available in"normal"
mode. Instead useset_image()
andset_options()
methods that enqueue the appropriate daophot commands for execution before any other command."bath"
- The command methods does not trigger the underlying daophot process. Instead, commands are stored in the internal commands queue and are send to daophot for execution together on explicitly calledrun()
method. All commands are executed one by one in a single daophot process, which terminates after completion of the last command.
Asynchronous execution¶
The "bath"
operation mode allows asynchronous execution by passing wait=False
to the run(wait=False)
method.
In that case, the run()
method returns immediately after passing
the commands to the underlying daophot process. Further execution of the Python program runs in parallel
to the daophot process.
The user can check if daophot is still processing commands by testing the
Daophot.running
property.
Setting image and options¶
The daophot options and the attached image are the parameters that persist in
`daophot session. In "normal"
mode each command is executed in a separate
daophot process which terminates after execution of the command, so the configuration options and the
attached image must be set before each command execution.
The ATtach()
and OPtions()
methods
enqueues ATTACH and OPTION commands like any other
command methods and are useless in “normal”.
The set_image()
and set_options()
methods
should be used instead, which enqueue the appropriate daophot
commands for execution before every command.
Logging¶
The astwro.pydaophot
uses the logger (from the logging
module) named "pydaophot"
and it’s child loggers.