SUN/216.8

Starlink Project
Starlink User Note 216.8

T. Jenness, J. F. Lightfoot
Joint Astronomy Centre, Hilo, Hawaii

3 April 2003

Copyright © 1997-2000,2003 Particle Physics and Astronomy Research Council

SURF – SCUBA User Reduction Facility

1.6

User’s manual

pdfpict

Abstract

Surf is a set of ADAM tasks necessary for reducing demodulated Submillimetre Common-User Bolometer Array (SCUBA) data obtained from the James Clerk Maxwell Telescope. The tasks allows one to completely re-reduce your SCUBA data.

This document describes how to reduce SCUBA data and includes detailed descriptions of each task.

Contents

1 Introduction
2 Starting up Surf
 2.1 Getting help
3 What data do I have?
4 Supported Observing Modes
5 Message filtering
6 SCUBA sections
7 Environment variables
 7.1 Surf environment variables
  7.1.1 DATADIR
  7.1.2 SCUBA_PREFIX
  7.1.3 SCUBA_SUFFIX
 7.2 Other useful environment variables
8 Basic outline of SCUBA data reduction
9 The data reduction process
 9.1 Preliminaries
 9.2 Skydips
 9.3 Noise measurements
 9.4 Common data reduction
 9.5 Despiking
  9.5.1 Manual despiking
  9.5.2 Automatic despiking
 9.6 Map making
  9.6.1 Rebinning multiple datasets
  9.6.2 Output coordinate frames
  9.6.3 Exporting maps
 9.7 Photometry
  9.7.1 Surf photometry and Kappa
 9.8 Scan maps
  9.8.1 Baseline removal
  9.8.2 Sky removal
  9.8.3 Dual beam deconvolution
 9.9 Polarimetry data reduction
10 Citing SURF
11 Future Work
12 Release Notes
 12.1 Changes in Version 1.6-11
 12.2 Changes in Version 1.6-10
 12.3 Changes in Version 1.6-9
 12.4 Changes in Version 1.6-8
 12.5 Changes in Version 1.6-7
 12.6 Changes in Version 1.6
 12.7 Changes in Version 1.5
 12.8 Changes in Version 1.4
 12.9 Changes in Version 1.3
 12.10 Changes in Version 1.2
 12.11 Changes in Version 1.1
 12.12 Version 1.0–0
Glossary
References
A An alphabetical summary of Surf commands
B Classified Surf commands
C Complete routine descriptions
ADD_DBM – Generate a chopped image from a single beam map
BOLREBIN – Generate a separate regridded image for each bolometer
CALCSKY – Calculate sky contribution from median image
CHANGE_DATA – Set SCUBA data to any value
CHANGE_FLAT – Change the flatfield in a SCUBA datafile
CHANGE_NACENTRE – Shift the Nasmyth centre of the array
CHANGE_POINTING – Change the pointing corrections to map data
CHANGE_QUALITY – Set SCUBA data quality bad or good
DESPIKE – Despike data by position
DESPIKE2 – Remove spikes from SCAN/MAP observations
DSPBOL – Interactive display and despiking
EXTINCTION – Remove the effect of atmospheric extinction from a SCUBA observation
EXTRACT_DATA – Write bolometer positions and values to text file
EXTRACT_FLAT – Extract a flatfield from a SCUBA demodulated data file
FLATFIELD – Flatfield demodulated SCUBA data
INTREBIN – Generate a separate regridded image for each integration
MAPSUM – Produce one-line summary of SCUBA map observations
OBSSUM – Produce one-line summary of SCUBA observations
PHOTSUM – Produce one-line summary of SCUBA photometry observations
PLTBOL – Interactive bolometer display
POINTSUM – Produce one-line summary of SCUBA pointing observations
QDRAW – Draw a data set with plus or minus 5 sigma range
REBIN – Rebin demodulated SCUBA data onto output map
REDUCE_NOISE – Process demodulated noise data
REDUCE_SWITCH – reduce the switch sequence for a SCUBA observation
REMDBM – Remove dual beam signature from scan maps
REMIP – Remove instrumental polarisation from SCUBA pol data
REMSKY – Remove sky noise and constant offsets from SCUBA jiggle data
RESTORE – remove the chopped beam response from SCAN/MAP observations
RLINPLOT – Interactive display
SCAN_RLB – Remove baselines from SCAN/MAP data
SCUBA2MEM – Calculate bolometer positions as tangent plane offsets
SCUCAT – Concatenate photometry datasets for further processing
SCUCLIP – Simple sigma clipping for each bolometer
SCUCLKERR – Determine the possible error in the times stored in the data header
SCUHELP – Gives help about SCUBA software
SCULOG – Produce summary of SCUBA observations
SCUMAKEWT – Create weights array for dual beam deconvolution
SCUNOISE – Display SCUBA noise data
SCUOVER – Routine to overlay the bolometer names onto a rebinned image
SCUPA – Show position angle of array
SCUPHOT – Reduce SCUBA PHOTOM data
SCUPLOT – Interactive display and despiking
SCUQUICK – automate the basic SCUBA data reduction
SCUSETENV – Set the startup environment variables for SURF
SCUSHIFT – Correct for data shift error in demodulated data files
SDIP – Reduces and displays skydip data
SETBOLWT – Calculate or set bolometer weights
SIGCLIP – Clip a dataset at n-sigma
SKYDIP – calculate sky properties from SCUBA skydip data
SKYSUM – Produce one-line summary of SCUBA skydip observations

