Skip to contents

Contributing

Source: .github/CONTRIBUTING.md

Contributions to autograph, whether in the form of issue identification, bug fixes, new code or documentation are encouraged and welcome.

Please note that the autograph project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Git

stocnet projects are maintained using the git version control system. A plain-English introduction to git can be found here. I recommend you read this before continuing. A more recent motivation can be found here. It will explain the basics of git version control, committing and repos, pulling and pushing, branching and merging.

Fork

Using git from the command line on your lap- or desktop can be intimidating, but I recommend Fork software for Mac and Windows. This allows mostly visual management of commits, diffs, branches, etc. There are various other git software packages available, but this one is fairly fully featured.

The Github page allows to access the issues assigned to you and check the commits. You can also access the documents in the repository, although this won’t be necessary after you have cloned it on your computer via Fork.

Cloning

Once you have downloaded Fork, the first thing you have to do is to clone the remote repository on your computer. Before cloning, you will be able to choose on which branch you want to work: develop or main.

Pull

This command allows you to pull changes from the remote repository to your local repository on Sourcetree. Make sure you do that before starting working on your files so you have the newest versions. When pulling, make sure you choose master or develop, depending on the branch you decided to work with. Once you pulled, you have now all the new commits and files and you can start working on your assigned tasks. Note that you can access and open the files either from the Finder or from Fork. Some documents might be stored using Large File Storage (LFS) to save space on the repository.

Commit and Push

Once you have made modifications on a file and saved them, it will appear in your commit window. Here you can control one last time your file, write the commit message with the issue reference (see below) and commit. Once your commit is ready, you can push them to the origin/main repository. Note that you can click the “push immediately” box in the commit window if you don’t want to do it in two steps. If you are working on a separate branch, it is important to select this branch when pushing to origin/main.

Branching and CI

  • main is the release branch; develop is the working branch (clone/work on develop).
  • PRs into main trigger prchecks.yml: R CMD check (macOS/Windows/Linux), binary build, codecov, lintr, spell check, a check that vignette articles and tutorials stay in sync, and PR metadata checks (DESCRIPTION version bump, PR title/description conventions).
  • Merges/pushes to main trigger pushrelease.yml: check, auto-bump version tag, GitHub release with binaries, then pkgdown site deploy.

Package architecture

Project overview

autograph is an R package (part of the stocnet ecosystem) providing the visual layer for network analysis: automatic ggplot2/ggraph-based plotting and consistent theming for network data and network-analytic results. It offers three graph-drawing entry points (graphr(), graphs(), grapht()) plus a large family of plot() S3 methods dispatched on result objects from other packages (migraph, netrics, RSiena, ergm, MoNAn, goldfish). Division of labour to keep in mind when adding functions:

  • manynet: network classes/coercion (as_*()) and network-level logical tests (e.g. is_directed(), is_twomode()).
  • netrics: everything analytic — marks, measures, memberships, motifs — at the node, tie, and network level.
  • autograph (this package): drawing graphs and plotting analytic, modelling, or diagnostic results, along with deep (often institutional) theming. All plot methods should live here.
  • migraph: testing and modelling, e.g. QAP/MRQAP and diffusion models.

In terms of style, we are aiming for sensible defaults in terms of user experience. As a ggplot2 object, most everything can be tweaked before or afterwards, but the default presentation should already be aesthetically pleasing, informative, and consistent.

Common commands

This is a standard R package developed with devtools/roxygen2. Run these from an R console with the working directory set to the package root (or via Rscript -e).

