Introduction

This section contains an overview of PyAST and its relationship to AST. It does not give details of the AST library itself.

What is PyAST?

PyAST is a collection of modules that allows the facilities of the Starlink AST library to be used within Python (version 2.7 or later) scripts.

What is AST?

The AST library provides a comprehensive range of facilities for attaching world coordinate systems to astronomical data, for retrieving and interpreting that information and for generating graphical output based on it. AST is written in ANSI C but has wrappers for various other languages, including Fortran, Java, Perl, and now Python.

About this document:

This document does not provide a full description of the facilities of AST, or of the AST wrapper functions provided by PyAST. For general information about how to use AST, or the specifics of individual functions and their parameters, the main AST documentation describing the native C interface should be consulted.

Requirements:

PyAST requires Python version 2.7 or later to be installed, and requires the numpy package.It has no other dependencies (a copy of the AST library itself is bundled with PyAST). However, PyAST includes extra optional facilities that assume the presence of other python libraries:

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:

The current version of PyAST can be downloaded from github. To build it, unpack the tar file and then do:

% python setup.py install

To test it, do:

% python starlink/ast/test/test.py

Using PyAST:

First import the PyAST module (starlink.Ast). For instance:

>>> 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
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.
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.