Program: ALLSKYPLOT Purpose: Plot an all sky graticule in a given sky system and plot shapes, markers and or images on that system. Category: ANALYSIS, COORDINATES, PLOTTING File: allskyplot.src Author: M.G.R. Vogelaar Keywords: Below we document several keywords that set the attributes of plot objects like lines, polygons, markers and text. Note that the syntax for all these keywords is: ATTXXXX= key:value key:value ..... or: ATTXXXX= ? or: ATTXXXX= key:? If you enter a question mark only, then you get a list of allowed parameters for the current object in the Hermes log file. If you enter a question mark where a value is expected, then a list with options for that key is printed in the Hermes log file. PROJECTION= Enter number [0,n] of a valid projection ... [0]: n is the maximum number of a list with projections. An all sky graticule (system of lines representing constant latitudes or constant longitudes) will be created for this projection. CDELT_XY= Enter pixel size in X and Y in deg. ... [-5,5]: The pixel size in degrees. The smaller this value the more pixels there will be in your plot. This value is important if you want to insert images. These will be projected on the pixels of the all sky plot. NAXIS_XY= Enter length of axes in pixels ... [80 40]: With CDELT_XY= one sets the default number of pixels. The smaller CDELT the more pixels. You can change this default for instance to have more pixels in the y direction, so that you can shift the plot a bit using non default values of CRPIX_XY= CRPIX_XY= Pixel coordinates for center ... [naxis_x, naxis_y]: Change the position of the center using pixel coordinates (FITS style i.e. first pixel is 1). Together with NAXIS_XY, this keyword is used to shift the plot a bit to create room for a legend. CRVAL_XY= Enter Projection center in X and Y ... [0,0]: This is the world coordinate in degrees of the center of your plot. Latitudes other than 0 result in oblique projections. Note that the input must be two numbers in degrees and these values represent a position in the sky system that you will enter later. SKY= Sky system 1=equat. 2=ecl 3=galactic 4=su.gal. ... [1]: Enter a number for a sky system. (In a next version this will be replaced by the input of a string that represents a sky definition, e.g. "equatorial, FK4, B1985") Note that the values at CRVAL_XY= represent a position in this sky system. FIGSIZE= Figure width, height in inches ... [12 6]: Enter figure size in inches. The default depends on the projection type (cylindrical or zenithal) If you enter one number, then this number is copied to the figure height. FRAME= Frame x0,y0,x1,y1 (norm. coords) ... [0.05 0.05 0.95 0.9]: Position of lower left and upper right corner of a frame containing the plot. The coordinates are normalized device coordinates running from 0 to 1. MERIDIANS= Meridians at longitudes ... [calculated]: PARALLELS= Parallels at latitudes ... [calculated]: BOR_ATTS= Plot atts base grat ... [color:k lw:1 ls:-]: Plot attributes for the border of a non-oblique graticule of which only the border is plotted. GR1_ATTS= Plot atts base grat ... [color:0.75 lw:1]: Plot attributes for the graticule of the base sky system. Order is not important. Key is separated from its value by a colon (:). Examples of attributes: color, linewidth (or lw), alpha Colors are Matplotlib colors as in: color:b color:#aabb22 color:0.75 XLABEL= Text to label X-axis ... [default]: Replace a default label for the X-axis by another text. LABX_ATTS= Plot atts X-axis label ... [defaults]: Attributes for Matplotlib text objects. See also description at keyword TITLE_ATTS. YLABEL= Text to label Y-axis ... [default]: Replace a default label for the Y-axis by another text. LABX_ATTS= Plot atts Y-axis label ... [defaults]: Attributes for Matplotlib text objects. See also description at keyword TITLE_ATTS. ILABLONS= Plot graticule labels at longitudes ... [calculated]: Enter longitudes at which a graticule must be labeled. Usually these values are copied from the values at which graticule lines are plotted. ILABLON_ATTS= Plot atts lon. labels ... [color:r fontsize:10]: Plot attributes for the longitude coordinate labels. ILABLATS= Plot graticule labels at latitudes ... [calculated]: Enter latitudes at which a graticule must be labeled. Usually these values are copied from the values at which graticule lines are plotted. In this default, the values -90, 0 and 90 are excluded. The longitude at which the latitude labels are plotted, is the first longitude in MERIDIANS= ILABLAT_ATTS= Plot atts lat. labels ... [color:b fontsize:10]: Plot attributes for the latitude coordinate labels. LABFORMAT= Enter format for longitude labels ... [Dms]: A valid format for all labels along longitude is degrees. If you want to change this, enter a new format using characters from the set 'H', 'D', 'M', 'S'. Use capitals to force to print a number and lower case characters to allow for printing a number if necessary. For an equatorial system one should enter Hms GRATOVER= Enter sky system for overlay 2nd graticule ... [skip]: A second system of coordinate lines can be added to the plot. Usually one combines equatorial systems with galactic or supergalactic sky systems in one plot. The input is what we call, a sky definition. It is usually a case insensitive minimal matched string as in: GRATOVER= eq (or equator, gal, sup etc.) But for equatorial systems with a reference system and/or an equinox and/or and observation epoch, the definition is given between curly brackets ({}), as in: GRATOVER={eq, fk4, B1950,B1966} GRATOVER={fk5} By default, no overlay graticule is plotted. HARDCOPY= Name of hard-copy of plot on disk ... [skip]: The file name extension sets the output format. If you don't enter a file extension, you can select an output format with attribute 'format' in HC_ATTS= HC_ATTS= Atts. hardcopy ... [papertype:a4 orientation:landscape]: Attributes for hardcopy on disk. From the Matplotlib documentation: dpi: [ None | scalar > 0 ] The resolution in dots per inch. If None it will default to the value savefig.dpi in the matplotlibrc file. facecolor, edgecolor: the colors of the figure rectangle orientation: [ 'landscape' | 'portrait' ] not supported on all backends; currently only on postscript (and pdf?) output papertype: One of 'letter', 'legal', 'executive', 'ledger', 'a0' through 'a10', 'b0' through 'b10'. Only supported for postscript output. format: One of the file extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg. transparent: If True, the axes patches will all be transparent; the figure patch will also be transparent unless facecolor and/or edgecolor are specified via kwargs. This is useful, for example, for displaying a plot on top of a colored background on a web page. The transparency of these patches will be restored to their original values upon exit of this function. TITLE= Title above plot ... [name of projection]: Enter a title to replace a default title. This default title is the name of the selected projection e.g. 'Hammer Aitoff'. A title can contain TeX syntax. TeX should start and end with a '$' character. Example: TITLE= Hammer Aitoff with $(\alpha_p,\delta_p) = (60^\circ, 30^\circ)$ TITLE_ATTS= Atts. title ... [color:g y:1.02]: Plot attributes for the title. Some useful properties are: backgroundcolor - any matplotlib color color - Color of the text family or fontfamily or fontname or name - [ FONTNAME | 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ] size or fontsize - [ size in points | 'xx-small' | 'x-small' | 'small' | 'medium' | 'large' | 'x-large' | 'xx-large' ] style or fontstyle - [ 'normal' | 'italic' | 'oblique'] y - Position of text in y direction in normalized device coordinates. Example: TITLE_ATTS= color:b style:italic fontsize:20 y:1.02 SHAPE1= E(ell),R(ect),N(-poly),M(arker),I(mage) ... [start plot] Select your object or start plotting. This keyword is part of a loop and the index of the keyword is increased, so the next is SHAPE2= etc. The objects are: E: Ellipse with major and minor axis in degrees and a position angle in degrees. The ellipse is centered at a position entered with CPOS1=. The position angle is defined as the angle between major axis and the North in the direction of increasing longitude. R: Rectangle with height and width an a position angle which is an angle between the North. The rectangle is centered at a position entered with CPOS1= N: Regular polygon with a radius of the circle onto which the angles are plotted. The number of angles is a second parameter and also a position angle can be entered. M: Given a position or a sequence of positions, plot a marker symbol on those positions. The positions can either be plotted as markers or as a irregular polygon or both. The positions can be entered as two numbers representing longitude and latitude, or as strings which allow for alternative sky systems. I: Image. Not yet implemented. The shapes ellipse, rectangle and regular polygon, have parameters that describe a distance on a sphere as function of an angle. The parameters are given in a projection-less flat surface. Sample points on the shape are calculated. Each point corresponds to an angle and a distance with respect to a central position, let's say (xc,yc). Then the shape is recalculated for a sphere and a projection in such a way that the angles and the distances on the sphere are preserved whatever the location (xc,yc) of the shape. ATTRIBS_E1= Facecol, edgecol, width, alpha ...... [r g 1 0.6]: ATTRIBS_R1= ATTRIBS_N1= Depending on the value of SHAPE1=, this keyword asks for attributes of the selected shape. The colors are strings that set a Matplotlib color ('r', '#23aa44', 0.75). The width is a floating point number (can be smaller than 1.0). Finally, alpha sets the transparency. It is a number between 0 and 1. The more close to 1, the less transparent the face color of the object. Polygons will be filled with a color by default. Use parameter fill:False to plot a shape that will not be filled. IOOPT1= Parameters from F(ile) or M(anual) input ... [M]: For ellipses, rectangles and regular polygons, the parameters for these shapes can be set manually (M) or they can be read from a file (F). FILENAME1= Enter name of file: If one wants to read the ellipse etc. parameters from file, then a file name is required. The format of its contents is: string float float float The string represents a position in pixel-, world- or mixed coordinates. Example content of a file with parameters for an ellipse, rectangle or regular polygon: "{} 0 {} 0" 40 20 0 "ga 10 ga 20" 50 20 90 "eq 20 eq 30" 30 10 0 "10h10m 5d10m" 40 10 40 "{} 4h10m10s {} 3d10m20s" 30 10 0 For a regular polygon, the second number should be a integer which sets the number of angles in the polygon. CPOS1= Central position xc, yc: A string that sets the position of the center of the selected shape. Examples: CPOS1=6h10m 30 deg CPOS1=ga 10 ga 20 PARAMS1= Enter maj, min, pa: Message depends on the selected shape. For an ellipse one enters the major axis, the minor axis (degrees) and the position angle (degrees). POSITIONS1= Assume we have a file called 'lasfootprint' which stores two sets of positions separated by an empty line. If we want to plot these positions as polygons, we need to separate them. You need some knowledge about the file. If the data (comment lines included) of the first polygon is in the lines 1 to 64 (64 included) and the second starts at line 66 and runs to the end, then the positions could be entered as: POSITIONS1= readcol(lasfootprint, 1,1,64) HMShour readcol(lasfootprint, 2,0,64) deg POSITIONS2= readcol(lasfootprint, 1,66,0) HMShour readcol(lasfootprint, 2,66,0) deg The first column (column 1) is a longitude in hours so we used unit 'hmshour' to convert it. The second column is a latitude (declination) in degrees. The coordinate is followed by a unit (deg) so it is a world coordinate. It was also possible to prepend the second coordinate with {} as in: POSITIONS1= readcol(lasfootprint, 1,1,64) HMShour {} readcol(Lasfootprint, 2,0,64) If columns 3 and 4 are galactic longitudes and latitudes, but our basemap is equatorial, then we could have read the positions with an alternative sky system as in: POSITIONS1= {ga} readcol(lasfootprint, 3,1,64) {} readcol(lasfootprint, 4,0,64) The second sky definition is empty which implies a copy of the first definition ({ga}). One can also read three columns at once to calculate longitudes and latitudes from coordinates given in hours/degrees, minutes and seconds. Some examples: POSITIONS1= {} readhms(hmsdms.txt,1,2,3) {} readdms(hmsdms.txt,4,5,6) POSITIONS1= {} readhms(hmsdms.txt,1,2,3,1,64) {} readdms(hmsdms.txt,4,5,6,1,64) POSITIONS1= ga readdms(hmsdms.txt,1,2,3) ga readdms(hmsdms.txt,4,5,6) POSITIONS1= readdms(hmsdms.txt,1,2,3) deg readdms(hmsdms.txt,4,5,6) deg Note that: - {} means a world coordinate in the current sky system - unit deg also sets the coordinate to a world coordinate - one should use 'readdms()' twice for non equatorial coordinates (usually these columns are given not in hours but in degrees) If you need keyword arguments for the READxxx functions, then you must escape the string with back quotes to prevent Hermes to interpret the string. For example POSITIONS1= `{} readhms(hmsdms.txt,col3=1,col2=2,col1=3) {} readdms(hmsdms.txt,4,5,6)` LEGEND1= Entry for legend ... [skip]: Each polygon that you enter can have an entry in a legend. What you enter here is a text label. The location of legend is entered using keyword LEGENDLOC= A recipe to create more space for your legend is given in the 'description' section. LEGENDLOC= Enter a legend location (number 0-10) ... [1]: Location number ======================= best 0 upper right 1 upper left 2 lower left 3 lower right 4 right 5 center left 6 center right 7 lower center 8 upper center 9 center 10 ANNTXT1= Enter text to plot in figure ... [stop loop]: Text for an annotation somewhere in the plot. The position is entered with ANNPOS1=. Alignment attributes can be set in ANNATTS1= ANNPOS1= Central position xc, yc: Position at which text for annotation is plotted. These coordinates can be pixel-, world- or mixed coordinates. Alignment can be set with attributes in ANNATTS1= ANNATTS1= Enter annotation attributes ... [color:r fontsize:10]: Useful attributes can be the horizontal alignment va:'center', 'top', 'bottom', 'baseline' or horizontal alignment: ha:'center' , 'right' , 'left' Description: I. Tool to plot footprints onto all-sky projections. Select a suitable projection from a list and plot a graticule for the entire sky. Define objects that represent a part of the sky. These objects are either polygons for which you enter longitudes and latitudes, or the polygons follow a prescription (ellipse, rectangle, regular polygon) and are plotted in a way that angles and distances on a sphere are preserved. Recipes: Legend: If one needs more space for a legend then select suitable values for the number of pixels and the coordinates of the central pixel. A simple plot with a lot of room at the right for a legend can be achieved in the following way: (all other keywords with their defaults) CDELT_XY= -1 1 CPOS1= {} 0 {} 0 CRPIX_XY= 200 100 LEGEND1= Test legend with a very long name NAXIS_XY= 600 200 PARAMS1= 50 20 0 SHAPE1= e II. Assume you need to inspect the distribution of pulsars in the sky. You want to plot the pulsar positions as dots in a galactic sky system. You downloaded (e.g. with Aladin) a 'tab separated values' text file and saved it as 'pulsars.txt'. The positions are R.A. and Dec. in decimal degrees. !_RAJ2000 _DEJ2000 PSR Simbad logL !-------- -------- ---------- ----- 003.5739 +47.7759 0011+47 Simbad 27.84 008.5370 -07.3648 0031-07 Simbad 27.96 015.6375 +65.6203 0059+65 Simbad 28.63 017.0917 +66.1422 0105+65 Simbad 27.22 024.8324 +58.2422 0136+57 Simbad 27.41 025.4165 +60.1590 0138+59 Simbad 28.47 027.8442 -06.5831 0148-06 Simbad 28.28 To plot the required overview in a Hammer Aitoff projection use the following keywords (only): ATTRIBS_M1= color:b ms:2 M_OPT1= m M_ORG1= p POSITIONS1= {eq} readcol("pulsars.txt", 1) {eq} readcol("pulsars.txt", 2) PROJECTION= 16 SHAPE1= m SKY= 3 Notes: - Updates: Sep 07, 2010: VOG, Document created. Oct 11, 2010: VOG, Removed utf8 characters from dc1 document Feb 17, 2011: VOG, Removed bug in M_ORGn= keyword. Added new example with positions from file Changed documentation for column numbering