14

SUN/190.11

Starlink Project
Starlink User Note 190.11

A.C. Davenhall

4th November 2001

Copyright © 2001 Council for the Central Laboratory of the Research Councils


CURSA
Catalogue and Table Manipulation Applications

Version 6.4 

User’s Manual



Abstract

CURSA is a package of Starlink applications for manipulating astronomical catalogues and similar tabular datasets. It provides facilities for: browsing or examining catalogues, selecting subsets from a catalogue, sorting catalogues, copying catalogues, pairing two catalogues, converting catalogue coordinates between some celestial coordinate systems, plotting finding charts and photometric calibration. Also, subsets can be extracted from a catalogue in a format suitable for plotting using other Starlink packages, such as PONGO. CURSA can access catalogues held in the popular FITS table format, the Tab-Separated Table (TST) format or the Small Text List (STL) format. Catalogues in the STL and TST formats are simple ASCII text files. CURSA also includes some facilities for accessing remote on-line catalogues via the Internet.

This manual describes how to use version 6.4 of CURSA. Its intended readership is users and potential users of CURSA.

Contents

1 Introduction
2 Obtaining copies of catalogues
3 Getting started
4 Terminology
 4.1 Column attributes
5 Null values
 5.1 Processing null values
 5.2 Displaying null values
6 Celestial coordinates
7 Target lists
8 Accessing catalogues
 8.1 FITS tables
 8.2 TST
 8.3 STL
9 Answering prompts in CURSA applications
10 Summary of applications
 10.1 Copying textual information
 10.2 Quiet mode
 10.3 Extra functionality
 10.4 Inter-operability with FTOOLS
 10.5 Inter-operability with Starbase
11 Browsing and selecting with an X display
 11.1 Statistics computed for individual columns
 11.2 Restarting xcatview after a crash
12 Browsing and selecting from the command line
 12.1 Running catview from a script
 12.2 Continuation lines for long lists of columns and expressions
  12.2.1 Examples
13 Listing header details
14 Copying a catalogue
15 Sorting a catalogue
16 Selecting subsets from a catalogue
 16.1 Running catselect
 16.2 Types of selections
17 Converting between celestial coordinate systems
 17.1 Running catcoord
18 Plotting finding charts
 18.1 Suitable catalogues
  18.1.1 Remote query
  18.1.2 Local copies
 18.2 Running catchart
 18.3 Customising the plot
  18.3.1 Running catchartrn
  18.3.2 Tutorial example graphics translation files
  18.3.3 The graphics translation file
 18.4 Worked example
19 Plotting with other packages
20 Pairing two catalogues
 20.1 Requirements
 20.2 Running catpair
  20.2.1 Special columns
  20.2.2 Retaining specified columns
  20.2.3 Running from a script
 20.3 Pairing criteria
  20.3.1 Cartesian coordinates
  20.3.2 Celestial coordinates
  20.3.3 Cases for the critical distance
 20.4 Rows in the output catalogue
 20.5 Multiple matches
 20.6 Pairing algorithm
21 Photometric calibration
 21.1 Description
 21.2 Assembling the input catalogues
  21.2.1 Standard star catalogue
  21.2.2 Programme object catalogue
 21.3 Applications for photometric calibration
 21.4 Running catphotomfit
 21.5 Running catphotomtrn
 21.6 Running catphotomlst
 21.7 Calculating the air mass
22 Binning columns in a catalogue into a grid
 22.1 Running catgrid
23 Importing CDS catalogues
 23.1 Running catcdsin
24 Importing regions of the HST GSC
25 Accessing remote catalogues
 25.1 Running catremote
  25.1.1 Listing the accessible catalogues
  25.1.2 Querying a remote catalogue
  25.1.3 Finding the coordinates of a named object
 25.2 Environment variables
 25.3 Specifying the list of remote catalogues
  25.3.1 Creating your own configuration file
 25.4 How remote access works
 25.5 Peculiarities and shortcomings
 25.6 Local or remote access?
