\documentclass[article]{jss}

\usepackage{epsfig}
\usepackage{natbib}
\usepackage{comment}
\usepackage{graphics}
\usepackage{graphicx}
\usepackage{hyperref}

\newcommand{\Rfunction}[1]{{\textsf{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textsf{#1}}}
\newcommand{\Rslot}[1]{\textsl{#1}}
\newcommand{\Rclass}[1]{\texttt{#1}}

\author{Elizabeth Whalen\\Harvard School of Public Health \And
        Duncan Temple Lang\\University of California at Davis \And
        Robert Gentleman\\Fred Hutchinson Cancer Research Center}
\title{Creating Linked, Interactive Views to \\ Explore Multivariate Data} 

\Plainauthor{Elizabeth Whalen, Duncan Temple Lang, Robert Gentleman}
\Plaintitle{Creating Linked, Interactive Views to Explore Multivariate Data}
\Shorttitle{iSPlot}

\Abstract{
  Visualizing data is an important component of exploratory data analysis.
  Ideally, one would be able to create views of the data, interact with those
  views to find interesting data points, and then perform statistical
  modeling of the data all within the same system.  In this paper, we present
  two new \proglang{R} packages, \Rpackage{MVCClass} and \Rpackage{iSPlot},
  that allow users to create linked, interactive views of multivariate data.
  Most importantly, the software was designed to be extensible using the
  model-view-controller paradigm to create linked views. We rely on 
  two other \proglang{R} packages, \Rpackage{RGtk} and \Rpackage{gtkDevice},
  to create interactive views.  This extensibility, which can be performed
  solely in the \proglang{R} language, lets developers create interactive
  views from the statically available plots in \proglang{R} 
  and new responses to user interactions, such as changing the response to a
  left button click from coloring a point to hiding a point.  In addition,
  since these packages are available in \proglang{R}, the user can perform
  statistical modeling in the same system as the exploratory data analysis.
}
\Keywords{interactive graphics, statistical computing, model view controller, R}
\Address{
  Elizabeth Whalen\\
  Department of Biostatistics\\
  Harvard School of Public Health\\
  655 Huntington Avenue\\
  SPH2, 4th Floor\\
  Boston, MA 02115\\
  E-mail: \email{ewhalen@hsph.harvard.edu}\\
}

\begin{document}

\section{Introduction}\label{Sec:Intro}
\subsection{Background}\label{Ssec:Backg}

Data often come in multivariate form, with many variables measured on
the same observational unit. We consider the situation where we have
$n$ observations each with $p$ variables being measured.  In order to
explore, understand and model such data, it is helpful to be able to
visualize them in this multidimensional setting.  As we are all keenly
aware, available graphics systems generally are limited to displaying
2, 3 or perhaps 4 dimensions and the media offered by computer screens
and paper are inherently 2 dimensional.

When computational resources were significantly more scarce and less
powerful than they are now, techniques were developed to visualize
data in more than 2 dimensions using the basic 2 dimensional media.
For example, on a scatter plot showing pairs of variables $(x, y)$, a
third categorical variable can also be displayed by using a plotting
character or glyph that indicates the $z$ value in the tuple $(x, y,
z)$. So when plotting height against weight, gender can also be
displayed, e.g.,  with a `+' identifying a male and a `o' identifying a
female.  In addition to using glyphs for identifying levels of a third
variable, color can be used. This will allow four variables to be
displayed, albeit typically with more work required by the viewer to
comprehend the information in the plot.  The use of glyph and/or color
is limited to categorical variables (or ``shingles'' of continuous
variables), and does not readily generalize to more than 4 variables.

 Another approach to show multivariate data is to use a collection of
 regular two dimensional plots.  The generalized draftsman's display
 of a table of pair-wise scatter plots is another example without the
 need for a third variable on each sub-plot.

\begin{figure}[!h]
  \begin{center}
    \includegraphics[height=3.2in, width=3.1in]{USArrests.jpg}
    \caption{ Generalized draftsman's display example }
    \label{Fig:USArrests}
  \end{center}
\end{figure}

We can also display a series of plots on a page or screen where
successive plots show the ``effect'' of varying a third variable. This
third variable might be a binary variable such as gender as before and
we would simply have two scatter plots side by side.  Alternatively,
we might break a continuous variable into different levels and for
each plot, view the relationship of the two variables for the subset
of observations whose value of the third variable falls within that
level or ``bin''.  And in other cases, the third variable might have a
natural discrete ordering such as time, e.g.  year, season or month.
Conditional plots (coplots) and Trellis \citep{Trellis} are examples of
these types of multi-panel, multi-page layouts.  Small multiples
\citep{VisualDisplay} are another similar approach.

And another method that is commonly associated with time is
animation. Rather than having a series of plots arranged statically on
the page, a single plot is displayed and its contents are updated
as we move over the levels of a third variable.  Such animated plots
can be automated by which we mean they cycle through a series of
successive plots in order at a fixed rate.  Alternatively, users can
control which ``frame'' they view via some sort of control such as a
slider.

As computers and computer graphics have become increasingly more
sophisticated and responsive in real time, the ability to do dynamic
interactive graphics has emerged. In \cite{DynGraphics}, the state of
the art for dynamic statistical graphics was described by a variety of
authors. By that time, the notion of linked or connected plots and
brushing were being discussed. Other publications on these ideas include
\cite{Stuetzle}. 
%FIXME: need some specific citations here:
%% WXS: Werner Stuetzle. Plot windows. JASA, 82:466--475, 1987
%%RG says I don't know these: Rick's and Bill's
Two (or more) plots are linked if a point on one display corresponds
to a point in the other display by being associated with the same
observation.  In interactive, linked plots, as we identify a point in
one plot, the corresponding points in the other linked plots are also
identified in some way.  This allows us to visually explore individual
points in multiple dimensions through a collection of plots
potentially of different types, e.g. scatter plots, time series, bar
charts.  By brushing, we mean that we identify a region of a plot via,
e.g. a rectangle, and identify all the points within that region in
both this plot and all the linked plots.  Again, this allows the
viewer to look at high dimensional data and to see the relationships
between subsets. It is similar to the idea of conditional plots, but
much more flexible.  Rather than having a series of static plots
defined by a levels of a third variable, the viewer can define the
levels interactively and look at a smaller number of plots.


One particular model for creating interactive applications involves
three components: some user action or input, which is referred to as
an event; a response to that action, which is executed by a function
that is called a callback function; and a method that connects the
event to the callback function, which is referred to as the signal
handler.  The events can range from the user moving the cursor over a
plot, to pressing a button on a graphical user interface (GUI), to
pressing certain keys.  Events are interpreted based on which window
has focus.  For example, in the X Windows system, if a user types C on
the keyboard and the window that has focus is a text editor, then the
letter C is printed on the text editor's screen.  Any other open
windows that do not have focus do not respond to this event.  The
callback function is a specific type of function because its signature
is determined by the event to which the callback function is linked.
The parameters passed to the callback function may include information
about the event, such as the on screen location of the event, and
information about the object that had focus when the event occurred,
such as a button on the GUI.  The signal handler is the element that
glues the event and the callback function together.  It is responsible
for looking to see if an event has occurred and invoking the
corresponding callback function with the event information.  The
programmer typically registers the callback function for the event
type (e.g. button click) and source (i.e. the widget) of interest and
the toolkit implicitly creates the signal handler to connect the two.

The strengths of this model of interactivity are that programmers can
decide which events to react to by specifying event
type-source-callback function triples; programmers can change the
response to an event by changing the callback function that is linked
to an event; and the system's event loop can continue working on other
things until an event occurs raising a signal.  The event loop
processes different events, as the occur during the normal evaluation
of the program.  In the model of interactivity described above, when a
signal handler is implemented by the programmer the event loop
periodically checks to see if this event has occurred.

These three pieces in this model of interactivity are ordered as
follows: an event occurs, the event causes a signal to be emitted that
is caught by the signal handler, and then the signal handler calls the
callback function, which results in the response to the user action.
A flowchart of these steps is shown below in Figure~\ref{Fig:Event}.

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=0.6in, width=4.5in]{Event.jpg}
    \caption{ Flow Chart of the Response to an Event }
    \label{Fig:Event}
  \end{center}
\end{figure}

This style of dynamic and interactive plots  -- in which the user can
perform interactive queries and the collection of plots are
dynamically updated to reflect the subset of interest -- is a very
powerful tool for exploring and visualizing data.  Surprisingly, in
the commonly used modern statistical computing environments, such
tools are not widely available or well developed.  Instead, much of
the focus has been on publication quality, static graphics.  This is
partly due to legacy, partly to an incompatibility between interactive
and static graphics models, and partly to the difficulty in developing
interactive graphical tools and frameworks.

In this paper, we will present an approach to providing the
fundamental elements needed for interactive, dynamic graphics within
\proglang{R}, and also present high-level tools for the end user to deploy this
form of visualization.  Perhaps most significantly, the tools are
layered on top of the existing, powerful \proglang{R} graphics system.  Unlike
other approaches (see below), this framework does not require us to
provide new implementations of familiar plot types and so the quality
of the plots is unaltered.  This allows us to use all of the features
of the \proglang{R} graphics system such as mathematical annotations, powerful
and precise control of fonts, layout, legends, etc.  in the
traditional system.  And furthermore, it allows us and others to take
advantage of future developments in the graphics system.  Another
benefit to our approach is that the entire framework is programmed
within \proglang{R} making use of two packages with native code and third party
libraries, rather than relying on additional external programming
languages.  Along with the extensible design of the approach, this
makes it comparatively simpler to provide and experiment with new
forms of interactivity.  This extensibility is essential for allowing
us and others to take advantage of interactive and dynamic graphics
and integrate it more into the mainstream of data analysis and
statistical computing environments.


\subsection{Current tools/software}\label{Ssec:CurTools}

There are numerous research projects which have explored dynamic and
interactive graphics for statistical data analysis.  Most, if not all,
have resulted in software for analysts to use with general or
sometimes specific types of data.  These different projects have
focused on various aspects of dynamic graphics and here we discuss several of
them. 

\begin{itemize}
\item \textbf{MANET and MONDRIAN:} When each of these was developed
  \citep{MONDRIAN, MANET}, the researchers decided to focus
  on under-represented areas of interactive statistical graphics,
  specifically categorical data and geographical displays.  For good
  reasons, these tools were developed as stand-alone applications.
  MANET was written in \proglang{C++} for use on the older Macintosh systems
  (OS 9).  It deals with missing values and provides interactive mosaic
  plots which allows users to reorder the variables and provide 
  links between different displays.
  MONDRIAN is written in \proglang{Java} and therefore comes much closer to
  providing platform-neutral software for interactive data
  visualization.  It was developed at a time when \proglang{Java} appeared to
  be emerging as the dominant language and environment for high-level
  scientific computation.  However, since that has not occurred to any
  large extent, MONDRIAN has become a somewhat niche tool, isolated
  from commonly used data analysis systems.  In theory, it could be
  connected to \proglang{R} via the various general \proglang{R-Java}
  interfaces (i.e. \Rpackage{SJava}, \Rpackage{rJava}, \Rpackage{arji}) and its
  facilities made available to \proglang{R} programmers.  However, this would
  give rise to two separate graphics systems and the systems would
  only be very weakly integrated in the absence of more extensive redesign.
  
\item \textbf{GGobi:} XGobi is a stand-alone tool developed in the
  early 1990s that provides the basic interactive facilities such as
  point identification and brushing for scatterplots, scatterplot
  matrices and average shifted histograms \citep{DavidScott}.  One of
  XGobi's strengths was its grand tour facilities. These show the data
  being projected into intelligently chosen sub-spaces via a smooth
  trajectory from one sub-space to another.  These sub-spaces are
  selected by optimizing an index function that identifies features of
  interest.  Users can interact with the plots, including the grand
  tours and spin and rotate the data manually to view different
  perspectives.
  
  As with other systems, XGobi suffered from being a stand-alone
  application that was only weakly connected with data analysis
  systems such as \proglang{R} and \proglang{S-Plus}.  There is very limited
  communication,
  allowing the host system only to launch an instance of XGobi with a
  particular dataset.  After that, the user had to manage all
  communication between the systems.  GGobi \citep{GGobi} is an
  upgrade of XGobi to use a more modern GUI toolkit.  In addition,
  GGobi was designed to explicitly support a much tighter integration
  between the data analysis system and the interactive plots.  GGobi
  was written to be a compiled library that provided classes for
  interactive displays.  It can be dynamically loaded into \proglang{R} via the
  \Rpackage{Rggobi} package (and now with the more up-to-date
  \Rpackage{rggobi} package).  \proglang{R} users can then create new displays
  via the GGobi menus or the \proglang{R} command language.  At any time,
  \proglang{R} users
  can query certain information from GGobi.  The design allows for \proglang{R}
  programmers to provide actions for different events and so customize
  the linking of the interaction.  Actions can be specified for both
  low-level events such as mouse motion and clicks, and also
  higher-level events such as changes to the set of brushed/identified
  points, new variables or datasets being added, and so on.

  As described above, the \proglang{R-GGobi} interface uses dynamic reflection
  via the \Rpackage{RGtk} package and provides a potentially very powerful and
  customizable framework for exploring interactive graphics within a
  data analysis system.  However, there are several limitations. On an
  implementation level, the interface was not pushed as far as its
  potential permitted, primarily because it required the developers to
  be familiar with both \proglang{R} and GGobi and so greatly reduced the pool
  of potential implementers. This is not a technical problem, but
  rather one of resources, but it does identify the limitations of
  integrating sophisticated, specialized tools.

  A more conceptual limitation is that adding new types of plots to
  GGobi is significantly more complex than developing them in \proglang{R}.
  The GGobi and \proglang{R} graphics systems are entirely separate and users
  cannot 
  add arbitrary annotations such as text, lines, etc. to GGobi plots
  from within \proglang{R}.  GGobi is extensible via an object-oriented design
  and a plugin mechanism for externally added modules.  However, it is
  not trivial to add new features without understanding GGobi's
  design.  So while it is relatively easy to add new interactive
  linking rules, it is difficult to add new plot types and interactive
  rules for such plot types that connect them to other built-in plot
  types in GGobi.
  
  
\item \textbf{XLisp-Stat:} \proglang{XLisp-Stat} \citep{Lisp} was both
  conceived and implemented in an intelligent fashion that introduces dynamic,
  interactive graphics into the design of the data analysis system
  itself.  As a result, the graphics system that produces static plots
  is the same as that used for interactive plots.  And these
  interactive graphics are tightly integrated with a rich programming
  language for data analysis and simulation.  As a result, the design
  satisfies all the criteria that we would want, except one, that is
  being a commonly used environment for data analysis. Accordingly,
  and rather unfortunately, \proglang{XLisp-Stat} has not had the impact on
  interactive graphics that it might have had in the statistics
  community. And it provides an important lesson for us when
  developing tools and infrastructure for interactive dynamic
  graphics.  Specifically, we need to tightly integrate the framework
  into languages with which statisticians work and provide facilities
  for them to extend the basics that are provided. 

\item \textbf{iPlots:} iPlots \citep{iPlots} is a
  \proglang{Java}-based graphics 
  system that is connected to \proglang{R} and provides linked plots for a
  shared data set.  The choice of \proglang{Java} makes the rendering and
  interactivity relatively platform-independent. The connection with
  \proglang{R} is explicitly 
  designed to allow \proglang{R} users to draw plots and add annotations using
  \proglang{R} functions that mirror the regular graphics functions,
  e.g. \Rfunction{itext} rather than \Rfunction{text}.  While this is
  a good approach, the end user cannot dynamically change or add event
  handlers to control the interactivity and rules for linking
  plots. As a result, the interactivity is hard coded, and any changes
  must be made by the programmer using \proglang{Java} and before the session
  is started. This is not a consequence of the design of iPlots, but
  due to the fact that it does not exploit a bi-directional interface
  between \proglang{R} and \proglang{Java}.  It uses either the
  \Rpackage{rJava} or \Rpackage{SJava} package as the underlying connection
  mechanism.  The \Rpackage{SJava} package does provide a facility for using
  \proglang{R} functions to implement \proglang{Java} class methods and
  dynamically defining \proglang{Java} classes within a session. This approach
  would allow \proglang{R} users to dynamically program new linking rules
  entirely within \proglang{R}, but this has not been pursued, as yet.  Also,
  there are design issues of synchronizing copies of data sets that are
  maintained in both \proglang{R} and iPlots. 


\end{itemize}

Each of these systems has several merits and advantages over the
approach we describe in this paper. Separate, specialized components
represent an important and effective approach to design in software.
However, it is essential that such components be tightly integrated
into larger systems in which they are used. Because of the popularity
and acceptance of \proglang{R} in different communities, we feel that it is
important to at least explore the possibilities of adding
interactivity to the existing \proglang{R} graphics systems and to allow users
to easily specify their own rules for interaction.  This will allow for a
flexible, self-contained system that can work for non-standard
graphics, and it will also greatly facilitate experiments in
interactive dynamic graphics for data analysis.

\clearpage
\subsection[From current tools to iSPlot and MVCClass]{From current tools to
  \Rpackage{iSPlot} and \Rpackage{MVCClass}}
\label{Ssec:From}

Given the state of the current tools, creating new \proglang{R} software that
could implement linked, interactive views with an extensible design
would be useful for performing exploratory data analysis on multivariate
data.  According to the goals mentioned in Section
\ref{Ssec:CurTools}, the software should be able to visualize
multivariate data, allow for user interaction, perform statistical
analyses, and allow for future extensions.  And it is extensibility
that sets this research apart from the projects discussed above.

All software is, by its nature, extensible as long as developers have
access to the code.  However, the goal here is to create an extensible
system where developers only need to be familiar with one language to
make changes, and to provide a well defined path that facilitates
implementing changes and extensions. By only requiring knowledge of
\proglang{R} we hope that more users will make use of, and extend, the system
based on the needs of their data and analytic methods. This system was
carefully designed and implemented so that users can create new
responses to events, can change the response to an event, can add new
interactive views, and can add new data types all within the \proglang{R}
language.

Deciding to create the software in \proglang{R} was a natural choice because of
\proglang{R}'s statistical analysis capabilities and its ability to create
publication-quality plots.  However, the only interactivity currently
implemented in \proglang{R} are the functions, \Rfunction{identify} and
\Rfunction{locator}, which only respond to a mouse button press
events.  Fortunately, by combining two \proglang{R} packages, \Rpackage{RGtk}
and \Rpackage{gtkDevice}, it is possible to create interactive views that
can respond to many events.  Finally, by carefully implementing the
model-view-controller (MVC) paradigm, the design is flexible enough
for future additions.  These ideas are discussed further in Section
\ref{Sec:Design}.  We further believe that the design will readily
extend to other toolkits such as the upcoming \proglang{R}-wxWidgets interface
and tcl/tk, where \proglang{R}-level language bindings are provided to the
interactive widgets.

\section[Design of the R packages, iSPlot and MVCClass]{Design of the
  \proglang{R} packages, \Rpackage{iSPlot} and \Rpackage{MVCClass}}
\label{Sec:Design}

\subsection[Goals of these new R packages]{Goals of these new \proglang{R} packages}\label{Ssec:Goals}

We have three goals: to create views that are linked, views that are
interactive and a design that is extensible.  Each goal is discussed
in more detail in the following paragraphs.

For the views to be linked, displays based on the same data must be
simultaneously updated when the underlying data change.  As an
example, consider two views where the first view displays height
versus weight and the second view displays age versus cholesterol
level.  Suppose that these four variables (height, weight, age, and
cholesterol level) all come from the same data set and that we have
complete data on a number of individuals, including John Doe.  We will
link the views of the different variables through the individuals. In
order to do that we store certain data, such as the color to be used,
whether the point is hidden or highlighted, and the plotting character
of the point, in a location where all views can access it. These
additional data allow all linked views to render the data in the same
fashion.  Information that is specific to any one view, and does not
need to be accessed by other views does not need to be stored in this
same way.  Items such as axis information, background color, margin
information, user coordinates, etc. are view specific and could be
stored with the view.  To continue the previous example, John Doe's
data was originally colored blue and a request was made to change it
to red (usually through some form of interaction from the user).  Then
all views need to be updated to reflect the change in color.

Having interactive views means that when the user interacts with a view,
a response occurs.  Recall from Section \ref{Ssec:Backg} that when
an event occurs, a signal is emitted so an event is a mechanism to tell
an application that something has happened.  Events, such as a button
press or a mouse movement, can then be linked to a callback
function, which determine the response to that event.  The ideas
of events and callback functions are discussed further in 
section \ref{Ssec:RGtk} describing \Rpackage{RGtk}. 

Suppose that the user clicked on a point in an interactive view.  Here
clicking on the view would generate the event.  In response to this
mouse button press event an action is taken. In one common scenario,
the nearest point is determined and its color is altered. In the MVC
paradigm, the callback function would not directly change the points on
the screen, but rather send a message to the model that indicates a
change in color is required. The model then updates itself and sends
out messages to all subscribed views and the views then respond to
these messages appropriately.  Other possibilities include, but are not
limited to, responding to a key press event generated when the user
presses a key on the keyboard, or a motion notify event when the mouse
moves.  For instance, in response to a motion notify event, an
identifying name could appear next to a point when the cursor rolls
over that point.

Finally, an extensible design is imperative so that users can make
further additions and extensions based on their needs.  Thus, the
question is how to create software that can implement linked,
interactive plots while being user-friendly and sufficiently flexible
to allow future additions or revisions.  While using this
software, the user has access to \proglang{R}'s computational and plotting
capabilities.  Another key issue for extensibility is to ensure that
users only need to know one computing language to make additions. For
this software, the user only needs to know how to program in \proglang{R} to
make additions.   And it is importantly, the software must present a clear
mechanism to specify changes and add extensions rather than requiring
the programmer to find the appropriate path herself.


\subsection[RGtk and gtkDevice]{\Rpackage{RGtk} and \Rpackage{gtkDevice}}
\label{Ssec:RGtk}

\Rpackage{RGtk} \citep{RGtk} is an \proglang{R} package that allows one to
interact with Gtk+ functions from within \proglang{R}.  Gtk+ \citep{Gtk} is an
open-source window toolkit for creating user interfaces.  Not only is
Gtk+ a particularly rich toolkit that gives the programmer access to
many user interface components, such as a scroll bar, text box,
button, or drawing area -- typically referred to generically as
``widgets'' -- to quickly build interfaces, but it also gives access
to many events, such as button press events, motion notify events,
window and component deletion events.  By exposing the events at this
high level, we can respond to different user interactions in rich
ways.

In Gtk+, each widget can respond to certain events.  When an event
occurs, the active widget emits a signal.  If the programmer has
defined a callback function for that signal, then the signal is caught
by the signal handler, which invokes the callback function.  Thus, the
programmer can decide which events to respond to, and what actions
occur in response to those events.  As an example, suppose a button
widget is placed on the interface and the programmer has created a
callback function for the button press event for that button.  Let's
say that the button has the label, ``Show Plot'', and the callback
function for the button press event causes an X window to open with a
plot on it.  Then when the user presses the button, the callback
function is called and a new X window opens with a plot on it.

Events are crucial for creating an interactive view.  More available
types of events mean more possible types of interactions that can be
supported, and at an increasingly higher-level of abstraction such as
drag and drop events rather than mouse click, motion and unclick
sequences.  In our two packages, all views should respond to certain
events, such as delete and button press but can also optionally
respond to other events.  The delete event occurs when the Gtk+ window
containing the view is deleted and thus, storing information on that
view is no longer necessary.  The button press event allows the user
to interact with the view.  For certain views, we use the motion notify
event so that the user can identify points by rolling the cursor over
the view.  Of course, these are just some of the possible events and
users can always add callback functions for additional signals if
there are events they want to use.  Also, users can add multiple
callbacks for the same event and each of these callbacks will be
processed in turn.  This allows different actions to be separated into
different callback functions and managed separately. The
\Rpackage{RGtk} package encapsulates the interface between \proglang{R} and
Gtk+ and users of our packages need only be familiar with the \proglang{R}
language to make these additions.

Some of the possible events \citep{Gtk} available for widgets in Gtk+ are:
\begin{list}{}{\setlength{\leftmargin}{0.5in}
               \setlength{\itemsep}{0in}}
  \item \textbf{button press event:} when a mouse button is pressed over a widget
  \item \textbf{button release event:} when a mouse button is released over a widget
  \item \textbf{motion notify event:} when the mouse pointer moves over a widget
  \item \textbf{delete event:} when a widget is deleted or discarded
  \item \textbf{expose event:} when (part of) a widget is exposed and needs to be redrawn 
  \item \textbf{key press event:} when a key is pressed and the widget
  is active and has the input focus
  \item \textbf{key release event:} when a key is released and the
    widget is active
  \item \textbf{focus in event:} when the widget gets focus 
  \item \textbf{focus out event:} when the widget loses focus
  \item \textbf{drag/drop events:} when a button press occurs on a
    widget, then the button is held down while the mouse is moved, and
    finally the mouse button is released
\end{list}
This list is by no means exhaustive of all events available to widgets
in Gtk+.  For a complete list see
\url{http://www.gtk.org/tutorial1.2/gtk\_tut-28.html}.  Also, specific
widgets may have their own particular events to which they can
respond.  For example, a Gtk+ \texttt{CList} widget, which provides a
spreadsheet-like display of a table of cells, has events such as
select row, unselect row, click column, resize column, etc.  Clearly,
these events only pertain to a widget with appropriate
characteristics.

So far the necessity of events for an interactive view has been
discussed, but the area where these views are displayed has not been
mentioned.  In \proglang{R}, graphics are displayed on a device.  There are two
basic types of device: screen and file devices.  Screen devices
display the graphics directly on the computer screen; file devices
write the graphics in a format that can be displayed using other
software, e.g.  a Web browser, PDF viewer.  Many different types of
devices are available to the user in \proglang{R}, such as postscript, pdf,
windows, X11, jpeg, etc.  For interactive graphics discussed in this
paper, we need a screen device that looks like one of the regular \proglang{R}
devices, but also makes low-level user events available to the \proglang{R}
programmer.  The package \Rpackage{gtkDevice} \citep{gtkDevice}
provides such a graphics device.  It uses a \texttt{GtkDrawingArea}
widget as a canvas on which to display the \proglang{R} graphics.  It works in
much the same way as other screen devices, allowing the user to create
new top-level windows for graphics, and each window acts as a
container for the drawing widget that is transparently connected to
the \proglang{R} graphics engine.  In addition to top-level windows, a
\texttt{GtkDrawingArea} widget can be located in an arbitrary GUI
(e.g. surrounded by buttons and menus, within a scrolled window, or
even within an HTML document display) and then connected to the
graphics engine and used as a regular graphics device via the function
\Rfunction{asGtkDevice}.  While the \texttt{GtkDrawingArea} plays a
special role in this context of display content from the \proglang{R} graphics
engine, it behaves as a regular Gtk+ widget to the \Rpackage{RGtk}
package. Therefore, it allows the \proglang{R} programmer to associate callback
functions with different events.  The \Rpackage{gtkDevice} package
therefore gives the \proglang{R} programmer both regular \proglang{R} graphics
and programmable interactive events.


\subsection{Model-View-Controller (MVC)}\label{Ssec:MVC}

The MVC paradigm \citep{DesignPatterns} is a design that consists of
three types of objects: the controller, which defines what actions
occur in response to user input; the view, which consists of displays
of the data; and the model, which manages the data.  The power of the
MVC design is that it decouples the views of the model from the model
itself by creating a subscribe/notify procedure between them. In other
words, the views subscribe to a particular model and the model must
notify the views when a change occurs so that the views can be
updated.  This allows multiple views of the model that are linked, but
are not aware of each other.  And similarly, the model has no
particular knowledge of any of the views, just how to notify them of
changes to the contents of the model.  Those familiar with \proglang{Java} may
recognize this as similar to the listener -- interface approach.

Figure~\ref{Fig:ModelV} from \cite{DesignPatterns} gives an example of
a model (on the second row) with several views (on the first row)
based on that model.  The model data consist of a labelled vector of
numbers data that are reflected in the views.  When the model changes,
it must notify the views so that the views reflect the current data.
Once the views have been notified of a change in the model, they can
ask the model for information.  By separating the model from its
views, only one copy of the model is needed.

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=3in, width=4in]{ExMVC.jpg}
    \caption{ Model with its Views }
    \label{Fig:ModelV}
  \end{center}
\end{figure}

The views must know which model they are displaying, but the model
does not need to know about the views.  If the model changes,
it needs to notify the views in some manner that it has
changed.  This communication between components in a \Robject{MVC} object is
discussed in detail in Section \ref{Sssec:Message}. 

Not only does there need to be communication between the views and the
model, but there must also be information passed between the
controller and the views. Recall that the controller defines what
actions occur in response to user input.  If the user input is
interaction with a view, the controller must query the view in order
to determine which component was selected. For example, a mouse click
event typically only provides the $(x,y)$ coordinates of the cursor at
the time the mouse was clicked. To identify the nearest point the
callback function must query the view.  When the user clicks a point
on a view, the controller responds to this event by asking the view
which point was nearest.  Then the controller tells the model that it
should be updated. The model data are updated and all views notified.
Note, that typically the callback function does not directly modify
the view.

There are exceptions to this rule, and one common situation is when
the controller itself has an on-screen representation. For example, a
histogram might have associated with it a slider to represent the
number of bins to use. When the user moves the slider the new
information must be stored somewhere, and the view updated. There are
two different ways this can be addressed. One is where the model is
sufficiently rich so that it holds such information and in that case
the behavior is much as we described above. But an equally valid
implementation would store such information with the view, since it is
unlikely to be of any interest to other views and could vastly
complicate the model (this is in fact our design choice). 

In our system there is a mechanism that allows the user to change the
response associated with an event, for any of the views.  Users are
able to change the response to the mouse button click event, so
sometimes it hides points, other times it colors them, and other times
pops up glyphs or other graphical objects. In our design this
corresponds to being able to alter the controller, but one could also
imagine an implementation where such data were part of the model,
although again that may complicate the model, and we feel ambiguates
the roles of model and controller.

Figure \ref{Fig:MVC} shows a visual representation of the MVC design.  As
shown in this representation, communication is possible between any of the
components of the design.  For instance, the model may send information
to the view or the view may send information to the model.  

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=1.5in, width=3in]{MVC.jpg}
    \caption{ MVC Design }
    \label{Fig:MVC}
  \end{center}
\end{figure}

For extensibility, it is crucial to have the design consist of
separate components with communication mechanisms so that if one
component changes, it does not affect the other components.  By using
the MVC paradigm with messages to communicate between components, the
components are compartmentalized.  Thus, if a user wants to change one
piece, such as the model layer, only that component needs to change
and possibly the messages that are sent and received from that
component.  However, the other two components should not be
affected. The changes to the model must of course leave unchanged the
programming interface that the other components use to communicate
with that model. 

\subsection[Overview of iSPlot and MVCClass]{Overview of \Rpackage{iSPlot} and \Rpackage{MVCClass}}
\label{Ssec:Overview}

The MVC paradigm is the basis of the new \proglang{R} package,
\Rpackage{MVCClass}.  The \Rpackage{MVCClass} package creates class
definitions and generic functions to implement the MVC design.  By
separating these definitions into their own \proglang{R} package, these
components can be used by any other package that creates linked views.

To create interactive views, a front end that creates these views is
necessary and we have written the \Rpackage{iSPlot} to demonstrate the
use of the MVC paradigm we have developed. Users can create
interactive views using either command line functions or a GUI.
These interactive views are linked to each other via the underlying
data set, or model, by creating objects from the model, view and MVC
classes defined in the \Rpackage{MVCClass} package.  A detailed
discussion of these classes is given in Section \ref{Ssec:Details}.
The \Rpackage{iSPlot} package determines how objects of a class act by
defining the methods for the classes.

If a user wants to add a new class or a new generic function they
extend the class definitions in the \Rpackage{MVCClass} package
(i.e. by inheriting from classes already defined in
\Rpackage{MVCClass}). New menu items can be added to the GUI using
command line functions available in the \Rpackage{iSPlot} package.
Examples of the functionality defined in the packages are given
in Sections \ref{Ssec:Details} and \ref{Sec:Func}, but basically a
user can think of the \Rpackage{MVCClass} package as the back end,
which defines classes and generic functions, and the \Rpackage{iSPlot}
package as the front end, which creates the views and defines the
responses to user interactions through either a GUI or command line
functions.

\subsubsection[Overview of MVCClass design]{Overview of \Rpackage{MVCClass} design}
\label{Sssec:OverMVC}

Prior to explaining the details of the \Rpackage{MVCClass} design, a short
overview of design decisions for the MVC package is
explained here and then in Section~\ref{Ssec:Details} a more in-depth
discussion of the design is given.

The controller must perform several tasks, including storing
information about the state of the \Robject{MVC} entity (such as how
to respond to user interaction with a view) and allowing users to
load data, to create views, and to quit the program.  These tasks can
be separated into two functions: i) the controller stores MVC state
information, ii) the controller provides some form of interactive
interface that allows the user to determine the course of actions. MVC
state information is stored in the \Rslot{controller} slot of a
\Robject{MVC} instance (Section~\ref{Sssec:MVC}).  The implementation
of ii) is contained in the \Rpackage{iSPlot} package, because this
package lets the user determine the course of actions through either
command line functions or the GUI.

In the MVC paradigm, the model component is the place where data are
stored and updated.  Thus, the model is basically a storage location
with certain operations, such as loading and updating the model data,
defined for it. Information can be sent to the model to add, update
and remove data and the model can send out messages that changes have
occurred to the data.  The details of the model component design are
given in Section \ref{Sssec:Model}.

The views consist of different ways of representing the data visually.
Even though there are different ways to view the data, such as via a
scatter plot or a spreadsheet, each view needs to store information
and needs to respond to events, such as a mouse button click. This
observation suggests an object model where different view classes
inherit from a common virtual class. This implementation ensures that
all views store common information in a standard way and respond to
certain events without the need to write specialized methods. Views
that require specialized responses require the implementation of
specialized methods, but the virtual class ensures that they all make
use of the standard methods if they are appropriate. 

These three components -- model, view, and controller -- of the MVC design are
tied together in one class, called \Rclass{singleModelMVC}.  Each object of
class \Robject{singleModelMVC} contains one data set (the model)
and the \Robject{singleModelMVC}
object contains all the information pertaining to that particular model.
More details on this class can be found in Section \ref{Sssec:MVC}.

Communication between the three MVC components is crucial for the
pieces to work together and yet, still be independent of each other.
Communication is facilitated through a set of message classes.  Just
as with the view classes, there are different types of messages, such
as update or add, and they inherit from a common virtual class.

There is a class called \Rclass{gEventFun} that contains all the necessary
information for a callback function. Users that want to define their
own handlers for events will make use of this class.

\subsubsection[Overview of iSPlot design]{Overview of \Rpackage{iSPlot} design}
\label{Sssec:OveriSPlot}

The \Rpackage{iSPlot} package gives the user access to its
functionality either through a GUI or through command line functions.  Thus,
the \Rpackage{iSPlot} package fulfills one of the goals of the controller,
mentioned in Section \ref{Sssec:OverMVC}, which is to allow the user to
determine the course of actions.  For the GUI, a design that users are
familiar with from using Windows software is to have menus that allow the user
to determine which action to take next.  In the \Rpackage{iSPlot} package's
implementation, the GUI is created using the \Rpackage{RGtk} package, which
was discussed in Section \ref{Ssec:RGtk}.  For users that do not want to use
the GUI, the same functionality is available through command line funtions.
More information on the controller and thus, on the API is given in Section
\ref{Sssec:Control}. 

Since the \Rpackage{iSPlot} package creates the front end, decisions made in
this package pertain to what types of data are allowed and what
operations can be performed on these data sets and their views.  Of course,
since one of the goals of this software is to be extensible, the user is
welcome to make additions to the available operations.  A more detailed
discussion of what is currently possible through the \Rpackage{iSPlot}
package's front end is given in Sections \ref{Ssec:Details} and \ref{Sec:Func}.

\subsection{Details of the design}\label{Ssec:Details}

This section intertwines the details of the design of the
\Rpackage{MVCClass} and the \Rpackage{iSPlot} packages because the
packages work together to satisfy the goals of this software. The
classes and generic functions are defined in the \Rpackage{MVCClass}
package, and the methods and the API are implemented in the
\Rpackage{iSPlot} package. Since \Rpackage{MVCClass} is more general
it does contain classes and generic functions that are not used by
\Rfunction{iSPlot}. 

\subsubsection{Model}\label{Sssec:Model}

In Section \ref{Sssec:OverMVC}, the model layer is explained to be a
storage location where data can be added, updated, or removed.  Thus,
the model class reflects those operations.  The functions of storing
and updating the data are reflected in Figure \ref{Fig:Model}, which
shows the inheritance structure for the model classes.  Here the
virtual class, \Rclass{gModel}, has the slots \Rslot{modelData},
\Rslot{linkData}, \Rslot{virtualData}, and \Rslot{modelName}.  These
four slots are common information that all models need.  The
\Rslot{modelData} slot is the data set for this model; the
\Rslot{linkData} slot is used to link this model to other models (this
feature is not used in this software so it is left as an empty slot).
The \Rslot{virtualData} slot is data pertaining to the views that need
to be stored with the model so that it can be shown in all views of
this model, and the \Rslot{modelName} slot is simply a string giving
the name of the model, which is used to manage a collection of different
\Rclass{MVC} objects.

\begin{figure}[ht]
  \begin{center}
    \includegraphics[height=2.8in, width=1.6in]{ModelClass.jpg}
    \caption{ Inheritance for Model Objects. }
    \label{Fig:Model}
  \end{center}
\end{figure}

As for specific model classes, the only class used by the
\Rpackage{iSPlot} package is \Rclass{dfModel}.  The \Rclass{dfModel}
class represents a model where the \Rslot{modelData} slot has class
data frame (or matrix). Other model classes are defined in the
\Rpackage{MVCClass} package, but here we only discuss linking views of
two-dimensional data structures, such as a data frame or a matrix.
 
The model class is also responsible for updating the data and a a
method for the generic function \Rfunction{updateModel} will be
needed. This method is called whenever the data need to be updated in
response to a user interaction with a view. All view specific
information is stored in the \Rslot{virtualData} slot. This includes
color of point, glyph used, and other variables. These are held
separate from the model data itself, partly for efficiency purposes
and partly to avoid name conflicts. Often the \Rfunction{updateModel}
method is actually updating the \Rslot{virtualData} slot because these
data control the coloring etc. This is an important and potentially
slightly subtle point. The data are often essentially considered
fixed/immutable.

If a user wants to create linked, interactive views based on different
data types, then they will need to add a new model class.  For
example, a user may want to add a new model class called, say,
\Rclass{tsModel} to represent time series data and define methods for
the different generic functions to implement the way updates work for
this particular model. Some examples of such extensions are available
in the \Rpackage{iSNetwork} package which provides a different set of
extensions of the MVC paradigm.
  
\subsubsection{Views}
\label{Sssec:View}

Although there are different types of views of the data, all view
objects should store some common information and respond to certain
events.  View classes extend the \Rclass{genView} virtual class from
the \Rpackage{MVCClass} pacakge. A design of the view classes that
fits the representation of the views and allows for extensibility is
shown in Figure~\ref{Fig:View}. 

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=4.5in, width=3.3in]{ViewClass2.jpg}
    \caption{ Inheritance for View Objects }
    \label{Fig:View}
  \end{center}
\end{figure}

The \Rclass{genView} class is a virtual class that has three slots,
\Rslot{dataName}, \Rslot{win}, and \Rslot{winNum}.  \Rslot{dataName} is the
name of the model that the view displays, \Rslot{win} is the Gtk+ window object
that holds the view, and \Rslot{winNum} is the number of the window so that
the window can be identified in the Window menu on the GUI (see Section
\ref{Sssec:Control}).

A specific example of the view class is the \Rclass{spreadView} class
which represents a spreadsheet view of the data.  The additional information
needed for this view is stored in the slot, \Rslot{clist}, which is
the Gtk+ spreadsheet object for displaying the data in the view.

When plotting the data, there is a general class, \Rclass{plotView},
that has the slots, \Rslot{drArea}, \Rslot{plotDevice} and
\Rslot{plotPar}, which store the Gtk+ drawing area object, \proglang{R}
graphics device number (which uniquely identifies the device to \proglang{R})
of the plot,
and the plotting parameters, respectively.  The \Rclass{sPlotView}
class represents a scatter plot view of the data.  The extra
information needed for this view (that is not already contained in
\Rclass{genView} and \Rclass{plotView}) is stored in the three slots
-- \Rslot{dfRows}, \Rslot{xvar} and \Rslot{yvar} -- where
\Rslot{dfRows} are the model row names, \Rslot{xvar} is the variable
name from the model that is shown as the ``X'' or horizontal axis
variable in the plot and \Rslot{yvar} is the variable name from the
model that is shown as the ``Y'' variable, i.e. on the vertical axis,
in the plot.

These four view classes (\Rclass{genView}, \Rclass{spreadView},
\Rclass{plotView}, and \Rclass{sPlotView}) are defined in the
\Rpackage{MVCClass} package.  The \Rpackage{MVCClass} package also has other
view classes that are defined, but these views represent displays of data
structures that are not currently used in the \Rpackage{iSPlot} package.

Since all views are expected to be interactive, all view classes have
methods that correspond to user interaction. At any one time at most
one view has the focus and if an event occurs the view that has focus
will react according to the controller that is active for that
view. The events we are most interested in responding to include key
press events, where a certain configuration of keys are pressed;
button click events, where one of the mouse buttons is clicked over
the view; and mouse movement events, where the cursor moves over the
view.  

For example, in the code below, \Rfunction{gtkAddCallback} is the signal
handler and it connects the button press event on the drawing area of a view
with the callback function, which is the unnamed function, with the signature:
function(obj, ev).  In the callback function, the \Rfunction{clickEvent}
method for the current view is called.  The signature for the scatter plot's
\Rfunction{clickEvent} method is shown directly below.  Using the information
that is passed to the \Rfunction{clickEvent} method in the \Rslot{where}
parameter, the method converts the Gtk+ pixel coordinates that indicate where
the event occurred into user coordinates and then into an object from the
plot, such as a point on the plot.

\begin{verbatim}
gtkAddCallback(drArea(curView), "button_press_event",
  function(obj, ev)
  {
    clickEvent(curView, ev)
    return(TRUE)
  }
)

setMethod("clickEvent", "sPlotView", 
  function(object, where, ...) 
  {}
)

\end{verbatim}

Currently, both \Robject{spreadView} and \Robject{sPlotView} respond
to button press events, while only \Robject{sPlotView} responds to a
motion notify event.  However, linking a response to the motion notify
event for \Robject{spreadView} can be accomplished by
performing the following two steps: i) adding a Gtk+ callback for the
motion notify event to the \Rfunction{initialize} method for
\Robject{spreadView} and ii) defining the \Rfunction{motionEvent}
method for \Robject{spreadView}.

For \Robject{spreadView} the \Rfunction{clickEvent} method is called
when Gtk+ emits a signal that a row has been selected or unselected.
For \Robject{sPlotView}, which is a scatter plot, the
\Rfunction{clickEvent} method is called when Gtk+ emits a signal that a
mouse button has been pressed and the \Rfunction{motionEvent} method
is called when Gtk+ emits a signal that the cursor has been moved over
a view.  Both the \Rfunction{clickEvent} and \Rfunction{motionEvent}
methods for a \Robject{sPlotView} object determine which point on the
plot was clicked or under the cursor, respectively.  For more
information about the \Robject{sPlotView}'s \Rfunction{clickEvent}
method, please see the Appendix.

As with the model classes, each view class needs a method that tells
an instance to update its display. This is the \Rfunction{updateView}
function, and a method is defined for each view class.  
This method must take the information that a model has just been updated and
appropriately update the view to reflect that change.  Each
\Rfunction{updateView} method depends on how the view represents the
data.  For instance, a \Robject{spreadView} object's
\Rfunction{updateView} method may select or unselect a row on the
spreadsheet, while for a \Robject{sPlotView} object the
\Rfunction{updateView} method may change the appearance of one or more
points on the plot.  Notice that this method would ideally only redraw
the relevant portion of the view to reflect the change in the data in
the interest of efficiency and minimizing visual impact.  For certain
views, this may not be possible, and a view may need to update its
entire display.  Indeed, the view classes also should be able to
completely redraw the view rather than just updating a portion of the
view, and it is sometimes necessary for the software to be able to
instruct one or more views to do this. Thus, all views have a
\Rfunction{redrawView} method.  Both the \Rfunction{updateView} and
\Rfunction{redrawView} methods are called by the \Rfunction{handleMessage}
method of a \Robject{gUpdateViewMessage}, which is created after the model is
updated.  Message classes are discussed in Section \ref{Sssec:Message}. 

The design of the view class hierarchy and inheritance structure is
intended to facilitate extensibility.  For instance, if users wanted
to add a new plot view, say a density plot, they could create a new
view class that inherits from \Rclass{plotView}, called say
\Rclass{dPlotView}.  This new class, \Rclass{dPlotView}, has slots
named \Rslot{dfRows} and \Rslot{var} to store which rows and which
variable, respectively, were used to calculate the density shown in
the view.  Alternatively, one could elect to extend \Rclass{sPlotView}
if the characteristics of the new view were more like a scatter plot,
and the inherited methods were sensible.  In this case, the new class
would inherit the \Rslot{dfRows} slot, and could make use of the
\Rslot{xvar}, and ignore the inherited \Rslot{yvar}.  Whether this is
a good design choice depends on the complete set of characteristics of
the three classes - \Rclass{plotView}, \Rclass{sPlotView} and
\Rclass{dPlotView}.

\subsubsection{Controller}\label{Sssec:Control}

Recall that the controller performs two tasks: i) store information on
state, and ii) provide an interactive interface that allows the user to
determine the course of actions.  In Section \ref{Sssec:OverMVC}, it
was also mentioned that the first task is implemented via classes and
methods in the \Rpackage{MVCClass} package and the second is
implemented in the \Rpackage{iSPlot} package.

