README.txt

PixCorrect
==========

Introduction
------------

pixcorrect is currently just a dummy product to provide a skeleton
into which to generate a refactored imdetrend product. 

Two dummy steps are currently implemented, foo and bar.

Preparation
===========

This application has two dependencies:

 - numpy
 - pyfits

A makefile in the parent directory compiles the needed C libraries,
and also generates some dummy images to be used in the examples below.

Both mainline UPS and eups table files can be found in the ups
subdirectory. The product should be setup by whichever is appropriate
for your system prior to use.

Execution
=========

Each step may be executed either stand-alone, or muliple steps
executed together in one pipeline.

Parameters for each step are specified in a configuration file, in the
format parsed by python's ConfigParser. Example files can be found in
$PIXCORRECT_DIR/etc.

Using the example configurations and dummy data generated by the
makefile in the test directory, you can run foo thus::

  $ cd $PIXCORRECT_DIR/test
  $ foo $PIXCORRECT_DIR/etc/foo.config

Options set in the configuration file can be overridden with the -o
option::

  $ cd $PIXCORRECT_DIR/test
  $ foo $PIXCORRECT_DIR/etc/foo.config -o coeff=33.2 out_fname=goo_out.fits

bar can be executed similarly::

  $ cd $PIXCORRECT_DIR/test
  $ bar $PIXCORRECT_DIR/etc/bar.config 

Finally, imcorrect, which can run either or both of these, can be run thus::

  $ imcorrect ../etc/imcorrect.config

Options to both imcorrect and bar allow options in the config files to
be overriden, as in the case of foo.

Automated code testing
======================

pixcorrect has several automated code tests, more designed as examples
of running tests than to be valuable as tests in themselves.

To run the tests, use test.py in $PIXCORRECT_DIR/test::

  $ python test.py test.config

The test.config configuration file defines which tests are to be run,
and tests can be turned on and off by modifying this file.

Addition information about writing testing code can be found in 
$PIXCORRECT_DIR/test/README.txt

Code structure
==============

The pixcorrect python module and its submodules provide the interface
to all pixcorrect code; the foo, bar, and imcorrect executables are
just symbolic links to foo.py, bar.py, and imcorrect.py.

There are three general categaries of pixcorrect submodules:

 - general utilities (dbc, imtypes, corr_util)
   - contains code used by multiple steps
 - step code (foo, bar)
   - contains code specific to the corresponding step.
   - each step may be run stand-alone
 - pipeline code (imcorrect)
   - contains only code required for calling steps in a pipeline, and
     moving data from one step to another.

In the above list, submodules of each category only depend on other
submodules higher on the list, never other submodules in the same
category or below.

Optimization with C
===================

As much code should remain in python as possible. For optimization,
some operations (particularly iteration over pixels) can be
implemented in C shared libraries, and called from python using the
base python ctypes module.

Configuration and argument parsing
==================================

All configuration and argument parsing is handled by
pixcorrect.corr_util.prep_main. This function reads a configuration
file (following the format using by python's SafeConfigParser class),
and overrides values set therein based on command line arguments.

It also includes options to set the logging level and the log file,
and can return a help string.

Sanity checking of input and output
===================================

Much of the code in the old imcorrect seemed to be dedicated to sanity
checking of input. pixcorrect provides a mechanism for doing this
while maximizing reuse of checking code while keeping it segrageted
from the code that does the calculation.

It does this following a "Design by Contract" mechanism using python
decorators.

For example, the pixcorrect.imtypes submodule contains a function,
args_type1, that checks whether a python object is a PyFITS ImageHDU
with a certain shape, certain keywords presen, and other having
specific values. Preceeding the declarion of foo with a
precondition and postcondition decorators::

  @precondition(imtypes.args_type1, 0)
  @postcondition(imtypes.args_type1, 0)
  def foo(hdu1, config):
      # content

causes the python interpreter to perfom this check on the object
passed as argument 1 to foo (specified by the second argument, "0", in
the decorators) before and after every call to foo.

When first exploring the code, I recommend ignoring the decorators at
first.

Exploring the code
==================

To get a handle on the code, I recommend starting by running and
experimeting with foo.py first, then bar, then imcorrect.