Release Notes for stsci_python
stsci_python 2.3 Release Notes

Release Notes for STScI_Python 2.3

27 March 2006

General
=======
This release includes new versions of PyFITS, PyRAF, MultiDrizzle and
related tasks.  A couple of tasks previously distributed separately
have now been added; namely, FITSDIFF and READGEIS have been added
to the PYTOOLS distribution.  This distribution now also includes
proper LICENSE information for reference.

Platform Support
================
Normally, platform support issues do not apply to Python tasks, as
most Python code will run on all platforms on which Python has been
installed.  This distribution was updated from the last release to
correctly support installation on Windows, as well as the previously
supported platforms of Linux, Solaris, and MacOS X.  The Windows
installation requires the latest version of numarray, 1.5.1, and
Python 2.4 or later, due to extensions for some applications which
were compiled with these versions.

Documentation
=============
Documentation for these tasks has been consolidated into a single
location complete with a index viewable as a local web page.
The documentation includes any available user guides and API
documentation generated using 'EPYDOC' for the modules or packages.
This index can be accessed using:

--> import stscidocs
--> stscidocs.viewdocs()
--> stscidocs.help()

This will automatically bring up the default web browser application
to display the index page. All the available documentation for software
packaged with this distribution can be accessed through this interface,
as this documentation resides locally upon installation.  


PyFITS
======
The changes to PyFITS were primarily to improve the docstrings and to 
reclassify some public functions and variables as private. Readgeis and 
fitsdiff which were distributed with PyFITS in previous releases were 
moved to pytools. This release of PyFITS is v1.0.1. The next release of 
PyFITS will support both numarray and numpy (and will be available separately 
from stsci_python, as are all the python packages contained within stsci_python). 
An alpha release for PyFITS numpy support will be made around the time of this 
stsci_python release.

- Updated docstrings for public functions.
- Made some previously public functions private.

PyRAF
=====
Support for graphics redirection added and for all IRAF CL string  functions.
Also support for boolean arrays was added. This release includes a number of 
bug fixes.

New features:

- Added support for graphics redirection
- Added functions isindef, strlwr, strupr, strstr, strlstr, strldx
- Added support for boolean arrays 

Bug fixes:

- Fixed bug introduced by changes made to Numeric that broke graphics  (when 
  users updated Numeric beyond what was distributed with the last  
  stsci_python release)
- Made the imaccess function behave much closer to that of IRAF CL  version
- PyRAF was mishandling cases where a task that produced no stdout  output 
  was piped into another task. In the process, a new line was  appended 
  causing subsequent tasks to behave differently than they would  have for the 
  CL. PyRAF now will handle this case identically.
- PyRAF previously improperly handled types for some variables in  certain 
  expressions. This was fixed, at the expense of now not being  able to add strings 
  and numeric values together when one exist outside  of the script (i.e., in 
  the calling environment). This behavior is not  a wise one to depend on in any case.
- Scripts that passed gcur and imcur parameters to other tasks did not  work properly 
  since they were passing values rather than references to  the parameter. PyRAF was 
  update to recognize these cases and pass the  parameter object rather than its value.
- Built in functions (one that did not call IRAF executables, e.g.,  printf) were not 
  handling I/O redirection properly. This was fixed.
- The function stridx previously did not behave the same as the IRAF  version. This 
  has been fixed.
- PyRAF previously did not pass parameters that had embedded newlines  properly to 
  IRAF executables. This has been corrected.
- PyRAF previously did not handle special characters in strings  identically to how 
  the IRAF CL did. More specifically, IRAF has a  smaller set of special (i.e., 
  backslashed) of characters it recognizes  than does Python. PyRAF now more closely 
  (but not exactly) mimics the  handling of special characters and does not interpret 
  backslashed  characters unless IRAF does. Note that this only applies to strings  
  specified in CL-like syntax. Python strings still follow Python  standard behavior.

Build related:

- The handling of the "memory has been corrupted" error seen on some
  Linux systems is now handled automatically (rather than requiring users
  to set it manually or in their startup scripts). Thanks to Nicola Caon
  for suggesting how to accomplish this.
- Clcache files were recompiled.
- The OpenGL-based graphics kernel was removed.


numarray
========= 

Full release notes are here:

http://sourceforge.net/project/shownotes.php?release_id=391704&group_id=1369

1. Implementation of scipy newcore array interface and __array_struct__
support (supplying and consuming) for numarray.  This should facilitate
better interoperability with numpy and Numeric.  This protocol
is documented here: http://numeric.scipy.org/array_interface.html
but also in numarray's source code in Include/numarray/arrayif.h.