For the first task of storing information we make use of
\Robject{environments}, which are \proglang{R} data structures that contain
key-value pairs, but for which the usual copying sementics do not
apply. Hence the provide an efficient and natural mechanism for
storing state information and provide functionality that is similar to
references in other languages. This data structure is stored in the
\Rslot{controller} slot of an \Robject{MVC} instance.  This
environment store data such as information about the appearance of
the views for that particular \Robject{MVC} entity.  

For the second task the we implemented a GUI interface in the
\Rpackage{iSPlot} package. Users can either use this GUI or the set of
command line interfaces. Through this GUI, the user can load data,
create views, set the response to user interaction with a view, quit
the program and perform other functions.  Within the GUI, there are
menus to let users decide which action is taken next. The GUI is shown
in Figure \ref{Fig:Control} and is referred to as the control window.

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=1.7in, width=2.7in]{ControlWindow.jpg}
    \caption{ The \Rpackage{iSPlot} Controller (The Control Window) }
    \label{Fig:Control}
  \end{center}
\end{figure}

As shown in Figure \ref{Fig:Control}, the menus on the control window
are File, Edit, Display, Event, and Window.  These menus always appear
on the control window.  Because more than one model can be loaded we
have employed the concept of an ``active'' model. At any one time one
model is active and operations performed through the control window
menus (or through the command line functions) only affect the active
model and its views and its controller.  The active model is the same
as the active \Robject{MVC} entity since each \Robject{MVC} entity can
only have one model.  For example, if the user has two models (Model 1
and Model 2) loaded and Model 2 is the active model then only views of
Model 2 can be created through the control window menus or command
line functions.

