Function: WCSINP Purpose: WCSINP prompts the user to enter the name of a GIPSY set or FITS file together with a specification of the subsets. Returned is a WCSset object with useful attributes. Category: USER IO Files: ioutils.py Author: M.G.R. Vogelaar Use: setobject = wcsinp(key, # Character string mes, # Character string create, # Boolean write, # Boolean hdukey, # Character string hdumes, # Character string altkey, # Character altmes, # Character string axkey, # Character string axmes, # Character string axsuffix, # Character string swapkey, # Character string swapmes, # Character string requireddim, # Integer listopt) # Boolean Python call with defaults for keyword parameters: setobject = wcsinp(key="INSET=", mes="Enter data file: ", create=False, write=False, hdukey="HDU=", hdumes="Enter number of Header Data Unit: [0]", altkey="ALTHEAD=", altmes=None, axkey="AXNAMES=", axmes=None, axsuffix=None, swapkey="AXSWAP=", swapmes=None, requireddim=None, listopt=True) wcsinp Returns an object from class WCSset (inherits from class Set) or None in case of unrecoverable errors or when nothing was entered. See: http://www.astro.rug.nl/~gipsy/pguide/pygipsy.html to find the methods and attributes of objects of this class. key Keyword prompt, default is "INSET=" mes Message for the prompt. Default is "Enter data file: " create If True than a set is created. Default is False write Set to True if it is required to modify the set on disk. Default is False. hdukey Keyword for a prompt when the data is a FITS file and there are multiple data header units. The default is "HDU=" hdumes Message for the 'hdukey' prompt. There is a default message. The default is HDU=0. altkey Keyword for a prompt for an alternate header. An alternate header is an alternative description of a world coordinate system. The corresponding keywords are appended with a character a..z. This character is the input that is expected at this prompt. altmes A message for the prompt for 'altkey'. The message is only composed if there are alternate headers available. axkey If the input of a data structure has more dimensions than the number in parameter 'requireddim' then a user will be prompted to enter the names of the axes in the data structure that has the dimension 'requireddim'. The axes names are case insensitive and minimal matched against the list of available axes names. Also the positions of the slice(s) are prompted. These keywords are derived from the names of the 'repeat' axes. These are the axes outside the entered data slice/subset. axmes A message for the 'axkey' prompt. A default message contains 'requireddim' axes names in order of the names in the header of the data set. axsuffix Distinguish axes names in the prompt for 'repeat' axes. swapkey Axis swapping is only possible for two dimensional sets. Usually one wants to swap axes for plotting purposes. If subset axes are selected from a list and the subset is two dimensional, then the order is important. If a set with subset specification is entered, then the order is fixed by GIPSY. For two dimensional structures, the user gets an option to swap the axes. swapmes A message for the 'swapkey' prompt. If omitted, a default message is constructed using the axis names in the selected two dimensional subset. requireddim The required minimal dimension of the subsets. If set, there is a check whether the dimension of the subsets is equal to this 'requireddim' or equal to the dimension of the set. listopt Extend the prompt in 'mes' with a default option '[list files]', which lists all GIPSY sets and FITS files in the current working directory. Returns: A 'WCSset' object. Its attributes are described in the document: http://www.intra.astro.rug.nl/~gipsy/pguide/pygipsy.html Assume we call this object 's', then below we summarize these attributes: s.image the set's image as a NumPy array. s.header a SetHeader object which interfaces to the set's header. On write, a copy of the element is created. On read, the value of the copy is returned if it exists, or otherwise the set's header element itself. See below. s.naxis the set's dimensionality. s.ncoords the set's number of axes, including 'hidden axes'. s.axnames the set's list of axis names. s.slo, s.shi lists with the set's lower and upper grid limits. s.blo, s.bhi if a box has been specified, lists with the box's limits, otherwise identical to s.slo, s.shi. s.spec the set's specification string as given when the object was created. s.open True when set is open. s.wmode True when set is writable. s.boxspec the set's box specification string as given to the method 'setbox()'. s.subsets set's list of subset coordinate words. s.blank Value of the undefined pixel. s.fits True when set is a FITS 'pseudo set'. s.fitsname For FITS pseudo sets: the name of the FITS file. s.hdunum For FITS pseudo sets: the number of the HDU. Zero-relative. s.altwcs For FITS pseudo sets: alternative WCS version code used for creating the set. Default: blank. But the WCSset class adds attributes for coordinate systems: s.dataname Name of source (GDS- or FITS file) s.axperm_in Axis permutation array for axes inside subset s.axperm_out Axis permutation array for axes outside subset s.wcsinfo String with information about the coordinate system s.transax Axis number (starting with 1) of the spectral axis (if any is available otherwise its value is None). s.projection The 'Projection' object s.mixax Axis number of a missing spatial axis. E.g. in XV maps we need the missing spatial axis for X to be able to do coordinate transformations. s.subproj The Projection object that corresponds to a subset s.projaxnum The axis number array for the subset axes. s.spatialmap Boolean. Is True if both subset axes are spatial. s.slicepositions Pixel coordinates at which a slice/subset is taken. E.g. in a RA-DEC-FREQ-STOKES data structure we need a pixel position in FREQ and STOKES to define one two-dim subset. The attributes for the projection objects ('projection' and 'subproj'), also have attributes. They are described in the documentation of module 'wcs' in the Kapteyn Package, see: http://www.astro.rug.nl/software/kapteyn/wcs.html#class-projection An important attribute is 'gridmode'. In the GIPSY environment this attribute is set to True. The input coordinates are regarded as grid coordinates. If one wants to work in (FITS) pixel coordinates only, then set: s.subproj.gridmode = False s.projection.gridmode = False The Set object has a number of methods. These methods are described in the document: http://www.intra.astro.rug.nl/~gipsy/pguide/pygipsy.html at section 3.1, the Set class. Methods: Besides all methods of the Set class, we added some new methods: s.swapaxes(): Method to change the axes permutation array for two dimensional subsets only. spec = s.set_spectraltranslation(key=None, mes=None, default=1, inside=True) Set a spectral translation. Either for an position-velocity diagram or for a repeat axis with type 'spectral' (inside=False). The default is always set to the current system. skyout = s.set_skyout(key=None, mes=None, default=1) Set and return an output sky definition The default is always set to the current system. s.printinfo() Print an informative message about the set in Hermes. Description: WCS is a function which prompts the user to enter the name of a set and (optionally) subset(s) and returns an object from class 'Set'. This routine checks whether subsets are entered with the dimensionality given in parameter 'requireddim'. If not present, it will inform the user and prompts again for subsets using axes names found in the header of the input data. It accepts also a FITS file. The parsing of a FITS file involves module PyFITS. This module enables us to enter FITS data using a location on the web (url) and/or read data from a compressed file (.gz). If a FITS file is entered and the FITS file has multiple header Data Units (hdu's) then the user is prompted to give the number of the hdu that contains the wanted data. If it has alternate headers (header with an alternative description of the world coordinate system), then it will prompt for a character corresponding to the alternate header. Examples: Below a real (but useless) GIPSY task. It prompts for a GIPSY set or FITS file. #!/usr/bin/env python import gipsy import ioutils gipsy.init() gipsyset = ioutils.wcsinp() gipsy.finis() Parameter 'requireddim' is important. This parameter sets the dimension of the subsets (an attribute of the object returned by 'wcsinp()'). If one enters only the name of the data and the dimension of that data structure is not equal to the required dimension, then a user will be prompted to enter the names of the axes in a subset. Examples: gipsyset = ioutils.wcsinp(requireddim=4) # Subsets must be 4-dim.! Any data entered here with a dimension less than 4 will be rejected. Assume we have a 4 dimensional data structure called '4dimtest' described by: Set 4dimtest.fits has 4 axes: FREQ from -4 to 5 DEC--NCP from -4 to 5 STOKES from -1 to 2 RA---NCP from -4 to 5 Set the required subset dimension to 2: gipsyset = ioutils.wcsinp(requireddim=2) If you enter only the name (and not any subset specification) on the INSET= prompt, then you will get a AXNAMES= prompt to enter the 2 (requireddim=2) names of the subset axes. AXNAMES= Enter 2 names of FREQ,DEC,STOKES,RA [FREQ,DEC] Then you will get a prompt to enter grid coordinates on the so called repeat axes (axes outside the subset). STOKES= Enter grid position(s) on STOKES ..... [-1:2] RA= Enter grid position(s) on RA ..... [-4:5] Note that this is all equivalent to: INSET=4dimtest.fits STOKES -1:2 RA -4:5 Which is the same as: INSET=4dimtest.fits STOKES RA Other examples -------------- At the prompt one can enter GIPSY sets, and FITS files using the same syntax for extracting subsets. FITS files can also be retrieved from the web using its URL. Also gzipped FITS files can be read. INSET=aurora freq 1:10 INSET=http://www.atnf.csiro.au/people/mcalabre/data/WCS/1904-66_ZPN.fits.gz INSET=ngcxxx.fits.gz velo 50 A complete GIPSY task ---------------------- As an example of using methods 'wcsinp()' and 'wcspos()' in a GIPSY task we wrote a small application which converts between grids and world coordinates. It prompts a user for a data structure (GIPSY set or FITS file), a spectral translation (if useful) and an output sky system. These will change the output of the calculated world coordinates into the new spectral system and/or sky system. #------- Start -------- !/usr/bin/env python import gipsy from kapteyn import ioutils gipsy.init() gipsyset = ioutils.wcsinp() gipsyset.printinfo() gipsyset.set_spectraltranslation("SPECTRANS=", mes=None, inside=True) gipsyset.set_skyout("SKYOUT=") # Using a prompt to enter positions for the same GIPSY set: # Abort the loop if only enter is pressed. key = "POS=" while 1: grids, world, pix, units, errmes = gipsyset.wcspos(0, key, "") gipsy.cancel(key) if not len(grids): if errmes: gipsy.reject(key, errmes) else: break else: for g,w in zip(grids, world): s = str(g) + "=" + str(w) + ' ' + str(units) gipsy.anyout(s) gipsy.finis() #------- End ------- Updates: Apr 23, 2009: VOG, Document created. Jul 15, 2010: VOG, New version compatible with Kapteyn version v2.0 Feb 03, 2011: VOG, Example of small task added.