18 Plotting finding charts

CURSA contains the application catchart for plotting a basic finding chart showing objects selected from a catalogue which lie within in a given region of the sky. catchart plots equatorial coordinates using the tangent plane projection conventional in optical astronomy. This projection is described in standard textbooks on spherical astronomy (see, for example, Spherical Astronomy by R.M. Green[15]).

catcoord plots target lists (see Section 7). It will plot either a single target list or superimpose several target lists on a single finding chart.

All that can be guaranteed about a target list is that it contains columns defining the coordinates of the objects. Therefore, by default, catcoord plots all the objects in the list using the same default plotting symbol (circle, square etc), drawn to the same size in the same colour. However, it is often desirable to plot the objects with a specified symbol and colour and the size of the symbol varying with some property of the object (traditionally magnitude). The application catchartrn allows extra columns to be added to the target list which prescribe how each object is to be plotted.

Thus, a simple, default finding chart can be produced by running catchart on any target list. However, the plot can be customised by running catchartrn, to specify how each object is to be plotted, prior to running catchart. The next section (18.1) suggests some catalogues which might be suitable for producing finding charts, the subsequent one (18.2) describes how to run catchart and the following one (18.3) how to customise the plot. The final section (18.4) gives a complete worked example.

18.1 Suitable catalogues

Any target list can be plotted as a finding chart. However, often you will want to select and plot stars from one of the large, general-purpose astrometric catalogues. Depending on the details of your work you might either want to simply plot these stars in isolation or to use them as ‘background’ objects in a plot which also includes your more specialised programme objects. Various general-purpose astrometric catalogues which are suitable for plotting finding charts are available to CURSA, either by issuing a remote query via the Internet or by obtaining a local copy of the catalogue.

18.1.1 Remote query

Remote catalogues and databases can be queried using catremote or xcatview (see Section 25). The catalogues available include:

• the SuperCOSMOS Sky Surveys¹⁰ (SSS),
• the USNO PMM¹¹ catalogue[20],
• various traditional standard catalogues, including the Catalogue of Positions and Proper Motions (PPM)[23, 2], the SAO Catalog, the Bonner Durchmusterung and objects in SIMBAD¹².

Example graphics translation files (see Section 18.3) are available to customise charts produced using most of these catalogues (see Section 18.3.1). Subsets from the SuperCOSMOS catalogues can be obtained by either using CURSA’s remote access facilities or via form on the SuperCOSMOS Web pages.

18.1.2 Local copies

Versions of the following catalogues are available which are fully compatible with CURSA. You can obtain a local copy, find the objects in a given region of sky with catselect (see Section 16), and then plot a finding chart.

• The Catalogue of Positions and Proper Motions (PPM) by S. Röser and U. Bastian[23, 2]. The PPM is similar in scale and scope to the SAO catalogue, but more modern and accurate. A CURSA-compatible version is available and can be obtained by ftp (see Section 2). This version covers both hemispheres.
• The Hipparcos and Tycho catalogues. These catalogues, compiled from observations made with the Hipparcos astrometric satellite, contain extremely accurate coordinates. They are available as ASCII files on CD-ROM. Programs to reformat the files into CURSA-compatible catalogues can be obtained by ftp (see Section 2).
• Regions of the Hubble Space Telescope Guide Star Catalog (GSC). CURSA application catgscin can be used to reformat a GSC region into a CURSA-compatible target list (see Section 24).

18.2 Running catchart

To run catchart simply type:

It is possible to supply a title for the finding chart:

Note that the title must be enclosed in quotes and each quote preceded by a backslash character (as shown) in order to prevent the quotes from being interpreted by the Unix shell. By default catchart will plot a single target list. To plot several target lists superimposed on a single finding chart type:

Also by default catchart marks the centre of the chart with a ‘gun sight’ open cross. To suppress this cross type:

(think of ‘mark centre?’ to remember ‘mcentre’.) These options can be combined. For example, to plot several target lists with no central cross type:

You should then answer the following prompts.

GRPHDV

