Added optional plot title; option for single column main and signed c…

…ounts; nudge_venndir_label() to adjust set label positions.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: venndir
 Title: Directional Venn diagrams
-Version: 0.0.40.900
+Version: 0.0.41.900
 Authors@R: c(
     person(given="James M.",
        family="Ward",

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(plot,JamPolygon)
 export(add_orientation_JamPolygon)
 export(area_JamPolygon)
 export(bbox_JamPolygon)
@@ -38,7 +39,6 @@ export(nearest_point_JamPolygon)
 export(nudge_JamPolygon)
 export(nudge_venndir_label)
 export(overlaplist2setlist)
-export(plot.JamPolygon)
 export(point_in_JamPolygon)
 export(polyclip_to_JamPolygon)
 export(polygon_circles)

NEWS.md

@@ -1,3 +1,52 @@
+# venndir 0.0.41.900
+
+## overall
+
+* Add plot titles!
+* Arrange signed counts in single column, under main counts.
+* Outside Venn labels default slightly toward the top, rather than the sides.
+* `nudge_venndir_label()` is convenient for moving inside or outside labels.
+
+## changes to existing functions
+
+* `Venndir` S4 object changes.
+
+   * New slot name `"metadata"` to store miscellaneous settings.
+   All efforts are made to accept older Venndir objects without
+   this slot available.
+
+* `venndir()`
+
+   * New argument `main` to draw a plot title. It uses `gridtext` to
+   enable custom Markdown font options.
+   When provided, `main` is also stored in `Venndir@metadata$main`
+   for persistence.
+   * New argument `template="wide"` is used to arrange count and signed
+   count labels together:
+   `"wide"` places them side-by-side, `"tall"` places them in one column.
+   When provided, `template` is also stored in `Venndir@metadata$template`
+   for persistence.
+   * New argument `center` passed to `label_outside_JamPolygon()`.
+   The default `center=c(0, -0.15)` tends to place labels at the top
+   rather than the left/right sides by default.
+   The default use case is improved.
+
+* `render_venndir()`
+
+   * Now properly converts set names with `"\n"` to use `"<br>"` as
+   originally intended, so it "just works".
+   * New arguments `main` and `template` as above, except that when
+   no argument is defined, it will use `Venndir@metadata$template`
+   or `Venndir@metadata$main` if defined.
+
+* `nudge_venndir_label()`
+
+   * New argument `offset_list` to define a list of offsets to one or more
+   sets, where set is defined by `names(offset_list)`.
+   * New arguments `align_x`,`align_y` to apply uniform alignment of labels
+   to the top/bottom/left/right of a set of labels. Useful to ensure
+   labels are the same y-position and not slightly different heights.
+
 # venndir 0.0.40.900
 
 * Updated label positioning logic, silenced some unintended verbose output

R/Venndir-class.R

@@ -21,7 +21,20 @@ check_Venndir <- function
    # all(c("jp", "jps", "label_df", "setlist") %in% slotNames(object))
    is_valid <- (c("jps", "label_df", "setlist") %in% slotNames(object))
    # jamba::printDebug("is_valid:", is_valid);
-   all(is_valid)
+
+   # new practical validation
+   vnames <- object@jps@polygons$venn_name;
+   vsets <- unique(unlist(strsplit(vnames, "&")))
+   onames <- object@label_df$overlap_set;
+   osets <- unique(unlist(strsplit(onames, "&")))
+   # validate venn contents
+   is_valid_venn <- (
+      all(vsets %in% names(object@setlist)) &&
+      all(osets %in% names(object@setlist)) &&
+      all(length(vnames) == 0 ||
+         object@jps@polygons$venn_name %in% object@label_df$overlap_set)
+   )
+   all(is_valid) && all(is_valid_venn)
 }
 
 #' Venndir class
@@ -103,6 +116,8 @@ check_Venndir <- function
 #'    Previously this data could be inferred from `label_df` which was
 #'    tedious, and required column `"item"` which is optional.
 #'    That said, `setlist` can be an empty `list()`.
+#' * **metadata**: `list` with optional metadata, intended for future
+#'    expansion, such as plot title.
 #' 
 #' @family JamPolygon
 #' 
@@ -111,20 +126,22 @@ setClass("Venndir",
       # jp="JamPolygon",
       jps="JamPolygon",
       label_df="data.frame",
-      setlist="list"
+      setlist="list",
+      metadata="list"
    ),
    prototype=prototype(
       jps=NULL,
       label_df=data.frame(),
-      setlist=list()
+      setlist=list(),
+      metadata=list()
    ),
    validity=check_Venndir
 );
 
 
