


Changes in lattice 0.9
======================



improvements
------------


 o Axis labelling code has been rewritten to internally use S3 method
   dispatch, with (unexported) methods for numeric (default),
   character (for factors), POSIXct and date. More methods can be
   considered on request.  reversed limits are now allowed.

 o contourplot can now handle missing rows in the data frame
   (equivalent to NA's in z). contourplot now uses contourLines().

 o cloud and wireframe now use better 3-D projection calculations, and
   are generally much better than before.  wireframe is much faster,
   and has a better shading algorithm. It can also handle NA's and
   missing rows.

 o splom (specifically panel.pairs) has more functionality, including
   the option of using different panel functions below and above the
   diagonal, user defined diagonal panels, and a table-like layout
   (similar to pairs)

 o font specifications now allow for fontface and fontfamily

 o much improved update method for trellis objects

 o setting auto.key = TRUE now computes key at printing time,
   honouring any changes in trellis settings



new features
------------

 o arbitrary reordering of conditioning variables, as well as of
   levels within a conditioning variable. This works in the update
   method (as well as high-level plots), making it easy to examine
   parts of a multipanel trellis display and view it in different
   conditioning orders.

 o extended key functionality (via the legend argument) that allows
   multiple legends and the use of arbitrary grid objects as keys

 o option to NOT drop unused factor levels when subsetting, by setting
   drop.unused.levels = FALSE or 
   drop.unused.levels = list(cond = FALSE, data = FALSE) 
   in high-level functions like xyplot.

 o Ability to attach settings to a trellis object (rather than
   changing the global settings), via argument par.settings in high
   level calls.

 o Wireframe can now draw parametrized 3-D surfaces like spheres
   (generally of the form f(u,v) = (x(u,v), y(u,v), z(u,v)), for
   (u,v) in the square [0,1] x [0,1]).

 o Functionality similar to locator() (possible due to recently added
   features of grid). All panels should have predictable viewport
   names, which can be used in seekViewport() to grab a particular
   viewport. grid.locator() can subsequently be used to locate points
   in the native coordinate system of that panel.


changes in behaviour
---------------------

 o allow.multiple now defaults to TRUE (whenever it makes sense),
   since '+' in a formula is interpreted differently than S-PLUS
   anyway. As in model formulae, I(x+y) works as expected.


 o default behaviour of qq and qqmath changed (from S-PLUS behaviour)
   to match corresponding base functions qqplot and qqnorm


bug fixes
---------

 o Fixed important bug concerning interaction of subscripts and
   subsets
   

 o lots of other fixes, mostly obscure








Changes in lattice 0.8
======================

Major change is the addition of a NAMESPACE. grid is now not
'require()-d', but imported only. To use grid functions directly in
lattice calls (which is a very reasonable thing to do), one needs to
explicitly call library(grid).


contourplot() has improved when data has NA's. Still doesn't work when
the NA rows are completely omitted (in other words, the full "matrix"
has to be specified, even the entries with NA).

Clipping can now be turned off in panels and strips via the
trellis.par.get("clip") setting.

See the Changelog for other minor changes. 






Changes in lattice 0.7
======================


grouping variables
------------------
The handling of Grouped displays has been made more consistent (and
different from S-Plus). Whenever a groups= argument is specified, it
is assumed that the user wants a grouped display and an attempt is
made to honour this whenever appropriate (this ultimately depends on
the panel function). A non-trivial addition to the list of functions
that support this is barchart.

Specification of legend (key) has been made slightly easier in the
most common cases. The key is used most often in conjunction with the
groups argument, and using the global trellis settings. The simpleKey
function (and the auto.key argument to high level functions) uses the
global settings to create a key with a not very flexible but simple
interface.

Handling of the formula argument has been extended to allow multiple
variables on either side of the formula (with allow.multiple = TRUE),
e.g. xyplot(y1 + y2 ~ x, data, allow.m = TRUE). These are treated as
grouped displays.




scales
------
Some components of scales, namely tck, rot and cex, can now be length
2 vectors, controlling left/bottom and right/top separately. 

Some more functions (not all) now handle factors in the formula
correctly (i.e., coerce them to numeric when factors are not
appropriate, but use levels of the factor for labelling).





Changes in lattice 0.6
======================

API change: 

panel functions
---------------
In earlier versions, panel functions and prepanel functions were
guaranteed to be passed numeric vectors as x,y (and z) arguments. This
is no longer true. All panel functions are now expected to handle
other possibilities. This has been done in all the predefined panel
functions in lattice (but not in llines, lpoints, etc.). In practice,
the only changes required are (unless I have overlooked something) to
add calls like

x <- as.numeric(x)
y <- as.numeric(y)

at the beginning. prepanel functions can now return, as their xlim or
ylim components, either a numeric vector of length 2 (possibly a
DateTime object), or a character vector. The latter implies that the
elements of this vector should be the respective axis labels,
associated with tick marks at 1:length_of_this_vector.


high-level functions
--------------------
The default panel functions of high level functions can now be
different, depending on whether a groups argument was passed. In
practice, this now happens for xyplot, splom and densityplot.
(densityplot has an additional high-level argument specifically for
this, called panel.groups, which is passed to the panel function.)
This is a convenience feature, (and is inconsistent with S-Plus) in
that it presumes that if the user has specified a groups argument, she
wants it to be used, where appropriate. 

scales
------
In anticipation of future use (in nlme, for example), the at and
labels components of scales can now be a list. Each element
corresponds to a panel. This is thoroughly untested and not guaranteed
to work.


There are also some other API changes associated with cloud and
wireframe, discussed below.




New Features and Fixes:


Mathematical Annotation
-----------------------
Following changes in grid 0.7, lattice now supports latex-style
labelling using expressions. These can be used in almost all sensible
places (an exception being in colorkey axis labels in
levelplot/contourplot, and this is not expected to change).

Date-Time Labelling
-------------------
Axis labelling procedures did not recognize DateTime objects in
earlier versions. This has been fixed. The routine currently used is a
hack of axis.POSIXt (without the format option), but will hopefully
improve in future.

3-D functions
-------------
The 3-D functions cloud and wireframe have been greatly improved in
terms of extensibility. The code is much cleaner, and writing new
panel functions are much simpler. Earlier versions had a problem with
the default placement of the labels (x/y/z-lab) and scales
(arrows/ticks), which has been fixed. [The only major problem that
still remains is when, in a perspective plot, the projection of the
distant face is fully contained inside the projection of the near
face.]

Earlier wireframe code used an unnecessarily large amount of
memory. This has been fixed, although speed is still not good (fixes
are in the planing stage, and would involve changes in
grid). drape=TRUE used to give wrong coloring, which is now fixed.

The 'group' argument now works with wireframe, resulting in multiple
surfaces. This is mostly satisfactory, but is not sophisticated enough
to render intersecting surfaces properly (might be approximated by a
fine enough grid).

There are also some rudimentary lighting options, which can render the
surface as being illuminated from a light source. No shadows. (Try
shade=TRUE in wireframe.)

Although these changes go a long way towards stabilizing
cloud/wireframe, some further changes, especially in how the panel
function handles the groups argument, are expected in the future.



Known bugs: 
==========

Handling of NA values are often inconsistent and buggy. Some of these
are not easily fixable (particularly one in contourplot), but some
are, so bug reports on this are still welcome.

Fonts specified in the new R font specification may not work yet.





Changes in lattice 0.5
======================

Not many. 

 o Biggest change in the way settings are handled. Settings are now
   stored in a global list called lattice.theme, and is truly
   device-specific (i.e., settings for more than one device can be
   used concurrently). Improved theme management via lset and
   show.settings. Changed defaults for color postscript/pdf.

 o bwplot and friends which had to have the grouping factor/shingle on
   the y-axis, can now have it on the x-axis as well. Far from
   perfect, though, since long labels can overlap with default
   settings.

 o panel.superpose now accepts an additional argument called
   panel.groups (by default panel.xyplot), which is the panel function
   actually called for each subset of the data determined by
   groups. Avoids having to write something as big as panel.superpose
   for natural generalizations like interaction plots. (Related new
   panel function: panel.linejoin)

 o colorkey in levelplot on all sides. Rendering of large key's much
   much faster (using grid.place suggested by Paul)

 o Other minor changes (doc, more arguments etc)

 o Following changes in grid, calls to base R graphics and lattice
   functions can now be mixed.
  

Changes in lattice 0.4
======================

Some of the implementation details have changed a lot. This might
cause some old code to fail, though no such instances are known.

No significant new features have been added, but there are several
bugfixes (notably in levelplot). The important changes are:

 o documentation restructured. There is no topic called `trellis.args'
   any more. The detailed description of the arguments common to all
   high level trellis functions can be found under help(xyplot)

 o once trellis.device() is called, Lattice graphics and base R
   graphics should mix more or less seamlessly. There is an optional
   argument in trellis.device() that can deal with the first blank
   page problem, with certain restrictions.

 o a (as yet very small) demo, called by demo("lattice")

 o Clipping: whatever is drawn by the panel function is now clipped to
   inside the panel region. Strip texts are clipped to inside the
   strips.

 o Axis tick labels by default do not overlap, some tick marks are
   left unlabelled if necessary.

 o The argument list for strip.default changed to be like S

 o levels() and nlevels() give sensible answers for shingles. new
   print methods for shingles and levels of shingles

 o colorkey (currently used only in levelplot) can now be placed to
   the left, top or bottom as well

 o new ``lines'' component in the par.strip.text argument that can be
   used to change the height of strips 

 o xlab, main etc can be double height strings (containing "\n"-s),
   the spaces allocated for these would be automatically adjusted

 o strip.default now has style=5

 o new panel.superpose.2 (suggested by Neil Klepeis)

 o the default colour settings sometimes seem too light on a white
   background. To deal with this, there is a new setting with some
   darker colours that can be set by calling lset(theme =
   "white.bg"). see ?lset for details. This is currently in a
   proof-of-concept stage (the colors in "white.bg" were chosen just
   because I liked their names), and suggestions for better color
   schemes would be most welcome.

 o show.settings() added






  

Changes in lattice 0.3
======================


The overall internal structure of the lattice library has changed
considerably in verion 0.3, in particular making it far more readable
and debuggable. However, this also means that some code which had
worked with the earlier version might now fail. (This is just a
discalimer, there are no known instances.)

New Features:
============

 o (Almost) full support for the `key' argument for drawing legends

 o Support for log scales

 o levelplot (but no contourplot. In particular, the contour = T option
   in levelplot does not work)

 o tmd now works on the output from qq 

 o panel function names can now be quoted strings

 o scales and its x and y components can now be just a character
   string like "free" or "sliced", i.e., the relation tag can be
   omitted. 

 o extension to the `type' argument in panel.xyplot and
   panel.superpose to allow stair-like and histogram-like plots
   (type="s" and "h" in plot), as well as loess smooths (using
   the loess.smooth function in the modreg library). Also, more
   than one of these options can now be used concurrently. This
   allows, for example, a grouped plot where a grouping variable
   can be used to fit separate loess curves along with the scatter
   for each group. See example(xyplot)

 o wrappers around grid functions with API-s of traditional graphics
   functions to help port existing S-Plus Trellis code. See below for
   details.

 o changes in print.trellis to allow mixing of Lattice and usual R 
   graphics. See below for details.


Porting S-Plus Trellis code to Lattice
======================================

One of the basic problems in porting existing Trellis code to R is the
unusability of the base R functions like lines and points inside panel
functions. To help make the changes more transparently, lattice now
includes several wrappers around grid functions that provide an API
similar to the corresponding base R functions. The list currently
includes lpoints, llines, ltext and lsegments [update: larrows].

Using Lattice and base R graphics concurrently [OBSOLETE]
==============================================

Grid graphics normally do not mix with usual R graphics. However,
end-users typically might want to use lattice functions concurrently
with traditional R graphics. To allow this without intermittent calls
to grid.stop() and grid.start(), print.trellis (which ultimately does
all the plotting in lattice) now tries to preserve the state of the
device on which it plots. By default, library(lattice) opens a device
in grid enabled mode. It can be reverted to non grid mode by
grid.stop(). Subsequently, both Lattice functions and traditional
graphics functions can be used. Devices opened by trellis.device()
start in non-grid mode, unless grid.start() is called.



Still Missing [OBSOLETE, except for the parts about piechart and scale]
=============

 o contourplot, wireframe, cloud (partially implemented) and of course,
   piechart

 o Some components of scale (I haven't found a full list, so
   can't say exactly which are missing)

 o Fonts 

 o axis labels badly implemented, no checking for overlaps.