Enter the name of the graphics device on which the plot is to be produced. The names of some common graphics devices are listed in Table 8. On Starlink systems you can run a program to list all the graphics devices which are currently available by typing:

  /star/bin/examples/gnsrun_gks

See SUN/57[28] for further details. Where the alternative exists the plots usually look better with with a ‘landscape’ rather than ‘portrait’ orientation.

---

Device	Name
X-windows.	xwindows
Postscript A4 landscape	ps_l
Postscript A4 portrait	ps_p
Colour postscript A4 landscape	pscol_l
Colour postscript A4 portrait	pscol_p
Encapsulated postscript (landscape)	epsf_l
Encapsulated postscript (portrait)	epsf_p
Colour encapsulated postscript (landscape)	epsfcol_l
Colour encapsulated postscript (portrait)	epsfcol_p

Table 8: The names of some common graphics devices

---

GRPLST

Enter the name of the of the required target list. If several are to be superimposed on a single finding chart you will be repeatedly prompted to enter the next to be plotted. To terminate the sequence enter ‘QUIT’.

18.3 Customising the plot

By default catchart plots all the objects in a target list using the same plotting symbol drawn to a constant size in the same colour. Often this effect will not be what you want. Traditionally in astronomical atlases and charts stars are shown as circles whose size varies with their magnitude. Also different symbols and colours may be used to indicate different types of object or different aspects of the same sort of object.

The target lists which catchart might have to plot can come from a wide variety of sources (for example, catremote allows you to retrieve target lists from data centres and archives scattered around the world). All that can be guaranteed about them is that they will contain columns of celestial coordinates. No other assumptions can be made about the other columns which they may contain or how the objects in them should be plotted. It is not even possible to guarantee that the columns will include a magnitude; many non-optical catalogues do not and even if they do it may not be appropriate to plot symbols scaled on the magnitude.

To solve this problem application catchartrn is provided to allow you to prescribe how the objects in a target list are to be plotted; you specify the symbol, size and colour of the plotted objects. These quantities may be constant for all the objects or may be computed for each object, based on the value of other columns for the object (the traditional example is computing the symbol size from the magnitude). catchartrn adds some extra columns and parameters to the target list defining how the objects are to be plotted and catchart automatically uses these. This technique is very flexible and allows a great deal of control over the way objects are plotted. catchartrn itself reads a prescription of how the objects are to be plotted from a simple pre-existing file, the so-called graphics translation file. Example graphics translation files are provided for most of the catalogues in CURSA’s default list of remote on-line catalogues (see Table 9 and Section 25). You can either use one of these or prepare your own. Thus, the sequence for preparing a customised finding chart is:

(1)

obtain or prepare a graphics translation file,

(2)

run catchartrn to add the extra columns defining how the objects are to be plotted,

(3)

run catchart to plot the finding chart.

Often you will use the same graphics translation file for different finding charts plotted from the same catalogue, or even from different catalogues. Usually you will need some knowledge of the columns in the target list in order to construct a graphics translation file. For example, you would need to know the name of the column containing magnitude if you wished to scale the symbols on magnitude. You can, of course, examine the target list using xcatview (see Section 11), catview (see Section 12) or catheader (see Section 13).

The following sections describe how to run catchartrn, give a brief, tutorial introduction to the graphics translation file, and finally document the file format in full. Creating a graphics translation file is usually straightforward, particularly if you use one of the examples as a starting point, and the tutorial will probably give enough information to allow you to create your own. You will probably only need to read the full description if you want to create more complex effects.

18.3.1 Running catchartrn

Once you have prepared a suitable graphics translation file you run catchartrn to customise a target list by simply typing:

The amount of textual information written to the new target list is controlled using the command line mechanism described in Section 10.1. You should then answer the following prompts.

GTFILE

Enter the name of the graphics translation file.

CATIN

Enter the name of the original target list.

CATOUT

Enter the name of the output target list, customised for plotting.