Because interacting with the views should be driven by the user, the
Event menu allows the user to determine what response occurs when
there is user interaction with a view.  For example, the user may
initially want a point on a plot to be colored when the left button is
pressed and the cursor is over that point.  Then the user may decide
that the point should be hidden when the left button is pressed and
the cursor is over that point.  The Event menu lets the user decide
what happens in response to a left button click, a middle button
click, a right button click, and mouse movement. User interaction with
a view is flexible enough to allow for multiple outcomes.

Since extensibility is a key concern with the design of
\Rpackage{iSPlot}, users are able to add menus and menu items to the
control window through the command line.  As an example, if a
programmer in the future wants to add a new type of view, such as a
histogram, then a new menu item to create instances of that view could
be added to the Display menu.  The steps for adding a histogram view
to \Rpackage{iSPlot} are shown in the Use Case in Section
\ref{Sssec:Extens}.  By allowing users to change the control window,
they can add new functionality that is specific to their problem.

\subsubsection{Linking events to functions}
\label{Sssec:Event}

Linking callback functions to events, such as a button click, a mouse
movement or a key press event, is what allows users to have an
interactive graphics environment.  When an event occurs, the callback
function linked to the event determines the response to that event.
To create a flexible environment it should be possible to change the
response, which is determined by the callback function, to an event.
For example, when a left button press event occurs, a user may
sometimes want a point to be colored and at other times she may want a
point to be hidden.  In order to smplify programming for end-users, it
is desirable to be able to replace one callback (e.g. change color)
with another callback (e.g. hide point) dynamically. Otherwise, all
potential actions would have to be encoded in a single fixed callback
and that single function would need to consult a state variable to
determine which action to take in response to an event.