A Expression syntax
 A.1 Creating a new column
 A.2 Defining a new selection
 A.3 Details of expressions
 A.4 Mathematical functions provided
 A.5 Rules for expressions
 A.6 Operator precedence
B Storing and representing columns of angles
 B.1 Angular format specifiers
C Catalogue formats
 C.1 FITS
  C.1.1 Textual information
 C.2 TST
  C.2.1 Textual information
  C.2.2 Null values
 C.3 STL
  C.3.1 Textual information
  C.3.2 Null values
D STL description tutorial
 D.1 First example
 D.2 Second example
E STL description reference
 E.1 Basics
  E.1.1 Continuation lines
  E.1.2 Strings
  E.1.3 Comments
 E.2 Columns
  E.2.1 Mandatory items
  E.2.2 Optional items
  E.2.3 Storing sexagesimal angles
 E.3 Parameters
  E.3.1 Mandatory items
  E.3.2 Optional items
 E.4 Directives
F KAPPA format STL
 F.1 Inter-operability with KAPPA
G Inter-operability with PISA
H Detailed description of applications
CATCDSIN – Convert a CDS ReadMe file into a CURSA STL description file
CATCHART – Plot a one or more target lists as a finding chart
CATCHARTRN – Translate a target list into a graphics attribute list
CATCOORD – Convert to a new celestial coordinate system
CATCOPY – Generate a new copy of a CAT catalogue
CATGRID – Generate an NDF grid from up to three columns in a catalogue
CATGSCIN – Convert a GSC region to the preferred CURSA format
CATHEADER – List various header information for a catalogue
CATPAIR – Pair two catalogues
CATPHOTOMFIT – Fit instrumental to standard magnitudes
CATPHOTOMLST – List a file of photometric transformation constants
CATPHOTOMTRN – Transform instrumental to calibrated mags. for programme stars
CATREMOTE – A simple script to query remote catalogues
CATSELECT – Generate a selection from a catalogue
CATSORT – Create a copy of a catalogue sorted on a specified column
CATVIEW – Application to browse and generate selections from a catalogue

References

CURSA Quick Reference

To set up for using CURSA type:    cursa

Applications
xcatview browse and generate selections from a catalogue (X-windows, easy-to-use),
catview browse and generate selections from a catalogue (command line),
catselect select a subset from a catalogue,
catcoord convert between celestial coordinate systems,
catchart plot a finding chart,
catchartrn set up ready for plotting a finding chart,
catheader list various header information for a catalogue,
catcopy copy a catalogue,
catsort sort a catalogue,
catpair pair two catalogues,
catgrid bin one, two or three columns into a histogram, image or data cube,
catphotomfit define photometric transformation coefficients,
catphotomtrn apply photometric transformation coefficients to programme objects,
catphotomlst list photometric transformation coefficients,
catcdsin convert a CDS text catalogue to STL format,
catgscin convert a region in the HST Guide Star Catalog to a more convenient format,
catremote access remote on-line catalogues.
Catalogue formats
FITS tables
(file types: .FIT .fit .FITS .fits .GSC .gsc). Binary and ASCII FITS tables.
TST
(file types: .TAB .tab). The Tab-Separated Table format used by GAIA.
STL
(file types: .TXT .txt). The Small Text List format.
Expressions

arithmetic operators: + - * / **
relational operators: .EQ. .NE. .GE. .GT. .LE. .LT. == /= >= > <= <
logical (boolean) operators: .AND. .OR. .NOT. & | #
brackets: use brackets, ‘(’, ‘)’, as appropriate,
sexagesimal values: use a colon (‘:’) to separate hours/degrees, minutes and seconds. Unsigned values are interpreted as hours; values in degrees must always have a sign (‘+’ or ‘-’). Sexagesimal values are converted to radians prior to evaluating the expression.
great circle distance: GREAT(α1, δ1,α2, δ2)
position angle of point (α2, δ2) from point (α1, δ1): PANGLE(α1, δ1,α2, δ2)

