source: trunk/CHANGES @ 654

Duchamp version 1.2-beta (2009/??/??)
-------------------------------------

Improvements: 

* Profiling of the code has led to a few changes that have sped up
  some calculations, particularly those involving the median. Rather
  than using std::sort, the code now simply uses std::nth_element,
  which shows a substantial speedup factor.

* When using the objectList parameter, the maps will now only show the
  selected objects, rather than all detected objects.

* There is a new verification test that looks at the "growing"
  functionality.

Bug fixes:

* There was an occasional error in writing out FITS keywords, due to
  the way comment strings were intialised. This has been improved and
  made more robust.

* Testing with gcc-4.3.2 showed a number of compilation warnings &
  errors, which have been fixed.

* The Gaussian smoothing kernel was too small - it is now made big
  enough to encompass all possible values. It was also being
  incorrectly scaled. This had no functional effect on the detection
  of objects, but for other uses was incorrect. This has been
  rectified.

* Some outputs that weren't caught by the verbose flag now are.


Code development notes:

  The following notes only apply if you want to use the code as a
  library, rather than the stand-alone package. These have generally
  come out of the ASKAP software development. If you just use the
  stand-alone package, they won't be a concern.

* The API for storing detected objects has changed, making it more
  robust from a programming point of view.

* Additional versions of some functions (and the Gaussian smoothing
  class) have been added - this has come out of the ASKAP development
  work.

* A number of instances of "unsigned int" being used for loops have
  been changed to iterators or "size_t". There shouldn't be any
  functional change from this -- the code should just build more
  cleanly.


Duchamp version 1.1.8 (2009/07/20)
----------------------------------

Improvements:

* The final source list can now be sorted on one of a range of object
  parameters: x-value, y-value, z-value, ra, dec, vel, w50, iflux,
  pflux (integrated and peak flux respectively), or snr. Simply use
  the new input parameter sortingParam. Its default value is vel, so
  the default behaviour stays the same.

* The FDR method involves calculating how many pixels are
  correlated. This previously involved multiplying the beam area by 2,
  implying that 2 neighbouring channels were correlated. This factor
  is now a user-selectable parameter, so that if you know how many
  spectral channels should be correlated, you can set the parameter
  FDRnumCorChan and the FDR calculation will be done correctly.

* Screen output now has more information on the growing threshold when
  the cube statistics are printed.


Bug fixes:

* When reading in previous detections, there was a bug causing a
  segmentation fault. This has been fixed and made more robust.

* There was an apparent bug when writing out the reconstructed cubes
  to a FITS file that caused the new file to be very large. Changing
  the cfitsio function used has fixed this.

* Using NCP projections near the equator could result in a large
  stream of error messages, due to coordinate transformations being
  done in blank regions outside of the acceptable range of world
  coordinates. This has been fixed.

* The function that grows objects had a major bug, that stopped it
  working when flagAdjacent=false. This has been fixed and should work
  fine.

* The input parameter spectraTextFile was not being read
  properly. This has been remedied.

* The units for the integrated flux were wrong for some types of pixel
  flux units. This has been fixed.

* A minor bug caused incorrect calculation of the 20% widths.

* All calls to uint were changed to unsigned int, as some compilers
  had problems recognising that they were the same thing.

* src/fitsHeader.cc was missing an include statement for stdlib.h,
  again causing some compilers to fail.


Duchamp version 1.1.7 (2009/01/16)
----------------------------------

Improvements:

* The mask file that can be created with flagMask can now specify
  which object a given detected pixel belongs to, by taking the object
  ID as its value. This applies if you set flagMaskWithObjectNum=true
  (it defaults to false, which means each detected pixel has the value
  1). Non-detected pixels still have the value 0.

* The names of the output FITS files are now able to be specified
  directly by input parameters. These will override the default names
  that Duchamp provides.

* The Karma annotation file now specifies a font - previously it did
  not and so was at the mercy of whatever was specified in other
  annotation files being viewed at the same time. Please let me know
  if the font I've chosen (lucidasans-12) is not suitable.

* The default flag, used in the absence of 'E', 'S' or 'N', is now '-'
  rather than blank. This will ensure that each column in the results
  file has something in it.

* The configure script is somewhat more robust to non-standard
  systems, particularly when the X11 libraries are in unusual
  places. It can also deal with the slightly different way that
  wcslib-4.3 installs itself.