To allow this flexibility in the response to an event, a class called
\Rclass{gEventFun} was created in the \Rpackage{MVCClass} package.
The \Rclass{gEventFun} class stores all of the information needed to
respond to a particular event.  Clearly, the response to an event can
be performed by a single function, which is called the callback
function, as discussed in Section \ref{Ssec:Backg}.  However,
different responses to an event may require functions with different
signatures, where a function signature is the combination of the function name
along with its parameters.
Using the example in the previous paragraph, a callback
function that colored a point needs two parameters, the new color to
use and the point to color, while a callback function that hid a point
needs just one parameter, the point to hide.  Since the intention is
to be able to interchange the responses to an event, the signatures of
different callback functions should be the same.  These design
decisions determined the slots in the \Rclass{gEventFun} class and are
discussed more fully in the following paragraphs.

\begin{figure}[ht]
  \begin{center}
    \includegraphics[height=1in, width=1.2in]{EventClass.jpg}
    \caption{ The gEventFun Class. }
    \label{Fig:EventFun}
  \end{center}
\end{figure}

As shown in Figure \ref{Fig:EventFun}, the slots in the \Robject{gEventFun}
class are \Rslot{callFun}, \Rslot{shortName}, and \Rslot{preprocessFun}.  The
\Rslot{callFun} slot is the callback function, the
\Rslot{shortName} slot is a short description of the function that identifies
the callback function, and the
\Rslot{preprocessFun} slot is a list of all
preprocessing functions that must be called before the callback function.