CURSA home page and on-line documentation

A ‘home page’ giving useful information about CURSA is available via the World Wide Web. Its URL is:

http://www.starlink.ac.uk/cursa/

An on-line version of SUN/190 (this manual) is also available via the World Wide Web. On Starlink systems type:

  % showme sun190

Otherwise access URL:

http://www.starlink.ac.uk/docs/sun190.htx/sun190.html

Assistance and further information

If you are experiencing difficulties using CURSA then in the first instance you should probably seek advice and assistance from your local site manager. Bug reports should be sent to username:

starlink@jiscmail.ac.uk

Bug reports should always be sent to username starlink@jiscmail.ac.uk. However, you are welcome to contact me directly for advice and assistance. Suggestions for enhancements and improvements to CURSA are also welcome. Details of how to contact me are given below.

Clive Davenhall

Postal address: Institute for Astronomy, Royal Observatory, Blackford Hill, Edinburgh,

EH9 3HJ, United Kingdom.

Electronic mail: acd@roe.ac.uk

Fax:

from within the United Kingdom: 0131-668-8416
from overseas: +44-131-668-8416

Acknowledgments

CURSA is far from being all my own work. Clive Page, Rodney Warren-Smith and Alan Wood have all been involved in aspects of its development. Indeed, Clive Page wrote the expression parser which CURSA uses, and Appendix A is based on documentation which he supplied. Malcolm Currie and Anne Sansom tested an early version of xcatview and suggested several significant improvements. Numerous other people have made useful contributions.

I am grateful to everyone who has contributed time and expertise.

Clive Davenhall
Department of Physics and Astronomy, University of Leicester
Saint Indract’s Day 1995

Various items of external software have been introduced into version 3.1 of CURSA which it is a pleasure to acknowledge. catremote accesses remote on-line catalogues using the catlib library developed by Allan Brighton, Miguel Albrecht and colleagues at the European Southern Observatory. Patrick Wallace gave useful advice and assistance during the development of catcoord and this application uses his SLA library to convert between celestial coordinate systems. catchart uses Tim Pearson’s PGPLOT to produce its plots. Last, but not least, FITS tables continue to be accessed using Bill Pence’s invaluable FITSIO library. I am also grateful to the numerous people who have commented on, and suggested improvements to, CURSA.

Clive Davenhall
Institute for Astronomy, University of Edinburgh
Saint Médard’s Day 1997

I am grateful to John Lucey for useful discussions about photometric calibration and for kindly providing the data used in the example catalogue of observations of photometric standard stars. Peter Draper gave helpful comments on the section of the manual describing the photometric calibration.

Clive Davenhall
Institute for Astronomy, University of Edinburgh
Saint Aed’s Day 1997

Revision history