D Reducing data at the Joint Astronomy Centre
 D.1 During Observing
 D.2 Hilo
E File naming and data structures
 E.1 Naming Conventions
 E.2 Structure of RO files
 E.3 Structure of demodulated files
F FITS keywords
 F.1 Demodulated data
 F.2 Rebinned data
G Description of despiking method used by despike
H Quality flags
I Skydips
 I.1 Calibration
 I.2 Removing bad skydip data from the fit
J Correcting ‘shifted’ data
K Notes on scripts

Glossary

chopping The secondary mirror is continuously moved on and off source at approximately 7 Hz in order to remove the sky to zeroth order. This is done in addition to standard jiggling.
demodulation Removal of the chop signal by the transputers. At this time, the raw data can not be accessed, only the demodulated data are stored.
exposure An exposure is the result from a complete set of switches. For example, in a JIGGLE/MAP or PHOTOM observation where the telescope is nodding the source between left and right beams, the data from each nod position is a switch and the reduced result ‘left switch’ - ‘right switch’ say, is an exposure. In a SCAN/MAP observation there is no beam switching so, in this case, an exposure is the same as a switch.
integration An integration means different things for different observations.

For one of the mapping modes it means the data from one fully-sampled coverage of the map area. In a JIGGLE/MAP, where full sampling is achieved by jiggling the secondary mirror, an integration is generally the results from one pass through the complete jiggle pattern. An integration is made up of one or more exposures.

Similarly, an integration for a SCAN/MAP observation is made up of data from the raster scans that cover the map area once.

For PHOTOM observations an integration is usually the average of a 9 point mini-jiggle.

For a SKYDIP observation, an integration is the data from a single revolution of the sector chopper in front of the cryostat window.

jiggle In order to sample an image fully the secondary mirror is moved once a second (whilst chopping) to move the position of the array on the sky; this is called ‘jiggling.’ There are a complete set of jiggle positions for each integration. A PHOTOM observation can also jiggle in order to correct for seeing effects.
measurement A measurement is a group of integrations. Most MAP or PHOTOM observations will consist of only one measurement.

A FOCUS or ALIGN observation consists of five measurements (one for each secondary mirror position). A SKYDIP observation consists of one measurement at each elevation.

nod In order to correct for atmospheric variation the telescope is moved off-source in each exposure so that sky can be measured.
ODF The observation definition file (ODF) is a file containing a list of instructions for an observation with SCUBA.
sub-instrument SCUBA contains bolometer arrays and photometric pixels that can operate at several wavelengths simultaneously. Each of these is called a sub-instrument. They are:
switch The switch is the fundamental unit of data-taking in an observation. For example in a JIGGLE/MAP or PHOTOM observation each chunk of jiggle positions measured with the object in the beam of a telescope is a switch. Each scan across the source in a SCAN/MAP observation is also a switch.
tau (τ) Submillimetre extinction is measured using the zenith optical depth, tau or τ, this is a measure of the amount of water vapour present in the atmosphere. For a tau, τ at a given airmass, A, the attenuation due to the atmosphere is given as e−Aτ. Note that tau is wavelength dependent and that the value quoted by the Caltech Submillimetre Observatory (CSO) is the τ at 225 GHz and will therefore be different at the other wavelengths used by SCUBA (see [31] for details of the variation with SCUBA filters; or [32] for details on the variation seen with UKT14).

References

[1]   Holland W. S, Cunningham C. R., Gear W.K., Jenness T., Laidlaw K., Lightfoot J. F., Robson E. I., 1998, “SCUBA – A submillimetre camera operating on the James Clerk Maxwell Telescope” in Advanced Technology MMW, Radio and Terahertz Telescopes, Philips T. G. (ed), Proc. SPIE 3357, 305

[2]   Holland W. S., Robson E.I., Gear W.K., Lightfoot J. F., Jenness T., Ivison R. J., Stevens J. A., Cunningham C. R., Ade P. A. R., Griffin M. J., Duncan W. D., Murphy J. A., Naylor D. A., 1999, MNRAS, 303, 659

[3]   Warren-Smith R. F., 1995, NDF – Routines for Accessing the Extensible N-Dimensional Data Format, Starlink User Note 33

[4]   Draper P. W., 1997, GAIA – Graphical Astronomy and Image Analysis Tool, Starlink User Note 214