Example graphics translation files are available for most of the catalogues in the default list of remote on-line catalogues supplied with CURSA. The files available are listed in Table 9. The SuperCOSMOS graphics translation files both plot all the objects in the finding chart as ellipses. In scosmosbw.grt all the objects are plotted using the default colour (usually black objects on a white background or vice versa). In scosmoscol.grt the colour used for each object varies with the value of the CLASS classification column in the target list, according to the following scheme: stars are shown in blue, galaxies in red, unclassifiable objects in green and objects considered to be noise in yellow. Most of the other files plot the objects as symbols which scale with magnitude or flux.

18.3.2 Tutorial example graphics translation files

By convention graphics translation files have file type ‘.grt’. A graphics translation file is a simple ASCII text file which can be created and modified with an editor. Figure 3 shows a simple graphics translation file. This example is available as file:

It plots all the stars in a target list extracted from the version of the Bonner Durchmusterung available at LEDAS as red filled circles scaled according to magnitude. The lines beginning with an exclamation mark (‘!’) are comments and are ignored. Similarly text to the right of exclamation marks is ignored. Blank lines are ignored.

The plotting symbol is defined by the SYMBOL item. The various options are listed in Table 10. Similarly, the colour is set by item COLOUR. The permitted colours are given in Table 11. The symbol size is simply a fraction of the plotting area available, as specified by UNITS. The alternative units are listed in Table 12. The size of the plotting symbol is defined by parameter SIZE1. SIZE1 can be any valid CURSA expression (including a constant value, such as ‘SIZE1 = 5.0E-2’, of course). The additional functions scale and ascale are provided for scaling quantities for display. They are described in the following section.

Figure 4 shows a more complicated graphics translation file. This example is available as file:

Again it plots all the stars in a target list scaled according to magnitude. However, here the scaling is between the fixed magnitude range 7.5 - 10.0 rather than being determined from the brightest and faintest stars in the list. Also, the IF …ELSE …END IF construct is used to vary the plotting symbol with magnitude. Stars brighter than magnitude 7.5 are plotted as blue open stars, stars between magnitude 7.5 and 9.0 as red filled circles and fainter stars as red open circles.

Both the examples given here have shown the symbol size being scaled with magnitude. However, it is important to realise that the expressions defining both SIZE1 and the IF …ELSE …END IF conditions can be any valid CURSA expressions (see Appendix A) involving any columns in the target list. Graphics translation files are provided for most of the catalogues in the default list of remote on-line catalogues used by CURSA (see Table 9) and these can be used as further examples.

18.3.3 The graphics translation file

This section fully documents the graphics translation file. By convention graphics translation files have file type ‘.grt’. A graphics translation file is a simple ASCII text file which can be created and modified with an editor. The following general rules apply to the contents of graphics translation files:

• they are free format; there is no requirement that items occur at fixed absolute positions in lines,
• keywords are case-insensitive (though throughout this manual they are shown in upper-case for clarity),
• blank lines are ignored; they may be introduced freely to improve readability as required.

Any text following an exclamation mark (‘!’) is treated as a comment and ignored. The exclamation mark introducing a comment may be either the first non-blank item in a line (‘comment lines’) or may follow other items (‘in-line comments’). Comments are terminated automatically at the end of the line.

The graphics translation file defines how objects in a target list are to be plotted. Each symbol plotted is defined by a number of items: SYMBOL, COLOUR, UNITS, SIZEn and LABEL, They are specified using the syntax:

For example:

specifies that the objects will be plotted as open circles. The details of the individual items are as follows. SYMBOL  The name of the symbol to be used to plot the object. The permitted names are listed in Table 10. If omitted the default is undefined.

scale(column, colmin, colmax, smin, smax)

 
Performs a simple linear scaling. column is the name of the column to be scaled. colmin and colmax are the minimum and maximum values in the column to be scaled. If a value of the column, $V_c$, lies within the range colmin to colmax, then the scaled value returned, $V_s$, is computed using the formula:

$$V_s=$$smin + (Vc −colmin). (smax−smin) (colmax−colmin)

(6)

If $V_c$ is larger than colmax then colmax is returned; if it is smaller than colmin then colmin is returned. smin and smax are the largest and smallest values of the plotting symbol, expressed in the units of UNITS. To accommodate quantities such as magnitudes which increase ‘the wrong way round’ simply flip the values for smin and smax.