-#' Plot JamPolygon object
+#' Plot Venndir object
 #' 
-#' Plot JamPolygon object
+#' Plot Venndir object
 #' 
 #' @returns `Venndir` object, invisibly.
 #' 

R/venndir-base-polyclip.R

@@ -47,6 +47,11 @@
 #'    * _i_tems: "i" only, by default hidden. When enabled, item labels
 #'    defined by `show_items` are spread across the specific Venn overlap
 #'    region.
+#' @param main `character` string used as a plot title, default NULL
+#'    will render no title. When provided, it is rendered using
+#'    `gridtext::richtext_grob()` which enables some Markdown-style
+#'    formatting. The title is stored in `venndir@metadata$title`
+#'    for persistence.
 #' @param return_items `logical` (default TRUE) indicating whether to
 #'    return items in the overlap data. When `FALSE` item labels also
 #'    cannot be displayed in the figure.
@@ -91,6 +96,16 @@
 #'    * `"box"` adds a dark border around the label region
 #' @param label_preset `character` deprecated in favor of `show_labels`.
 #'    This argument is passed to `venndir_label_style()`.
+#' @param template `character` (default "wide") describing the default
+#'    layout for counts and signed counts. The value is stored in
+#'    `venndir@metadata$template` for persistence.
+#'    * `"wide"` - main counts on the left, right-justified; signed counts
+#'    on the right, left-justified.
+#'    This option is preferred for small numbers, and less-crowded diagrams.
+#'    * `"tall"` - main counts, center-justified; signed counts below main
+#'    counts, center-justified.
+#'    This option is recommended for large numbers (where there are 1000
+#'    or more items in a single overlap region), or for crowded diagrams.
 #' @param unicode `logical` (default TRUE) indicating whether to 
 #'    display Unicode arrows for signed overlaps. Passed to
 #'    `curate_venn_labels()`.
@@ -141,6 +156,16 @@
 #' @param r `numeric` radius in units `"mm"` used for rounded
 #'    rectangle corners for labels. Only visible when `label_preset`
 #'    includes a background fill ("lite", "shaded", "fill"), or "box".
+#' @param center `numeric` coordinates relative to the plot bounding box,
+#'    default `c(0, -0.15)` uses a center point in the middle (x=0)
+#'    and slightly down (y=-0.15) from the plot center.
+#'    It is used to place labels outside the diagram.
+#'    In short, labels are placed by drawing a line from this center point,
+#'    outward through the Venn overlap region to be labeled. The
+#'    label is positioned outside the polygon region by `segment_distance`.
+#'    The default `c(0, -0.15)` ensures that labels tend to be at the
+#'    top of the plot, and not on the left/right side of the plot.
+#'    This argument is passed along to `label_outside_JamPolygon()`.
 #' @param segment_distance `numeric` value indicating the distance
 #'    between outside labels and the outer edge of the Venn diaram region.
 #'    Larger values place labels farther away, while also shrinking the
@@ -229,6 +254,7 @@ venndir <- function
  legend_labels=NULL,
  proportional=FALSE,
  show_labels="Ncs",
+ main=NULL,
  return_items=TRUE,
  show_items=c(NA,
     "none",
@@ -250,6 +276,8 @@ venndir <- function
     "lite",
     "lite_box"),
  label_preset="none",
+ template=c("wide",
+    "tall"),
  unicode=TRUE,
  big.mark=",",
  curate_df=NULL,
@@ -263,6 +291,7 @@ venndir <- function
  sign_count_delim=": ",
  padding=c(3, 2),
  r=2,
