From 479e8dc70141157e44701ac516952c01b78d2280 Mon Sep 17 00:00:00 2001 From: "Malcolm J. Currie" Date: Sun, 16 Sep 2012 02:57:54 -1000 Subject: [PATCH] docs: SC/21---Use text links for hypertext for internal cross referencing. Those boxes for internal cross-referencing look naff especially the cluster of them in the Introduction, and they aren't as clear as text strings. Added a newcommand to simplify this. In some cases this was not ideal; to avoid repeating the title in the link as already written or paraphrased in the sentence there are a few "this appendix" or equivalent. There was a bonus in that some named objects previously did not begin with a capital letter and were missing the ~ to prevent an object and its \ref{label} number from being broken across lines. (cherry picked from commit 777836c20122fbe7b8a6e2d577b5d7386127460f) --- docs/sc/021/sc21.tex | 276 +++++++++++++++++++++++++------------------ 1 file changed, 159 insertions(+), 117 deletions(-) diff --git a/docs/sc/021/sc21.tex b/docs/sc/021/sc21.tex index e2210cd8f53..2cd12bfb266 100644 --- a/docs/sc/021/sc21.tex +++ b/docs/sc/021/sc21.tex @@ -331,7 +331,11 @@ } \end{htmlonly} - +% A command to cross-reference in both LaTeX and hypertext. +% #1 is the type such as Section, Table, Figure; #2 is +% the label; and #3 is the text or title associated with the +% reference. +\newcommand{\cref}[3]{\latexhtml{#1~\ref{#2}}{\htmlref{#3}{#2}}} % ? End of document specific commands % ----------------------------------------------------------------------------- @@ -480,24 +484,36 @@ \subsection{\xlabel{using_guide}This Cookbook} Cookbook.}{sc19}{}\latex{\footnote{\texttt{http://www.starlink.ac.uk/docs/sc19.htx/sc19.html}}} A brief description of the instrument and the observing modes is given -in Section~\ref{sec:s2}. Details on data acquisition and instructions -for examining raw data are given in Section~\ref{sec:raw}. -Section~\ref{sec:dimm} introduces the Dynamic Iterative Map-Maker -(DIMM). This section offers an in-depth description of the map-making +in \cref{Section}{sec:s2}{an Overview}. Details on data acquisition and +instructions for examining raw data are given in +\cref{Section}{sec:raw}{Raw SCUBA-2 data}. +\cref{Section}{sec:dimm}{This page} introduces the Dynamic Iterative Map-Maker +(DIMM). It offers an in-depth description of the map-making process and introduces the configuration files necessary to run the -reduction. The most important section will be Section~\ref{sec:maps}; +reduction. The most important section will be +\cref{Section}{sec:maps}{Reducing your data}; this outlines all the steps that may be taken to produce your final science map, including running the DIMM, applying the flux conversion factor (FCF), co-adding multiple maps and estimating the noise. -Section~\ref{sec:tweak} discusses your options for tweaking the configuration +\cref{Section}{sec:tweak}{Tweaking the configuration file} +discusses your options for adjusting the configuration parameters when running the map-maker; this gives you added control and flexibility over the map-making routine. Two worked examples -covering different science case are shown in Section~\ref{sec:eg} -- a -blank cosmology field (\S\ref{sec:cosmology}) and a galactic field -(\S\ref{sec:bright_ex}) with bright, extended emission. Section -\ref{sec:pipe} introduces the science pipeline and data retrieval from -the JCMT Science Archive. Data calibration is discussed in Section -\ref{sec:cal}, along with instructions for calculating your own FCF. +covering different science case are shown in +\cref{Section}{sec:eg}{Examples} -- a +\htmlref{blank cosmology field}{sec:cosmology} +\begin{latexonly} +(\S\ref{sec:cosmology}) +\end{latexonly} +and a \htmlref{galactic field}{sec:bright_ex} +\begin{latexonly} +(\S\ref{sec:bright_ex}) +\end{latexonly} +with bright, extended emission. +\cref{Section}{sec:pipe}{SCUBA-2 Pipeline} introduces the science +pipeline and data retrieval from the JCMT Science Archive. Data +calibration is discussed in \cref{Section}{sec:cal}{SCUBA-2 data +calibration}, along with instructions for calculating your own FCF. \subsection{\xlabel{computing}Before you start: Computing resources} @@ -506,7 +522,9 @@ \subsection{\xlabel{computing}Before you start: Computing resources} map. For large-area maps it is important to process a full observation in a -single chunk -- see the text box on Page~\pageref{page:text} for a +single chunk -- see the text box on +\latexhtml{Page~\pageref{page:text}}{\htmlref{What to look +for}{box:chunk}} for a discussion of the effects of chunking. For normal map-maker parameters this implies that a machine of 96GB should be acceptable. It is important that the memory is as fast as can be afforded as RAM speed @@ -527,8 +545,8 @@ \subsection{\xlabel{computing}Before you start: Computing resources} \htmladdnormallink{JCMT Science Archive at CADC.}{http://www3.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/jcmt/} \latex{\footnote{\texttt{http://www3.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/jcmt/}}} -See Section~\ref{sec:pipe} for details on the science pipeline and -retrieving your data from CADC. +See \cref{Section}{sec:pipe}{SCUBA-2 Pipeline} for details on the +science pipeline and retrieving your data from CADC. \subsection{\xlabel{software}Before you start: Software} @@ -593,11 +611,11 @@ \subsection{\xlabel{software}Before you start: Software} to be run (note the caps) and \param{} is a list of files to be run, which must be int the current directory, or a directory defined by \param{ORAC\_DATA\_OUT}. A number of \textsc{Picard} -recipes will be demonstrated in Section~\ref{sec:maps}. +recipes will be demonstrated in \cref{Section}{sec:maps}{Reducing your data}. \textbf{Note:} The \textsc{Picard} recipes require all input files to have the \texttt{.sdf} extension included; this is not the case for the -Starlink packages \textsc{Kappa} and textsc{Smurf}. +Starlink packages \textsc{Kappa} and \textsc{Smurf}. \clearpage \section{\xlabel{scuba2_overview}SCUBA-2 Overview} @@ -708,8 +726,8 @@ \subsection{\xlabel{obs_modes}Observing modes} is recommended a minimum of 3, but preferably more than 5, \textsc{pong} maps are included in a single observation with a rotation introduced between each one. In this way a circular pattern -is built up, (see the right hand panel of Figure~\ref{fig:scan}), with -a diameter equal to your requested map size. +is built up, (see the right hand panel of \cref{Figure}{fig:scan}{graphic below}), +with a diameter equal to your requested map size. \vspace{0.2cm}\\ To recover large scale extended structure you are advised to use larger \textsc{pong} maps which scan at a higher rate. This option is @@ -726,8 +744,8 @@ \subsection{\xlabel{obs_modes}Observing modes} ($<$3\,arcmin) by maximising the exposure time on the centre of the image. The telescope moves at a constant velocity in a `spirograph' pattern that has the advantage of keeping the source on the array -throughout the observation. This is shown in the top panel of Figure -\ref{fig:scan}. +throughout the observation. This is shown in the top panel of +\cref{Figure}{fig:scan}{the figure below}. \end{minipage} \myfig{sc21_wayne_scan}{[b!]}{width=0.9\linewidth}{fig:scan}{ @@ -740,8 +758,8 @@ \subsection{\xlabel{obs_modes}Observing modes} \textsc{pong} pattern for a typical map based on an 1800-arcsec demanded map size. The scan pattern for your observation can be visualised like this with \topcat\ using the output from \jcmtstate. - See Section~\ref{sec:exam} for more details. Figure taken from - Holland et al. (2012).} + See \cref{Section}{sec:exam}{Examining raw data} for more details. + Figure taken from Holland et al. (2012).} \clearpage @@ -757,7 +775,8 @@ \section{\xlabel{data_files}Raw SCUBA-2 Data} \end{itemize} \vspace{-2mm} The \param{SEQ\_TYPE} parameter in the FITS header may be used to -identify the nature of each scan (see Section~\ref{sec:fitsheader}). +identify the nature of each scan (see +\cref{Section}{sec:fitsheader}{Headers and file structure}). When you access you data either at the JCMT or by downloading from the \htmladdnormallink{Science Archive}{http://www3.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/jcmt/} \begin{latexonly} @@ -802,9 +821,10 @@ \section{\xlabel{data_files}Raw SCUBA-2 Data} (Jy). The first step is applied internally by the map-maker but can be done -manually when examining the raw data -- see Section~\ref{sec:concat}. +manually when examining the raw data -- see +\cref{Section}{sec:concat}{Concatenate \& apply a flat-field}. The second step must be done manually with the instructions given in -Section~\ref{sec:cmult}. +\cref{Section}{sec:cmult}{Applying the FCF and determining fluxes}. \subsection{\xlabel{examine}Examining raw data} @@ -986,9 +1006,10 @@ \subsubsection{\xlabel{scan_pat}Displaying scan patterns} \end{myquote} Example of scan patterns displayed with \topcat\ can be seen in -Figure~\ref{fig:scan}. Detailed instruction on how to display the scan -pattern for your observation are given in Figure~\ref{fig:topcat}. All -of the time-varying header values are available for plotting. Other +\cref{Figure}{fig:scan}{telescope tracks}. Detailed instruction on +how to display the scan pattern for your observation are given in +\cref{Figure}{fig:topcat}{box below}. +All of the time-varying header values are available for plotting. Other values include the azimuth and elevation offsets (DAZ \& DEL), the WVM and 225\,GHz opacity values, and the instrument temperatures (e.g. SC2\_FPUTEMP gives the temperature of the focal plane). @@ -1041,7 +1062,7 @@ \subsubsection{\xlabel{display_cube}Displaying time-series data} \end{myquote} Loading a file in \textsc{Gaia} produces two windows (see -Figure~\ref{fig:gaia_main}). The main window shows a map of bolometer +\cref{Figure}{fig:gaia_main}{upper graphic}). The main window shows a map of bolometer values at a given point in time. The time slice displayed may be changed by scrolling through the time axis. This is done in the second window entitled `Display image sections of a cube'. The `Index of @@ -1080,7 +1101,7 @@ \subsection{\xlabel{regrid_map}Regridding data into a map} \end{verbatim} \end{myquote} The output map here is called \texttt{crl2688\_sky.sdf} and is shown -in Figure~\ref{fig:regrid}. +in \cref{Figure}{fig:regrid}{the figure below}. The pixel scale is left at the default values of 2~arcsec on a side at 450$\mu$m and 4~arcsec at 850$\mu$m (although this can be changed using the \texttt{pixsize=}$x$ option on the command-line, where $x$ is in @@ -1095,7 +1116,7 @@ \subsection{\xlabel{clean}Notes on cleaning your data} Cleaning raw data is an essential first step towards making a quality final map. The map-maker performs all of these cleaning steps during the pre-processing stage. The commands for manually cleaning your data -are given in Appendix~\ref{app:clean}. +are given in \cref{Appendix}{app:clean}{Cleaning the Raw Data}. % Split to avoid paragraph break mid-sentence. \begin{htmlonly} @@ -1137,8 +1158,9 @@ \subsection{\xlabel{calcnoise}Checking the array performance} If you have a bright source in the field this will contaminate the signal. In this case you should examine the -\texttt{NOI} model from the map-maker instead -- see Section -\ref{sec:models} for a description and Section~\ref{sec:export} for +\texttt{NOI} model from the map-maker instead -- see +\cref{Section}{sec:models}{The Individual Models} for a description +and \cref{Section}{sec:export}{Exporting individual models} for details on how to examine it. \clearpage @@ -1164,8 +1186,9 @@ \subsection{\xlabel{dimm_theory}The theory} contributions that make up the signal recorded by each bolometer. It models and then subtracts all the sources of signal in order of decreasing magnitude, ultimately leaving just the astronomical signal -plus noise. A list of the modelled components can be seen in Table -\ref{tab:mods} and a description found in Section~\ref{sec:models}. +plus noise. A list of the modelled components can be seen in +\cref{Table}{tab:mods}{tabulated} and a description found in +\cref{Section}{sec:models}{The Individual Models}. The map-maker requires a configuration file to accompany each reduction. This file instructs the map-maker on the pre-processing @@ -1174,23 +1197,25 @@ \subsection{\xlabel{dimm_theory}The theory} There is single `master' configuration file -- \texttt{dimmconfig.lis} -- which contains \emph{all} the available options (though most are commented out by default) and is fully documented. A copy of this file -is available in Appendix~\ref{app:dimm}. +is available in \cref{Appendix}{app:dimm}{an appendix}. Often, the default configuration file will not give optimal results for your particular observation. For this reason, specialised configuration files have been developed which are tailored to different science goals, be they detecting faint galaxies or mapping -large molecular clouds. Nevertheless, these specialised models A -description of these specialised configuration files can be found in -Section~\ref{sec:config}. +large molecular clouds. A +description of these specialised configuration files can be found +\cref{in Section}{sec:config}{here}. \\ \\ {\large{\texttt{\bf dimmconfig.lis}}}\\ -Figure~\ref{fig:dimm} shows of flow chart of the map making process +\cref{Figure}{fig:dimm}{The graphic below} shows the flow chart +of the map making process for \texttt{dimmconfig.lis}. It is divided into two sections: the pre-processing stage where the data are cleaned, then the iterative stage where the different models are subtracted. -Table~\ref{tab:dimmdef} gives all the variables in -\texttt{dimmconfig.lis} again divided into the two main stages. +\cref{Table}{tab:dimmdef}{A table of active variables} gives all the +configuration parameters in \texttt{dimmconfig.lis} again, divided +into the two main stages. \myfig{sc21_flow_dimm_blue}{}{width=0.78\linewidth}{fig:dimm}{ A flow chart illustrating the dynamic iterative map-maker. Note that @@ -1282,7 +1307,8 @@ \subsection{\xlabel{models}The individual models} \vspace{-0.1cm} The only recipe not following this model order is the one tailored for blank field maps which does not include a \texttt{FLT} model in the -iterative stage (see Section~\ref{sec:config}). Below is a basic +iterative stage (see \cref{Section}{sec:config}{Specialised +configuration files}). Below is a basic description of each model, while more complete descriptions of the models and all the associated caveats can be found in Chapin et al. (2012) \cite{mapmaker}. @@ -1318,9 +1344,9 @@ \subsection{\xlabel{models}The individual models} \end{minipage} \begin{minipage}[t]{0.92\linewidth}\texttt{EXT} applies the extinction correction. This is a time-varying scaling factor that is derived from -the JCMT water vapour radiometer. As it deals with 30-second chunks of +the JCMT water-vapour radiometer. As it deals with 30-second chunks of data this accounts for varying conditions over a long observation. For -more details see Section~\ref{sec:cal}. \\ +more details see \cref{Section}{sec:cal}{SCUBA-2 data calibration}. \\ \end{minipage} \begin{minipage}[t]{0.07\linewidth} \texttt{FLT} @@ -1336,7 +1362,7 @@ \subsection{\xlabel{models}The individual models} extended emission varies slowly over the array; it therefore appears at low frequencies and complicates the choice of a high-pass filter. A further discussion of this matter is given in -Section~\ref{sec:bright_ex}\\ +\cref{Section}{sec:bright_ex}{Extended galactic sources}\\ \end{minipage} \begin{minipage}[t]{0.07\linewidth} \texttt{AST} @@ -1355,9 +1381,10 @@ \subsection{\xlabel{models}The individual models} \end{minipage} \begin{minipage}[t]{0.92\linewidth}\texttt{NOI} should come last in the model order and calculates the RMS noise in each bolometer. \texttt{NOI} is -determined by running \calcnoise\ (see Section~\ref{sec:calcnoise}) on -the residual signal (the \texttt{RES} model, see -Section~\ref{sec:export}). Unlike the other models, \texttt{NOI} is +determined by running \calcnoise\ (see \cref{Section}{sec:calcnoise}{Checking the +array performance}) on the residual signal (the \texttt{RES} +model, see \cref{Section}{sec:export}{Exporting individual models}). Unlike +the other models, \texttt{NOI} is not a subtraction or a correction but if specified, is used (from the second iteration onwards) to weight the bolometers in the map estimate. @@ -1474,7 +1501,8 @@ \subsection{\xlabel{export}Exporting individual models} remaining after the other models have been removed. By contrast, the \texttt{NOI} model is the noise in \texttt{RES}, as determined by running \texttt{RES} through \calcnoise\ (see -Section~\ref{sec:calcnoise}). If \texttt{NOI} is exported, it can be +\cref{Section}{sec:calcnoise}{Checking the array performance}). If +\texttt{NOI} is exported, it can be viewed as the VARIANCE component of the \texttt{RES} model; thus, export of \texttt{RES} is implied if \texttt{NOI} is specified. @@ -1503,7 +1531,8 @@ \subsection{\xlabel{export}Exporting individual models} which can be examined using all of the existing Starlink tools. Examples of the time traces for a single bolometer from these output -models is shown in Figure~\ref{fig:itercomp}. These traces cover a +models is shown in \cref{Figure}{fig:itercomp}{time-domain components}. +These traces cover a subset of an observation of the secondary calibrator CRL2688. The \texttt{COM} model is removed first, being the dominant source. The \texttt{FLT} model stores the data removed by the high-pass filter. In @@ -1606,7 +1635,7 @@ \subsection{\xlabel{export}Exporting individual models} \caption{\small The active variables from \texttt{dimmconfig.lis} and their default values. For a fuller description of each, as well as other options, see the comments in the file itself. This can be found in -Appendix~\ref{app:dimm}.} +\cref{Appendix}{app:dimm}{this appendix}.} \end{footnotesize} \end{center} \end{table*} @@ -1704,7 +1733,7 @@ \subsection{\xlabel{export}Exporting individual models} \caption{\small The active variables from \texttt{dimmconfig.lis} and their default values. For a fuller description of each, as well as other options, see the comments in the file itself. This can be found in -Appendix~\ref{app:dimm}.} +\cref{Appendix}{app:dimm}{this appendix}.} \end{footnotesize} \end{center} \end{table*} @@ -1730,16 +1759,16 @@ \subsection{\xlabel{config}Specialised configuration files} \\ \\ The specialised files are all based on \texttt{dimmconfig.lis}, and any parameters in these files simply override the relevant default -values. Table~\ref{tab:dimmdef} list all the active variables +values. \cref{Table}{tab:dimmdef}{A table} lists all the active variables contained in \texttt{dimmconfig.lis} and gives their default values and a brief description. For comprehensive documentation on \emph{all} available variables see the \texttt{dimmconfig.lis} file itself in -Appendix~\ref{app:dimm}. +\cref{Appendix}{app:dimm}{an appendix}. \\ \\ Below is a description of each of the specialised configuration files available; the table following each description lists the parameters set for each recipe. A verbatim copy of these files can be found in -Appendix~\ref{app:special}. +\cref{Appendix}{app:special}{Specialised Configuration Files}. \subsubsection{dimmconfig\_blank\_field.lis} @@ -1759,11 +1788,12 @@ \subsubsection{dimmconfig\_blank\_field.lis} improved but with the loss of any structure on scales larger than a single sub-array -- not an issue for blank fields. -Figure~\ref{fig:bfcompare} shows the sharp contrast in the output map -between reducing data with the default configuration file and using -\texttt{dimmconfig\_blank\_field.lis}. +\cref{Figure}{fig:bfcompare}{The images below} shows the sharp +contrast in the output map between reducing data with the default +configuration file and using \texttt{dimmconfig\_blank\_field.lis}. -Normally blank-field map would subsequently have a applied to it to aid source detection (see Section~\ref{sec:mf}), +Normally blank-field map would subsequently have a applied to it to aid +source detection (see \cref{Section}{sec:mf}{Point-source detection}), however this is not applied by the map-maker. \vspace{0.3cm} \latex{\renewcommand*\arraystretch{0.8}} @@ -1809,8 +1839,8 @@ \subsubsection{dimmconfig\_bright\_compact.lis} This is the recipe that is commonly used to reduce calibration observations with a pixel size set to 1~arcsec -- see -Section~\ref{sec:fcf} for details on determining the FCFs from -calibrators. +\cref{Section}{sec:fcf}{Flux conversion factors} for details on +determining the FCFs from calibrators. \vspace{0.3cm} \begin{latexonly} @@ -1880,10 +1910,10 @@ \subsubsection{dimmconfig\_bright\_extended.lis} mask from the emission and rerun the map-maker with this external mask applied. This method is superior to simply forcing to zero everything below 5$\sigma$. Details on how to do this are outlined in -Section~\ref{sec:maskbe}. +\cref{Section}{sec:maskbe}{Supplying an external mask}. -Figure~\ref{fig:becompare} shows a comparison between maps reduced -with the default configuration file and using +\cref{Figure}{fig:becompare}{The images below} shows a comparison between +maps reduced with the default configuration file and using \texttt{dimmconfig\_bright\_extended.lis}; the most noticeable difference is the improvement in the bowling around strong sources. @@ -1964,18 +1994,20 @@ \subsection{\xlabel{running_dimm}Running the map-maker} The map-maker is enabled using the \texttt{method=iterate} option for the \makemap\ task. In the following example we produce a map of CRL2688, one of SCUBA-2's secondary calibrators. As discussed in -Section~\ref{sec:dimm}, all of the settings for the map-maker are +\cref{Section}{sec:dimm}{The Dynamic Iterative Map-Maker}, all of +the settings for the map-maker are stored in configuration files. In this example we will just use the default configuration file,\texttt{dimmconfig.lis}. For an overview of the specialised configuration files available see -Section~\ref{sec:config}. +\cref{Section}{sec:config}{this section}. As an input to the map-maker, any of the standard \smurf\ configuration files can be called directly from the Starlink path with \texttt{\^\,\$STARLINK\_DIR/share/smurf/dimmconfig*.lis}. Alternatively, a local copy can be made and called with \texttt{\^\,dimmconfig*.lis}. Details of how to edit any of the -parameters can be found in Section~\ref{sec:tweak}. +parameters can be found in \cref{Section}{sec:tweak}{Tweaking the +configuration file}. \textbf{Note:} An up-caret (\,\^\,) is required any time you are reading in a file in \starlink. For the map-maker this includes the configuration @@ -2102,9 +2134,9 @@ \subsection{\xlabel{running_dimm}Running the map-maker} \subsection{\xlabel{look_for}What to look out for} \flushbottom Once the map-maker has completed you can open your output map using -\gaia\ -- see Figure~\ref{fig:itermap}. The excerpt above shows the -output written to the terminal as you run the map-maker. There are a -number of clues in this output that indicate the status of the +\gaia\ -- see \cref{Figure}{fig:itermap}{the figure below}. The excerpt +above shows the output written to the terminal as you run the map-maker. There +are a number of clues in this output that indicate the status of the reduction. \myfig{sc21_crl2688}{[t!]}{width=0.7\linewidth}{fig:itermap}{ @@ -2123,6 +2155,7 @@ \subsection{\xlabel{look_for}What to look out for} -- the default at 850$\mu$m. \\ \\ \textbf{Chunking}\\ +\label{box:chunk} The map-maker then determines if the raw data should be split and processed in more than one chunk. In this map the data is reduced in one continuous piece: \param{Continuous chunk 1 / 1}. Chunking is @@ -2217,8 +2250,8 @@ \subsection{\xlabel{look_for}What to look out for} \\ \\ \textbf{Convergence}\\ What about the convergence parameter? As discussed in -Section~\ref{sec:converge} there are two noise based convergence -criteria that can be set -- \texttt{maptol} and \texttt{chitol}. Both +\cref{Section}{sec:converge}{Convergence} there are two noise based +convergence criteria that can be set -- \texttt{maptol} and \texttt{chitol}. Both are reported during processing but only one will be used to determine if convergence has been achieved. @@ -2258,8 +2291,8 @@ \subsection{\xlabel{apply_fcf}Applying the FCF and determining fluxes} data from units of pW to janskys. \textbf{The FCF to be applied depends on the reduction date for your data. For data that have been reduced \emph{prior} to July 2012 you should see -Appendix~\ref{app:fcfs} for alternative FCFs.} For reduction dates -from July 2012 onwards the FCF factors are: +\cref{Appendix}{app:fcfs}{FCFs by Reduction Date} for alternative FCFs.} For +reduction dates from July 2012 onwards the FCF factors are: \begin{table}[h!] \centering \begin{tabular}{|c|c|c|c|} @@ -2280,16 +2313,16 @@ \subsection{\xlabel{apply_fcf}Applying the FCF and determining fluxes} flux of your source. applying \fcfb\ will result in a map with units of Jy/beam. For point-like or compact sources smaller than the beam (with a Gaussian profile), this peak value will be the flux density of -your source. Be aware that the pipeline (see Section~\ref{sec:pipe}) -reports FCFs in units of mJy/beam. +your source. Be aware that the pipeline (see +\cref{Section}{sec:pipe}{SCUBA-2 Pipeline}) reports FCFs in units of mJy/beam. To get the flux density of extended sources with \textbf{aperture photometry} you should apply the \fcfa. You can then sum the emission in an aperture. \fcfa\ was determined using a 60-arcsec diameter aperture. If your aperture differs from this you should scale your flux accordingly -- the scaling factor can be read off the curve of -growth (see Appendix~\ref{app:cog}). This graph gives the ratio of -aperture flux to total flux for a range of aperture diameters. +growth (see \cref{Appendix}{app:cog}{this appendix}). This graph gives +the ratio of aperture flux to total flux for a range of aperture diameters. Multiplying your data file by the FCF can be done using the \Kappa\ command \cmult. @@ -2400,7 +2433,7 @@ \subsection{\xlabel{noise}Calculating the noise} If you have not already cropped your map you should do so. The data at the edges of the map are considerably noisier due to reduced exposure time, so to get an accurate RMS you will need to remove these noisy -edges -- see Section~\ref{sec:crop}. +edges -- see \cref{Section}{sec:crop}{Cropping your map}. Once cropped, the noise can then be read from the statistics of the file. The \Kappa\ command \stats\ may be used for this: @@ -2427,7 +2460,8 @@ \subsection{\xlabel{noise}Calculating the noise} % histogram 850_map_cal_crop comp=err numbin=200 style="color=white" \end{verbatim} \end{myquote} -The output is shown in the left-hand panel of Figure~\ref{fig:bfnoi}. +The output is shown in the left-hand panel of \cref{Figure}{fig:bfnoi}{the +graphics below}. \myfigduo{sc21_noihist}{sc21_crl2688_err}{}{width=0.47\linewidth}{fig:bfnoi}{3mm}{ The error map of the cropped make-map output viewed in two different @@ -2444,9 +2478,10 @@ \subsection{\xlabel{noise}Calculating the noise} \end{verbatim} \end{myquote} The error file (\texttt{850\_map\_cal\_crop\_noi}) can then be viewed -with \gaia -- see the right-hand panel of Figure~\ref{fig:bfnoi}. +with \gaia -- see the right-hand panel of \cref{Figure}{fig:bfnoi}{the +figure above}. -\subsection{\xlabel{match_filter}Point source extraction -- Applying a matched filter} +\subsection{\xlabel{match_filter}Point-source extraction -- Applying a matched filter} \label{sec:mf} This effectively fits a point spread function (PSF), centered over every pixel in the map, and applies a background suppression filter to @@ -2483,8 +2518,8 @@ \subsection{\xlabel{match_filter}Point source extraction -- Applying a matched This is a fairly common technique used throughout the extra-galactic sub-millimetre community to identify potential sources. A full description of the matched filter principle is given in -Appendix~\ref{app:mf}, while the \textsc{Picard} manual gives full details -of all the available parameters. +\cref{Appendix}{app:mf}{SCUBA-2 Matched Filter}, while the \textsc{Picard} +manual gives full details of all the available parameters. \clearpage \section{\xlabel{tweak}Tweaking the Configuration File} @@ -2620,7 +2655,7 @@ \subsection{\xlabel{filter}Adjusting the filtering} filtering in the configuration files. You can apply the filtering either before or during the iterative stage, with the latter the recommended default. All the parameters dealing with the \texttt{FLT} -model can be found in Appendix \ref{app:dimm}. +model can be found in \cref{Appendix}{app:dimm}{this appendix}. The maximum spatial scale of structure that can be recovered by the map-maker is determined by the scanning speed and frequency cut @@ -2643,7 +2678,8 @@ \subsection{\xlabel{filter}Adjusting the filtering} The scanning speeds are fixed for a given observing mode; you can put the speed for your map from the \texttt{SCAN\_VEL} parameter in the -FITS header (see Section~\ref{sec:fitsheader}). +FITS header (see \cref{Section}{sec:fitsheader}{Headers and file +structure}). \subsection{\xlabel{filter}Fitting COM for each sub-array} @@ -2680,7 +2716,7 @@ \subsection{\xlabel{mask}Masking options} The position of this circle defaults to the centre of the map. You can specify alternative coordinates if this is not appropriate -- see -Appendix \ref{app:dimm} for details. +\cref{Appendix}{app:dimm}{dimmconfig.lis} for details. The recipe \texttt{dimmconfig\_bright\_extended.lis} also uses zero based masking. It uses the parameter \texttt{ast.zero\_snr} to define @@ -2699,7 +2735,7 @@ \subsection{\xlabel{maskbe}Supplying an external mask for bright-extended maps} The sequence below is a summary of the procedure for generating an external mask from your data. These steps are followed in the example -in Section~\ref{sec:bright_ex}. +\cref{in Section}{sec:bright_ex}{Extended galactic sources}. \textbf{(1)} First a map is made in the standard way with the map-maker. \begin{myquote} @@ -2772,8 +2808,9 @@ \subsection{\xlabel{Cosmology}Deep point-source maps} The recommended reduction method for maps like these follow two main steps -- running the data through the map-maker using the \texttt{dimmconfig\_blank\_field.lis} recipe (see -Section~\ref{sec:config}). Then applying the \picard\ -\texttt{SCUBA2\_MATCH\_FILTER} recipe (see Section~\ref{sec:mf}). +\cref{Section}{sec:config}{Specialised configuration files}). Then +applying the \picard\ \texttt{SCUBA2\_MATCH\_FILTER} recipe (see +\cref{Section}{sec:mf}{Point-source extraction}). \\ \\ \textbf{(1) Running the map-maker}\\ In this example the raw data is stored locally in a directory called @@ -2805,7 +2842,7 @@ \subsection{\xlabel{Cosmology}Deep point-source maps} \end{verbatim} \end{myquote} The output map, \texttt{cosmo2\_mos.sdf}, is shown in the left-hand -panel of Figure~\ref{fig:cosmomap}. The advantage of using the +panel of \cref{Figure}{fig:cosmomap}{the figure below}. The advantage of using the \textsc{Picard} recipe over standalone \Kappa\ commands is that the exposure time is also propagated correctly to the output mosaic (it is stored in the \texttt{MORE.SMURF.EXP\_TIME} extension). @@ -2840,7 +2877,7 @@ \subsection{\xlabel{Cosmology}Deep point-source maps} % The output of this operation is a smoothed image called \texttt{cosmo2\_mos\_mf.sdf} and a cropped version is shown in the -right-hand panel of Figure~\ref{fig:cosmomap}. You can immediately +right-hand panel of \cref{Figure}{fig:cosmomap}{figure above}. You can immediately see the contrast to the left-hand panel which is the output from the map-maker. A number of signal peaks now as possible sources. \\ \\ @@ -2870,7 +2907,8 @@ \subsection{\xlabel{Cosmology}Deep point-source maps} \end{myquote} The resulting map, \texttt{cosmo2\_mos\_mf\_snr}, is shown in -Figure~\ref{fig:snrmask}. Compared with the matched filter map the +\cref{Figure}{fig:snrmask}{signal-to-noise image}. Compared with the +matched filter map the edges no longer appear as noisy because they have been down-weighted by the larger noise values where there were less data. \\ \\ @@ -2929,7 +2967,7 @@ \subsection{\xlabel{Galactic}Extended galactic sources} \textbf{(2) Generating an external mask}\\ Next we create an external mask from the output of make-map. Here we -follow the steps outlined in Section~\ref{sec:mask}. +follow the steps outlined in \cref{Section}{sec:mask}{Masking options}. \begin{myquote} \begin{verbatim} @@ -2945,8 +2983,8 @@ \subsection{\xlabel{Galactic}Extended galactic sources} % thresh 850map_snr 850map_mask thrlo=3 newlo=0 thrhi=3 newhi=1 \end{verbatim} \end{myquote} -The thresholded map is shown in the left-hand panel of figure -\ref{fig:mask}. The next step is to smooth this map by convolving it +The thresholded map is shown in the left-hand panel of +\cref{Figure}{fig:mask}{this figure}. The next step is to smooth this map by convolving it with a Gaussian of 16~arcsec. For this we use a factor of 4 for the FWHM parameter. @@ -2965,7 +3003,7 @@ \subsection{\xlabel{Galactic}Extended galactic sources} % thresh 850map_mask_sm 850map_mask_zm thrlo=0.02 newlo=bad thrhi=0.02 newhi=1 \end{verbatim} \end{myquote} -The final mask is shown in the right-panel of Figure~\ref{fig:mask}, +The final mask is shown in the right-panel of \cref{Figure}{fig:mask}{this figure}, note how is encompasses more emission and has softer edges than the first threshold map. \\ \\ @@ -3004,9 +3042,9 @@ \subsection{\xlabel{Galactic}Extended galactic sources} \textbf{(4) Cropping the map}\\ We can now crop the map to remove the noisy edges using the \picard\ recipe \drrecipe{CROP\_JCMT\_IMAGES}. To determine what to trim we can look -at the exposure time image with \gaia. Figure~\ref{fig:exptime} shows -a sharp drop off at a radius of 30$'$. We can thus specify a -parameter file like so: +at the exposure-time image with \gaia. +\cref{Figure}{fig:exptime}{The exposure-time image} shows a sharp drop +off at a radius of 30~arcmin. We can thus specify a parameter file like so: \begin{myquote} \begin{verbatim} @@ -3020,8 +3058,9 @@ \subsection{\xlabel{Galactic}Extended galactic sources} % picard CROP_JCMT_IMAGES 850galactic.sdf \end{verbatim} \end{myquote} -The final cropped map is shown in Figure~\ref{fig:crop_map}. Compared -to the first map out of the map-maker (Figure~\ref{fig:galmakemap}), +The final cropped map is shown in \cref{Figure}{fig:crop_map}{this plot}. Compared +with the first map out of the map-maker +(\cref{Figure}{fig:galmakemap}{first map}), slightly more of the faint extended emission is apparent. \myfig{sc21_gal_exptime}{[th!]}{width=0.7\linewidth}{fig:exptime}{ @@ -3043,9 +3082,10 @@ \subsection{\xlabel{Galactic}Extended galactic sources} are essentially indistinguishable. There are areas you may wish to experiment with. One is to adjust the -filtering -- see Section~\ref{sec:tweak} for details. Another option -is to supply an external mask from a different dataset, e.g. a -Herschel map. +filtering -- see \cref{Section}{sec:tweak}{Tweaking the configuration +file} for details. Another option is to supply an external mask from +a different dataset, e.g. a +\htmladdnormallink{Herschel}{http://herschel.esac.esa.int/} map. \myfig{sc21_gal12_crop}{[t!]}{width=0.8\hsize}{fig:crop_map}{ The final cropped, reduced map from the map-maker run with @@ -3088,7 +3128,7 @@ \subsection{\xlabel{pl_overview}Pipeline overview} \subsection{\xlabel{science_pl}The Science Pipeline} The science pipeline will automate many of the steps discussed in -Section~\ref{sec:maps}: +\cref{Section}{sec:maps}{Reducing your data}: \vspace{-0.3cm} \begin{itemize}\itemsep-0.3em \item Run the iterative map-maker. @@ -3218,7 +3258,7 @@ \subsection{\xlabel{fcf}Flux conversion factors (FCF)} the specifically designed \texttt{dimmconfig\_bright\_compact.lis}. The maps produced from this are then analysed using tailor-made \picard\ recipes. For instructions on applying the FCFs to your map see -Section~\ref{sec:cmult}. +\cref{Section}{sec:cmult}{this page}. A map reduced by the map-maker has units of pW. To calibrate the data into units of janskys (Jy), a set of bright, point-source objects with @@ -3332,7 +3372,7 @@ \subsection{\xlabel{ownfcf}Calculating your own FCF} This recipe will produce a log file log.fcfnefd which records the FCFs mentioned above along with a third (\fcfm\ which is not currently recommended). These can then be applied to your data using -\cmult\ (see Section~\ref{sec:cmult}). +\cmult\ (see \cref{Section}{sec:cmult}{Applying the FCF}). \end{enumerate} \subsection{\xlabel{extinction}Extinction correction} @@ -3464,9 +3504,9 @@ \section{\xlabel{app_clean}Cleaning the Raw Data} In this first basic example, we just want to clean up some data enough to see whether the bolometers have been flat-fielded correctly, and -more-or-less exhibit the same behaviour over time. the pre-processing +more-or-less exhibit the same behaviour over time. The pre-processing or cleaning steps used by the default configuration file are -summarised in table~\ref{tab:dimmdef}. +summarised in \cref{Table}{tab:dimmdef}{this table}. \begin{myquote} \begin{verbatim} @@ -3485,15 +3525,17 @@ \section{\xlabel{app_clean}Cleaning the Raw Data} \texttt{s8a20110417\_00051\_\textbackslash*} (the whole observation). If you inspect the resulting \texttt{clean.sdf} in \gaia\ -(Section~\ref{sec:gaiacube}) and flip through the data cube you should +(\cref{Section}{sec:gaiacube}{Displaying time-series data}) and flip +through the data cube you should see all of the bolometers signals go up and down together with about the same amplitude: the hope is that for a well-behaved instrument you are mostly seeing sky noise variations that are seen with roughly the same amplitude by all bolometers. Another common feature, if the scans are particularly long and/or fast -(e.g. 1\,degree across), is strong periodic signals that are correlated -with the scan pattern. See Section~\ref{sec:scan} -- in particular +(e.g. 1~degree across), is strong periodic signals that are correlated +with the scan pattern. See \cref{Section}{sec:scan}{Displaying scan +patterns} -- in particular you will want to plot \texttt{az} and \texttt{el} (the absolute azimuth and elevation), and also \texttt{daz} and \texttt{del} (the azimuth and elevation offsets from the map centre). This signal is @@ -3554,7 +3596,7 @@ \section{\xlabel{app_clean}Cleaning the Raw Data} \end{myquote} Or you can create your own customised configuration file. All the pre-processing options that may be specified are listed and described -in \texttt{dimmconfig.lis} -- see Appendix~\ref{app:dimm}. +in \texttt{dimmconfig.lis} -- see \cref{Appendix}{app:dimm}{here}. \section{\xlabel{matchedfilter}SCUBA-2 Matched Filter}