Conversation
…sage - add regression tests for spread/connector assignment semantics - clarify in docs that spread/align return updated objects (no in-place mutation) - document that connectGrob uses coordinates from passed objects - modernize examples to flowchart() + pipe-style align/spread/connect API - add interactive page pauses between multi-plot example sections - regenerate Rd docs and add NEWS entries for 3.3.1 Fixed issue #68
insert() called coords() on its neighbours, which failed with a confusing "Must inherit from class 'box', but has class 'list'" error when the neighbour was a grouped stage (a list of arm boxes) — so a label could be placed above a split but not after it. Resolve neighbours via prConvert2Coords() so insert() uses the stage's merged bounding box. Add phaseLabel(), a one-call-per-stage helper for the CONSORT phase labels the issue asks for (Allocation, Follow-up, Analysis): it centres a label between a stage's arms, sits it slightly above with a small corner overlap, and draws it on top. The width adapts to the stage — the central gap for two arms, a full-width banner for three or more — and can be set via width=. Add the underlying overlay primitive insert(..., on_top = TRUE): the box is drawn after the other boxes and connections regardless of its list position, with the marker preserved through move()/align(); print.Gmisc_list_of_boxes draws on-top boxes in a final pass. Update the grid-based flowchart vignette with a phaseLabel example, add tests, and bump to 3.4.0. Fixes #72
…ormatting - Added a custom wrapper function `get_stats()` for consistent statistics and formatting. - Updated the example to include additional variables (hp, cyl) and group them using `mergeDesc()`. - Adjusted the table caption and footer for clarity. - Changed the image width for better presentation.
There was a problem hiding this comment.
Pull request overview
This PR prepares Gmisc v3.4.0 with new flowchart overlay capabilities, most notably a phaseLabel() helper for CONSORT-style phase banners, alongside improvements to insert()/printing so certain boxes can be rendered above others and above connectors. It also refreshes documentation, examples, README content, and minor package/CI infrastructure.
Changes:
- Added
phaseLabel()(S3) to place CONSORT phase headings above a flowchart stage, using an overlay (“draw on top”) mechanism. - Enhanced
insert()with anon_topflag and improved handling of insertion between grouped (list) stages; updatedprint.Gmisc_list_of_boxes()to draw “on top” boxes last. - Updated vignette, man pages, examples, README, tests, version/dependencies, and CI workflow configuration.
Reviewed changes
Copilot reviewed 25 out of 40 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| vignettes/Grid-based_flowcharts.Rmd | Adds vignette section demonstrating CONSORT phase labels and overlay positioning. |
| tests/testthat/test-s3-api-design.R | Adds tests for grouped-stage insertion, on_top persistence, and phaseLabel() geometry/width behavior. |
| tests/testthat/test-connectGrob-spread-assignment.R | Adds tests clarifying spread/align return updated objects (no in-place mutation) and connector usage. |
| README.Rmd | Introduces a source README with expanded examples (flowcharts, Table 1, Transition), generating README.md assets. |
| README.md | Updates rendered README to match README.Rmd content and include generated figures. |
| R/boxGrobs_spread.R | Documents that spread helpers return updated boxes and do not mutate existing bindings. |
| R/boxGrobs_s3_phaseLabel.R | Implements new phaseLabel() S3 generic and methods. |
| R/boxGrobs_s3_append.R | Extends insert() with on_top and improves grouped-neighbor coordinate resolution. |
| R/boxGrobs_print.Gmisc_list_of_boxes.R | Updates print order so draw_on_top boxes render after connections. |
| R/boxGrobs_connect.R | Adds documentation clarifying connector coordinate sourcing when using spread/align. |
| NEWS.md | Adds 3.4.0 release notes describing phaseLabel(), insert(on_top=TRUE), and doc/example changes. |
| NAMESPACE | Exports phaseLabel() and registers its S3 methods. |
| man/spread.Rd | Updates spread documentation and examples to emphasize pipe-style flowchart usage and non-mutation. |
| man/print.Gmisc_list_of_boxes.Rd | Documents new “draw on top last” print behavior. |
| man/prGetBoxAxisDefaults.Rd | Fixes duplicated title text. |
| man/phaseLabel.Rd | Adds generated documentation for phaseLabel(). |
| man/moveBox.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/move.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/insert.Rd | Documents new on_top parameter and adds phaseLabel() cross-reference. |
| man/flowchart.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/equalizeWidths.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/distance.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/coords.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/connect.Rd | Expands examples (pipe-style connect()) and documents spread/align coordination guidance. |
| man/boxShapes.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/boxPropGrob.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/boxHeaderGrob.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/box.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/append.Rd | Adds phaseLabel() to flowchart-related “See also” section. |
| man/align.Rd | Updates examples to pipe-style align() usage and adds phaseLabel() cross-reference. |
| inst/examples/spreadBox_ex.R | Updates example to pipe-style `flowchart() |
| inst/examples/connectGrob_example.R | Updates example to pipe-style connect() usage and adds interactive paging. |
| inst/examples/alignBox_ex.R | Updates example to pipe-style align() usage. |
| DESCRIPTION | Bumps version to 3.4.0 and adds webshot2 to Suggests. |
| .Rbuildignore | Ignores README.Rmd in package builds. |
| .github/workflows/ci.yaml | Fixes CI by removing unsupported max_errors from devtools::check(). |
Files not reviewed (11)
- man/align.Rd: Language not supported
- man/append.Rd: Language not supported
- man/box.Rd: Language not supported
- man/boxHeaderGrob.Rd: Language not supported
- man/boxPropGrob.Rd: Language not supported
- man/boxShapes.Rd: Language not supported
- man/connect.Rd: Language not supported
- man/coords.Rd: Language not supported
- man/distance.Rd: Language not supported
- man/equalizeWidths.Rd: Language not supported
- man/flowchart.Rd: Language not supported
Comment on lines
+94
to
+100
| x1 <- to_npc_x(coords(stage[[1]])$x) | ||
| x2 <- to_npc_x(coords(stage[[2]])$x) | ||
| left_arm <- if (x1 <= x2) stage[[1]] else stage[[2]] | ||
| right_arm <- if (x1 <= x2) stage[[2]] else stage[[1]] | ||
| gap <- to_npc_x(coords(right_arm)$left) - to_npc_x(coords(left_arm)$right) | ||
| arm_w <- to_npc_w(coords(left_arm)$width) | ||
| target_w <- max(gap + 2 * overlap * arm_w, auto_w) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces version 3.4.0 of the
Gmiscpackage, focusing on enhancing flowchart functionality, particularly with the addition of a newphaseLabel()helper for CONSORT-style phase labeling, improvements to box insertion and overlay mechanisms, and better documentation for flowchart operations. It also includes minor package infrastructure updates.Key highlights:
phaseLabel()for easily overlaying stage labels in flowcharts.insert()function to support drawing boxes on top of others.Most important changes:
Flowchart Overlay and Labeling Enhancements
phaseLabel()function, which allows users to add a CONSORT-style phase label (e.g., "Allocation", "Follow-up") above a flowchart stage. The label is automatically centered and drawn on top of other elements, with adaptive width and overlap options. S3 methods and documentation/examples are included. (R/boxGrobs_s3_phaseLabel.R,NAMESPACE,NEWS.md) [1] [2] [3] [4]insert()function for flowchart box lists to accept anon_topargument, marking inserted boxes to be drawn above others and preserving this overlay status through subsequent operations. This underpins the new phase label overlay mechanism. (R/boxGrobs_s3_append.R,NEWS.md) [1] [2] [3] [4]Drawing and Rendering Logic
print.Gmisc_list_of_boxes()method to ensure boxes marked with thedraw_on_topattribute (e.g., viainsert(..., on_top = TRUE)) are always drawn last, keeping them visible above other boxes and connections. (R/boxGrobs_print.Gmisc_list_of_boxes.R) [1] [2] [3]Documentation and Example Improvements
connectGrob(),spreadVertical(), andspreadHorizontal()to emphasize that these functions return updated box objects and do not mutate originals. Updated flowchart examples to use the recommended pipe (|>) style and improved interactive example ergonomics. (R/boxGrobs_connect.R,R/boxGrobs_spread.R,NEWS.md) [1] [2] [3]Package Infrastructure and Dependency Updates
webshot2toSuggests. Updated.Rbuildignoreto ignoreREADME.Rmd. (DESCRIPTION,.Rbuildignore) [1] [2] [3]max_errorsparameter fromdevtools::check(). (.github/workflows/ci.yaml)