The callback function that is stored in the \Rslot{callFun} slot must
take only one required argument.  All callback functions need to know
what object they should act on so this is the one parameter that the
callback functions take.  For instance, for a data frame model, the
parameter is of class \Rclass{character}, identifying a row in the
data frame.  Any other information a callback function may need is set
using the preprocessing functions.

The preprocessing functions that are stored in the
\Rslot{preprocessFun} slot take no parameters.  The purpose of the
preprocessing functions is to set variables that the callback function
needs.  Thus, not all callback functions need preprocessing functions
and if no preprocessing functions are needed, then this slot is set to
NULL.  If the callback function sets the color of a point in a scatter
plot, then a preprocessing function is needed to determine what color
is used.  Thus, in this example, the preprocessing function opens a
color browser to allow the user to choose what the new color is.

When a user wants to link a callback function stored in a
\Robject{gEventFun} instance to an event, this can be performed either
through the Event menu on the GUI or through the command line
functions.  The controller environment in each \Robject{MVC} object,
which is discussed in section \ref{Sssec:MVC}, stores which
\Robject{gEventFun} object (representing the callback function) is
linked with each event.  Not all callback functions make sense for
each event, so the controller environment also stores a list for each
event of appropriate \Robject{gEventFun} instances that can be linked
to that event.

