Reduce the wall of text on startup?

[krivit]

Quoth @martinamorris,

Honestly, we need to rationalize this now. Here is the current wall for ergm:

Copyright (c) 2021, Mark S. Handcock, University of California -- Los Angeles
                    David R. Hunter, Penn State University
                    Carter T. Butts, University of California -- Irvine
                    Steven M. Goodreau, University of Washington
                    Pavel N. Krivitsky, UNSW Sydney
                    Martina Morris, University of Washington
                    with contributions from
                    Li Wang
                    Kirk Li, University of Washington
                    Skye Bender-deMoll, University of Washington
                    Chad Klumb
                    Michal Bojanowski, Kozminski University
                    Ben Bolker
                    Christian Schmid, Penn State University

There is no other package I have ever used in R that does this. And with JoSS we have the venue for ensuring that packages are publicized and cited properly.

Some of the folks listed under contributions have made foundational changes to the code. Others not so much.

So, it's both embarrassing and misleading, whatever the intent.

The "standard" startup message is implemented here:

statnet.common/R/startup.utilities.R

Lines 28 to 147 in 4347e20

	#' Construct a "standard" startup message to be printed when the package is
	#' loaded.
	#'
	#' This function uses information returned by [packageDescription()]
	#' to construct a standard package startup message according to the
	#' policy of the Statnet Project, including printing the contributors'
	#' institutional affiliations. See below for details on how it is
	#' detected.
	#'
	#' To determine the institutional affiliation,
	#' `statnetStartupMessage()` first looks for an `affil` element in the
	#' `comment` list. For example,
	#' ```
	#' person("Albus Percival Wulfric Brian", "Dumbledore", role=c("hdm"),
	#' email="apwb.dumbledore@hogwarts.ac.uk",
	#' comment=c(ORCID="0123-4567-8910-1112",
	#' affil="Hogwarts School of Witchcraft and Wizardry"))
	#' ```
	#' will copy the `affil` value. If it were not there, it would extract
	#' the domain `hogwarts.ac.uk` and attempt to find it on the list of
	#' institutions.
	#'
	#' Note that the e-mail mechanism is deprecated and may be removed in
	#' a future version.
	#'
	#' @param pkgname Name of the package whose information is used.
	#' @param friends This argument is required, but will only be interpreted if
	#' the Statnet Project policy makes use of "friendly" package information.
	#'
	#' A character vector of names of packages whose attribution information
	#' incorporates the attribution information of this package, or `TRUE`.
	#' (This may, in the future, lead the package to suppress its own startup
	#' message when loaded by a "friendly" package.)
	#'
	#' If `TRUE`, the package considers all other packages "friendly". (This
	#' may, in the future, lead the package to suppress its own startup message
	#' when loaded by another package, but print it when loaded directly by the
	#' user.)
	#' @param nofriends This argument controls the startup message if the Statnet
	#' Project policy does not make use of "friendly" package information but does
	#' make use of whether or not the package is being loaded directly or as a
	#' dependency.
	#'
	#' If `TRUE`, the package is willing to suppress its startup message if
	#' loaded as a dependency. If `FALSE`, it is not.
	#' @return A string containing the startup message, to be passed to the
	#' [packageStartupMessage()] call or `NULL`, if policy
	#' prescribes printing default startup message. (Thus, if
	#' [statnetStartupMessage()] returns `NULL`, the calling package should
	#' not call [packageStartupMessage()] at all.)
	#'
	#' Note that arguments to `friends` and `nofriends` are merely
	#' requests, to be interpreted (or ignored) by the `statnetStartupMessage()`
	#' according to the Statnet Project policy.
	#' @seealso [packageDescription()], [packageStartupMessage()]
	#' @keywords utilities
	#' @examples
	#'
	#' \dontrun{
	#' .onAttach <- function(lib, pkg){
	#' sm <- statnetStartupMessage("ergm", friends=c("statnet","ergm.count","tergm"), nofriends=FALSE)
	#' if(!is.null(sm)) packageStartupMessage(sm)
	#' }
	#' }
	#' @export
	statnetStartupMessage <- function(pkgname, friends, nofriends){
	INST_MAP <- list(washington.edu="University of Washington",
	uw.edu="University of Washington",
	psu.edu="Penn State University",
	uci.edu="University of California -- Irvine",
	ucla.edu="University of California -- Los Angeles",
	nyu.edu="New York University",
	murdoch.edu.au="Murdoch University",
	uow.edu.au="University of Wollongong",
	unsw.edu.au="UNSW Sydney",
	kozminski.edu.pl="Kozminski University",
	uw.edu.pl="University of Warsaw"
	)
	STATNET.ORG_MAP <- list(pavel = "unsw.edu.au")
	# Note that all options are ignored at this time, and the "wall of
	# text" is displayed unconditionally.
	desc <- utils::packageDescription(pkgname)
	pns <- eval(parse(text=desc$`Authors@R`))
	# The gsub is necessary because R CMD build can put line breaks in all sorts of fun places.
	pnnames <- gsub("[\n ]+", " ", format(pns, include=c("given","family")))
	# Find the institution associated with the domain of the specific e-mail message.
	find.inst <- function(email, map){
	if(is.null(email)) return(NULL)
	if(endsWith(email, "@statnet.org")) email <- paste0("@",STATNET.ORG_MAP[[gsub("@.*","",email)]])
	insts <- which(sapply(names(map),
	function(inst){
	instre <- paste('[@.]',gsub('.','\\.',inst,fixed=TRUE),sep='')
	grepl(instre, email)
	}
	))
	if(length(insts)) map[[insts]]
	else NULL
	}
	pninsts <- sapply(pns, function(pn) NVL(as.list(pn$comment)$affil, find.inst(pn$email, INST_MAP),""))
	authors <- sapply(pns, function(pn) "aut" %in% pn$role)
	pnlines <- ifelse(pninsts=="", pnnames, paste(pnnames,pninsts, sep=", "))
	copylist <- paste("Copyright (c) ",substr(desc$Date,1,4),", ",sep="")
	copylist <- paste(copylist, pnlines[authors][1L],"\n",
	paste(
	paste(rep(" ",nchar(copylist)),collapse=""),
	c(pnlines[authors][-1],if(sum(!authors)) "with contributions from",pnlines[!authors]),sep="",collapse="\n"),
	sep="")
	paste("\n",desc$Package,": version ", desc$Version, ', created on ', desc$Date, '\n',copylist,"\n",
	'Based on "statnet" project software (statnet.org).\n',
	'For license and citation information see statnet.org/attribution\n',
	'or type citation("',desc$Package,'").\n', sep="")
	}