* The installation part of the Makefile was altered so that the
  symbolic link Duchamp that points to Duchamp-1.1.7 does not have the
  absolute path encoded in it. This will enable the files to be moved
  around at a later date.

Bug Fixes:

* Fixed a bug that caused problems when the flux units were less than
  5 characters long (e.g. 'K')

* The new velocity width values were not getting proper headers in the
  VOTable output. This has been remedied.

* Minor improvements to help non-pgplot use

* Minor fix in WCS functionality.

* Minor fixes to the FitsHeader class.

* Improved FITS data reading, that doesn't require a nullarray
  array. This will reduce memory usage.

* Improved subsection parsing, particularly for non-standard WCS
  systems.

* Improving the memory allocation of the Cube class.

* Fixed a bug that meant the growthThreshold values were sometimes
  being lost.

* Improving the way the growing and merging is done, particularly in
  the case of non-adjacent merging.

* Fixed a scaling bug in the GaussSmooth function.

Other:

* Numerous changes to the code that do not affect how Duchamp itself
  runs, but were necessary for code development with the Duchamp
  libraries (primarily as a part of the ASKAP code development).


Duchamp version 1.1.6 (2008/09/08)
----------------------------------

New features:

* The velocity widths can now be quoted in two additional ways: the
  full width at 50% of the peak flux (ie. the FWHM) and the full width
  at 20% of the peak flux (w_50 and w_20 respectively). The w_50
  parameter is now quoted in the results printed to the screen
  (instead of w_VEL), but all three are written to the results file.

* The facility now exists to bypass the searching step and go straight
  to the output stage using a list of previously detected objects. The
  list is extracted from a previously-created log file. The user can
  change the way the spectra are plotted (e.g. choose to plot
  integrated rather than peak spectra), and select a subset of the
  detected objects to be printed to individual postscript files. Use
  the input parameter usePrevious (set to true) to use this facility,
  and provide a list of objects using the objectList parameter
  (eg. 1,2,4,7-10,15)

* A new parameter "growthThreshold" has been created, that goes with
  "threshold". If you manually specify a threshold, and you wish to
  grow detections, you need to manually specify a growthThreshold (in
  flux units).

Bug fixes:

* Cubes that do not have a spectral axis (such as Stokes cubes) were
  causing memory leaks and crashing, due to some assumptions of the
  existence of the spectral axis. These bugs have been fixed, so that
  Duchamp will run on such cubes, although the WCS transforms may not
  always work appropriately. Please let me know via bug reports of
  difficulties you encounter!

* The growing function has had a few bugs fixed and is now more
  efficient.

* The FDR method was previously overriding any manually-specified
  threshold. This has been fixed so that if the user specifies
  threshold=X, then the FDR method is not called.

* Some undefined things were happening with textual output when no
  objects were detected. This has been fixed.

* Memory leaks caused by FITS WCS irregularities have been fixed
  (specifically, if a FITS header had NAXIS=2 but more than two WCS
  axes were defined).



Duchamp version 1.1.5 (2008/03/20)
----------------------------------

Bug fixes:
* A major bug was discovered in the calculation of integrated
  fluxes. The flux was incorrectly being weighted by the spatial size
  of the detection, resulting in a (often considerable) overestimation
  of the integrated flux. This has been corrected.

* The beam size calculation was also incorrect, being out by a factor
  of 1/ln(2). 

* The "make install" command previously failed to work properly if the
  library had not been created. This has been fixed so that the
  installation works even if there is no library file.

New Features:
* You can now provide a new flux unit string, so that the pixel fluxes
  will be converted to these new fluxes before any calculations are
  done. This is done with the newFluxUnits input parameter. The new
  units should be directly convertible from the old ones (given by the
  BUNIT header -- e.g. if BUNIT = Jy/beam, you can give newFluxUnits
  as mJy/beam, but not mJy).

* You can now specify the precision used in the output files for flux,
  velocity and S/N ratio columns, via new input parameters precFlux,
  precVel and precSNR. These will apply to the VOTable output as well
  as the text table and information on the spectral plots.

