Implemented AST functions
The starlink.Ast module provides Python wrappers for the following AST
functions. For each function, the corresponding Python API is displayed
on a yellow background, together with any explanatory notes. For
information about the purpose and parameters of each function, click on
the "ast..." function name to display the AST reference documentation
from SUN/211.
For examples of calling these wrappers, see the PyAST test script
(starlink/ast/test/test.py).
General Notes:
- A returned value of "
result" refers to the function value
returned by the corresponding C function.
- When the C documentation refers to a NULL pointer, "
None" should be
used instead.
- Parameters that are optional in the Python API are indicated by
strings of the form "
name=default".
- Constructors are shown preceeded by the full module name
"
starlink.Ast".
- Methods are shown preceeded by a reference with name equal to the class
that provides the method.
•
astAddColumn - Add a new column definition to a table
- table.addcolumn( name, type, dims=None, unit="" )
•
astAddFrame - Add a Frame to a FrameSet to define a new coordinate system
- frameset.addframe( iframe, map, frame )
•
astAddParameter - Add a new global parameter definition to a table
- table.addparameter( name )
•
astAngle - Calculate the angle subtended by two points at a third point
- result = frame.angle( a, b, c )
•
astAxAngle - Returns the angle from an axis, to a line through two points
- result = frame.axangle( a, b, axis )
•
astAxDistance - Find the distance between two axis values
- result = frame.axdistance( axis, v1, v2 )
•
astAxOffset - Add an increment onto a supplied axis value
- result = frame.axoffset( axis, v1, dist )
•
astBBuf - Begin a new graphical buffering context
•
astBorder - Draw a border around valid regions of a Plot
•
astBoundingBox - Return a bounding box for previously drawn graphics
- ( lbnd, ubnd ) = plot.boundingbox( )
•
astBox - Create a Box
- box = starlink.Ast.Box( frame, form, point1, point2, unc=None, options=None )
•
astChannel - Create a Channel
- channel = starlink.Ast.Channel( source=None, sink=None, options=None )
- If supplied, the "source" argument can either be a reference to an object that provides a method named "astsource", or a sequence. In the first case, the "astsource" method will be invoked with no arguments, and should return the next line of text on each invocation, returning None when all text has been read. In the second case, each element of the sequence is converted to a string and used as the next line of text.
- If supplied, the "sink" argument should be a reference to an object that provides a method named "astsink". This method is called with each succesive line of text as its only argument, and should store each line in some external data sink.
•
astCircle - Create a Circle
- circle = starlink.Ast.Circle( frame, form, centre, point, unc=None, options=None )
•
astClear - Clear attribute values for an Object
•
astClip - Set up or remove clipping for a Plot
- plot.clip( iframe, lbnd, ubnd )
•
astCmpFrame - Create a CmpFrame
- cmpframe = starlink.Ast.CmpFrame( frame1, frame2, options=None )
•
astCmpMap - Create a CmpMap
- cmpmap = starlink.Ast.CmpMap( map1, map2, series=True, options=None )
•
astCmpRegion - Create a CmpRegion
- cmpregion = starlink.Ast.CmpRegion( region1, region2, oper=starlink.Ast.OR, unc=None, options=None )
•
astColumnName - Get the name of the column at a given index within the Table
- result = table.columnname( index )
•
astColumnNull - Get or set the null value for an integer column of a FITS table
- ( result, wassset, hasnull ) = fitstable.columnnull( name, set=0, newval=0 )
•
astColumnShape - Returns the shape of the values in a named column
- result = table.columnshape( column )
•
astColumnSize - Get the number of bytes needed to hold a full column of data
- result = fitstable.columnsize( column )
•
astConvert - Determine how to convert between two coordinate systems
- result = frame.convert( from, to, domainlist=None )
•
astCopy - Copy an Object
- result = object.copy( )
- The "
deepcopy" function in the copy module can also be used to create a deep copy of a PyAST object.
•
astCurrentTime - Return the current system time
- result = timeframe.currenttime( )
•
astCurve - Draw a geodesic curve
- plot.curve( start, finish )
•
astDSBSpecFrame - Create a DSBSpecFrame
- dsbspecframe = starlink.Ast.DSBSpecFrame( options=None )
•
astDecompose - Decompose a Mapping into two component Mappings
- ( map1, map2, series, invert1, invert2 ) = mapping.decompose( )
•
astDelFits - Delete the current FITS card in a FitsChan
•
astDistance - Calculate the distance between two points in a Frame
- result = frame.distance( point1, point2 )
•
astDownsize - Reduce the number of vertices in a Polygon
- result = polygon.downsize( maxerr, maxvert )
•
astEBuf - End the current graphical buffering context
•
astEllipse - Create a Ellipse
- ellipse = starlink.Ast.Ellipse( frame, form, centre, point1, point2, unc=None, options=None )
•
astEmptyFits - Delete all cards in a FitsChan
- result = fitschan.emptyfits( )
•
astEscapes - Control whether graphical escape sequences are included in strings
- result = starlink.Ast.escapes( newval )
- This is a static module function.
•
astFindFits - Find a FITS card in a FitsChan by keyword
- ( result, card ) = fitschan.findfits( name, inc=False )
•
astFindFrame - Find a coordinate system with specified characteristics
- result = frame.findframe( template, domainlist=None )
•
astFitsChan - Create a FitsChan
- fitschan = starlink.Ast.FitsChan( source=None, sink=None, options=None )
- If supplied, the "source" argument can either be a reference to an object that provides a method named "astsource", or a sequence. In the first case, the "source" method is called with no arguments, and should return the next header card on each invocation, returning None when all cards have been read. In the second case, each element of the sequence is converted to a string and used as the next header card.
- If supplied, the "sink" argument should be a reference to an object that provides a method named "astsink". This method is called with each succesive header card as its only argument, and should store each card in some external data sink.
•
astFitsTable - Create a FitsTable
- fitstable = starlink.Ast.FitsTable( header=None, options=None )
•
astFluxFrame - Create a FluxFrame
- fluxframe = starlink.Ast.FluxFrame( specval=starlink.Ast.BAD, specfrm=None, options=None )
•
astFrame - Create a Frame
- frame = starlink.Ast.Frame( naxes, options=None )
•
astFrameSet - Create a FrameSet
- frameset = starlink.Ast.FrameSet( frame, options=None )
•
astGet - Get an attribute value for an Object
- result = object.get( attrib )
- The starlink.Ast.get() method is equivalent to astGetC in that it always returns the string representation of the AST attribute value. By contrast, each Python property returns the attribute value using the native data type of the AST attribute (integer, boolean, floating point or string).
•
astGetFits<X> - Get a named keyword value from a FitsChan
- ( result, value ) = fitschan.getfits<X>( name )
- Replace the <X> in the Python function name with one of F, I, L, S, CN, CF or CI to select the data type of the returned value.
•
astGetFrame - Obtain a pointer to a specified Frame in a FrameSet
- result = frameset.getframe( iframe=starlink.Ast.CURRENT )
•
astGetMapping - Obtain a Mapping that converts between two Frames in a FrameSet
- result = frameset.getmapping( iframe1=starlink.Ast.BASE, iframe2=starlink.Ast.CURRENT )
•
astGetRefPos - Return the reference position in a specified celestial coordinate system
- ( lon, lat ) = specframe.getrefpos( frm )
•
astGetRegionBounds - Returns the bounding box of Region
- ( lbnd, ubnd ) = region.getregionbounds( )
•
astGetRegionFrame - Obtain a pointer to the encapsulated Frame within a Region
- result = region.getregionframe( )
•
astGetTables - Retrieve any FitsTables currently in a FitsChan
- result = fitschan.gettables( )
•
astGrid - Draw a set of labelled coordinate axes
•
astGridLine - Draw a grid line (or axis) for a Plot
- plot.gridline( axis, start, length )
•
astGrismMap - Create a GrismMap
- grismmap = starlink.Ast.GrismMap( options=None )
•
astHasAttribute - Test if an Object has a named attribute
- result = object.hasattribute( attrib )
•
astHasColumn - Returns a flag indicating if a column is present in a Table
- result = table.hascolumn( column )
•
astHasParameter - Returns a flag indicating if a named global parameter is present in a Table
- result = table.hasparameter( parameter )
•
astIntersect - Find the point of intersection between two geodesic curves
- cross = frame.intersect( a1, a2, b1, b2 )
•
astInterval - Create a Interval
- interval = starlink.Ast.Interval( frame, lbnd, ubnd, unc=None, options=None )
•
astKeyMap - Create a KeyMap
- keymap = starlink.Ast.KeyMap( options=None )
•
astLinearApprox - Obtain a linear approximation to a Mapping, if appropriate
- ( result, fit ) = mapping.linearapprox( lbnd, ubnd, tol )
•
astLock - Lock an Object for exclusive use by the calling thread
•
astLutMap - Create a LutMap
- lutmap = starlink.Ast.LutMap( lut, start=0.0, inc=1.0, options=None )
•
astMapBox - Find a bounding box for a Mapping
- ( lbnd_out, ubnd_out, xl, xu ) = mapping.mapbox( lbnd_in, ubnd_in, coord_out, forward=1 )
•
astMapRegion - Transform a Region into a new Frame using a given Mapping
- result = region.mapregion( map, frame )
•
astMapSplit - Split a Mapping up into parallel component Mappings
- ( out, map ) = mapping.mapsplit( in )
•
astMark - Draw a set of markers for a Plot
•
astMatchAxes - Find any corresponding axes in two Frames
- axes = frame.matchaxes( frm2 )
•
astMathMap - Create a MathMap
- mathmap = starlink.Ast.MathMap( nin, nout, fwd, inv, options=None )
•
astMatrixMap - Create a MatrixMap
- matrixmap = starlink.Ast.MatrixMap( matrix, options=None )
- The supplied array of matrix element values must be either 1- or 2- dimensional. If it is 1-dimensional, it is assumed to contain the values for the diagonal of the (square) matrix, all other elements being zero. In this case the length of the array determines the number of inputs and outputs for the Matrixmap. If the array is 2-dimensional, it should consist of a list in which each element is a list of values for a single row of the matrix. For instance, the 2-dimensional array [[1,2,3],[4,2,1]] specifies a matrix with two rows and three columns. The resulting MatrixMap would have Nin=3 and Nout=2.
•
astNorm - Normalise a set of Frame coordinates
- value = frame.norm( value )
•
astNormMap - Create a NormMap
- normmap = starlink.Ast.NormMap( frame, options=None )
•
astNullRegion - Create a NullRegion
- nullregion = starlink.Ast.NullRegion( frame, unc=None, options=None )
•
astOffset - Calculate an offset along a geodesic curve
- point3 = frame.offset( point1, point2, offset )
•
astOffset2 - Calculate an offset along a geodesic curve in a 2D Frame
- ( result, point2 ) = frame.offset2( point1, angle, offset )
•
astOutline - Create a new Polygon outling values in a 2D data grid
- result = starlink.Ast.outline( value, oper, array, lbnd, ubnd, maxerr, maxvert, inside, starpix )
- This is a static module function.
•
astOverlap - Test if two regions overlap each other
- result = region.overlap( that )
•
astParameterName - Get the name of the global parameter at a given index within the Table
- result = table.parametername( index )
•
astPcdMap - Create a PcdMap
- pcdmap = starlink.Ast.PcdMap( disco, pcdcen, options=None )
•
astPermMap - Create a PermMap
- permmap = starlink.Ast.PermMap( inperm, outperm, constant=None, options=None )
•
astPickAxes - Create a new Frame by picking axes from an existing one
- ( result, map ) = frame.pickaxes( axes )
•
astPlot - Create a Plot
- plot = starlink.Ast.Plot( frame, gbox, bbox, grf, options=None )
- The "grf" argument is a reference to an object that provides primitive drawing fiunctions for the Plot. PyAST provides the starlink.Grf.grf_matplotlib class that implements the required operations using the matplotlib plotting package. Others can be written following the same pattern.
•
astPointList - Create a PointList
- pointlist = starlink.Ast.PointList( frame, points, unc=None, options=None )
•
astPolyMap - Create a PolyMap
- polymap = starlink.Ast.PolyMap( fcoeff, icoeff=None, options=None )
•
astPolyTran - Fit a PolyMap inverse or forward transformation
- result = polymap.polytran( forward, acc, maxacc, maxorder, lbnd, ubnd )
•
astPolygon - Create a Polygon
- polygon = starlink.Ast.Polygon( frame, points, unc=None, options=None )
•
astPrism - Create a Prism
- prism = starlink.Ast.Prism( region1, region2, unc=None, options=None )
•
astPurgeWCS - Delete all cards in the FitsChan describing WCS information
•
astPutCards - Store a set of FITS header cards in a FitsChan
- fitschan.putcards( cards )
•
astPutFits - Store a FITS header card in a FitsChan
- fitschan.putfits( card, overwrite=False )
•
astPutTable - Store a single FitsTable in a FitsChan
- fitschan.puttable( table, extnam )
•
astPutTables - Store one or more FitsTables in a FitsChan
- fitschan.puttables( tables )
•
astQuadApprox - Obtain a quadratic approximation to a 2D Mapping
- ( result, fit, rms ) = mapping.quadapprox( lbnd, ubnd, nx, ny )
•
astRate - Calculate the rate of change of a Mapping output
- result = mapping.rate( at, ax1=1, ax2=1 )
•
astRateMap - Create a RateMap
- ratemap = starlink.Ast.RateMap( map, ax1=1, ax2=1, options=None )
•
astRead - Read an Object from a Channel
- result = channel.read( rewind=True )
- The "rewind" argument indicates if the Channel should be rewound before the read is performed. Currently, this only has any effect if the Channel is an instance of the FitsChan class, in which case it causes the "Card" attribute to be cleared before the read is performed.
•
astReadFits - Read cards into a FitsChan from the source function
- result = fitschan.readfits( )
•
astRebin - Rebin a region of a data grid
- ( out, out_var ) = mapping.rebin( wlim, lbnd_in, ubnd_in, in, in_var, spread, params, flags, tol, maxpix, badval_d, lbnd_out, ubnd_out, lbnd, ubnd )
•
astRebinSeq - Rebin a region of a sequence of data grids
- nused = mapping.rebinseq( wlim, lbnd_in, ubnd_in, in, in_var, spread, params, flags, tol, maxpix, badval_d, lbnd_out, ubnd_out, lbnd, ubnd, out, out_var, weights, nused )
•
astRemapFrame - Modify a Frame's relationship to other Frames in a FrameSet
- frameset.remapframe( iframe, map )
•
astRemoveColumn - Remove a column from a table
- table.removecolumn( column )
•
astRemoveFrame - Remove a Frame from a FrameSet
- frameset.removeframe( iframe=starlink.Ast.CURRENT )
•
astRemoveParameter - Remove a global parameter from a table
- table.removeparameter( name )
•
astRemoveRegions - Remove any Regions from a Mapping
- result = mapping.removeregions( )
•
astRemoveTables - Remove one or more tables from a FitsChan
- fitschan.removetables( key )
•
astResample - Resample a region of a data grid
- ( result, out, out_var ) = mapping.resample( lbnd_in, ubnd_in, in, in_var, interp, params, flags, tol, maxpix, badval_d, lbnd_out, ubnd_out, lbnd, ubnd )
- There is no "finterp" argument, and the AST__UKERN1 and AST__UINTERP interpolation schemes are not supported in PyAST.
•
astResolve - Resolve a vector into two orthogonal components
- ( point4, d1, d2 ) = frame.resolve( point1, point2, point3 )
•
astRetainFits - Indicate that the current card in a FitsChan should be retained
•
astSame - Test if two AST pointers refer to the same Object
- result = object.same( that )
•
astSet - Set an attribute value for an Object
•
astSetFits<X> - Store a keyword value in a FitsChan
- fitschan.setfits<X>( name, value, comment=None, overwrite=False )
- Replace the <X> in the Python function name with one of F, I, L, S, CN, CF or CI to indicate the data type of the supplied value.
•
astSetRefPos - Set the reference position in a specified celestial coordinate system
- specframe.setrefpos( frm, lon, lat )
•
astShiftMap - Create a ShiftMap
- shiftmap = starlink.Ast.ShiftMap( shift, options=None )
•
astShow - Display a textual representation of an Object on standard output
•
astSimplify - Simplify a Mapping
- result = mapping.simplify( )
•
astSkyFrame - Create a SkyFrame
- skyframe = starlink.Ast.SkyFrame( options=None )
•
astSkyOffsetMap - Returns a Mapping which goes from absolute coordinates to offset coordinates
- result = skyframe.skyoffsetmap( )
•
astSpecFluxFrame - Create a SpecFluxFrame
- specfluxframe = starlink.Ast.SpecFluxFrame( frame1, frame2, options=None )
•
astSpecFrame - Create a SpecFrame
- specframe = starlink.Ast.SpecFrame( options=None )
•
astSphMap - Create a SphMap
- sphmap = starlink.Ast.SphMap( options=None )
•
astStcsChan - Create an StcsChan
- stcschan = starlink.Ast.StcsChan( source=None, sink=None, options=None )
- If supplied, the "source" argument can either be a reference to an object that provides a method named "astsource", or a sequence. In the first case, the "source" method is called with no arguments, and should return the next line of text on each invocation, returning None when all text has been read. In the second case, each element of the sequence is converted to a string and used as the next line of text.
- If supplied, the "sink" argument should be a reference to an object that provides a method named "astsink". This method is called with each succesive line of text as its only argument, and should store each line in some external data sink.
•
astTable - Create a Table
- table = starlink.Ast.Table( options=None )
•
astTableSource - Register a source function for accessing tables in FITS files
- fitschan.tablesource( tabsource )
- If supplied, the "tabsource" argument should be a reference to an object that provides a method named "asttablesource". This method will be invoked with arguments (fc,extname,extver,extlevel), where "fc" is a reference to the FitsChan. Any returned value will be ignored. See the documentation for astTableSource for more information.
•
astTest - Test if an Object attribute value is set
- result = object.test( attrib )
•
astTestFits - See if a named keyword has a defined value in a FitsChan
- ( result, there ) = fitschan.testfits( name )
•
astText - Draw a text string for a Plot
- plot.text( text, pos, up=[0, 1], just="CC" )
•
astTimeAdd - Add a time coordinate conversion to a TimeMap
- timemap.timeadd( cvt, args )
•
astTimeFrame - Create a TimeFrame
- timeframe = starlink.Ast.TimeFrame( options=None )
•
astTimeMap - Create a TimeMap
- timemap = starlink.Ast.TimeMap( flags=0, options=None )
•
astTranGrid - Transform a grid of positions
- out = mapping.trangrid( lbnd, ubnd, tol=0, maxpix=50, forward=True )
- The "lbnd" and "ubnd" arguments are 1-dimensional numpy arrays of integers, or any sequence (lists, tuples, etc.) that can be converted to a numpy array. The length of these arrays must equal the number of inputs for the Mapping. The returned value (out) is a 2-dimensional numpy array holding the mapping output values at the grid points.
•
astTranMap - Create a TranMap
- tranmap = starlink.Ast.TranMap( map1, map2, options=None )
•
astTranN - Transform N-dimensional coordinates
- out = mapping.tran( in, forward=True, out=None )
- The "
tran" method combines the functions of astTran1, astTran2, and astTranN.
- The "in" argument should be a 2-dimensional array with shape (nin,npoint), where "nin" is the number of inputs for the Mapping, and "npoint" is the number of positions to transform.
- If the Mapping has only a single input then a 1-dimensional array may be supplied for "nin" with length (npoint).
- If the "out" argument is supplied, it should be an existing 1- or 2-dimensional numpy array with a shape of (npoint) (if 1-dimensional) or (nout,npoint) (if 2-dimensional), where "nout" is the number of outputs from the Mapping and "npoint" is the number of positions being transformed. A 1-dimensional array may be supplied only if "nout" is 1. If "out" is supplied supplied, the transformed stored are stored in the supplied array. If not supplied, a new array with suitable shape is created to store the transformed positions. In either case, the value returned by the method is a new reference to the array storing the transformed values.
•
astTune - Set or get an integer-valued AST global tuning parameter
- result = starlink.Ast.tune( name, value )
- This is a static module function.
•
astTuneC - Set or get a character-valued AST global tuning parameter
- buff = starlink.Ast.tunec( name, value )
- This is a static module function.
•
astUnitMap - Create a UnitMap
- unitmap = starlink.Ast.UnitMap( ncoord, options=None )
•
astUnlock - Unlock an Object for use by other threads
- object.unlock( report=1 )
•
astVersion - Return the version of the AST library being used
- result = starlink.Ast.version( )
- This is a static module function.
•
astWarnings - Returns any warnings issued by the previous read or write operation
- result = channel.warnings( )
•
astWcsMap - Create a WcsMap
- wcsmap = starlink.Ast.WcsMap( ncoord=2, type=starlink.Ast.TAN, lonax=1, latax=2, options=None )
•
astWinMap - Create a WinMap
- winmap = starlink.Ast.WinMap( ina, inb, outa, outb, options=None )
•
astWrite - Write an Object to a Channel
- result = channel.write( object )
•
astWriteFits - Write out all cards in a FitsChan to the sink function
- result = fitschan.writefits( )
•
astZoomMap - Create a ZoomMap
- zoommap = starlink.Ast.ZoomMap( ncoord, zoom, options=None )