\documentclass[twoside]{article}[12pt]

% include packages; if you don't like the big default margins, 
% then set the geometry BEFORE including the votutorial-style
\usepackage[a4paper, top=2cm, bottom=2cm, left=2cm, right=2cm]{geometry}

%\usepackage{latex-votut/votutorial}
\usepackage[gavo]{latex-votut/votutorial}

%\usepackage{listings}
%\usepackage{textcomp}

% more commands:
\newcommand{\RAVE}{%
\link{RAVE}{http://www.rave-survey.org/}%
}

% image directory for screenshots, further icons:
\def\dir{images}

% overwrite some defaults:
% -- icons
\renewcommand{\icon}[1]{%
  % parameter: file name
  \raisebox{-1ex}{\includegraphics[scale=\iconscale]{\icondir/#1}}%
}



% -- styles
\renewcommand{\menu}[1]{{\color{darkblue}  \tt $\,$#1$\,$}}
%\renewcommand{\url}[1]{ \href{#1}{#1} } --- that's the default anyway
%\newcommand{\menu}[1]{\textcolor{darkgreen}{ \sffamily{#1}}}

% -- adjust listings style for syntax highlighting


\lstset{style=daiquiri, language=SQL}


% maketitle options
\title{RAVE radial velocities with TOPCAT and Aladin}
\author{Kristin Riebe\thanks{Leibniz-Insitute for Astrophysics Potsdam (AIP); email: kriebe@aip.de}, GAVO}
\date{September, 16, 2015}
\titlepicture{\dir/titlepicture}

\def\runtitle{RAVE with TOPCAT and Aladin}
\def\abstractname{Introduction}

\fancyhead[LE,RO]{\runtitle}


\begin{document}
\maketitle


\begin{abstract}
The RAVE survey has measured radial velocities from spectra of about 500,000 stars of the Milky Way. 
In this tutorial, we extract the positions and radial velocities of stars from the RAVE survey and send them to TOPCAT and Aladin to create an all-sky map.
\end{abstract}

\usedsoftware{\RAVE\ database web interface, \Topcat\ 4.3 or higher\footnote{Tutorial was tested with the indicated version; other versions may differ in button names, functionality etc. Please contact the authors if you realize that the tutorial is out of date.}, \Aladin\ 8.0}

\section{Getting the data}
There are different ways to get the data from the RAVE survey. We show here two possibilities: retrieving the data via the RAVE website (http://www.rave-survey.org/query) or via TOPCAT's TAP interface.


\subsection{Using the RAVE website}\label{sec:raveweb}
Let us retrieve our stars from the RAVE website (http://www.rave-survey.org/query), where the most recent data are available. You need to register and login before you can access the data, since each user will get his/her own space on the database server to store the results. But don't worry: registration is free and open to anyone. You can also ask your tutors or the GAVO contacts for a demo user account.
\begin{enumerate}
    \item Open \url{http://rave-survey.org/query/} in a web browser. Click on \key{Query} and \key{Login} with your credentials or a demo accout. 
    
    \item The query interface allows you to write database queries in SQL (dialect MySQL) directly into the text area. Click on \menu{Database browser} above the query form. Here you can see all the possible databases, tables and columns that you can ask for. There is also a number of \menu{Example queries} to help you get started. 
    Now enter following \key{SQL query} into the text area of the query interface:
          
    \begin{lstlisting}
SELECT RAdeg, DEdeg, hrv, Teff_K, Obsdate, pmRA_PPMXL, pmDE_PPMXL
FROM `RAVEPUB_DR4`.`RAVE_DR4`
WHERE `Obsdate` like '2008%'
    \end{lstlisting}      
      %
    This will retrieve positions, heliocentric radial velocities (\lstinline{hrv}), proper motions (\lstinline{pm*}) and some other properties for all stars observed in the year 2008.
    
    \item Enter a \key{new table name} for the result table below the SQL area. This name must be unique; if you leave the field empty, the web application will generate a unique name for you (some random number or timestamp). Select \key{Short queue}, click on \key{Submit new SQL Query} and confirm the message box.
    
    \item Each query returns results in a (private) result table, the names of these tables are listed in the \key{Jobs} list on the left side. Click on your job to see its details.   
    Once your job is finished (check-mark), click the job name again, then choose the tab \key{Results Table}. Browse the table to view the retrieved data. 


\item VO-enabled applications can talk to each other via the SAMP protocol. The RAVE web application also supports this feature.

\begin{enumerate}
\item If you don't have it open already, \key{start TOPCAT} (e.g. with \texttt{java -jar topcat-*.jar}).
\item Back in your web browser, go to the \menu{SAMP}-tab and click the link \key{Register with a local SAMP Hub}.
This registers the web application with the SAMP hub that was started by TOPCAT. If nothing happens, check the instructions given on the webpage to make sure that your browser does not stop SAMP due to security reasons. 
Click on the link \key{Send table to Topcat}. In TOPCAT, you should see now your table being loaded.

\item If SAMP does not work for some reason, you can download the data via the \menu{Download} tab: select a format, e.g. VO Table ASCII and click on the corresponding link. This will generate a file for you and a new link will appear. Click on the download-link and save the file. In TOPCAT, go to \menu{File}\goto\menu{Load Table}, click \menu{System Browser} and choose your downloaded table file.

\end{enumerate}
\end{enumerate}

\subsection{Using TOPCAT's TAP interface}
Alternatively you can access RAVE data via TOPCAT'S TAP interface. This will load the data directly into TOPCAT, even without the need to register first.

\begin{enumerate}
    \item Open \Topcat, go to \menu{VO} \goto\ \menu{TAP Query}. Enter \entry{rave} as keyword and click \menu{Find Services}. Select \entry{AIP GAVO TAP} and click \entry{Use Service}. TOPCAT now loads information about the available tables. 

    \item Select the table \entry{ravedr4.rave\_dr4} in the list on the left side. This loads additional information about the available columns and their descriptions. At the bottom, there is the \menu{ADQL Text} area. Enter here the same query as described above in section \ref{sec:raveweb}. Some parts of your query will be highlighted in red: this is the automatic error detection of TOPCAT! Adjust the database name from \sql{RAVEPUB\_DR4} to \entry{ravedr4} and the red should disappear.
If you picked a different service providing older RAVE tables, you may need to adjust some more column names and change the \sql{WHERE}-condition.

    \item Make sure to set \menu{Max Rows}, the maximum number of retrieved rows, up to the maximum.  Otherwise you will only get a subset of your data.

    \item Click \menu{Run Query} to load the data into TOPCAT.
      % and continue with section \ref{lab:ravetopcat}.
\end{enumerate}





\section{RAVE in TOPCAT\label{label:topcat}}
\label{lab:ravetopcat} 
\begin{enumerate}
    \item Select the table in TOPCAT's main window. You can view the table via \menu{Views}\goto\menu{Table Data} or by clicking the corresponding icon \icon{topcat-tablebrowser}. For more details on each column, including units, go to \menu{Views}\goto\menu{Column Info} \icon{topcat-colmeta}.
       
    \item For \key{plotting}, choose \menu{Graphics}\goto\menu{Sky Plot} \icon{topcat-skyplot} to show the distribution of the observed stars on the sky. Make sure that you have chosen the correct coordinates:
    \menu{Lon:} \entry{RAdeg}, \menu{Lat:} \entry{DEdeg}.
    
    \item \textbf{[Extra:]} Add \key{vectors for proper motions}: select the \menu{Form}-tab and click on the arrow-icon \icon{topcat-addnewvectorform} to add a new vector form. Choose following \menu{Coordinates}:\\
        \menu{Proper Motion Longitude:} \entry{pmRA\_PPMXL},\\
        \menu{Proper Motion Latitude:} \entry{pmDE\_PPMXL}.
        Hide the arows again for the next steps by unchecking the check mark at \menu{SkyVector}.


    
    \begin{minipage}[c]{0.59\linewidth} 
    
    \item Add more color: Still staying with the \menu{Form}-tab, in section \menu{Shading} (at the top) choose: 
    \menu{Mode}: \entry{aux}, \menu{Aux}: \entry{hrv}.\\
    This adds an auxiliary color axis to \key{color the points by the measured radial velocity}. The points will now look mostly green.
    To change that, choose the property \menu{Aux Axis} at the left side, then in the tab \menu{Map} choose a different colormap, e.g. \entry{Accent}. It's still not looking much better, we need to adjust the range for the colormap as well.
    
        
    \item Go back to TOPCAT's main window and choose \menu{Graphics}\goto\menu{Histogram Plot} \icon{topcat-histogramplot}. 
    Choose the column \entry{hrv}. The plot shows that most stars have radial velocities between around -200 and +200 km/s.

    \item Switch back to the Sky Plot window. Go to the \menu{Range}-tab for your \menu{Aux} axis and enter:\\
        \menu{Minimum Aux:} \entry{-200}, 
        \menu{Maximum Aux:} \entry{+200}
        
        Alternatively, you can also move the subrange sliders up and down until the point colors looks nicer.


    \end{minipage}
    \hfill
    \begin{minipage}[c]{0.35\linewidth}
        \includegraphics[width=1\linewidth]{\dir/screenshot-topcat-ravemap}
    \end{minipage}

    \item The image has now some similarity to an impressionistic snow landscape, but we can also extract some scientific insights. Rotate the image (click and drag left mouse button) so that you have the white rectangularly area in the center. This is the area of the Milky Way, where individual stars would be hard to measure and thus this area was not observed. Can you see the trend of negative radial velocities (darker, redder colors) on one side compared to positive radial velocities (with paler, more yellowish colors) on other side? This is an indication for the rotation of the Milky Way! 
    
\end{enumerate}

\subsection*{Extra: Improved radial velocity coloring in TOPCAT}

\begin{enumerate}
    
    \item In order to get the effect of the rotation of the Milky Way more pronounced, you can sort the stars into radial velocity bins first. We'll do this by creating an additional \key{synthetic column}:
        \begin{itemize}
            \item In TOPCAT's main window, select \menu{Views} \goto \menu{Column Info} (\icon{topcat-colmeta}).
            \item Choose \menu{Columns} \goto \menu{New Synthetic Column} (\icon{topcat-plus}). This opens another dialogue for specifiying the new column.
            \item Provide a \menu{Name} (e.g. \entry{hrvbin}) and use following expression:\\
                \menu{Expression}: \entry{(hrv > 50)?1:( (hrv > 10)?2:( (hrv>-10)?3:( (hrv>-50)?4:5 ) ) )}.\\
                This creates the additional column and assigns an integer between 1 and 5, depending on the radial velocity.
        \end{itemize}
    \item Create a new \menu{Sky Plot} \icon{topcat-skyplot}, choose \entry{RAdeg} and \entry{DEdeg} for coordinates.
    \item Select the \menu{Form}-tab and pick for \menu{Shading, Mode}: \entry{aux}, \menu{Aux}: \entry{hrvbin}. 
    \item The default rainbow color is not so well suited for our case, so let's change it by switching to the \menu{Aux Axis} properties (left side). At \menu{Shader} select a different color map, e.g. \entry{Red-Blue}\footnote{One can even use custom color maps in TOPCAT, see http://www.star.bristol.ac.uk/~mbt/topcat/sun253/jvmProperties.html, \texttt{lut.files} for instructions}.
    Now the red-blue-shift is much better visible.

\end{enumerate}


\section{RAVE stars in Aladin\label{label:aladin}}
A radial velocity map of Milky Way stars would look much nicer if we had an image of the Milky Way loaded in the background. Fortunately that's not so hard to do using \Aladin.

\begin{itemize}
\item \key{Start Aladin} (in Unix-like environments, use e.g. \texttt{java -jar Aladin.jar}).
\item In TOPCAT, make sure the correct table is selected (highlighted in main window). Goto \menu{InterOp} and \menu{Send table to ...} \goto \menu{Aladin}.
\item In Aladin, you should see a new plane with the name of your table. All the points still have the same color (probably red), but we're going to change this now.
\item \key{Add radial velocity color:} Go to \menu{Catalog}\goto\menu{Create a filter...}. This opens the filter properties window. Choose the tab \menu{Advanced mode} and enter following rows:

\begin{lstlisting}[language=bash]
${hrv}>=50 { draw red circle(150) }
${hrv}>=10 && ${hrv}<50 { draw orange circle(150) }
${hrv}>=-10 && ${hrv}<10 { draw yellow circle(150) }
${hrv}>=-50 && ${hrv}<-10 { draw cyan circle(150) }
${hrv}<-50 { draw blue circle(150) }
\end{lstlisting}

and click \menu{Apply}.
This draws small circles for each star, colored by the radial velocity (column \texttt{hrv}).
The colors are chosen to match those of the RAVE coverage map at the RAVE webpage\footnote{\url{http://www.rave-survey.org/}}.

  \begin{minipage}[c]{0.5\linewidth} 
\item \key{Load background images} of the sky by clicking on one of the catalogues at the top, e.g. \key{2MASS} or WISE. Rotate the plot (click and drag middle mouse button) and zoom in (mouse wheel). If you zoom in far enough, you will see the circles and the stars from the background image. A click or hover on a star displays the stars name, if it is contained in the Simbad catalogue. If you click on the name, your default web browser will open the corresponding Simbad-information for you. 

    \end{minipage}
    \hfill
    \begin{minipage}[c]{0.4\linewidth}
        \includegraphics[width=1\linewidth]{\dir/screenshot-aladin-viewstar}
    \end{minipage}


% \begin{minipage}[c]{0.5\linewidth} 

\item Zoom out again to get a good full view and rotate the image such that the Milky Way is orientated horizontally. You should be able to discover a similar \key{color gradient} as before, indicating the \key{rotation of the Milky Way}. Note that we only used stars observed in 2008; the picture would look much more complete, if we had added more observations.
%    \end{minipage}
%    \hfill
%    \begin{minipage}[c]{0.4\linewidth}
%        \includegraphics[width=1\linewidth]{\dir/screenshot-aladin-ravemap}
%    \end{minipage}

\vspace{2em}
\centerline{\includegraphics[width=0.5\linewidth]{\dir/screenshot-aladin-ravemap}}


\end{itemize}



\end{document}