(1)
8th May 1995: Original draft (ACD).
(2)
10th October 1995: Version 1 (ACD).
(3)
11th April 1996: Version 2. Modified so that the Latex source could be used to create an HTML as well as a paper version (ACD).
(4)
31st January 1997: Version 3. Modified for release 2.1 of the CURSA package. The major changes were the addition of the Small Text List (STL) format and the new application catselect (ACD).
(5)
8th June 1997: Version 4. Modified for release 3.1 of the CURSA package. The major changes were the new applications catcoord, catchart, catchartrn and catremote (ACD).
(6)
10th November 1997: Version 5. Modified for release 4.1 of the CURSA package. The major changes were the new applications for photometric calibration: catphotomfit, catphotomtrn and catphotomlst (ACD).
(7)
13th December 1998: Version 6. Modified for release 5.1 of the CURSA package. The major changes were the new application catcdsin and additional formats for reading sexagesimal angles from fixed-format STL catalogues (ACD).
(8)
29th November 1999: Version 7. Modified for release 6.1 of the CURSA package. The major changes were the addition of the Tab-Separated Table (TST) format, the new application catgrid and options for plotting scatter-plots and histograms in xcatview (ACD).
(9)
25th July 2000: Version 8. Modified for release 6.2 of the CURSA package. Version 6.2 contains no major enhancements, just some minor improvements and bug fixes. The main changes to the document are the removal of the description of the Tab-Separated Table (TST) format, which has been moved to SSN/75 and the inclusion of an additional appendix in the hyper-text version which gives descriptions of individual applications (ACD).
(10)
14th May 2001: Version 9. Modified for release 6.3 of the CURSA package. Version 6.3 contains no major changes, but rather a number of enhancements and bug fixes. There are improvements to the applications catcopy and catchart. The facilities to access remote catalogues via the Internet have been completely re-worked. A ‘quiet mode’ has been added to most of the applications. Support for the little-used CHI/HDS catalogue format has been removed.
(11)
4th November 2001: Version 10. Modified for release 6.4 of the CURSA package. Version 6.4 contains no major enhancements. Application catheader has been re-worked and now offers various options and more convenient output. A bug in xcatview has been fixed.

References

[1]   M. Albrecht, M. Barylak, D. Durand, P. Fernique, A. Micol, F. Ochsenbein, F. Pasian, B. Pirenne, D. Ponz and M. Wenger, 19 September 1996, Astronomical Server URL (Version 1.0). See URL: http://vizier.u-strasbg.fr/doc/asu.html

[2]   U. Bastian, S. Röser, V.V. Nesterov, D.D. Polozhentsev, Kh.I. Potter, R. Wielen, L.I. Yagudin and Ya.S. Yatskiv, 1991, Astron. Astrophys. Suppl, 87, pp159-162.

[3]   D.S. Berry, G.J. Privett and A.C. Davenhall, 15 September 1997, SUN/203.3: SX & DX — IBM Data Explorer for Data Visualisation, Starlink.

[4]   W.H. Beyer (editor), 1974, CRC Standard Mathematical Tables, twenty-fourth edition (CRC Press: Cleveland, Ohio).

[5]   M.J. Currie and D.S. Berry, 20 October 2000, SUN/95.16: KAPPA – Kernel Application Package, Starlink.

[6]   M.J. Currie, G.J.Privett, A.J.Chipperfield, D.S. Berry and A.C. Davenhall, 21 September 2000, SUN/55.14: CONVERT — A Format-conversion Package, Starlink.

[7]   A.C. Davenhall, 18 March 1993, SUN/162.1: A Guide to Astronomical Catalogues, Databases and Archives available through Starlink, Starlink.

[8]   A.C. Davenhall, 1 October 1997, SC/2.3: The DX Cookbook, Starlink.

[9]   A.C. Davenhall, 26 July 2000, SSN/75.1: Writing Catalogue and Image Servers for GAIA and CURSA, Starlink.

[10]   A.C. Davenhall, 4 April 2001, SUN/181.10: CAT — Catalogue and Table Manipulation Library: Programmer’s Manual, Starlink.

[11]   A.C. Davenhall, 24 May 2001, SSN/76.1: CATREMOTE — a Tool for Querying Remote Catalogues, Starlink.

[12]   P.W. Draper and N. Gray, 16 October 2000, SUN/214.8: GAIA — Graphical Astronomy and Image Analysis Tool, Starlink.

[13]   P.W. Draper and N. Eaton, 24 May 1999, SUN/109.10: PISA – Position Intensity and Shape Analysis, Starlink.

[14]   N. Eaton, P.W. Draper and A. Allan, 15 November 1999, SUN/45.10: PHOTOM – A Photometry Package, Starlink.

[15]   R.M. Green, 1985, Spherical Astronomy (Cambridge University Press: Cambridge).

