Updating ggplot2 code for new version

Question

Since installing the latest version of ggplot2 (0.9.1), I have been getting messages from my old code including:

> warnings()
Warning messages:
1: 'opts' is deprecated.
Use 'theme' instead.
See help("Deprecated")
2: 'theme_text' is deprecated.
Use 'element_text' instead.
See help("Deprecated")
8: In opts(title = trait axis.text.x = theme_text(size = fontsize$axis),  ... :
  Setting the plot title with opts(title="...") is deprecated. Use labs(title="...") or ggtitle("...") instead.
9: 'opts' is deprecated.

I have a few questions:

1. help("Depreciated") returns "no documentation for 'Depreciated' in specified packages and libraries"; is this an error?
2. Is there some time at which 'Depreciated' will turn to 'Obsolete' and my code will begin to throw errors?
3. How can I update my code (to solve these specific issues and prevent others still waiting to be found)?
4. Can I load two versions of ggplot2 and specify which version of each function I am using?
5. On what timescale might updated syntax become obsolete?

I accept that this is a common issue with software, but perhaps some contributors to SO have specific insight into the longer term plans and rationale of the package's author.

Solution 1

For many of these things, I'd start following the ggplot2-dev mailing list, and/or the packages github repository.

The reason you were not finding anything was simply because you had misspelled "deprecated".

For upgrading your code, see this transition guide or this one. My understanding is that deprecation is the first step in total removal, which would typically happen in the next "major" release. Since 0.9.2 just came out, I'd guess the next one is at least 6-8 months away, but that's just a guess.

It is possible to load different versions of a package.

(Minor point: the latest version is 0.9.2.1!)

Solution 2

From Winston's github wiki, the key changes are:

1. theme_xx() functions changed to element_xx()

   theme_segment() incorporated into theme_line()

2. opts() changed to theme()

3. opts(title = "mytitle") changed to labs(title = "mytitle")

4. New features that make programming easier, e.g. ggtitle("mytitle") does the same as #3

Here is a diff of some functions that I updated:

Comments

[mnel]

The current version on CRAN is 0.9.2.1, not 0.9.1. @joran's suggestion of the transition guide is valid, but there are a number of changes to 0.9.2 in terms of theme settings

[joran]

@mnel Thanks for pointing out the correct current version!

[Matt Bannert]

+1 for joran's answer. This is basically the way to go. That being said ggplot has one of the nicer warning messages here. Just try do to what the warning suggests. use theme instead of opts. For me it worked out of the box. ah and you might want to follow @hadleywickham on twitter...

[Dieter Menne]

And note that it should be help("Deprecated"), not "Depreciated" as you consistently write. Not that the help file is of much help here...