There is no non-R build system — no package.json/Makefile. Roxygen is configured with markdown = TRUE; NAMESPACE and all man/*.Rd files are generated — never hand-edit them.

Graph drawing pipeline (graphr()/graphs()/grapht())

graphr() (R/graphr.R) is the single-network entry point and the core of the package. It accepts any manynet-compatible network object and builds a ggplot2/ggraph plot through an internal pipeline of helper functions, each in its own file:

  • graph_layout() (R/graph_layout.R) — resolves the layout algorithm (igraph/ggraph/graphlayouts, or autograph’s own layouts), builds the ggraph layout object, and optionally snaps coordinates to a grid.
  • graph_nodes(), graph_edges(), graph_labels.R, graph_legends.R, graph_aes.R, graph_checks.R — each layer adds/styles one visual component (node aes, edge aes, text labels, legends) onto the ggraph plot, resolving arguments that may be literal values (e.g. node_size = 6) or references to a node/tie attribute name (e.g. node_size = "wealth").
  • Note that users are not expected to call any of these graph_*() functions themselves; exported modularity makes development, debugging, and testing easier.

graphs() (R/graphs.R) calls graphr() per network in a list and arranges the results with patchwork (deliberately chosen over gridExtra/cowplot/ggpubr because it doesn’t interfere with ggplot2 themes — see the comment in R/autograph_utilities.R).

grapht() (R/grapht.R) animates a longitudinal/dynamic network over time using gganimate/gifski.

Custom layout algorithms not provided by igraph/ggraph/graphlayouts live in their own layout_*.R files (layout_configurational.R, layout_grid.R, layout_layered.R, layout_matching.R, layout_partition.R, layout_valence.R) and follow the layout_tbl_graph_*() naming convention.

Plot-method dispatch (plot_*.R)

The rest of the package implements plot.<class> S3 methods so that plot(result) “just works” for objects returned by other stocnet/network packages, without the user needing to know which autograph function to call. Methods are grouped by the kind of result object, not by source package:

File Covers
plot_analysis.R node/tie/network measures, motifs, memberships (node_measure, tie_measure, network_measures, node_member, node_motif, network_motif, matrix)
plot_summaries.R diffusion/learning model summaries (diff_model, diffs_model, learn_model, mnet)
plot_gof.R goodness-of-fit objects (gof.ergm, sienaGOF, gof.stats.monan, autograph’s own ag_gof)
plot_convergence.R, plot_diagnostics.R, plot_tests.R, plot_interp.R model diagnostics, convergence traces, statistical tests, and interpretation plots for netlm/netlogit/ergm etc.
plot_manydata.R goldfish changepoints/outliers and other longitudinal data objects

New plot.* methods must be registered in NAMESPACE via roxygen @method/@export tags — run devtools::document() after adding one. Suggestions for new plot methods are welcome.

Theming

R/theme_set.R implements stocnet_theme() (alias set_stocnet_theme()), which sets an R option (stocnet_theme, default "default") read by every plotting function in the package. Institutional and stylistic palettes (default, bw, crisp, neon, iheid, ethz, uzh, rug, unibe, oxf, unige, cmu, iast, hwu, rainbow) are defined in R/theme_palettes.R and exposed via consistent accessor functions (ag_base(), ag_highlight(), ag_positive(), ag_negative(), ag_qualitative(n), ag_sequential(n), ag_divergent(n), ag_font()) documented together under ag_call. Users can override individual palette colours via options() (e.g. options(snet_highlight = ...)) rather than editing theme code. R/theme_match.R maps a plot/result object to its appropriate theme treatment.

Because autograph re-exports several ggplot2 symbols (see R/reexports_ggplot2.R), loading autograph last in a session is recommended so its plot() methods take precedence over other packages’.

Precooked/vignette data

data/*.rda holds pre-computed example results (ERGM/SAOM GOF, goldfish changepoints/outliers, MoNAn convergence/GOF, migraph diffs/regressions/tests) used in examples, vignettes, and tests, documented in R/data_precooked.R. inst/extdata holds a serialized ergm_res object loaded via load_ergm_res(), deliberately kept out of data/ and serialized rather than stored as a live object because namespace references inside ergm model objects don’t survive a plain save()/reload across package versions.

Dependencies

autograph Depends on manynet (network data structures and coercion) and Imports ggplot2 (>= 4.0.0), ggraph, graphlayouts, igraph, dplyr, and patchwork. ergm and RSiena are listed under Enhances (their plot.* methods are only invoked if those packages are installed and such results are passed in), and gganimate, gifski, ggforce, migraph, and netrics are Suggests-only, so code paths depending on them should guard with requireNamespace() (see the thisRequires() helper in R/autograph_utilities.R) or be skipped gracefully when unavailable.

Tests

tests/testthat/ uses testthat edition 3 with parallel execution (Config/testthat/parallel: true in DESCRIPTION). tests/testthat.R sets stocnet_theme("default") before running the suite so theme state doesn’t leak between runs. Test files are organised by the same grouping as the R/ source files (e.g. test-graphr.R, test-layout_partition.R, test-theme_match.R).

In addition, the test-functional_*.R files implement functional (family-enumerating) testing, mirroring the approach in manynet: layout algorithms, plot.<class> methods, palette accessors, and graphr()’s aesthetic arguments are enumerated automatically from the namespace and run over a fixture grid, so new layouts/methods/palettes are audited without writing new tests. Helpers live in tests/testthat/helper-functional.R. Non-conformant combinations are skipped with a greppable AUDIT [...] message rather than failed, so the audits double as a to-do list locally; CI sets AUTOGRAPH_STRICT_AUDIT: true so the same cases fail there instead. tests/testthat/helper-tutorials.R extracts and evaluates the code chunks of the learnr tutorials in inst/tutorials/, so tutorial code that errors or raises a deprecation warning fails the suite (rendering the tutorials themselves is deliberately not tested).

NEWS.md conventions

NEWS.md groups each version’s changes under ## headings that mirror the website function overview (pkgdown/_pkgdown.yml reference: titles). Lead with ## Package (package-wide/website/infrastructure changes), then the function families in overview order: ## Graphing (graphr/graphs/grapht and internal functions, ## Plotting (all plot.* methods), ## Layouts, ## Theming. Put ## Tutorials and ## Data near the end. Each heading appears at most once per version.

Start each bullet with a verb matching the change type:

  • Added ... — new functionality
  • Fixed ... — bug fixes; if it relates to a GitHub issue, suffix with (closing #123)
  • Renamed ... to ... — function or data name migrations
  • Improved ... — functional updates to existing behaviour
  • Updated ... — documentation changes

If a cited GitHub issue was not authored by @jhollway, thank the author with an @-tag in the bullet. Cluster related changes (e.g. several fixes to the same function, or sub-points of one feature) as indented sub-bullets under a lead bullet, to improve readability.