* The Karma annotation files previously provided just a circle at the
  spatial location of the detected object. You now have the option to
  draw a border around the detected pixels (in a similar manner to the
  PGPLOT moment maps). Karma does not do this perfectly, so the lines
  may not line up exactly with the pixel borders, so the option
  remains to keep using the circles. This is controlled by the
  parameter "annotationType", with possible options being "borders"
  (the default) or "circles".

* There is a new function getMetadata() that loads the header and WCS
  data, but no pixel information. This is only of interest if you are
  doing code development with the Duchamp library -- it does not
  affect the running of Duchamp itself.

Duchamp version 1.1.4 (2008/02/15)
----------------------------------

Most of the changes incorporated in this update result from ASKAP code
development (that makes use of some of the Duchamp functionality),
but do not actually affect the way Duchamp runs (other than, in a
couple of cases, making it a bit faster). Changes that are
relevant for regular users of Duchamp are as follows:

* A new option has been made available (thanks to Mary Putman et al
  for the suggestion!) to save the spectra of all detected objects in
  a text file. This has the form of one column for the spectral
  coordinates and one column of fluxes for each object. This is
  enabled by the input parameters flagTextSpectra and spectraTextFile.

* Slight changes to the output include he formatting of the way the
  detected objects are written to the log file. This meant the
  verification files were also updated. Also the cube statistics are
  not printed to the results file if a user threshold is specified (as
  they are not calculated!).

* The determination of beam size has been made more reliable, as has
  the BUNIT determination.

* Fixed a bug that meant source merging was not done for 2D images
  (not usually a problem, as the source-finding takes care of this,
  but came up in parallelisation development).

Duchamp version 1.1.3 (2008/01/08)
----------------------------------

A minor update that just improves the build process. The location of
the wcslib include files was not specified correctly, so that some
machines were unable to find them. The configure script has been fixed
so that the compilation should work in all cases. 

Some minor changes have also been made to the code in the PixelMap
directory, and to param.cc, to fix warnings or errors that may appear
in compilation.

However, there are no changes to the actual workings of the code in
this minor version, so if you have a working version of Duchamp 1.1.2
there is probably no reason to update.

Duchamp version 1.1.2 (2007/12/07)
----------------------------------

Compilation:

* The compilation had problems working correctly when the cfitsio and
  wcs libraries were not in standard locations. The configure script
  has been tweaked to make sure the libraries are found.

* Problems with compiling in the absence of pgplot have been fixed,
  and it should now compile fine.

* Improved the configure script for use with Mac OS X and gfortran.


Bugfixing:

* A major problem with the text-based output was fixed. The widths of
  the columns were not being calculated correctly, and were running
  together. This should no longer be the case.

* There was a bug in the way Duchamp interpreted spectral axes,
  particularly AIPS types such as FELO-HEL, leading to incorrect
  scaling of the velocity axis. This has been fixed, so that
  non-standard types are now dealt with appropriately and the velocity
  scaling should be accurate.

* Another bug meant the beam correction was always applied to the
  integrated spectra, regardless of whether the flux units involved
  the beam (e.g. Jy/beam). This has been fixed. Note that the values
  of the integrated flux presented in the results table were always
  calculated correctly.

* Other minor changes to improve the speed and efficiency, especially
  of the merging code.

New user parameters:

* There is now the possibility to save a FITS file that contains a
  mask array, indicating where the detected objects are. This is
  governed by the flagOutputMask parameter.

* The header information that is printed at the start of the results
  file -- that is, the list of parameters, the statistics of the cube,
  and the number of detections -- can now be written to a separate
  file. Set the flagSeparateHeader parameter to true or 1 and it will
  go to the file indicated by the headerFile parameter (the default is
  duchamp-Results.hdr).

* A "scaleMax" parameter has been added, so that the wavelet
  reconstruction can include only a specified range of scales (for
  instance, if one wants to search just for narrow features such as
  absorption lines).

* A "flagRobustStats" parameter has been added. This allows the user
  to elect to use robust statistics (median and median absolute
  deviation from the median) to estimate the noise parameters. If set
  to false, the mean and standard deviation will be used. The default
  value is true.

New Feature:

* When Duchamp is run on a 2D image (i.e. with no spectral output), it
  now produces a postscript file that shows information each
  individual source plus the image cutout of the source. This is
  similar to the spectral output file, but without the spectra. The
  filename is given by the spectraFile parameter.

