A graticule is a system of crossing lines on a map representing positions of which one coordinate is constant. For a spatial map it consists of parallels of latitude and meridians of longitude as defined by a given projection.
This module is used to set up such graticules and labels for the selected world coordinate system. It plots the results with plotting library Matplotlib.
Besides spatial axes, it supports also spectral axes and a mix of both (e.g. position-velocity diagrams). It deals with data dimensions > 2 by allowing arbitrary selections of two axes. The transformations between pixel coordinates and world coordinates are based on module wcs which is a Python binding for Mark R. Calabretta’s library WCSLIB. >From WCSLIB we use only the core transformation routines. Header parsing is done with module wcs.
Axes types that are not recognized by this software is treated as being linear. The axes types correspond with keywords CTYPEn in a FITS file. The information from a FITS file is retrieved by module PyFITS
See also
Tutorial material with code examples:
Module author: Martin Vogelaar <gipsy@astro.rug.nl>
The variables native, notnative, bothticks, noticks correspond to the numbers 0, 1, 2 and 3 and represent modes to make ticks along an axis visible or invisible. Ticks along an axis can represent both world coordinate types (e.g. when a map is rotated). Sometimes one wants to allow this and sometimes not.
Tick mode | Description |
---|---|
native | Show only ticks that are native to the coordinate axis. Do not allow ticks that correspond to the axis for which a constant value applies. So, for example, in a RA-DEC map which is rotated 45 degrees we want only Right Ascensions along the x-axis. |
notnative | Plot the ticks that are not native to the coordinate axis. So, for example, in a RA-DEC map which is rotated 45 degrees we want only Declinations along the x-axis. |
bothticks | Allow both type of ticks along a plot axis |
noticks | Do not allow any tick to be plotted. |
Given a number in degrees and an axis type in axtype equal to ‘longitude’ or ‘latitude’, calculate and return the parts of its sexagesimal representation, i.e. hours or degrees, minutes and seconds. Also return the fractional seconds and the sign if the input was a value at negative latitude. The value for skysys sets the formatting to hours/minutes/seconds if it represents an equatorial system.
Parameters: |
|
---|---|
Returns: | tuple: (Ihours, Ideg, Imin, Isec, Fsec, sign) which represent Integer values for the hours, degrees, minutes and seconds. Fsec is the fractional part of the seconds. Element sign is -1 for negative latitudes and +1 for positive latitudes. |
From the output of function gethmsdms and some Booleans, this function creates a label in plain text or in TeX. The Booleans set a flag whether a field (hours, degrees, minutes or seconds) should be printed or not. The fmt parameter is used if it does not contain the percentage character (%) but instead contains characters from the set HDMS. A capital overules the corresponding Boolean value, so if fmt=’HMS’, the values for Hlab, Mlab and Slab are all set to True.
Parameters: |
|
---|---|
Returns: | lab, a label in either hms or dms in plain text or in LaTeX format. |
Examples: | >>> # Set the format in Hours, minutes and seconds with a precision
>>> # of three. The suppression of minutes will not work here:
>>> grat.setp_tick(wcsaxis=0, fmt="HmS.SSS")
>>> # The same effect is obtained with:
>>> grat.setp_tick(wcsaxis=0, fmt="HmS.###")
>>> # Let the system determine whether seconds are printed
>>> # but make sure that degrees and minutes are included:
>>> grat.setp_tick(wcsaxis=1, fmt="DM")
>>> # If we know that all minutes and seconds in our labels are 0.0
>>> # and we want only the hours to be printed, then use:
>>> grat.setp_tick(wcsaxis=0, fmt="Hms")
>>> grat.setp_tick(wcsaxis=0, fmt="Dms")
>>> # Plot labels in Degrees even if the axis is an equatorial longitude.
|
Creates an object that defines a graticule A (spatial) graticule consists of parallels and meridians. We extend this to a general grid so we can cover every type of map (e.g. position velocity maps).
Parameters: |
|
|||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Raises: |
|
|||||||||||||||||||||||||||
Returns: | A graticule object. This object contains the line pieces needed to draw the graticule and the ticks (positions, text and axis number). The basis method to reveal this data (necessary if you want to make a plot yourself) is described in the following example: graticule = wcsgrat.Graticule(header)
for gridline in graticule:
print "\nThis gridline belongs to axis", gridline.wcsaxis
print "Axis type: %s. Sky system %s:" % (gridline.axtype, gridline.skysys)
for t in gridline.ticks:
print "tick x,y:", t.x, t.y
print "tick label:", t.labval
print "tick on axis:", t.axisnr
for line in gridline.linepieces:
print "line piece has %d elements" % len(line[0])
|
Note
A Graticule object has a string representation and can therefore be easily inspected with Python’s print statement.
Attributes:
Read the PLOTaxis class documentation. Four PLOTaxis instances, one for each axis of the rectangular frame in pixels set by xplim and pylim If your graticule object is called grat then the four axes are accessed with:
- grat.axes[wcsgrat.left]
- grat.axes[wcsgrat.bottom]
- grat.axes[wcsgrat.right]
- grat.axes[wcsgrat.top]
Usually these attributes are set with method setp_plotaxis().
Examples:
grat.axes[wcsgrat.left].mode = 1
grat.axes[wcsgrat.bottom].label = 'Longitude / Latitude'
grat.axes[wcsgrat.bottom].mode = 2
grat.axes[wcsgrat.right].mode = 0
PLOTaxis modes are:
0: ticks native to axis type only
1: Only the tick that is not native to axis type
2: both types of ticks (map could be rotated)
3: no ticks
The default values depend on how many ticks, native to the plot axis, are found. If this is < 2 then we allow both native and not native ticks along all plot axes.
The limits of the map in pixels along the x-axis. This value is either set in the constructor or calculated. The default is [1,NAXISn]. The attribute is meant as a read-only attribute.
Same for the y-axis.
The limits of the map in world coordinates for the x-axis either set in the constructor or calculated (i.e. estimated) by this method. The attribute is meant as a read-only attribute.
Same for the y-axis
The (FITS) axis number associated with the x-axis Note that axis numbers in FITS start with 1. If these numbers are not given as argument for the constructor then xaxnum=1 is assumed. The attribute is meant as a read-only attribute.
Same for the y-axis. Default: yaxnum=2
List with strings that represent the wcs axis type of the axes.
The wcs projection object for this graticule. See the wcs module document for more information.
The pixel on the matching spatial axis for maps with only one spatial axis. This attribute is meant as a read-only attribute.
World coordinates associated with the x-axis which set the constant value of a graticule line as calculated when the object is initialized. This attribute is meant as a read-only attribute.
Same for the y-axis
Unformatted copy of input parameter skyout
Unformatted copy of input parameter spectrans
Examples: | Example to show how to use a custom made header to create a graticule object. Usually one uses this option to create all sky plots. It is also a useful tool for experiments.: #1. A minimal header for an all sky plot
header = {'NAXIS' : 2, 'NAXIS1': 100, 'NAXIS2': 80,
'CTYPE1' : 'RA---AZP', 'CRVAL1' :0,
'CRPIX1' : 50, 'CUNIT1' : 'deg', 'CDELT1' : -5.0,
'CTYPE2' : 'DEC--AZP',
'CRVAL2' : dec0, 'CRPIX2' : 40, 'CUNIT2' : 'deg',
'CDELT2' : 5.0,
'PV2_1' : mu, 'PV2_2' : gamma,
}
grat = wcsgrat.Graticule(header)
Use module PyFITS to read a header from a FITS file: #2. A header from a FITS file 'test.fits'
import pyfits
hdulist = pyfits.open('test.fits')
header = hdulist[0].header
grat = wcsgrat.Graticule(header)
Select the axes for the graticules. Note that the order of the axes should be the same as the order of axes in the image where you want to plot the graticule. If necessary one can swap the graticule plot axes with input parameter axnum: #3. Swap x and y- axis in a FITS file
grat = wcsgrat.Graticule(header, axnum= (2,1))
For data with more than two axes, one can select the axes with input parameter axnum: #4. For a FITS file with axes (RA,DEC,FREQ)
# create a graticule for the FREQ,RA axes:
grat = wcsgrat.Graticule(header, axnum=(3,1))
Use sexagesimal numbers for startx/starty: #5. Sexagesimal input
grat = wcsgrat.Graticule(...., startx="7h59m30s", starty="-10d0m30s')
|
---|
Methods which set (plot) attributes:
Set (plot) attributes for a wcs tick label. A tick is identified by the type of grid line it belongs to, and/or the plot axis for which it defines an intersection and/or a position which corresponds to the constant value of the graticule line. All these parameters are valid with none, one or a sequence of values.
Warning
If no value for wcsaxis, plotaxis or position is entered then this method applies the parameter setting on all the wcs axes.
Parameters: |
|
---|---|
Note: | Some projections generate labels that are very close to each other. If you want to skip labels then you can use keyword/value visible=False. There is not a documented keyword visible in this method because visible is a valid keyword argument in Matplotlib. |
Examples: | 1. Set tick properties with setp_tick(). The last line makes the label at a declination of -10 degrees (we assume a spatial map) invisible: grat.setp_tick(wcsaxis=0, color='g')
grat.setp_tick(wcsaxis=1, color='m')
grat.setp_tick(wcsaxis=1, plotaxis=wcsgrat.bottom,
color='c', rotation=-30, ha='left')
grat.setp_tick(plotaxis=wcsgrat.right, backgroundcolor='yellow')
grat.setp_tick(plotaxis=wcsgrat.left, position=-10, visible=False)
2. Example of an external function to change the values of the tick labels for the horizontal axis only: def fx(x):
return x/1000.0
setp_tick(wcsaxis=0, fun=fx)
Or use the lambda operator as in: fun=lambda x: x/1000 |
Set (plot) attributes for titles along a plot axis and set the ticks mode. The ticks mode sets the relation between the ticks and the plot axis. For example a rotated map will show a rotated graticule, so ticks for both axes can appear along a plot axis. With parameter mode one can influence this behaviour.
Note
This method addresses the four axes of a plot separately. Therefore its functionality cannot be incorporated in setp_tick()
Parameters: |
|
---|---|
Examples: | Change the font size of the tick labels along the bottom axis in 11: grat = Graticule(...)
grat.setp_plotaxis(wcsgrat.bottom, fontsize=11)
|
Helper method for setp_gratline(). It pre-selects the grid line that corresponds to the first world coordinate.
Parameters: | See description at setp_gratline() |
---|---|
Examples: | Make lines of constant latitude magenta and lines of constant longitude green. The line that corresponds to a latitude of 30 degrees and the line that corresponds to a longitude of 0 degrees are plotted in red with a line width of 2: grat.setp_lineswcs1(color='m')
grat.setp_lineswcs0(color='g')
grat.setp_lineswcs1(30, color='r', lw=2)
grat.setp_lineswcs0(0, color='r', lw=2)
|
Equivalent to method setp_gratline(). It pre-selects the grid line that corresponds to the second world coordinate.
Parameters: | See description at setp_gratline() |
---|---|
Examples: | See example at setp_lineswcs0(). |
Set (plot) attributes for one or more graticule lines. These graticule lines are identified by the wcs axis number (wcsaxis=0 or wcsaxis=1) and by their constant world coordinate in position.
Parameters: |
|
---|---|
Returns: | – |
Notes: | For each value in position find the index of the graticule line that belongs to wcsaxis so that the distance between that value and the constant value of the graticule line is the smallest of all the graticule lines. If position=None then apply change of properties to ALL graticule lines. The (plot) properties are stored in **kwargs Note that graticule lines are initialized with default properties. These kwargs only update the existing kwargs i.e. appending new keywords and update existing keywords. |
Utility method that calls method setp_plotaxis() but the parameters are restricted to the axis labels. These labels belong to one of the 4 plot axes. See the documentation at setp_plotaxis for the input of the plotaxis parameter. The kwargs are Matplotlib attributes.
Possible useful Matplotlib attributes:
Parameters: |
|
---|
Utility method for setp_tick(). It handles the properties of the tick marks, which are Line2D objects in Matplotlib. The most useful properties are color, markeredgewidth and markersize.
Utility method for setp_tick(). It handles the properties of the tick labels, which are Text objects in Matplotlib. The most useful properties are color, fontsize and fontstyle.
Parameters: |
|
---|---|
Note: | Some projections generate labels that are very close to each other. If you want to skip labels then you can use keyword/value visible=False. There is not a documented keyword visible in this method because visible is a valid keyword argument in Matplotlib. |
Utility method that calls method setp_plotaxis() but the parameters are restricted to the tick mode.
Each plot axis has a tick mode.
Parameters: |
|
---|
Methods that deal with special curves like borders:
For the slanted azimuthal projections, it is not trivial to draw a border because these borders are not graticule lines with a constant longitude or constant latitude. Nor it is easy or even possible to find mathematical expressions for this type of projection. Also, the mathematical expressions return world coordinates which can suffer from loss of precision. This method tracks the border from a starting point by scanning in x- and y direction and tries to find the position of a limb with a standard bisection technique. This method has been applied to a number of all-sky plots with slanted projections.
Parameters: |
|
---|---|
Returns: | Identifier to set attributes of this graticule line with method setp_linespecial(). |
Note: | This method uses an algorithm to find positions along the border of a projection. It scans along both x- and y-axis for a NaN (Not a Number number) transition as a result of an invalid coordinate transformation, and repeats this for a number of scan lines along the x-axis and y-axis. A position on a border off an all-sky plot is the position at
which a transition occurs from a valid coordinate to a NaN.
Its accuracy depends on the the tolerance given in argument tol. The start coordinates to find the next border position on the next scan line is the position of the previous border point. If you have missing line pieces, then add more borders by calling this method with different starting points. |
For any path given by a set of world coordinates of which none is a constant value (e.g. borders in slanted projections where the positions are calculated by an external routine), one can create a line that is processed as a graticule line, i.e. intersections and jumps are addressed. Instead of world coordinates, this method can also process pixel positions. The type of input is set by the pixels parameter.
Parameters: |
|
---|---|
Returns: | A Identification number id which can be used to set properties for this special path with method setp_linespecial(). Return None if no line piece could be found inside the pixel limits of the graticule. |
Note: | This method can be used to plot a border around an all-sky plot e.g. for slanted projections. See code at scanborder(). |
Set (plot) attributes for a special type of graticule line made with method addgratline() or method scanborder(). This graticule line has no constant x- or y- value. It is identified by an id returned by method addgratline().
Parameters: |
|
---|---|
Examples: | Create a special graticule line which follows the positions in two given sequences x and y. and set the line width for this line to 2: id = grat.addgratline(x, y)
grat.setp_linespecial(id, lw=2)
|
Methods related to plotting derived elements:
Annotate positions in world coordinates within the boundaries of the plot. This method can be used to plot positions on all-sky maps where there are usually no intersections with the enclosing axes rectangle.
Parameters: |
|
---|---|
Returns: | An Insidelabel object with a series of derived label objects. These label objects have a number of attributes, see Insidelabels |
Notes: | For a map with only one spatial axis, the value of ‘mixpix’ is used as pixel value for the matching spatial axis. The mixed() method from module wcs is used to calculate the right positions. |
Examples: | Annotate a plot with labels at positions from a list with longitudes at given fixed latitude: grat = Graticule(...)
lon_world = [0,30,60,90,120,150,180]
lat_constval = 30
inlabs = grat.Insidelabels(wcsaxis=0,
world=lon_world,
constval=lat_constval,
color='r')
|
This method handles the properties of the ‘inside’ labels, which are Text objects in Matplotlib. The most useful properties are color, fontsize and fontstyle. One can change the label values using an external function and/or change the format of the label.
Parameters: |
|
---|---|
Note: | Some projections generate labels that are very close to each other. If you want to skip labels then you can use keyword/value visible=False. Note that visible is a parameter of Matplotlib’s plot functions. |
Utility methods:
Calculate and set, the aspect ratio for the current pixels. Also set default values for figure size and axes lengths (i.e. size of canvas depends on the size of plot window with this aspect ratio).
Parameters: |
|
---|---|
Returns: | The aspect ratio defined as: AR = CDELTy/CDELTx. |
Note: | (i.e. AR > 10 or AR < 0.1), an aspect ratio of 1 is returned. This method sets the attributes: ‘axesrect’, ‘figsize’, ‘aspectratio’. The attribute ‘figsize’ is in inches which is compatible to the methods of Matplotlib. |
A WCStick object is an intersection of a parallel or meridian (or equivalent lines with one constant world coordinate) with one of the axes of a rectangle in pixels. The position of that intersection is stored in pixel coordinates and can be used to plot a (formatted) label showing the position of the constant world coordinate of the graticule line. This class is only used in the context of the Graticule class.
A small utility class for wcs labels inside a plot with a graticule. Useful for all sky plots.
This method handles the properties of the ‘inside’ labels, which are Text objects in Matplotlib. The most useful properties are color, fontsize and fontstyle. One can change the label values using an external function and/or change the format of the label.
Parameters: |
|
---|---|
Note: | Some projections generate labels that are very close to each other. If you want to skip labels then you can use keyword/value visible=False. Note that visible is a parameter of Matplotlib’s plot functions. |