Thanks to everyone who gave feedback on 1.4.1 and particularly to
Francesc Altet for his diligent testing (and doctest) of
Numeric<->numarray data interchange.

2. Better NumPy dtype Support.  

numarray's support for numpy-style numerical dtypes was refined and
the new dtype attribute was added:

>>> a = arange(10, dtype='i')
>>> a = arange(10, dtype='i4')
>>> a = arange(10, dtype='int32')
>>> a = arange(10, dtype='>> a = arange(10, dtype=numarray.dtype.int32)
>>> a.dtype.char   # i.e. int32
'i'
>>> a.dtype.kind   # i.e. integer
'i'
>>> a.dtype.itemsize
4
>>> a.dtype.byteorder  # little endian
'<' 
>>> a.dtype.str
'>> a.dtype.type
Int32
>>> a.dtype.isbuiltin
True
>>> a.dtype.isnative
True

This is still pretty superficial support for numpy's dtype and omits
specification of records, strings, and objects.  Although numarray's
dtype instances record byteorder, only native byteorder arrays can be
constructed at present.

II. Related Source Forge Tracker Items

1396372  	UInt32 AMD64 crash
1412737 	NumarrayType enumeration problem
1395938 	AMD64 Clipping, casting, and maximum values
1396742 	Slow performance in array protocol with string arrays
1397667 	Add scipy newcore numpy .dtype attribute
1386807 	sum(a boolean array) returns a negative value
1387438 	UFunc disease spreads (C operator hook bug)
1365121  	Definition of PyObject* operator conflicts with C++
1350954 	nummacro.h:27: error: expected type-specifier before ';' tok
1346470 	Please document more of what byteswap and byteswapped do
1364215 	Cannot combine array and masked array (e.g. via divide)
1363723 	my_array = +my_other_array uncovers a bug
1364811 	Infinite loop converting empty CharArrays to lists
1364815 	Strange behaviour when creating empty Int32 arrays
1340983 	Fix __get_array_data__
1346480 	byteswapped doesn't match doc string
1346425 	Please document if copy "fixes" byte order
1346426 	Please document what array does with numarray arrays


Imagestats
===========
 The 'centers' attribute was added to the histogram1d class to
 simplify use with matplotlib.
  

===========================================
====
====   Applications
====
===========================================

SAACLEAN
========
- SAACLEAN
   Significant algorithmic and error handling improvements have been made 
   in SAACLEAN.  Changes were also made to the SAACLEAN task parameters; 
   namely,    
   - removed GAINPLOT. Value is now taken from ADCGAIN keyword in  header.    
   - added CRTHRESH,NOISETHRESH,BINSIGFRAC replacing previously hardcoded 
       parameters.    
   - reordered parameters so all saaper-related params occur together
   - replaced INFILE by two new parameters, CALCIMAGE and TARGIMAGE.
       These are both input files:
         CALCIMAGE is the image from which the SAA correction is calculated;
         TARGIMAGE is the image to which the correction will be applied.
   - added a CLOBBER parameter to permit overwriting existing
       files. This parameter was added as a "query" parameter, so it
       will explicitly ask the user if it was not explicitly set. This
       permits the correction to be applied in place (if OUTPUT is the
       same as TARGIMAGE), as well as permitting other diagnostic files,
       persistence model files, etc, to be overwritten.
   - add 2 new parameters, HISTBINWIDTH and NCLIP, which are
       passed to imagestats when analyzing the saa persistence image
       histogram to compute the threshold separating the high and low
       signal domains.


MultiDrizzle
============
MultiDrizzle has been updated to version 2.7.2. The primary changes 
include:

- MultiDrizzle now runs Windows using the version of 'f2c' included
  in this release.  
- New parameters 'final_units' and 'updatewcs' have been added to the
  interface.  The 'final_units' parameter supports generating output
  products with units of either 'electrons/sec' or DN.  The 'updatewcs'
  parameter controls whether 'makewcs' gets run to update WCS header
  values.
- MultiDrizzle was modified to treat ACS (and STIS) images which
  have NGOODPIX == 0 as if they had EXPTIME==0.  This usually only
  happens when the entire image gets saturated as detected by CALACS
  (or CALSTIS), and would cause 'createMedian' to crash when included.
- Output crmask file now gets written out explicitly as a UInt8 array 
  instead of platform-specific INT. (64-bit support issue)
- In the driz_cr module, a message was added to warn users that the
  SNR and scale parameters only use 2 input values when more than two
  values are provided.  This was done to address an issue where users
  believed that they could input any number of values.