Introduction

What is PyAST?

What is AST?

About this document:

Requirements:

• If the matplotlib graphics library is available, then the starlink.Grf.grf_matplotlib "GRF module" can be used with the PyAST starlink.Ast.Plot class to produce annotated coordinate grids, etc. To use any other graphics system, an equivalent GRF module must be written.

  Note, if using PyAST with Python version 3, it is necessary to use the "matplotlib for Python 3" branch.

• If the PyFITS library is available, then the starlink.Atl.PyFITSAdapter class provides a simple means of transferring FITS header cards bwteeen PyFITS headers and the PyAST FitsChan class.

Obtaining and installing PyAST:

% python setup.py install

To test it, do:

% python starlink/ast/test/test.py

Using PyAST:

>>> import starlink.Ast as Ast

The following is a list of general points about how to use PyAST (until more appropriate examples are produced, the PyAST test script - starlink/ast/test/test.py - can be consulted for examples of how to use the functions provided by PyAST):

• Each AST object class has a corresponding Python class (e.g. the AST ZoomMap class corresponds to Python type starlink.Ast.ZoomMap)
• Each Python method name is the lower case equivalent of the corresponding AST method name, but without the "ast" prefix (e.g. the "astTranN" method becomes "trann" in Python).
• If an AST function fails, it will raise a Python Exception. Each AST error code listed in the AST header file "ast.h" has a corresponding subclass of Exception (e.g. the Exception subclass starlink.Ast.ZOOMI is raised if an AST function returns an error code of AST__ZOOMI). All of these Exception subclasses inherit from the single Exception type starlink.Ast.AstError, which itself inherits from Exception.
• When reading the AST C documentation, remember that an AST "attribute" is a property (i.e. an item of data) of a class instance. In the AST sense, methods are not conisdered to be attributes of an object.
• In C, each AST constructor has a final "options" parameter, which allow the attributes of the new object to be specified as a comma-separated list of "attribute=value" strings. Each PyAST wrapper has an equivalent optional string parameter. If the parameter is omitted, the object attributes will be left at their default values. A future version of PyAST may allow attributes to be set using the usual Python approach of an optional set of keyword arguments.
• Each AST Object "attribute" (as listed in the C documentation) has a corresponding Python property with the same name. So for instance, either of the following can be used to set the "Zoom" attribute (the zoom factor) in a ZoomMap refered to by "zm":

  >>> zm.set("Zoom=1.2")
  >>> zm.Zoom = 1.2

  Note, some AST attributes are multi-valued, with individual values being refered to by attribute names of the form "name(index)" (i.e. the attribute name followed by a numerical of string index in parentheses). The corresponding Python properties are of the form "name_index" (i.e.the index is appended with an underscore rather than being enclosed in parentheses). For instance, either of the following will set the Label attribute for the second axis of a Frame:

  >>> frm.set("Label(2)=Flux density")
  >>> frm.Label_2 = "Flux density"

  and this will set the colour of a Plot border to colour index 1:

  >>> plot.set("Colour(Border)=1")
  >>> Plot.Colour_Border = 1

  Colours: - when a colour is specified within an options string (as in the first of the above two examples), only integer values are allowed. However, when using the equivalent Python property (as in the second of the above examples), colours may also be specified as strings, if this is allowed by the Grf module in use. The default matplotlib Grf module supplied with pyast allows colours to be specified using any string format that is recognised by matplotlib. So the second example could for instance be replaced by:

  >>> Plot.Colour_Border = "lime"

  Note, when retrieving the value of a colour property, the colour will be converted to a named colour if possible, and will be represented as a hex HTML colour string otherwise. For instance:

  >>> Plot.Colour_Border = "#000000"
  >>> print( Plot.Colour_Border )
  'black'
  >>> Plot.Colour_Border = "#FFEBC0"
  >>> print( Plot.Colour_Border )
  '#FFEBC0'
  

• AST attributes can be retrieved using the starlink.Ast.get() method or the corresponding Python property:

  >>> print( zm.get("Zoom") )
  >>> print( zm.Zoom )

• The testing and clearing of AST attributes can only be done using the starlink.Ast.test() and starlink.Ast.clear() methods:

  >>> zm.clear("Zoom")
  >>> zm.test("Zoom")

• AST defines many constants. These are referred to in the C documentation using names of the form AST__xxx (e.g. AST__BAD). In Python, these constants are available as starlink.Ast.xxx (e.g. starlink.Ast.BAD).
• See section "Implemented AST functions" for details of the API for all functions provided by PyAST. In general, the argument lists for PyAST functions and methods are as listed in the C documentation, except that values returned via supplied pointers are instead returned as part of the function value. If this means that a PyAST function returns more than one value, they will be contained within a tuple. If the C AST function returns a non-void function value, it will be the first element in the tuple. Any other values returned by the C function via supplied C pointers will be returned as subsequent elements of the tuple, in the order in which the C pointers appear in the argument list of the C function. If the C function does not return any values via C pointers, then the returned Python value will be a single object reference rather than a tuple.
• In general, the PyAST wrapper for a function will omit arguments that are present in the C interface if their values can be derived from other arguments. In particular, if an array or list is supplied as an argument, the length of the array or list does not need to be supplied using a separate parameter, as is done in the C interface.
• When an array is expected as an argument, a numpy array of floating point values, or any sequence (lists, tuples, etc.) that can be converted to a numpy array, should be supplied.
• When a set of integer indices are supplied to identify a position within a multi-dimensional pixel array, the indices should be supplied in an order such that the fastest changing index (within the linear list of contiguous values) comes first. For instance, several functions require the upper and lower bounds of a pixel array to be supplied. If the array is (say) 2-dimensional the first supplied element in each case should should be the index of a column and the second should be the index of a row.
• Most methods for which AST provides variants for different data types (e.g. astRebin, astRebinSeq, astResample, etc) are unified into one method in the Python interface. The names of such function are the same as the AST names, but without any final letter indicating the data type (e.g. astRebinD, astRebinF and astRebinI are replaced by starlink.Ast.Mapping.rebin). The data type to use is determined from the supplied array containing the input data.

PyAST Licensing: