auxiliary/docsfordevelopers/documentation.md

In andreashandel/modeldiagram: Easy Creation of ggplot2 Based Figures of Flow Diagrams

Documentation for working on the package

Package organization

Folder structure

• /auxiliary contains folders with related resources that are not used/needed for the package use/build but are useful (to the package authors) for maintenance/development/advertising/tracking of the package
• /doc contains the built versions of the vignette and related files. Rebuild with devtools::build_vignettes(). Don't edit manually.
• /docs contains the package website created by the pkgdown package. Rebuild with pkgdown::build_site(). Don't edit manually.
• /man contains the documentation for all public functions, automatically generated by roxygen. Do not edit.
• /Meta contains some files used/created by devtools::build_vignettes(). Don't edit manually.
• /pkgdown contains extra files for styling of pkgdown created website. Edit to change layout of package website.
• /R contains the main R functions, i.e. the simulators and various helper functions. See more details below.
• /tests contains code/unit tests, done with the testthat package. Add tests as new functionality is added.
• /vignettes contains the vignette - this is copied to /inst/doc during package building. edits should be done to the file in the /vignettes folder, not the /inst/doc folder.

Functions/files in the R folder

The main functions that are exposed to a user are the following:

• prepare_diagram takes as input a model list and creates the data frames that form the input for the diagram generation.
• update_diagram updates the styling
• make_diagram takes as input a list of data frames as created by prepare_diagram and returns a ggplot2 object containing the model diagram.
• write_diagram takes the model list and writes the full ggplot2 code required to generate the model to a file. The resulting code is fully stand-alone.
• convert_from_modelbuilder takes a modelbuilder model object and turns it into a list object needed for this package.

The following are helper functions that are used internally but not exposed to the user:

• add_plus_signs - explicitly adds leading + signs to flows, e.g. turns b*S*I into +b*S*I. Used in prepare_diagram.

• calc_origin - a function from StackOverflow (link in function documentation) that locates the midpoint along a curved segment. Used in prepare_diagram for curved edges.

• calc_control_points - a function from StackOverflow (link in function documentation) that defines control points for interpolating a curved segment between two end points. Used in prepare_diagram for curved edges.

• check_model_list - conducts basic checks on the model_list argument for prepare_diagram. Used in prepare_diagram.

• check_node_matrix - makes sure that all the variables listed in the nodes matrix also show up in the model_list object. Used in prepare_diagram.

• convert_from_modelbuilder - converts a modelbuilder object to the model_list structure needed for flowdiagramr. Could eventually be user facing and is currently not used.

• fix_arrow_pos - DEPRECATED. Used to avoid overlap of arrows.

• get_code - returns the core ggplot2 code needed to make a diagram. Used in make_diagram.

• get_vars_pars - extracts the variables and parameters from a flow. Assumes that variables start with UPPERCASE letters (LETTERS) and parameters are lowercase. Used in prepare_diagram.

• make_vdf_angled - adjusts positions of the vertical flows (typically, births and deaths) to make them enter and exit at a 45 degree angle. Used in prepare_diagram.

• move_interaction_label - used in make_diagram to move the interaction label back to the main flow if the user specifies that no interaction arrows are drawn. Used in make_diagram.

• recycle_values - recycles values of length m to length n. Used in make_diagram to match number of styles (colors, linetypes, etc.) to number needed.

• remove_na_rows - removes rows from all edge and node data frames that do not have location information. These are typically placeholder nodes and edges needed to define the locations of other elements but are not plotted themselves. Used in prepare_diagram.

• set_curvature - defines the amount of curvature applied to curved arrows based on their type (interaction, feedback, other) and location (spanning one or two nodes). Used in prepare_diagram.

• set_node_to_na - sets location values to NA if the to/from nodes in the edge data frame is not present in the nodes data frame. This is part of a clean up step to remove auxiliary information that was used for location information but does not need to be plotted. Used in prepare_diagram.

• update_interactions - sets the interaction column to TRUE if the direct_interaction is TRUE and then removes the direct_interaction column that is no longer necessary. Used in prepare_diagram.

• update_tofroms - updates the to/from columns in the edges data frames to be the character label for the to/from variable rather than the numeric id.

Information for package development

To work on package (through RStudio):

• Fork and clone package.
• Load project in RStudio. Edit files as needed.
• Use devtools/roxygen to build and document the package. Either use RStudio's functionality (or command line) to test/build packages using devtools. The package follows Hadley's recommendations and workflow described here: http://r-pkgs.had.co.nz/
• Optionally, use RStudio tie-in with github to sync project to github (the 'git' tab). Alternatively, use your favorite git client.
• Rtools needs to be installed (on Windows).

Dependency packages

All libraries/packages needed to allow the package to run should be loaded via the DESCRIPTION file and not in separate R files. See that file for dependencies.

Additional packages are needed for development (but not use) of the package. Those are listed in the suggests section of the DESCRIPTION file.

Package logo

According to pkgdown, logo should be includes as described here: https://pkgdown.r-lib.org/reference/build_home.html#package-logo

To update R documentation and vignette

• Edit documentation inside R functions.
• Build documentation with More/Document or devtools::document()
• Edit vignette inside the /vignettes folder.
• To build new vignette, run devtools::build_vignettes()
• To update the pkgdown website, run pkgdown::build_site()

To build the package

• in RStudio, use the functions in the 'build' tab to test and build the package.
• Run clean and rebuild, then build and reload using menu, or devtools::load_all()
• Run the check, fix any errors

To-do for CRAN release

• "by hand" edit the DESCRIPTION file to make sure it's up to date
• update news.md and cran-comments.md
• run processing-script to Re-build documentation, vignettes and copy latest versions of simulator functions - see above
• Run check and make sure no problems occur
• Sync everything to github
• Run devtools::check_rhub(), devtools::check_win_release() and devtools::check_win_devel()
• Do a test run of devtools::release() - fix any remaining issues, then re-run and release

Trouble-shooting

• If you get the 'can't find qpdf error' during build, try this (on windows): https://stackoverflow.com/questions/41570633/how-to-build-qpdf-on-windows

andreashandel/modeldiagram documentation built on July 31, 2023, 10:05 a.m.