So, if we wanted to change it everywhere, we only need to change it in one place.

What changes would you like to make? @handcock, @drh20drh20, @CarterButts, @martinamorris, @skyebend? (I am pinging Statnet Commons EC members here, but everybody feel free to chime in.)

If you wish to add something, but prefer not to provide public feedback, please e-mail me.

[drh20drh20]

I strongly favor doing away with WOT. Perhaps as a starting point for this discussion we could start with something simple like:

Copyright (c) 2021.  Please cite statnet packages when you use them for data analysis.
Type citation(package="XXX") for information on citing package XXX.

Perhaps there's even a clever way to replace XXX by whatever package the user loaded.

[sgoodreau]

100% agree, as in all previous rounds of this discussion.

[martinamorris]

Possible shortened form:

package name, version, copyright XXXX the Statnet Development Team
For citation information type citation("pkgname")
Please report bugs and feature requests on our GitHub repository: github.com/statnet/repo.name

[handcock]

I like simple and the single cite of "Statnet Development Team".

The only suggestion was a change to:
"For citation information, type citation("pkgname")

[krivit]

I don't see a point in the copyright statement, but maybe a reference to statnet_help and news?

Package {name} {version}, released {date} by Statnet Development Team.
Type news(package="{name}") for major changes, citation("{name}") for citing. Subscribe to statnet_help@uw.edu for help and announcements. Feature requests and bug reports can be made at https://github.com/statnet/{name} .

For ergm, and wrapped to 80ish characters, it's something like this:

Package ergm 4.0.0, released 2021-06-01 by Statnet Development Team.
Type news(package="ergm") for major changes, citation("ergm") for citing.
Subscribe to statnet_help@uw.edu for help and announcements. Feature
requests and bug reports can be made at https://github.com/statnet/ergm .

[martinamorris]

It's a bit dense. Maybe instead of Subscribe... we should just point them to our website: For more info, go to statnet.org (or http://statnet.org).

And a couple of text tweaks to:

Package ergm 4.0.0, released 2021-06-01 by Statnet Development Team.
Type news(package="ergm") for version changes and citation("ergm") for
the full citation.  For more information, please go to statnet.org.

[krivit]

That makes sense. Perhaps:

Package ergm 4.0.0, released 2021-06-01 by Statnet Development Team.
Type news(package="ergm") for version changes and citation("ergm") for the full
citation.  For help, support, and other information, go to https://statnet.org .

to indicate what other information. For ergm, that would fit into 3 lines, though for networkDynamic it might take 4.

[martinamorris]

Help and support seem similar, so how about "help, bug reports, and other info..."

[CarterButts]

