Improved documentation and hickups.

DESCRIPTION

@@ -4,13 +4,15 @@ Title: splot! - Stefan's plot library of tricks
 URL: https://github.com/stefanedwards/splot
 BugReports: https://github.com/stefanedwards/splot/issues
 Version: 0.2.0
-Author@R: person(c('Stefan','McKinnon'), 'Edwards', email='sme@iysik.com', role=c('aut','ctb','cre'))
+Author@R: person(c('Stefan','McKinnon'), 'Edwards', email='sme@iysik.com',
+    role=c('aut','ctb','cre'))
 Author: Stefan McKinnon Edwards <sme@iysik.com> [aut, ctb, cre]
 Maintainer: Stefan McKinnon Edwards <sme@iysik.com>
 Description: Yet another ggplot2 and knitr extension package.
-  Includes functions for manipulating ggplot2 legends, 
-  axis lines, and a bit of knitr magic.
-Depends: R (>= 3.1.0)
+    Includes functions for manipulating ggplot2 legends,
+    axis lines, and a bit of knitr magic.
+Depends:
+    R (>= 3.1.0)
 Imports:
     ggplot2 (>= 2.2.0),
     grid,
@@ -21,7 +23,7 @@ Imports:
 License: GPL-3 + file LICENSE
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 6.0.1
+RoxygenNote: 5.0.1
 Collate:
     'ggplot2.r'
     'brackets.R'

R/coord-flex.r