\subsubsection{MVC}
\label{Sssec:MVC}

The \Robject{MVC} class binds the model, view, and
controller objects into one object.  Thus, whenever a new data set is
loaded, a \Robject{MVC} object is created.  The loaded \Robject{MVC} objects
are stored in an environment, called \Robject{mvcEnv}, which is discussed in
more detail in the Appendix.  A
\Robject{MVC} object can have one model and each model must be in one
\Robject{MVC} object so there is a one-to-one relationship between the
\Robject{MVC} and model objects.  Because of this relationship, the
\Robject{MVC} object and the model object are identified by the same name,
which is stored in the \Rslot{modelName} slot of the model object.  To load a
new model, the name of the model must be unique from all the previously loaded
models.  If it is not unique, the new data set is not loaded.

As shown in Figure \ref{Fig:MVCClass}, there is a virtual class, \Rclass{MVC},
that binds the MVC inheritance structure together.  This virtual class,
\Rclass{MVC}, has three slots, which are \Rslot{model}, \Rslot{viewList}, and
\Rslot{controller}.  The \Rslot{model} slot stores
the model object, the \Rslot{viewList} slot is a list of the view
objects for this model, and the \Rslot{controller} slot is an environment that
stores information for this \Robject{MVC}.  These three pieces of information
are needed to bind the model, view and controller into one object.  To create
instances of \Robject{MVCs}, the \Rclass{singleModelMVC} class, which inherits
from the virtual \Rclass{MVC} class, can be used.  

\begin{figure}[ht]
  \begin{center}
    \includegraphics[height=2.2in, width=1.2in]{partMVCClass.jpg}
    \caption{ Inheritance for MVC Objects. }
    \label{Fig:MVCClass}
  \end{center}
\end{figure}

\subsubsection{Messages}\label{Sssec:Message}

Whenever the components need to communicate with one another, a message object
is sent as discussed in Section \ref{Sssec:OverMVC}.  
This communication between the model, view and controller is crucial for the
pieces to work together and yet, still be independent of each other.  

The processing of messages in this MVC-style software is handled
centrally and generally.  It is important that
all messages have a common set of basic methods, such as
\Rfunction{initialize} and \Rfunction{handleMessage} so that this
central processing could work on any message without having to know
anything about its details.  All messages are sent to the
\Rfunction{handleMessage} method which determines where the
information should be sent, and hence is the dispatcher.  These
generic functions facilitate the introduction of new message classes
in new software without the programmer having to modify this software.

Since messages are sent when something has changed, either through
addition, alteration, or deletion, each message class reflects the
specific change/operation.  These common operations for the messages
allow the message object model to be constructed, and this model is
shown in Figure \ref{Fig:Message}.

\begin{figure}[!h]
  \begin{center}    
    \includegraphics[height=5in, width=6in]{newMessageClass.jpg}
    \caption{ Inheritance for Message Objects }
    \label{Fig:Message}
  \end{center}
\end{figure}

As with the view classes, the top message class, \Rclass{gMessage}, is
a virtual class.  It contains no slots and its purpose is to provide a
common node in the class hierarchy for the purpose of facilitating
extensibility and defining default methods for generic functions.

