Notes on individual classes

Channel

• The source and sink functions are specified by supplying two objects: the source object should be an instance of a class that provides a method called astsource, and the sink object should be an instance of a class that provides a method called astsink. The read() method of the Channel class calls the astsource method repeatedly with no arguments, and expects it to return a string holding the next line of text input to store in the Channel. Likewise, write() method of the Channel class will call the astsink method repeatedly with a single argument, the text of the next line to store in the external data sink, and will ignore anything returned by astsink.

FitsChan

• As with the basic Channel class, the source and sink functions are specified by supplying objects that provides methods called astsource and astsink. Note, the starlink.Atl module contains a class, PyFITSAdapter, that can be used to provide such methods for the specific case where the external data source is a PyFITS header.

• When invoking the read method to read an object from a FitsChan, the FitsChan's "Card" attribute will be cleared automatically before the read is performed. This means it is not necessary to clear "Card" explicitly before calling the read method (as is required in C and Fortran).

• The FitsChan class is an iterable class in Python. So, for instance, if "fc" is a reference to a FitsChan, you can loop round all cards in the FitsChan by doing

  >>> for card in fc:
  >>>    print(card)

  However, this is achieved by incrementing the Card attribute of the FitsChan. So the looping will be affected by any other operation that changes the Card attribute of the FitsChan during the loop.

• The FitsChan class can be used as a python mapping. So for instance, if "fc" is a reference to a FitsChan, you can assign a value to the NAXIS1 keyword by doing

  >>> fc["NAXIS1"] = 1200

  If a card for the keyword already exists in the FitsChan, the value of the card will be changed. If the FitsChan does not contain a card for the named keyword, a new card will be appended to the end of the FitsChan. You can retrieve the value of the a keyword in a similar way: for instance,

  >>> crval1 = fc["CRVAL1"]

  Note, if a keyword occurs more than once in a FitsChan, the the retrieved value will be a tuple containing all the individual keyword values.

• If a FitsChan is index using integers, the value returned is the whole 80-column header card at the given zero-based index. When assigning to an element of a FitsChan indexed by an integer, the assigned value should be a whole 80-column header card, which will overwrite the existing card at the given index. If the index is larger than the number of cards in the FitsChan, the new card will be appended to the end of the FitsChan.

Frame

• The methods astGetActiveUnit and astSetActiveUnit are not present in PyAST. Instead, each Frame has a Python property called "ActiveUnit", which takes boolean values True or False, and can be set and get just like any other property.

  >>> print( frame.ActiveUnit )
  >>> frame.ActiveUnit = True

KeyMap

• Currently, none of the methods available within AST for the KeyMap class are available in Python. However, KeyMaps can be created in the usual way, and entries can be written to or read from a KeyMap using the syntax of a Python mapping. For instance:

  >>> import starlink.Ast as Ast
  >>> km = Ast.KeyMap()
  >>> km['fred'] = 1.2

  Note, only strings and integers should be used as keys with a KeyMap. If a string is used, the returned value is the value of the KeyMap entry with the specified key. If an integer is used, the returned value is a tuple containing the key and value of the corresponding entry in the KeyMap (the order in which entries are returned is specified by the SortBy attribute of the KeyMap). When setting a value, a starlink.Ast.MPIND exception is reported if the specified zero-based integer index is greater than or equal to the number of entries in the KeyMap.

• Each KeyMap object is iterable, each item being returned as a (key,value) tuple.

  >>> for (k,v) in km:
  >>>    print(k)
  >>>    print(v)

Plot

• The Plot class does not draw any graphics itself. Instead, it invokes the methods of a specified "grf" object to draw lines, text strings, markers, etc. A reference to such a "grf" object must be supplied when a Plot is created. PyAST provides the starlink.Grf.grf_matplotlib class, that uses the facilities of the matplotlib library to plot the required primitives. So, the following code will create an annotated coordinate grid covering a square in a simple default 2D Frame:

  import matplotlib.pyplot as plt
  import starlink.Ast as Ast
  import starlink.Grf as Grf
  
  # Create a matplotlib figure covering the whole work space
  fig = plt.figure()
  
  # Create a matplotlib "Axes" (i.e. the plotting region) covering the whole
  # Figure. Ensure that the matplotlib axis annotations are not drawn.
  ax = fig.add_subplot(111)
  ax.xaxis.set_visible(False)
  ax.yaxis.set_visible(False)
  
  # Create a grf module that knows how to draw into the matplotlib plotting
  # region.
  grf = Grf.grf_matplotlib( ax )
  
  # Store the required bounds of the Plot within the plotting region.
  gbox = ( 0.1, 0.1, 0.9, 0.9 )
  
  # Store the required bounds of the Plot within the simple default Frame.
  bbox = ( -1.0, -1.0, 1.0, 1.0 )
  
  # Create the Plot, using the above grf object, and using a default Frame.
  plot = Ast.Plot( None, gbox, bbox, grf )
  
  # Set some niceattributes for the plot. Note, colours can be supplied in any
  # form that is acceptable to matplotlib.
  plot.Colour_Border = "lime"
  plot.Colour_Ticks = "lime"
  plot.MajTickLen = 0.02
  plot.Width_TextLab = 2
  plot.Width_NumLab = 2
  plot.Width_Title = 2
  
  # Draw a coordinate grid.
  plot.grid()
  
  # Display everything.
  plt.show()
  

  Other such classes could be written based on other graphics libraries, following the pattern of the grf_matplotlib class (for more detailed documentation on the required methods, see also the grf_pgplot.c file in the AST source distribution).

Table

• The following AST attributes have no corresponding Python properties due to the fact that the names are not static. Instead, they attribute values can be accessed using methods with the same names.
  • ColumnLenC
  • ColumnLength
  • ColumnType
  • ColumnNdim
  • ColumnUnit
  For instance, to print the value of the AST attribute "ColumnLength(BValues)", you should do: >>> print( table.columnlength( 'BValues' ) )

FitsTable

• The astPutColumnData and astGetColumnData methods are not implemented in PyAST - instead, access the individual cells of the table as entries within a KeyMap.