\documentclass{article}[11pt]

\usepackage[gavo]{votutorial}
% I'm widening up things a bit to save an almost-empty page.
% feel free to remove one that's not a consideration any more
\usepackage[width=12cm]{geometry}

\titlepicture{title.jpeg}

% tutorial about interoperability in the Virtual Observatory through the example
%  of TOPCAT and Aladin
\title{TOPCAT and Aladin Working Together}
\author{G.~Iafrate, M.~Ramella, K.~Riebe, F.~Rothmaier, M.~Demleitner, S.~Gabriel}

\begin{document}

\maketitle

\begin{abstract}
One of the greatest achievements of the Virtual Observatory (VO) is the
development of standards for how data should look like (data formats and models)
and how machines are expected to exchange such data (protocols).

Desktop and web applications in the Virtual Observatory can communicate with each other by
using the so-called ``Simple Application Messaging Protocol'', or short
``SAMP''.

This tutorial will show how tabular data can be easily transferred
between the table processing application
\Topcat{} and the image tool \Aladin{}.
\end{abstract}

\usedsoftware{\Topcat, \Aladin}


\noindent In this example, we will use Aladin to discover SDSS
objects\footnote{\url{https://classic.sdss.org/}}
geometrically within the center of the Coma
Cluster and use TOPCAT to filter out objects SDSS has actually
recognised as galaxies with about the right redshift.

\section{Aladin: A1656 and SDSS-DR7}

\tutstep[Find the Coma Cluster in Aladin]
Start Aladin and type \key{A1656}\footnote{A1656, also referred to as
the ``Coma Cluster'', is a large cluster of galaxies that contains over 1{,}000
identified galaxies.} into the text field \key{Command}. When you press
Enter, an image from the DSS of the corresponding area
is loaded into Aladin. Zoom out a bit using
the zoom slider in the right side panel or a mouse wheel
until your image covers about
$20^{\prime}$ (you will see the approximate size of the part of the sky
you're looking at at the bottom of the Aladin image pane).

\tutstep[Add sources from an SDSS photometric catalogue]
We now want to find sources in SDSS' photometric catalogue for
this field.  To do that, in Aladin's discovery tree (on the left side of
the window), type ``SDSS photo'' into the \key{select} field and hit
enter.  In
the discovery tree, you will see a lot of resources -- the green ones
have data for your view.  Click on one of the photometric catalogue
entries, make sure \key{in view} is checked and hit \key{Load}.  A new
plane will open, and the objects SDSS has identified will be plotted on
top of the image as red dots.  Clearly, not all of these are galaxies, let alone
members of the Coma Cluster.  Let's filter out everything else.

\section{Linking up TOPCAT and Aladin}


\tutstep[Transfer the Aladin object catalogue to TOPCAT]
Lauch TOPCAT. Best you find a configuration with your screen(s) so that
both TOPCAT and Aladin are next to each other or at least visible at the same time.
\footnote{Note that in the following we tell you how to
invoke functionalities through TOPCAT menu entries.  Most of these have
shortcuts in the icon bars -- try them (it's just a lot harder to
describe them in text).}

In Aladin's ``Stack'' (that's the pane on the right)
right-click on the label of your new plane and then choose \menu{Broadcast
selected tables to...} $\rightarrow$ \menu{topcat}.
Your table will then show up in TOPCAT.

\tutstep[Configure TOPCAT to tell Aladin what you look at]
In TOPCAT's main window, go to
\menu{Views}$\to$\menu{Activation Actions}. A new window will
open where you can configure what TOPCAT should do when you select a row
or plot point. Here, check \menu{Send Sky
Coordinates} under \key{Actions}.  Note that by clicking on an action
you can further configure it.  In this case, TOPCAT has automatically
figured out what to use as a position, so there's nothing you need to
do; this could be different for other actions.

\tutstep[Inspect objects in a plot]
Plot the table you received (e.g., \menu{Graphics}$\to$\menu{Plane Plot}),
perhaps umag over imag.  Zoom in in Aladin to a
field of view of perhaps $4^{\prime}$ (you may also want to reduce the
opacity of the objects layer or the size of the dots; there are sliders
for that when you select
the plane in Aladin's plane stack).  Now, as you click on points in the
TOPCAT plot, you will see images of their counterparts in Aladin.

\tutstep[Try Aladin-to-TOPCAT communication]
Conversely, if you mouse over the dots in Aladin's image, the
corresponding points in TOPCAT are highlighted.

\begin{figure}[h]
    \centering
    \includegraphics[width=12cm]{aladin1.png}
\end{figure}



\section{Selecting Galaxies in TOPCAT}

Let us now create a new sub-table containing only galaxies that SDSS
thinks likely belong to the Coma Cluster.

\tutstep[Define a named subset]
TOPCAT has a powerful feature called subsets; you can define
these graphically or through conditions on columns.  To do the latter,
select
\menu{Views}$\to$\menu{Row Subsets} in the main window, and then in
the ``Row Subsets'' window on
\menu{Subsets}$\to$\menu{New subset}. Name your subset,
perhaps
``redshift-selected''.

We now need to write the constraint.  For that, it is usually helpful
to consult the column metadata available through
\menu{Views}$\to$\menu{Column Info} in the main menu. We see, that
the spectroscopic redshift is saved in the variable \key{zsp}.


\tutstep[Constrain the redshift]
To find a suitable range of SDSS' estimated
redshifts, you can do a \menu{Graphics}$\to$\menu{Histogram Plot},
use \emph{zsp} in \key{X} and then zoom in to the
area with a pronounced over-abundance (mouse wheel or right drag).
We'd choose $0.0175 \cdots 0.03$ as a conservative range, but do
whatever you see fit.

Our choice would translate into
\verb|zsp>0.0175 && zsp<0.03| in the \key{Expression} field in the
\key{Define Row Subset} window.  Once you fill in the expression, hit
\key{Ok}.

You will find a reference of the functions and operators available for
the expressions if you click on the \key{f(x)} button in the \
\key{Activation Actions} window.


\tutstep[Make your TOPCAT ignore objects filtered out]
In the ``Current Table Properties'' box of TOPCAT's main window,
select the name of your subset in the ``Row Subset'' selector.
If you are observant, you can now see that in the \key{zsp} histogram,
this new subset is visible.

\begin{figure}[h]
    \centering
    \includegraphics[width=5.5cm]{histogram_zsp.png}
\end{figure}


Go to your plane
plot, in the \menu{Subsets} tab, uncheck \key{All}; \menu{Plot} $\to$
\menu{Rescale} will zoom the plot to the remaining points.  By the way,
you may see a few outliers; click on them to see why SDSS might have
gotten these wrong.


\tutstep[Does SDSS agree these are Galaxies?]  Open a table view (e.g., by
double-clicking on the table in TOPCAT's table list in the main window).
SDSS says what it thinks an object is in the \key{cl} column.  If you
sort by it (right click in the column), you can see if there are any
non-galaxies (cl would be $\neq 3$) left; again, selecting the
corresponding row will show you the doubtful object in the plot and in
Aladin.

\tutstep[Send the new subset back to Aladin]
Click on \menu{Interop} $\rightarrow$ \menu{Send table to...}
$\rightarrow$ \menu{Aladin} to bring your filtered catalogue back to
Aladin; TOPCAT will transmit what you set as the row subset above.
A new plane named \key{sdss8} as blue circles appears in Aladin.

\tutstep[Tune up Aladin's display]
You can now delete your original plane (right click on the label in the
stack).  You can make the galaxies a bit more conspicuous by
right-clicking on your new plane and selecting \menu{Properties} from
the context menu. You should end up with something in the lines of the title
picture.

If the basic catalogue gave dimensions of the matched
sources, you could go much further by using \menu{Catalog} $\to$
\menu{Create a filter} in Aladin.  But that is for another tutorial.

\end{document}