My views on the impact of such changes on citations, and on the relative value of citations to aesthetics, are well-known. But given that we seem to be moving to a model in which we have a much broader and more fluid development consortium, crediting the Statnet Development Team does make sense.

[krivit]

Hmm... One compromise might be to take just the package authors and only list their family names. E.g.,

Package ergm 4.0.0, released 2021-06-01 by Handcock, Hunter, Goodreau,
Krivitsky, Morris, and others, part of the Statnet Project.
Type news(package="ergm") for version changes and citation("ergm") for the full
citation.  For help, support, and other information, go to https://statnet.org .

[krivit]

Or, more compactly,

ergm 4.0.0 (2021-06-01) by Handcock, Hunter, Goodreau, Krivitsky, Morris, and
others, part of the Statnet Project.
Type news(package="ergm") for version changes and citation("ergm") for the full
citation.  For help, support, and other information, go to https://statnet.org .

[drh20drh20]

I'd posit that the value of citations to the specific people named above are no longer as valuable as recognition of the statnet effort as a whole, with the possible exception of Pavel. Please correct me if I'm mistaken, but personally at least I'd be happy to further compactify by eliminating the list of names. I'd also be happy if there were some way, whether upon loading or elsewhere, to feature Pavel's name as the most prominent and active current developer. (Such info could potentially be relevant to users.)

[martinamorris]

I'd vote "no" on names. But I agree with Dave that we need to feature Pavel to reflect the fact that the packages currently depend primarily on his contributions and release efforts.

The packages have a maintainer (and Pavel is the name for most of the core packages now), and they should have one or more papers (typically a JoSS paper for the software, others for the methods if appropriate), with a fallback to the JoSS 2008 volume. The norms in the scientific community have evolved since we first released statnet, and I think most people now understand the responsibility to cite packages.

What makes things complicated for us is:

1. Our packages are interdependent. They pretty much all depend on network; tergm and the other stat packages also depend on ergm. So, what do we want our users to cite? Every package in the dependency list? And if we take that approach, what about the non-statnet packages that our packages import? All of this code is part of the larger R open source ecosystem. There are other packages that depend on ours, and it's likely we don't get cited for that.

• At minimum, we need to decide if we want to tell users to cite the dependencies in the statnet suite.

• And if we do that, we need to exclude things like statnet.common and rle

2. Perhaps the more important question is what we want citation('package') to produce:

• The package citation itself, with the maintainer as the lead author, other authors as identified by the maintainer and some reference to the larger Statnet Development project?

for example, here's what dplyr reports (Wickham is the maintainer):

To cite ‘dplyr’ in publications use:
  Hadley Wickham, Romain François, Lionel Henry and Kirill Müller (2018). dplyr: A Grammar of Data Manipulation. R package version
  0.7.6. https://CRAN.R-project.org/package=dplyr
A BibTeX entry for LaTeX users is
  @Manual{,
    title = {dplyr: A Grammar of Data Manipulation},
    author = {Hadley Wickham and Romain François and Lionel Henry and Kirill Müller},
    year = {2018},
    note = {R package version 0.7.6},
    url = {https://CRAN.R-project.org/package=dplyr},
  }

• the JoSS paper (if it exists)?

• relevant methodology papers?

The survival package prints this:

> citation("survival")

Therneau T (2021). _A Package for Survival Analysis in R_. R package version
3.2-11, <URL: https://CRAN.R-project.org/package=survival>.

Terry M. Therneau, Patricia M. Grambsch (2000). _Modeling Survival Data:
Extending the Cox Model_. Springer, New York. ISBN 0-387-98784-3.

But this is the list of folks in the CRAN author field:

Author: | Terry M Therneau [aut, cre], Thomas Lumley [ctb, trl] (original S->R port and R maintainer until 2009), Atkinson Elizabeth [ctb], Crowson Cynthia [ctb]

And then there's Bioconductor -- which is much more elaborate, but similar in structure. They currently note over 2000 packages in their ecosystem, [https://www.bioconductor.org](https://www.bioconductor.org/, and have addressed the problem of core and extension package installation with a suite-specific install function: https://www.bioconductor.org/install/](https://www.bioconductor.org/install/.

[CarterButts]

It's definitely complicated. There is also an argument in some cases for basing citations on specific functions (based on what's in the man page); for instance, if you used the Gould and Fernandez brokerage function using the sna brokerage() command, you should really cite G+F (and a reference is given for that purpose). So some of this is a matter of giving folks reasonable opportunities to know whom to cite, and encouraging them to do so. Probably, there is no single magic bullet.