+ center=c(0, -0.15),
  segment_distance=0.1,
  sep="&",
  do_plot=TRUE,
@@ -282,6 +311,7 @@ venndir <- function
 
    overlap_type <- match.arg(overlap_type);
    item_style <- match.arg(item_style);
+   template <- match.arg(template);
 
    # show_set <- match.arg(show_set);
    show_set <- "main";
@@ -589,6 +619,7 @@ venndir <- function
          jp=venn_jps[use_whichset, ],
          which_jp=seq_along(use_whichset),
          distance=segment_distance,
+         center=center,
          # center_method="label",
          verbose=verbose,
          buffer=-0.9,
@@ -887,8 +918,9 @@ venndir <- function
    vo <- new("Venndir",
       jps=venn_jps,
       label_df=label_df,
-      setlist=setlist)
-
+      setlist=setlist,
+      metadata=list(template=template))
+
    ## venndir_label_style()
    #
    # Todo: use real x_outside
@@ -964,7 +996,7 @@ venndir <- function
    #    jps=venn_jps,
    #    label_df=label_df,
    #    setlist=setlist)
-   
+
    # Optionally plot
    if (do_plot) {
       gg <- render_venndir(

R/venndir-label-outside-jp.R

@@ -118,30 +118,37 @@ label_outside_JamPolygon <- function
 
    # get center
    set.seed(seed);
-   if (length(center) != 2) {
-      if ("bbox" %in% center_method || length(which_jp) == 1) {
-         center <- matrix(ncol=2,
-            rowMeans(jpbox)) + (rnorm(2) / 1000);
-      } else if ("label" %in% center_method) {
-         # use mean of label positions
-         if (all(c("label_x", "label_y") %in% colnames(jp))) {
-            center <- cbind(
-               x=mean(range(jp@polygons$label_x[which_jp], na.rm=TRUE)),
-               y=mean(range(jp@polygons$label_y[which_jp], na.rm=TRUE)))
-         } else {
-            label_xy <- labelr_JamPolygon(jp[which_jp, ]);
-            # average from range of labels
-            # center <- cbind(
-            #    x=mean(range(label_xy[,1], na.rm=TRUE)),
-            #    y=mean(range(label_xy[,2], na.rm=TRUE)))
-            # average from all actual labels
-            center <- cbind(
-               x=mean(label_xy[,1], na.rm=TRUE),
-               y=mean(label_xy[,2], na.rm=TRUE))
-         }
+   # calculate plot center
+   if ("bbox" %in% center_method || length(which_jp) == 1) {
+      new_center <- matrix(ncol=2,
+         rowMeans(jpbox)) + (rnorm(2) / 1000);
+   } else if ("label" %in% center_method) {
+      # use mean of label positions
+      if (all(c("label_x", "label_y") %in% colnames(jp))) {
+         new_center <- cbind(
+            x=mean(range(jp@polygons$label_x[which_jp], na.rm=TRUE)),
+            y=mean(range(jp@polygons$label_y[which_jp], na.rm=TRUE)))
+      } else {
+         label_xy <- labelr_JamPolygon(jp[which_jp, ]);
+         # average from range of labels
+         # center <- cbind(
+         #    x=mean(range(label_xy[,1], na.rm=TRUE)),
+         #    y=mean(range(label_xy[,2], na.rm=TRUE)))
+         # average from all actual labels
+         new_center <- cbind(
+            x=mean(label_xy[,1], na.rm=TRUE),
+            y=mean(label_xy[,2], na.rm=TRUE))
+      }
+   }
+   if (length(center) == 2) {
+      # relative adjustment
+      if (TRUE %in% relative) {
+         center[1] <- diff(jpbox["x", ]) * center[1];
+         center[2] <- diff(jpbox["x", ]) * center[2];
       }
+      center <- center + new_center;
    } else {
-      center <- matrix(ncol=2, head(center, 2));
+      center <- new_center
    }
    colnames(center) <- c("x", "y");
    # jamba::printDebug("center:");print(center);# debug