### 18 Plotting finding charts

18.2 Running catchart

18.4 Worked example

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 Surveys10 (SSS),
• the USNO PMM11 catalogue[20],
• various traditional standard catalogues, including the Catalogue of Positions and Proper Motions (PPM)[232], the SAO Catalog, the Bonner Durchmusterung and objects in SIMBAD12.

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[232]. 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:

catchart

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

catchart  title=\’NGC 3623\’

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:

catchart  multiple=yes

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

catchart  mcentre=no

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

catchart  multiple=yes  mcentre=no

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:

catchartrn

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.

 Catalogue File Bonner Durchmusterung /star/share/cursa/bd.grt HST Guide Star Catalog /star/share/cursa/gsc.grt IRAS Point Source Catalogue /star/share/cursa/iras_psc.grt Positions and Proper Motions (PPM) /star/share/cursa/ppm.grt Third Ref. Catalogue of Bright Galaxies /star/share/cursa/rc3.grt SAO Catalog /star/share/cursa/sao.grt SIMBAD /star/share/cursa/simbad.grt SuperCOSMOS surveys (black and white plot) /star/share/cursa/scosmosbw.grt SuperCOSMOS surveys (colour plot) /star/share/cursa/scosmoscol.grt USNO PMM /star/share/cursa/usno.grt

Table 9: Graphics translation files for remote catalogues

##### 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:

/star/share/cursa/simple.grt

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.

!+
! Simple graphics translation file.
!
! This file is suitable for use with target lists extracted from
! the version of the Bonner Durchmusterung available on-line at the
! Department of Physics and Astronomy, University of Leicester.
!
! All the stars are plotted as red filled circles scaled according
! to magnitude.
!
! A.C. Davenhall (Edinburgh) 10/6/97.
!-

SYMBOL = filledcircle   ! Plot the stars as filled circles,
COLOUR = red            ! coloured red.

UNITS  = fraction       ! Symbol size expressed as fraction of X range.

!
! Determine the symbol size by scaling the magnitudes between brightest
! and faintest stars in the target list.  VMAG is the magnitude column
! in the Bonner Durchmusterung.  Note how the minimum and maximum
! symbol sizes are flipped to accommodate magnitudes increasing ’the wrong
! way round’.

SIZE1  =  ascale(VMAG, 5.0D-2, 1.0D-2)

Figure 3: Simple graphics translation file

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:

/star/share/cursa/complex.grt

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.

!+
! More complicated graphics translation file.
!
! This file is suitable for use with target lists extracted from
! the version of the Bonner Durchmusterung available on-line at the
! Department of Physics and Astronomy, University of Leicester.
!
! Stars brighter than magnitude 7.5 are plotted as blue open stars.
! Fainter stars are plotted as red circles.  If the star is between
! magnitudes 7.5 and 9.0 the circle is solid, otherwise it is open.
! In all cases the size is scaled according to magnitude between the
! fixed range 7.5 - 10.0.
!
! A.C. Davenhall (Edinburgh) 10/6/97.
!-

IF VMAG < 7.5
SYMBOL = openstar       ! Open star,
COLOUR = blue           ! coloured blue.

ELSE IF VMAG >= 7.5  AND  VMAG < 9.0
SYMBOL = filledcircle   ! filled circle,
COLOUR = red            ! coloured red.

ELSE
SYMBOL = opencircle     ! open circle,
COLOUR = red            ! coloured red.

END IF

UNITS  = fraction         ! Symbol size expressed as fraction of X range.

!
! Determine the symbol size by scaling the magnitudes between the
! fixed range 7.5 - 10.0  VMAG is the magnitude column in the Bonner
! Durchmusterung.  Note how the minimum and maximum symbol sizes are
! flipped to accommodate magnitudes increasing ’the wrong way round’.

SIZE1  = scale(VMAG, 7.5D0, 1.0D1, 5.0D-2, 1.0D-2)

Figure 4: Star / galaxy graphics translation file

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:

item_name =value

For example:

SYMBOL = opencircle

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.

 Graphics symbol Name Size and shape specification $N$ omit from the plot omit none 0 undefined (catchart chooses) undefined size 1 dot dot none 0 open circle opencircle radius 1 filled circle filledcircle radius 1 open square opensquare centre to side 1 filled square filledsquare centre to side 1 open triangle opentriangle centre to vertex 1 filled triangle filledtriangle centre to vertex 1 open star (five point) openstar centre to vertex 1 filled star (five point) filledstar centre to vertex 1 plus sign (upright cross) plus centre to end of arm 1 multiplication sign (diagonal cross) mult centre to end of arm 1 asterisk asterisk centre to end of arm 1 open ellipse openellipse $a$, $b$, position angle § 3 filled ellipse filledellipse $a$, $b$, position angle § 3

§- $a$ = semi-major axis, $b$ = semi-minor axis.

Table 10: Plotting symbols. $N$ is the number of SIZEn values needed to specify the symbol

COLOUR  The name of the colour to be used to plot each object. The names of the permitted colours are shown listed in Table 11. If omitted the default is default.

 Colour Name default default red red green green blue blue cyan cyan magenta magenta yellow yellow

Table 11: Plotting colours. The default colour is the opposite of the plot background. Usually it will be black or white

UNITS  The units of the SIZEn columns. The options are listed in Table 12. The size of the symbol may be specified as an absolute angular size, in which case the units will usually be one of the angular measures. Here the size of the symbol corresponds to the actual size of an extended object on the sky. For example, the size of a circle could correspond to a circular isophote for a nebula. The ‘fraction’ option is provided for the other case where the symbol size varies with some property of the object, such as magnitude, which is not an actual angular extent on the sky. Here the symbol size is simply a fraction of the $x$ axis range of the plot (expressed on a scale where the entire range corresponds to 1.0). If omitted the default is fraction.

 Description Name fraction of $x$ range fraction seconds of arc arcsec minutes of arc arcmin degrees degrees hours hours radians radians

Table 12: Plotting UNITS

SIZE1, SIZE2 and SIZE3  Expressions defining the size of each symbol. The values are (more or less; see below) normal CURSA expressions involving columns in the targets list (see Appendix A). Most symbols (see Table 10) require only one size to be specified. This simple size is always given by SIZE1. However, the openellipse and filledellipse symbols require three values to define the ellipse. Here SIZE1 is the semi-major axis, SIZE2 the semi-minor axis and SIZE3 the position angle. SIZE1 and SIZE2 should evaluate to a value with the units specified by the UNITS item above. However, the SIZE3 should always be a position angle in degrees, measured eastwards from north, following the usual convention. The following two functions were added to assist in calculating sizes for columns such as magnitudes or flux which are not naturally angular extents and need to be scaled to produce a symbol size.
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.
LABEL  The name of the column to be used to label each object. If the graphics translation file simply consists of a set of specifiers for the above items they will be applied to all the objects in the list. Often this approach will be adequate. However, sometimes it will be desired to plot different objects in different ways (for example with different symbols or colours), depending on whether or not they meet some criteria. This behaviour is achieved by enclosing the definitions for the graphics attributes within a set of clauses, where each clause defines some aspect of the symbol to be used for objects which meet the criteria. The syntax is:

IF condition

$⋮$

ELSE IF condition

$⋮$

ELSE IF condition

$⋮$

ELSE

$⋮$

END IF

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 SIMBAD13. Alternatively, it is easy to obtain them using catremote, type:

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.

10http://www-wfau.roe.ac.uk/sss/

11http://www.nofs.navy.mil/