Citations are to an extent "coin of the realm," at least for those of us who have to justify software on our CVs to parts of the academic community that do not value it, hence it is good to encourage folks to cite the tools. (And they often don't, especially if they are buried somewhere at the bottom of a larger toolchain.) But that general point aside, at this stage (per above comments) many of our packages are becoming suitably diffusely authored that it is becoming sensible to attribute them to the development team (with a list somewhere of members). So this at least provides principled grounds for some simplification.

[krivit]

Shall we put it to a vote, or would everyone be OK with me making an executive decision in the next 48 hours and pushing statnet.common?

The good news is that we can change it any time by releasing a new version of statnet.common.

[martinamorris]

I guess I'm a bit confused about how this will work, given the different packages. But my vote would be to copy the survival package format with a pair of citations:

• citation for package itself, with maintainer as author + a nod to the Statnet Project and/or Dev team. (i see how statnet.common can handle this).
• package-specific citation to methods and/or JoSS paper (not sure how it would do this)

[krivit]

The way it works is that statnet.common implements a function statnetStartupMessage(), is called from .onAttach() of various packages. Thus, making a change in statnet.common will automatically affect all other packages.

If you are referring to citations, that's a whole separate thing, and while it uses a template, each package has to define their own individually.

[martinamorris]

right, thx.

[martinamorris]

Note that we have a citation format to update on our website also, here. It currently has:

Statnet Development Team
(Pavel N. Krivitsky, Mark S. Handcock, David R. Hunter, Carter T. Butts, Chad Klumb, Steven M. Goodreau, and Martina Morris) (2003-2021).  statnet: Software tools for the Statistical Modeling of Network Data. 
URL http://statnet.org

Raises the question: what should be the citation for the folks who library(statnet). Some version of the above?

[krivit]

As you know, I've advocated that we encourage people to cite individual packages for a long time. Though, again, it's not something statnet.common controls.

[martinamorris]

For me the complication with that is:

(1) should ergm.ego users just cite ergm.ego? or also ergm and network which it depends on?;

(2) while we like to think of all of these packages as separate, there's a part of our user community that is used to bundled packages like SAS and SPSS, and as a convenience for them we make the statnet bundle install. The old 2008 JoSS volume had multiple papers, so couldn't be cited as a single source. Maybe it would be good to have a short paper on the statnet core packages. Note the cite for tidyverse:

> citation("tidyverse")

  Wickham et al., (2019). Welcome to the tidyverse. Journal of Open Source Software,
  4(43), 1686, https://doi.org/10.21105/joss.01686

A BibTeX entry for LaTeX users is

  @Article{,
    title = {Welcome to the {tidyverse}},
    author = {Hadley Wickham and Mara Averick and Jennifer Bryan and Winston Chang and Lucy D'Agostino McGowan and Romain François and Garrett Grolemund and Alex Hayes and Lionel Henry and Jim Hester and Max Kuhn and Thomas Lin Pedersen and Evan Miller and Stephan Milton Bache and Kirill Müller and Jeroen Ooms and David Robinson and Dana Paige Seidel and Vitalie Spinu and Kohske Takahashi and Davis Vaughan and Claus Wilke and Kara Woo and Hiroaki Yutani},
    year = {2019},
    journal = {Journal of Open Source Software},
    volume = {4},
    number = {43},
    pages = {1686},
    doi = {10.21105/joss.01686},
  }

[krivit]

I've tested a bunch of these options out in their native environment (i.e., what does the R console actually look like when loading packages), and blocks of text don't work very well. Here's what I ended up doing:

> library(ergm)
Loading required package: network
‘network’ 1.17.0 (2021-05-31) part of the Statnet Project
* ‘news(package="network")’ for changes since last version
* ‘citation("network")’ for citation information
* ‘https://statnet.org’ for help, support, and other information

‘ergm’ 4.0.0 (2021-06-05) part of the Statnet Project
* ‘news(package="ergm")’ for changes since last version
* ‘citation("ergm")’ for citation information
* ‘https://statnet.org’ for help, support, and other information

If we decide to change it, we can always release an update to statnet.common.

[martinamorris]

I like it :). Some might think the news and citation are unnecessary handholding, but I think it's the right balance.

[drh20drh20]

I also like it but worry whether we've replaced one wall with another in the case where someone loads a package with many statnet dependencies. What is the largest possible such wall? I know it may be complicated to do this but is there a way to at least avoid repeating the "statnet.org" line more than once?

[martinamorris]

maybe with library(statnet)?

[krivit]

Before, I had some ideas for a package detecting whether it's being attached by a user command or as a dependency of another Statnet project and suppressing its startup message in the latter case. They didn't pan out.

Another approach that may work better is to set up the URL message to print only once per session, and then, naturally, it will print only the first time a Statnet project package loads. Where would we want it to print? (In particular, can I ask to you to edit the above example into what you would like to see?)