Currently, there are two types of messages for communicating within a
model, view, controller object: an add and an update message.  These two types
of messages are both performing some type of modification and thus, both the
add message, \Rclass{gAddMessage}, and the update message,
\Rclass{gUpdateMessage}, inherit from the virtual class,
\Rclass{gModifyMessage}, which contains three slots, \Rslot{dataName},
\Rslot{mData}, and \Rslot{type}.  \Rslot{dataName} is the character string
that gives the name of the model, \Rslot{mData} is a list of data needed to
perform the addition or alteration operation, and \Rslot{type} is a character
string that gives the type of addition or alteration to perform.  Both
\Rclass{gAddMessage} and \Rclass{gUpdateMessage} are virtual classes.

Since adding a view requires different information from adding a model
(and similarly with updating views versus models), it makes sense to
have two separate classes for these different types of
elements. 
Messages sent between the model, view, and controller components
are from one of the following
classes: \Rclass{gAddViewMessage}, \Rclass{gAddDataMessage},
\Rclass{gUpdateViewMessage}, and \Rclass{gUpdateDataMessage}.  The
\Rclass{gAddDataMessage} class represents a message to add a model and
a \Robject{MVC} object because whenever a model is added, a
\Robject{MVC} object is created that contains this model.  The
\Rclass{gAddViewMessage} class represents a message to create a view.
This type of message can only be used after a model has been added.

The \Rclass{gUpdateDataMessage} class represents a message to update
a model.  This message is crucial for linking because it is responsible for
ensuring that once a model has been updated, this information propagates to
all views of the model.  The \Rslot{from} slot in the
\Robject{gUpdateDataMessage} object is used to indicate which model sent this
message.  This slot is needed when models are linked because an update data
message may come from either a different model or from a view of this model.
Model linking is a feature that is not implemented in the \Rpackage{iSPlot}
package so this slot always reflects that the update data message came
from a view within the \Robject{MVC} object.  In the \Rpackage{iSPlot}
package views can be linked because they are based on the same data set, but
models can not be linked.

Finally, the \Rclass{gUpdateViewMessage} class represents a message to
update a view.  This message is created and handled whenever the model
is updated so that the views accurately reflect the model.

An example of message passing within a \Robject{MVC} object is shown
in Figure \ref{Fig:MPwithin}.  In this example, the response to a user
performing a button click event over a point in the scatter plot is to
color the point red.  Figure \ref{Fig:MPwithin} shows how messages are passed
over time to update this one scatter plot view (i.e. the same view is shown on
both the left and right hand side of Figure \ref{Fig:MPwithin}).
Here the user first clicks on a point
in the scatter plot, which is shown as Step 1 (the circled 1 on the
figure).  In the figure, the point that has been selected
has an arrow next to it.  Then, in Step 2, an update data message is sent to
the model, which updates the \Rslot{virtualData} slot of the model object.
After the model has been updated, the views must be notified that a
change has occurred so in Step 3, an update view message is created
and sent to all views of this model.  In response to this message, the
view updates itself in Step 4 and now the point is colored red on the
view to reflect the change in the model.  In this example, the
\Rslot{from} slot in the \Robject{gUpdateDataMessage} object is the
name of this \Robject{MVC} object since the message came from within
the \Robject{MVC}.

\begin{figure}[ht]
  \begin{center}
    \includegraphics[height=2in, width=5in]{newMPwithin.jpg}
    \caption{ Message Passing within a \Robject{MVC} object.  The first step,
      indicated by a circled one, occurs when a user interacts with the y
      versus x scatter plot.  Then an update data message is sent to the model
      in the second step, which alters the model.  Next in the third step all
      views of this model are sent an update view message, which causes the
      y versus x scatter plot to be updated in the fourth step.  Note that the
      same view is shown in step 1 and in step 4.  These steps are showing how
      messages are passed to update this one view. }
    \label{Fig:MPwithin}
  \end{center}
\end{figure}

All four classes, \Rclass{gAddDataMessage}, \Rclass{gAddViewMessage},
\Rclass{gUpdateDataMessage}, and \Rclass{gUpdateViewMessage}, have
\Rfunction{initialize} and \Rfunction{handleMessage} methods, which perform
the following tasks.  The \Rfunction{initialize} method is used to properly
fill the slots of the object when it is created.  The
\Rfunction{handleMessage} method is necessary to process the message.  Since a
message is a form of communication between two components, once it is created
it must be sent to the proper recipient and action must be taken in response
to its information, which is the purpose of the \Rfunction{handleMessage}
method. 

As with the inheritance structures seen in previous sections, the
message inheritance structure is designed to allow for extensibility.
For example, a user could create a \Rclass{gUpdateControlMessage}
class that inherited from the \Rclass{gUpdateMessage} class.  This new
class, \Rclass{gUpdateControlMessage}, could convey information that
told the control window to be updated in response to a change in the
active view (the active view is the view that has focus).  Currently,
the control window does not reflect what the active view is, but if a
view was created whose axes could be rotated to provide a different
perspective on the data, then a user may want the control window to
have some type of interface to allow control of the rotation.  The
goal for the message classes is that the design is flexible enough to
allow a user to make additions or changes.

\subsubsection{Extensibility in overall design}\label{Sssec:Extens}

Not only was the overall design using the MVC paradigm planned to
promote and facilitate extensibility, but within each component, the
goal has been to create a flexible design so that users can easily
make changes or additions.  For the controller, new menus and menu
items can be created and added to the control window, giving the user
the ability to create new actions for the system.  For the model, new
model classes can be added for new data structures.  For the views,
new view classes can be created that inherit from the existing view
classes, giving users the ability to create new displays that may be
applicable to their data.  Similarly, new message
classes can be created that inherit from the existing message classes.
Messages are particularly important in their role of communicating
between components since they allow the components to remain unware of
each others existence.  Also, to make extending the design easier for the
user, all additions can be made in the \proglang{R} language.

Developers can also extend the available options for a response to an event.
This extension can be performed by creating a new \Robject{gEventFun} object to
represent a callback function.  More details are given in Section
\ref{Ssec:EventMenu} about how to perform this extension. 

As an example of an addition that a user may want to make, the
following Use Case describes the general steps needed to add a
histogram view to \Rpackage{iSPlot}.  For a reference on Use Cases,
please see \cite{UseCase}.

\textbf{Use Case for Adding a Histogram}

\textbf{Primary Actor:} Programmer
\newline
\textbf{Scope:} \Rpackage{iSPlot} and \Rpackage{MVCClass} Package
\newline
\textbf{Level:} Summary
\newline
\textbf{Stakeholders and Interests:} Users of \Rpackage{iSPlot}
\newline
\textbf{Precondition:} Programmer has access to the \Rpackage{iSPlot} and
\Rpackage{MVCClass} code
\newline
\textbf{Success Guarantee:} A new histogram view, which is an
interactive and linked view, is available to users.
\newline
\textbf{Main Success Scenario:}
\newcounter{spacerule}
\begin{list}{\textbf{\arabic{spacerule}. }}
              {\setlength{\leftmargin}{0.5in}
               \setlength{\itemsep}{0in}
               \usecounter{spacerule}}
  \item Programmer adds a new menu item to the Display menu on the
               control window in the \Rpackage{iSPlot} package.  This menu
               item allows a user to create a histogram view.
  \item Programmer creates a function that is called when the
  menu item (created in step one) is activated.  This function
  allows the user to choose which variable to plot and then
  creates the histogram with the appropriate data from the active model. 
  \item Programmer creates a new view class that represents a
  histogram view and that inherits from one or more classes in the \Rpackage{MVCClass}
  package.  This new view class needs to store information, such as the column
  and rows that were used to create the histogram.  
  \item Programmer must define methods for the new histogram view class in the
  \Rpackage{iSPlot} package and these methods must include an
  \Rfunction{initialize}, an \Rfunction{updateView} and a
  \Rfunction{redrawView} method.  The \Rfunction{initialize} method properly
  sets up the view, creates the view instance, and makes sure that the view can
  respond to certain events, such as key press, delete, focus in, and button
  clicks (see the next step).  The \Rfunction{updateView} method updates the
  view when the model 
  has changed.  This method takes two parameters: object, which is the view
  object, and vData, which is a list of the following four elements: row name,
  column name, old value and new value.  This information passed in the
  parameters allows the programmer to update the view so it is synchronized
  with the model.  The \Rfunction{redrawView} method completely redraws the
  view.  Thus, the \Rfunction{redrawView} method only has one parameter:
  object, which is the view object to redraw.
  \item For the histogram view to be interactive, the view needs
  to respond to the following events: key press event, delete event,
  focus in event, the mouse button press event, and possibly the motion notify
  event.  The key press
  event adds accelerators to the view, the delete event ensures
  that the view list is current,
  and the focus in event ensures that
  the device is active when the histogram has the focus.  The mouse
  button press event allows the user to change plot information for
  the data (such as the color of a histogram bin) by interacting with the
  view.  Similarly, the motion notify event, if the programmer wants to
  respond to it, would let the user interact with the view by moving the
  cursor over the view.  Responding to these events is set in the
  \Rfunction{initialize} method for this new view class, which is defined by
  the programmer.  
\end{list}

\textbf{Extensions:}
\begin{list}{\textbf{\arabic{spacerule}. }}
              {\setlength{\leftmargin}{0.5in}
               \setlength{\itemsep}{0in}
               \usecounter{spacerule}}
  \item Other events besides those listed in step four may need to be
  noticed depending on what interactivity the programmer wants to
  support. 
  \item A controller, such as a slider, can be added to the histogram
               view to control the histogram bin width. 