* Ability to save a FITS file containing a mask array, with pixel
  values of 1 for pixels in a detected object, and 0 elsewhere.


Duchamp version 1.1.1 (2007/07/20)
------------------------------------

Minor update to the release, with just a few changes:

* The verification script was generating diffs due to differences in
  the precision of some calculations when done on different machines. 
  One of these was the integrated flux, and this has been corrected so
  that the same value should appear on all machines.
  The verification script has also changed so that just the number of
  sources and their positions are tested, as well as the
  logfiles. This should avoid the reporting of spurious differences.

* The grey-scale used in the image cutouts (in the spectral plots) has
  been inverted. This makes it consistent with the scale used in the
  maps, and hopefully easier to see when printing.

* The configure/make system has been altered to make it easier to
  install, and to specify different external libraries. In particular,
  it is now not necessary to have PGPLOT installed on your system to
  run Duchamp. In the absence of PGPLOT, Duchamp will run as normal,
  just without any graphical output. Some source code needed to be
  restructured to make this work. Please read the README file, or the
  Installation appendix in the User's Guide, for complete details.

* The time of completion is now written to the log file, so that the
  user can have some idea of how long the program took.


Duchamp version 1.1 (2007/05/17)
------------------------------------

Changes made since the last numbered release:

EFFICIENCY OF EXECUTION:

* Major change to the way detections are stored. They are now recorded
  via run-length encoding in the x-y plane, and stored as collections
  of channel-maps. This improves the memory usage and the speed of
  execution (particularly for routines such as the merging
  routines). The memory usage has also been improved by changing the
  way the list of detected objects is stored.

SMOOTHING:

* Addition of ability to spatially smooth the cube before
  searching. This is done with a Gaussian kernel, the size and shape
  of which can be specified by the user, using the parameters kernMaj
  & kernMin (which are the FWHM for the major & minor axes -- if
  kernMin is not given it is assumed to match kernMaj) and kernPA (the
  position angle of the major axis).  There is a new parameter
  smoothType that distinguishes this method from the spectral (Hanning)
  smoothing already in use.

DETECTIONS:

* Changed the way detection is done -- now only search in 2D images,
  keeping all detections (ie. no minimum-pixel requirement). This
  should be the same as doing both the 1D and 2D searches with the
  minimum pixel requirement in, but simpler. The rejection is done at
  the end after all the merging and growing has been done. This leads
  to a larger number of intermediate detections (ie.  the number
  before merging), which may increase the run-time slightly, although
  this is offset by the changes to the efficiency (see above).

* Increased the range over which objects can be grown to match the
  threshSpatial & threshVelocity parameters, as well as rejecting new
  pixels based on the BLANK and MW tests.

INPUTS:

* There has been a subtle change in the way BLANK pixels are dealt
  with. To enable trimming of BLANK pixels, users should use the new 
  parameter flagTrim. The parameters flagBlankPix and blankPixVal are
  no longer accessible via the parameter file -- warning messages are
  given if they are provided in the parameter file.

* Added ability to specify a statsec, so that the statistics are only
  calculated from a given subsection of the cube, rather than the full
  cube.

* The subsections can also specify the ability to remove a border of n
  pixels from the edges of an axis (ie. n from the start and from the
  end) -- as requested in Trac ticket #5.

* Changed the default value of the reconDim parameter from 3 to 1, and
  the default value of the flagATrous parameter to false.

OUTPUTS:

* The output now includes three different estimates of the "centre" of
  the detection: peak location, centroid (flux-weighted), or average. 

* Some slight improvements to the user feedback during execution.

* Spectral output now includes the baseline, if one was fitted. The
  format of the plot headers is slightly changed, to stop information
  falling off the edge of the page.

* Added command-line option -x to directly disable the PGPLOT X-window
  map plotting. This overrides the setting of flagXOutput in the
  parameter file.

* Fallback spectral units (in case the FITS header fails to record
  them) changed to SPC, but code has been fixed so that any problem
  should be caught before this becomes an issue.

BUGFIXES:

* Fixed bug (Trac ticket #4) that meant the velocity units were not
  correctly dealt with. Duchamp should be more robust for different
  velocity axis setups now.

* Fixed bug (ticket #9) with the VOTable output, where the tags were
  not closing.

* Fixed a bug that meant the integrated fluxes were not calculated
  properly -- no allowance was made for the number of spatial
  pixels. This should also work properly for 2D images now as well.

* Fixed minor bug in calculating the flux threshold from the p-value
  threshold when the FDR method is used. This did not affect the
  actual thresholding, merely the quoted flux threshold in the results
  file. Also, the MW channels are kept out of the p-value threshold
  determination if they are being flagged.



Duchamp version 1.0.7 (2006/11/22)
----------------------------------

One new feature, and some improvements and bug-fixes.

* The user can now elect to Hanning-smooth the spectral direction of
  the cube before the searching is done. This can be done instead of the
  wavelet reconstruction (although if both are selected, the
  reconstruction takes precendence). This functionality is switched on
  and off by the flagSmooth parameter, and the width of the Hanning
  kernel is governed by the hanningWidth parameter.

* The smoothed array can also be written to a FITS file and read in at
  the start in the same manner as the reconstructed array.

* Several improvements have been made to the memory
  management. Several memory leaks were fixed, and the memory usage of
  Duchamp is considerably less, which will be a help for running it on
  large cubes. The speed of some routines has also been improved, by
  removing unnecessarily repetitive loops.

* The sorting routines have been changed, and should now be slightly quicker
  (and a bit more robust).

* Enabled the scale bar (plotted on the 0th moment map in the spectral
  output file) to be able to deal with much finer spatial scales (as
  may be expected from VLBI data).

* Other minor changes to code and presentation.


Duchamp version 1.0.6 (2006/11/01)
----------------------------------

Some incremental improvements and changes to the code:

* The statistics used for the detection are now calculated once for
  the entire cube, rather than being calculated separately for each
  channel map and spectrum. This results in a uniform threshold value
  across the entire cube. The way the statistics calculations are
  implemented in the code was changed, using a new statistics class.

* This means we can report a peak signal-to-noise value for each
  detection. This is given in the text-based output, as well as in the
  summary information above the spectral output for each source.

* The user can now elect not to have the moment map displayed in a
  PGPlot window, through the use of the new flagXOutput
  parameter. This should help in cases of running Duchamp on a dumb
  terminal (with no X-display capabilities), or as part of a batch
  script where the continual popping-up of the PGPlot window might
  become annoying. 

* There are different Flags reported for the case of an object lying on
  the spatial edge and spectral edge of the cube (E and S respectively).

* A few minor bug fixes:
  - When providing a subsection, any axes with the range given by *
    had the pixel values offset incorrectly. This has been fixed.
  - Negative searches now correctly invert the reconstructed array
    when it is read in from a file.

* Other minor changes to the code, to improve memory handling and
  remove redundant arrays and variables.


Duchamp version 1.0.5 (2006/09/06)
----------------------------------

Since version 1.0, there have been a range of mostly minor
changes. These are generally bug-fixes, thanks to feedback from a
number of users, as well as a few extra features. 

Here is a summary of the changes since version 1.0:

USER INTERFACE:

* The user is now able to enter the value of flag parameters in the
  parameter file as strings, as well as integers (so one can enter
  true or 1 to give the same result).

GRAPHICAL OUTPUT:

* Added a new function that draws the edge of the blank region on the
  maps and image cutouts. There is a new flag parameter --
  drawBlankEdges -- that controls the use of this function (the
  default is true).
  Also, the edge of the field is plotted on the image cutouts as a
  yellow line. This distinguishes it from the purple blank pixel
  dividing line.

* The size of the tick mark in the image cutout (indicating the
  spatial scale of the image) is now adaptable, so that it shows the
  scale that best fits the image (ranging from 1 arcsec to 15
  degrees). (This is a change from the previous standard length of 15
  arcmin.)

* The zoomed spectrum had its flux scale determined by all points in
  the zoom box,including those flagged by the Milky Way (MW)
  range. This has been fixed so that any MW channels will not affect
  the flux scaling, potentially improving the appearance of objects
  detected close in velocity to strong MW emission or absorption.

* Improved Karma Annotation file output, so that files without good 
  WCS are dealt with appropriately.

TEXT-BASED OUTPUT:

* The position resolution in the IAU-format names has been increased,
  so that distinct objects close to one another are more readily
  distinguished.  Overlapping sources at different velocities may
  still have the same name, but this is a more general problem.

* The presentation of the results in tabular format has been improved,
  so that the precision of faint sources is sufficient to show their
  flux, for instance, is not 0. This also applies to the information 
  presented above the spectral plots.

* Improved error and warning reporting, so that the formatting and
  presentation of information is clearer.

FITS I/O RELATED:

* The previous version was did not deal well with 4 (or greater)
  dimensions in the FITS file -- the memory allocation was badly done,
  and the axes needed to be in a particular order. This has been
  fixed, so that the FITS I/O routines can now handle any sized FITS
  file, with axes in any order (as long as there are two spatial and one
  spectral axes).

* When the FITS file does not have a rest frequency defined, there is
  no way to transform the frequency axis into velocity. In this case,
  the spectral axis is left as frequency, and put into units of MHz.

* If the beam size is not indicated by the FITS header (through the
  BMAJ and BMIN keywords), the user can manually specify the size
  through the parameter file (using parameter beamSize).

* The FITS I/O routines make use of the command fits_file_exists. This
  was introduced into the CFITSIO package from version 2.5, so Duchamp
  will only work with this version or higher. Version 3+ is preferred.

OTHER BUG-FIXING:

* Several bugs related to the blank-pixels were dealt with.
  The correct values were not propagating through correctly, meaning
  that the default values were being used. Also, there was the
  potential for blank pixels to be detected when the FDR method was
  used. Finally, the image cutout displays occasionally did not
  obscure the blank pixels. All these problems should be fixed now.

* The FDR setup routine was occasionally failing with a segmentation
  fault, due to it accessing unallocated memory. This has been fixed. 

* Fixed bugs that affected the way 2D images (rather than 3D cubes)
  were dealt with. The minChannels test failed when minChannels=0.

* If there is no beam information in the FITS header, the user can now
  enter a beam size as a parameter.

* Other minor fixes to the code, to improve its structure and
  robustness.


Duchamp version 1.0 (2006/06/30)
--------------------------------

The first full release version.

Several major changes compared to previous version:

* Incorporated a FitsHeader class, to keep track of header information
  (including WCS) from the FITS file. All units-related calculations
  are done with this class, such as conversion to velocity, and
  pixel-to-WCS conversion.  The main advantage of this is improved
  speed of execution, more adaptable to different units, and improved
  code (easier for me!).

* Able to select the dimensionality of the reconstruction, rather than
  just doing it in 3-D.

* Robust text output, so that the columns are sized correctly given
  the data being written, and the relevant units (derived from the
  FITS header) are included in the output table.

* Improved the way the reconstructed image is saved and read back in,
  with a better naming scheme and a better set of new FITS header
  keywords. The MW headers are now not written.

Other, more minor changes include:

* MW channels now not set to 0, but just ignored for searching
  purposes (and for the scaling of the spectral output -- they are
  plotted though and highlighted with a hashed box).

* The scale bar in the moment map in the spectral output file has its
  length indicated.

* Improved VOTable output, with more information about the way Duchamp
  was run.

* Made sure all statistics calculations in the reconstruction are
  based on robust (ie. median) methods.

Also moved to an autoconf based configure/make compilation, for ease of use.


Duchamp version 0.9.2 (2006/06/27)
--------------------------------

* Added the use of warning flags for detections: for either edge
  location or negative enclosed flux.

* A new command line option added so that the user can specify a FITS
  file to be searched with the default parameters, rather than giving
  a full parameter file.

* The scale bar on the moment cutout now works in general case, using
  an iterative process to get to the correct length.

* RA axes are now done correctly on the full-scale maps.

* Various coding fixes, improving the readability of the code,
  particularly regarding the declaration of temporary variables.

* Changed the way the time of execution is called : now using time.h
  functions, rather than a system call.

* Changed output in Detection/outputDetection.cc for the pixel
  information of detected objects (the info printed above the spectral
  plots) -- now print out number of voxels in object, and have
  improved the formatting a little.

* Improved the functionality of saving the FITS file containing the
  reconstructed array. Added ability to save and read back in the MW
  parameters when saving a reconstructed cube (if a reconstructed cube
  has different MW range to that being considered, it would cause
  problems). ReadRecon now just returns a FAILURE and will reconstruct
  the cube anew.

* Changed default value of flagGrowth to 0. 



Duchamp version 0.9 (2006/05/05)
--------------------------------

First public release version.