[5]   Currie M. J., 1997, KAPPA — Kernel Application Package, Starlink User Note 95

[6]   Privett G. J., Jenness T., Matthews H. E., 1997, FLUXES – JCMT Position and Flux Density Calibration, Starlink User Note 213

[7]   Currie M. J., Privett G. J., Chipperfield A. J., 1995 CONVERT – A format-conversion package, Starlink User Note 55

[8]   Currie M. J., 1994, HDSTRACE – HDS data file listing, Starlink User Note 102

[9]   Stevens J. A., Ivison R. J., Jenness T., 1997, The SCUBA photometry cookbook, Starlink Cookbook 10

[10]   Sandell G., 1997, The SCUBA mapping cookbook: A first step to proper map reduction, Starlink Cookbook 11

[11]   Emerson D. T., Klein U., Haslam C. G. T., 1979, ApJ, 76, 92

[12]   Emerson D. T., A.S.P. Conf. Ser 75, 309

[13]   Jenness T., Lightfoot J. F., Holland W. S., 1998, “Removing Sky contributions from SCUBA data” in Advanced Technology MMW, Radio and Terahertz Telescopes, Philips T. G. (ed), Proc. SPIE 3357, 548

[14]   Matthews H. E., Jenness T., 1997, The Specx cookbook, Starlink Cookbook 8

[15]   Chipperfield A. J., 1999, ADAM, Starlink User Note 144

[16]   Richer J. S., 1992, MNRAS, 254, 165

[17]   Eaton N., 1995, AGI — Applications Graphics Interface, Starlink User Note 48

[18]   Rees P. C. T., Chipperfield A. J., 1995, MERS (MSG and ERR) – Message and Error Reporting Systems, Starlink User Note 104

[19]   Greisen E. W., Calabretta M., 2002, Representations of celestial coordinates in FITS, A&A, 395, 1077

[20]   Warren-Smith R. F., Berry D. S., 1998, AST – A Library for Handling World Coordinate Systems in Astronomy, Starlink User Note 210

[21]   Warren-Smith R. F., Lawden M. D., 1995, HDS – Hierarchical Data System, Starlink User Note 92

[22]   Terrett D. L., 1993, PSMERGE – Encapsulated Postscript handling utility, Starlink User Note 164

[23]   Berry D. S., Gong W., Parsons D. C., 1995, IRAS90 — IRAS Survey and PO Data Analysis Package – Reference Guide, Starlink User Note 163

[24]   Jenness T., Stevens J.A., Archibald E.N., Economou F., Jessop N.E., Robson E.I., MNRAS, 336, 14

[25]   Shortridge K., Meyerdierks H. M., Currie M. J., Clayton M., FIGARO – A general data reduction system, Starlink User Note 86

[26]   Hughes D. H., 1993, JCMT–UKIRT Newsletter, 4, 32

[27]   Economou F., Bridger A., Wright G. S., Rees N. P., Jenness T., 1998, “The future of data reduction at UKIRT”, Astronomical Data Analysis Software and Systems VII, Albrecht R., Hook R. N., Bushouse H. A. (eds), ASP Conference Series, 145, 195

[28]   Jenness T., Economou .F., 1999, The SCUBA Data Reduction Pipeline: ORAC-DR at the JCMT, in Astronomical Data Analysis Software and Systems VIII, Mehringer D. M., Plante R. L., Roberts D. A. (eds), ASP Conf. Ser., 172, 171

[29]   Berry D. S., Gledhill T. M., 1999, Polpack – An imaging polarimetry reduction package, Starlink User Note 223

[30]   Jenness T., Lightfoot J. F., 1999, The SURF Programming Interface, Starlink System Note 72

[31]   Archibald E.N., Jenness T., Holland W.S., Coulson I.M., Jessop N.E., Stevens J.A., Robson E.I., Tilanus R.P.J., Duncan W.D., Lightfoot J.F., 2002, MNRAS, 336, 1

[32]   Stevens J. A., Robson E. I., 1994, MNRAS, 270, L75

[33]   Meyerdierks H. M., Berry D., Draper P., Privett G., Currie M. J., 1997, PDA – Public Domain Algorithms, Starlink User Note 194

[34]   Berry, D. S., 1996, GRP – Routines for Managing Groups of Objects, Starlink User Note 150

[35]   Duncan, W. D., SCUBA project documentation, SCU/WDD/31.1/1093

[36]   Archibald, E., Wagg J. W., Jenness T., 2000, Calculating Sky Opacities: a re-analysis for SCUBA data, SCUBA Calibration Database System Note 002

[37]   Wall L., Christiansen T., Schwartz R. L., 1996, Programming Perl, 2nd edn., O’Reilly & Associates, Inc.

[38]   Jenness T., Bly M. J., 1998, NDFPERL – Perl interface to NDF, Starlink User Note 222