\end{list}

\section[iSPlot functionality]{\Rpackage{iSPlot} functionality}\label{Sec:Func}

Some of the functionality available through the control window in
\Rpackage{iSPlot} is discussed here along with how it relates to how the
package has been designed.  All of the functionality discussed below is also
available through command line functions.  For a full explanation of
\Rpackage{iSPlot} capabilities, please see the \Rpackage{iSPlot} vignette.

\subsection{Event}\label{Ssec:EventMenu}

As mentioned in Section \ref{Sssec:Control}, the control window
controls the user interaction with views and this particular task is
implemented in the Event menu on the control window.  The Event menu lets the
user change the response to an event.  For example, the menu items under the
Event menu let the user set the response to a mouse over event, a left button
click event, a middle button click event, and a right button click event.
Suppose the user chooses the Set Left Button Click menu item under the Event
menu.  The user is then presented with several radio buttons that let
the user set the response to the left button click event.  For now, the
potential responses for the left button click event are color a point, hide a
point, highlight a point, and no action (i.e. no response).  These options
are all callback functions that have been defined by creating an instance of
class \Rclass{gEventFun}, which was explained in Section
\ref{Sssec:Event}.

By designing the linking of callback functions with events in this manner, the
user can either use one of the predefined callback functions for an event or
the user can create his or her own callback function by defining an object of
class \Rclass{gEventFun}.  Thus, a user can change at any time the response
to a left button click event by using the Event menu.  Also, if the user
wanted a callback function that changed the plotting character of a point, for
example, the user could create an object of class \Rclass{gEventFun} that
represents this callback function.  This can be done directly on the command
line by calling the function, \Rfunction{addCBFunction}, and the man page for
this function gives an example of creating a new callback function for
changing the plotting character.  Then after this instance has been created,
the user could set the left button click event to change the plotting
character.  This flexibility lets the user decide the response to events and
lets the user extend the options for an event.  Notice that this design lets
the user have different responses to a left button click event versus a middle
button click event, for example.  For more details about the Event menu please
see the \Rpackage{iSPlot} package vignette.

\clearpage
\subsection{Find}\label{Ssec:Find}

Find is a menu option under the Edit menu on the control window, but it
can also be activated through the accelerator, Ctrl-F.  Find
allows a user to look for a particular row or a data element in a data
set.  When the user enters the row or element he or she wants to
find, the callback function that is linked to the left button click event
is called.  

For example, suppose that a user wants to find row ``Ohio'' in a data
frame where the row names are state names and the left button click event is
set to highlight a point.  Then by finding ``Ohio'', any points that
reflect that row in the data frame become highlighted.  This highlighting
of points on a view happens in two steps.  First, a
\Robject{gUpdateDataMessage} object is created that updates the
\Rslot{virtualData} slot in the model object.  Then, after the data have
changed, a \Robject{gUpdateViewMessage} object is created and handled so that
all views highlight points that represent ``Ohio''.


\subsection{Reset}\label{Ssec:Reset}

Reset is also a menu option under the Edit menu on the control window.  It
can be activated by clicking on the Reset menu item or by using the
accelerator, Ctrl-T.  Reset removes any changes
made to the data set since the data were loaded.  Reset performs
this action by resetting the \Rslot{virtualData} slot in the model object back
to its default values through a \Robject{gUpdateDataMessage} object.  If there
are views that display this data, a \Robject{gUpdateViewMessage} object is
created and handled so that the views are updated.

\section{Discussion}\label{Sec:Disc}

The goals of the software discussed in this paper were to create views that
are linked, views that are interactive, and a design that is extensible.
Constructing linked views was achieved by using the model, view, controller
paradigm, which is a widely used and well understood design.  In addition, by
carefully implementing the MVC design using S4 classes and inheritance in
\proglang{R} 
for the model, view, and message components, users can make extensions to the
model, view, and message classes.  An example discussed in the Use Case in
Section \ref{Sssec:Extens} created a histogram view class that inherited from
existing view classes in the \Rpackage{MVCClass} package.  To extend the model,
view, and message classes, the user only needs to know the \proglang{R}
language. 

The second goal of creating interactive views was realized by using the
\Rpackage{RGtk} and \Rpackage{gtkDevice} packages, which connected
\proglang{R} to Gtk+'s 
functionality.  Because Gtk+ is such a rich toolkit, many events can be
accessed, which allows a more interactive environment for the user.  Also,
users can make additions to the interactivity that is currently implemented.
Users can add signal handlers for events that are presently not caught and
this extension again only requires that the user program in \proglang{R}.  More
likely, though, the user may want to change the response to an event.  The
\Rclass{gEventFun} class was created so that users can encapsulate the
functionality needed for a new response to an event in one \Robject{gEventFun}
object.  Once a new \Robject{gEventFun} object has been created by the user,
this response can be linked to an event through either the GUI or through
command line functions.  Creating this new response again only requires that
the user program in \proglang{R}. 

The final goal was to create an extensible design.  Extensibility was
incorporated in several places in the design of this software.  Several
examples of extensibility were already given in previous paragraphs, such as
adding new model, view, and message classes as well as changing the response
to an event.  Users can also add new functionality to the GUI (the control
window) using certain command line functions, which add a menu item to the GUI
and link it to a function they have created.  An important concern for
creating an extensible design was that users only need to know one
programming language to make additions.  Thus, the software was designed such
that all extensions can be done in the \proglang{R} language. 

The functionality that is currently available in the \Rpackage{iSPlot}
package through either the GUI or command line functions lets the user perform
exploratory data analysis on two-dimensional data.  However, the hope is that
the design encourages users to make additions based on the needs of their
data.  By giving users a tool for visualizing their data that is
designed to be extensible, users have great flexibility in determining how to
visually present and explore their data. 

\clearpage

\section*{Appendix}

\subsection*{Implementation}

In Sections \ref{Ssec:Overview} and \ref{Ssec:Details}, the design of
\Rpackage{iSPlot} and \Rpackage{MVCClass} was discussed, but certain
implementation decisions were also mentioned.  Here, more details of how
\Rpackage{iSPlot} was implemented are given.

Although each \Robject{MVC} object uses the \Rslot{controller} slot as an
environment to store information about that \Robject{MVC} object, there still
needs to be an overall environment that stores information for the software as
a whole.  This environment is called, \Robject{mvcEnv}, and it is created in
the \Rpackage{iSPlot} package.  The \Robject{mvcEnv} environment stores
information such as the list of loaded \Robject{MVC} objects, the name of the
active \Robject{MVC} (active model), the Gtk+ window that is the
control window, the menus for the control window, and any default
values that apply to all \Robject{MVC} objects, such as the default values for
the \Rslot{virtualData} slot in a model object.  

Also, as mentioned several times previously, the API of the
\Rpackage{iSPlot} package can be accessed through either a GUI front end or
through command line functions.  To learn more about the command line
functions, please see the \Rpackage{iSPlot} package vignette. 

\subsection*{Example event}

An example of the steps that occur in response to an event is
given here.  For these steps, the active view is a scatter plot
and the left button click event causes a point to be colored.  

\begin{list}{\textbf{\arabic{spacerule}. }}
              {\setlength{\leftmargin}{0.5in}
               \setlength{\itemsep}{0in}
               \usecounter{spacerule}}
  \item First the user clicks with the left button on a point on the active
  scatter plot.  Suppose that the current color is red.
  \item The mouse button press event on the view emits a signal
               that is caught by the Gtk+ drawing area signal
               handler.
  \item The signal handler for the drawing area calls the
               \Rfunction{clickEvent} method for the
               \Robject{sPlotView} object.
  \item The \Rfunction{clickEvent} first determines if there is a callback
  function assigned to the left button click event and for this example, the
  callback function assigned to the left button click event is to color a
  point. 
  \item The \Rfunction{clickEvent} next determines if the mouse button
               press event occurred over a point on the plot and if it
               did, then the callback function is called and this callback
               function creates and handles a \Robject{gUpdateDataMessage}
               object to update the data in the active model.
  \item When the \Robject{gUpdateDataMessage} object is handled in the
               \Rfunction{handleMessage} method, the data in the model
               are updated and then a \Robject{gUpdateViewMessage}
               object is created and handled.
  \item When the \Robject{gUpdateViewMessage} object is handled in the
               \Rfunction{handleMessage} method, the \Rfunction{updateView}
               method is called to update the views of the active model.
  \item Now any view showing this point has the point colored red.

\end{list}

\subsection*{Code for a callback function}

Below is an example of \proglang{R} code for a callback function.  This is the
callback function for a mouse button press event on a Gtk+ drawing
area.  The function, \Rfunction{gtkAddCallback}, connects the event to
the callback function so \Rfunction{gtkAddCallback} is the signal
handler.  Now when a mouse button press event occurs, this callback
function calls the \Rfunction{clickEvent} method for the view object. 

\begin{verbatim}
  gtkAddCallback(drArea(curView), "button_press_event",
    function(obj, ev)
    {
      clickEvent(curView, ev)
      return(TRUE)
    }
  )
\end{verbatim}

Many other examples of callback functions are found in the
\Rpackage{iSPlot} code.

\bibliography{iSPlotPaper2}

\end{document}



