[16]   R.H. Hardie, 1962, Photoelectric Reductions, Chapter 8 of Astronomical Techniques, ed. W.A. Hiltner, Stars and Stellar Systems, II (University of Chicago Press: Chicago), pp178-208. See especially p180.

[17]   P. Harrison, P. Rees and P. Draper, 12 November 1997, SUN137.6: PONGO – A Set of Applications for Interactive Data Plotting, Starlink.

[18]   P. Kunitzsch and T. Smart, 1986, Short Guide to Modern Star Names and Their Derivations (Otto Harrassowitz: Wiesbaden).

[19]   H. Meyerdierks, D.S. Berry, P.W. Draper, G.J. Privett and M.J. Currie, 14 February 1997, SUN/194.2: PDA — Public Domain Algorithms, Starlink.

[20]   D. Monet, A. Bird, B. Canzian, H. Harris, N. Reid, A. Rhodes, S. Sell, H. Ables, C. Dahn, H. Guetter, A. Henden, S. Leggett, H. Levison, C. Luginbuhl, J. Martini, A. Monet, J. Pier, B. Riepe, R. Stone, F. Vrba and R. Walker, 1996, USNO-SA1.0, (U.S. Naval Observatory: Washington DC). See also URL: http://www.nofs.navy.mil/

[21]   F. Ochsenbein, 12 September 1994, Astronomical Catalogues at CDS: Adopted Standards, version 1.4, p14. Available on-line from the CDS (see Section 2).

[22]   J. Palmer and A.C. Davenhall, 31 August 2001, SC/6.4: The CCD Photometric Calibration Cookbook, Starlink.

[23]   S. Röser and U. Bastian, 1988, Astron. Astrophys. Suppl, 74, pp444-451.

[24]   J.R. Rumble and F.J. Smith, 1990, Database Systems in Science and Engineering (Adam Hilger: Bristol).

[25]   E. Schoenberg, 1929, Hdb. d. Ap, 2, (Julius Springer: Berlin), p268.

[26]   K.T. Shortridge, H. Meyerdierks, M.J. Currie, M.J. Clayton, J. Lockley, A.C. Charles, A.C. Davenhall, M.B. Taylor, T. Ash, T. Wilkins, D. Axon, J. Palmer, A. Holloway and V. Graffagnino, 31 October 2001, SUN/86.19: FIGARO — A General Data Reduction System, Starlink.

[27]   R.W. Sinnott, 1988, NGC 2000.0 (Cambridge University Press: Cambridge and Sky Publishing Corporation: Cambridge, Massachusetts).

[28]   D.L. Terrett and N. Eaton, 12 July 1995, SUN/57.8: GNS – Graphics Workstation Name Service, Starlink.

[29]   M.-P. Veron-Cetty and P. Veron, 1989, Catalogue of Quasars and Active Galactic Nuclei, fourth edition (ESO Sci. Rep. 7).

[30]   J.V. Wall, 1979, ‘Practical Statistics for Astronomers’, Q. J. R. Astron. Soc, 20, pp138-152.

[31]   P.T. Wallace, 21 June 1995, SUN/56.10: COCO — Conversion of Celestial Coordinates, Starlink.

[32]   P.T. Wallace, 17 October 2000, SUN/67.51: SLALIB — Positional Astronomy Library, Starlink.

[33]   R.F. Warren-Smith, 11 January 2000, SUN/33.7: NDF — Routines for Accessing the Extensible N-Dimensional Data Format, Starlink.

[34]   R.F. Warren-Smith and D.S. Berry, 23 May 2000, SUN/210.7: AST — A Library for Handling World Coordinate Systems in Astronomy (Fortran Version), Starlink.

[35]   R.F. Warren-Smith and D.S. Berry, 23 May 2000, SUN/211.7: AST — A Library for Handling World Coordinate Systems in Astronomy (C Version), Starlink.