CIAO 4.0 to 4.1 upgrade guide

• State files from CIAO 4.0 can not be used in CIAO 4.1
• Filled Histograms and Regions
• Annotations are now parts of a Plot and not a Frame

State files from CIAO 4.0 can not be used in CIAO 4.1

Due to the changes in the object hierarchy for annotations, binary state files created by save_state (S-Lang or Python help) in CIAO 4.0 can not be read into CIAO 4.1. Trying to do so will result in an error message like:

chips ERROR: Unable to load incompatible state file (unsupported major version)

Please contact the CXC Helpdesk if this is a problem for you.

Filled Histograms and Regions

In CIAO 4.0 the fill.visible attribute determined whether a histogram or region was drawn empty (when set to 0) or with a solid fill (when set to 1).

Using this attribute name in CIAO 4.1 will now result in an error message like one of the following:

chips ERROR: Unknown or unsupported <obj>.<attribute> entry: fill.visible
chips ERROR: Invalid ChipsHistogram attribute 'fill.visible' in list.
chips ERROR: Invalid ChipsRegion attribute 'fill.visible' in list.

This has happened because ChIPS now supports a range of Fill Patterns for histograms and regions, and to do so the attribute name was changed from fill.visible to fill.style. To update to CIAO 4.1, you will need to change:

1. all occurrences of fill.visible to fill.style;

2. change the value from 0 to "nofill" and from 1 to either "solidfil" or one of the new fill pattern names, such as "updiagonal".

Annotations are now parts of a Plot and not a Frame

In CIAO 4.0 the object hierarchy - in other words how are objects related - looked like:

      WINDOWS--------------------------+ 
      |   FRAMES-------------------+   | 
      |   |   LABELS               |   | 
      |   |   LINES                |   | 
      |   |   PLOTS -----------+   |   | 
      |   |   |   AXES         |   |   | 
      |   |   |   CONTOURS     |   |   |
      |   |   |   CURVES       |   |   |
      |   |   |   HISTOGRAMS   |   |   |
      |   |   +----------------+   |   |
      |   |   POINTS               |   | 
      |   |   REGIONS              |   | 
      |   +------------------------+   |
      +--------------------------------+

This has changed - in CIAO 4.1 - to the following:

      WINDOWS--------------------------+ 
      |   FRAMES-------------------+   | 
      |   |   PLOTS -----------+   |   | 
      |   |   |   AXES         |   |   | 
      |   |   |   CONTOURS     |   |   |
      |   |   |   CURVES       |   |   |
      |   |   |   HISTOGRAMS   |   |   |
      |   |   |   LABELS       |   |   | 
      |   |   |   LINES        |   |   | 
      |   |   |   POINTS       |   |   | 
      |   |   |   REGIONS      |   |   | 
      |   |   +----------------+   |   |
      |   +------------------------+   |
      +--------------------------------+

In other words the annotations - labels, lines, points, and regions - are now parts of a Plot and not a Frame.

For most use cases this will not change the appearance of a plot. The main time that the change will make a noticeable difference is when an annotation is either added to a frame with no plot, or is the first ChIPS command to create a window. In CIAO 4.1 this call will now automatically create a plot for the annotation to live in. To hide this plot from display, change the plot style to "open" either when creating the annotation - e.g.

# Python
add_label(0.05, 0.9, "file=src.fits", ["plot.style", "open", "coordsys", FRAME_NORM])

% S-Lang
add_label(0.05, 0.9, "file=src.fits", {"plot.style", "open", "coordsys", FRAME_NORM});

or after the annotation has been created:

# Python
add_point(0.5, 0.5, ["style", "diamond", "size", 8, "coordsys", FRAME_NORM])
set_plot(["style", "open"])

% S-Lang
add_point(0.5, 0.5, {"style", "diamond", "size", 8, "coordsys", FRAME_NORM});
set_plot({"style", "open"});

Note that we have also used the coordsys attribute (which is new to CIAO 4.1) to make sure the annotations are placed in frame normalized coordinates (as they would have been in CIAO 4.0) since they default to using plot-normalized coordinates in this situation.