@@ -166,7 +166,8 @@ flex_render_axis_v <- function(self, scale_details, theme) {
 
 # ggproto objects -------------------------------------------------------------
 
-#' @rdname ggplot2-ggproto
+#' @rdname splot-ggproto
+#' @keywords internal
 #' @format NULL
 #' @usage NULL
 #' @export
@@ -177,7 +178,8 @@ CoordFlexCartesian <- ggplot2::ggproto('CoordFlexCartesian',
                               render_axis_v = flex_render_axis_v
 )
 
-#' @rdname ggplot2-ggproto
+#' @rdname splot-ggproto
+#' @keywords internal
 #' @format NULL
 #' @usage NULL
 #' @export
@@ -187,7 +189,8 @@ CoordFlexFlipped <- ggplot2::ggproto('CoordFlexFlipped',  `_inherit` = ggplot2::
                             render_axis_v = flex_render_axis_v
 )
 
-#' @rdname ggplot2-ggproto
+#' @rdname splot-ggproto
+#' @keywords internal
 #' @format NULL
 #' @usage NULL
 #' @export

R/facet-rep-lab.r

@@ -39,7 +39,8 @@ remove_labels_from_axis <- function(axisgrob) {
   axisgrob
 }
 
-#' @rdname ggplot2-ggproto
+#' @rdname splot-ggproto
+#' @keywords internal
 #' @format NULL
 #' @usage NULL
 #' @export

R/facet-wrap.r

@@ -14,7 +14,8 @@ facet_rep_wrap <- function(..., repeat.tick.labels=FALSE) {
 }
 
 
-#' @rdname ggplot2-ggproto
+#' @rdname splot-ggproto
+#' @keywords internal
 #' @format NULL
 #' @usage NULL
 #' @export

R/ggplot2.r

@@ -5,16 +5,15 @@
 #' @import gtable
 NULL
 
-#' Base ggproto classes for ggplot2
+#' ggproto classes used in splot!
 #'
 #' If you are creating a new geom, stat, position, or scale in another package,
 #' you'll need to extend from \code{ggplot2::Geom}, \code{ggplot2::Stat},
 #' \code{ggplot2::Position}, or \code{ggplot2::Scale}.
-#'
-#
-#' @seealso \code{\link[ggplot2]{ggproto}}
+#' 
+#' @seealso \code{\link[ggplot2]{ggproto}}, \code{\link[ggplot2]{ggplot2-ggproto}}
 #' @keywords internal
-#' @name ggplot2-ggproto
+#' @name splot-ggproto
 NULL
 
 #' A waiver object.
@@ -26,18 +25,19 @@ NULL
 #'
 #' Code taken from \file{ggplot2/R/utilities.r}.
 #'
+#' @seealso \code{\link[ggplot2]{waiver}}
 #' @references ggplot2
-#' @rdname waiver
+#' @rdname splot-waiver
 #' @keywords internal
 waiver <- function() structure(list(), class = "waiver")
 
 #' @param x The object to inquery is a \code{waiver}.
-#' @rdname waiver
+#' @rdname splot-waiver
 #' @keywords internal
 is.waive <- function(x) inherits(x, "waiver")
 
 
-#' @rdname waiver
+#' @rdname splot-waiver
 #' @keywords internal
 "%|W|%" <- function(a, b) {
   if (!is.waive(a)) a else b

README.Rmd

@@ -65,7 +65,7 @@ devtools::install_github("stefanedwards/splot")
 
 
 
-## Usage
+## Axis lines
 
 We can display a limit on the axes range.
 ```{r usage1}
@@ -80,12 +80,33 @@ ggplot(mtcars, aes(x=cyl, y=mpg)) +
 
 We could also show that the x-axis is categorical (or ordinal):
 ```{r brackets_demo}
-ggplot(mtcars, aes(x=as.factor(cyl), y=mpg)) + 
+(p <- ggplot(mtcars, aes(x=as.factor(cyl), y=mpg)) + 
   geom_point(position=position_jitter(width=0.1)) + 
-  coord_flex_cart(bottom=brackets_horisontal(), left=capped_vertical('none')) +
+  coord_flex_cart(bottom=brackets_horisontal(), left=capped_vertical('both')) +
   theme_light() + theme(panel.border=element_blank(), axis.line = element_line())
+)
+```
+
+When capping the axis lines, they are never capped further inwards than the ticks!
+Look up
+
+* `coord_capped_cart`, `coord_capped_flip`
+* `coord_flex_cart`, `coord_flex_flip`, `coord_flex_fixed`
+* `brackets_horisontal`, `brackets_vertical`
+* `capped_horisontal`, `capped_vertical`
+
+## Facets 
+
+Having produced such wonderous axes, it is a pity they are not plotted around 
+all panels when using faceting. 
+We have extended both `facet_grid` and `facet_wrap` to produce axis, ticks, and 
+labels on _all_ panels:
+
+```{r facets}
+p + facet_rep_wrap(~gear, ncol=2, label=label_both)
 ```
 
+They work just like the normal ones; look up `facet_rep_grid` and `facet_rep_wrap`.
 
 ## Legends
 

vignettes/capped-axes.Rmd

@@ -77,7 +77,75 @@ ggplot(dat1, aes(gp, y)) + geom_point(position=position_jitter(width=0.2, height
 
 ## The `coord` objects
 
+ggplot2's Cartesian coordinates systems, `coord_cartesian`, have been extended 
+to allow for flexible specification of how axes are drawn. 
+You've seen them above. 
+The following table summarises the connection between ggplot2's coord functions
+and those of splot!.
+
+ ggplot2          | splot's flexible   | splot's short hand
+------------------|--------------------|--------------------
+`coord_cartesian` | `coord_flex_cart`  | `coord_capped_cart`
+`coord_flip`      | `coord_flex_flip`  | `coord_capped_flip`
+`coord_fixed`     | `coord_flex_fixed` | --
+
+The short hand functions in the table's right column simply are almost identical
+to those in the middle column.
+If one of the side arguments are specified with a character value, the 
+relevant axis drawing function is used. You can however choose to use e.g.
+`brackets_horisontal` in place.
+
+### The axis drawing functions
+
+The functions `capped_horisontal` or `brackets_vertical` returns a function
+that is called when ggplot2 prints the plot. It is called with the arguments
+
+    scale_details, axis, scale, position, theme
+
+and the function should return a grob.
+Some pointers to how it is used can be found in ggplot2's help pages; just run
+`?"ggplot2-ggproto"`. 
+In this package, we use ggplot2 to build the axes, then modify in place the
+return grobs.
+
+### Brackets
+
+The brackets comes in two orientations: 
+`brackets_horisontal` and `brackets_vertical`. 
+If you attempt to use a vertical bracket on a horisontal axis, it will fail with
+a undescriptive error.
+
+The bracket functions accept a `direction` argument, which can be used to control
+which direction the end-points are pointing:
+
+```{r brackets}
+p <- ggplot(mpg, aes(cyl, hwy, colour=class)) +
+  geom_point(position=position_jitter(width=0.3)) +
+  scale_x_continuous(breaks=c(4,5,6,8), sec.axis=dup_axis()) + 
+  scale_y_continuous(sec.axis=dup_axis()) +
+  coord_flex_cart(bottom=brackets_horisontal(), 
+                  top=brackets_horisontal(direction='down'),
+                  left=brackets_vertical(), 
+                  right=brackets_vertical(direction='right')) +
+  my.theme
+p
+```
+
+The look of the brackets are controlled via `theme(axis.ticks)`. 
+The length of the end-point are controlled via the theme 
+`theme(axis.ticks.length)`. If these needs to be specified for each margin,
+use the argument `tick.length`:
+
+```{r}
+p <- ggplot(mpg, aes(cyl, hwy, colour=class)) +
+  geom_point(position=position_jitter(width=0.3)) +
+  coord_flex_cart(bottom=brackets_horisontal(tick.length=unit(0, 'cm')), 
+                  left=brackets_vertical(tick.length = unit(1, 'cm'))) +
+  my.theme
+p
+```
 
+As shown above, using `tick.length=unit(0, 'cm')` results in a flat line.
 
 ## Facets