ascale(column, smin, smax)

 
(auto-scale) is similar to scale, but the scaling is defined by the minimum and maximum values of the column.

condition is the condition, expressed in terms of columns in the targets list, which objects must satisfy to be plotted in the particular way. An example might be ‘MAG .LT. 12.0’ to plot objects brighter than 12th magnitude in a given way. The following points apply.

• An arbitrary number of clauses are permitted; there is no upper limit.
• The optional ELSE is a special clause which is applied to any objects in the targets list which do not satisfy any of the other cases. There is no condition attached to ELSE. If ELSE is omitted then objects which satisfy none of the cases are not written to the output target list (and hence are not plotted).
• Because the conditions defining the set of objects to be included in each case are not necessarily mutually exclusive it is technically possible for a given object to match more than one case. In this event it will be plotted in the manner prescribed by the first case it matches.
• Any graphics attributes defined outside an IF …END IF apply to all the objects plotted.
• An arbitrary number of separate IF …END IF constructs can be included in the graphics translation file. Typically, more than one might be used to set up different aspects of the plotting symbol (for example, one construct to set the plotting colour, based on the photometric colour of the object and a second to set the symbol shape based on the object classification).
• However, IF …END IF constructs may not be nested.
• The two words ‘ELSE IF’ may be separated by zero, one or an arbitrary number of spaces; similarly the two words ‘END IF’ may be separated by zero, one or an arbitrary number of spaces.
• The LABEL item cannot appear inside a clause. If present it must be outside any clauses and refers to the entire target list.

18.4 Worked example

This section gives a complete worked example of producing a customised finding chart. It starts be searching a remote on-line catalogue with catremote (see Section 25) to find the list of objects which will produce the chart. The finding chart will show objects in the USNO PMM catalogue[20] within 5 minutes of arc of the radio source PKS 1417-19. Proceed as follows.

(1)

You need to know the coordinates of the central object for epoch and equinox J2000. You may already know them, or it might be convenient to look them up in a paper catalogue or on-line using SIMBAD¹³. Alternatively, it is easy to obtain them using catremote, type:

  catremote name  simbad_ns@eso  pks1417-19

The object name is entered without spaces and may be in either case (upper or lower). catremote will return the coordinates of the object for epoch and equinox J2000:

  Right Ascension: +14:19:50
  Declination: -19:28:21

The Right Ascension is in sexagesimal hours and the Declination in sexagesimal degrees. If you know the coordinates for some equinox other than J2000 then you can use the Starlink utility COCO (see SUN/56[31]) to convert them to the required equinox.

(2)

To search the USNO PMM catalogue[20] for objects within 5 minutes of arc of this position type:

  catremote query usno@eso  14:19:50  -19:28:21  5

catremote will respond:

  !(Info.) Catalogue usno_eso_141950_m192821.tab written successfully.

and the target list of selected objects will be written to file usno_eso_141950_m192821.tab in your current directory.

(3)

The target list can be customised for plotting using the graphics translation file supplied for the USNO PMM (see Table 9). Type:

  catchartrn

and answer the prompts (the prompts are shown on the left and replies on the right):

GTFILE - Graphics translation file:	/star/share/cursa/usno.grt
CATIN - Input target list:	usno_eso_141950_m192821.tab
CATOUT - Output graphics attribute list:	usno_plot.txt

The customised target list will be written to file usno_plot.txt.

(4)

To plot a finding chart from the customised target list type:

  catchart ~ title=\’PKS 1417-19\’

Note that the title must be enclosed in quotes and the quotes preceded by a backslash (as shown) to prevent them being interpreted by the Unix shell. Answer the prompts as follows (again prompts to the left, replies to the right):

GRPHDV - Graphics device:	ps_l
GRPLST - Target list:	usno_plot.txt

The position of PKS 1417-19 will be marked by an open cross. Here the finding chart has been written as a postscript file, called gks74.ps, which may be printed, displayed interactively etc, as desired.