Convert ergm-terms documentation to Roxygen?

[krivit]

At the moment, all the ergm terms are documented in one big file (ergm-terms.Rd) with a "standard" syntax for keywords. Porting them to Roxygen (somehow) would greatly simplify maintenance in the following ways:

• Documentation "source" could be placed next to the InitErgmTerm function definitions, for much better maintainability.
• Using @template, common bits of text (like meanings of arguments common among many terms) only need to be written and updated once.
• Markdown is less clunky than the Rd format.

AFAIK, roxygen2 has an API for custom @ tags and document types, and we could write them to generate automatically formatted Rd files. Some other things we might be able to do:

• Generate a help file for each term and a help file with all the terms and/or a term index. This would allow us to link to a specific term's help.
• @seealso-style cross-referencing for related terms.

Any thoughts?

[krivit]

Another possibility is to use the dynamic pages mechanism, which could also be used to make help("ergm-terms") list all terms defined so far. E.g., something like this:

1. Each InitErgmTerm.*() function is to be able to define attr attributes that document it. For example,

   InitErgmTerm.absdiff <- structure(
     function(nw, arglist, ..., version=packageVersion("ergm")) {
       ### Check the network and arguments to make sure they are appropriate.
       a <- check.ErgmTerm(nw, arglist, directed=NULL, bipartite=NULL,
                           varnames = c("attr","pow"),
                           vartypes = c(ERGM_VATTR_SPEC,"numeric"),
                           defaultvalues = list(NULL,1),
                           required = c(TRUE,FALSE))
       ### Process the arguments
       nodecov <- ergm_get_vattr(a$attr, nw, accept="numeric")
       covname <- attr(nodecov, "name")
       ### Construct the list to return
       list(name="absdiff",                                     #name: required
            coef.names = paste(paste("absdiff",if(a$pow!=1) a$pow else "",sep=""), covname, sep="."), #coef.names: required
            inputs = c(a$pow,nodecov),  # We need to include the nodal covariate for this term
            dependence = FALSE # So we don't use MCMC if not necessary
            )
     },
     args = alist(attr, pow=1),
     keywords = c("binary", "dyad-independent", "frequently-used", "directed", "undirected", "quantitative nodal attribute"),
     title = "Absolute difference",
     description = "The \\code{attr} argument specifies a quantitative attribute (see \\NodalAttr for details). This term adds one network statistic to the model equaling the sum of \\code{abs(attr[i]-attr[j])^pow} for all edges (i,j)  in the network.")

2. A helper function (e.g., .gen_term_docs()) scans through the namespaces of loaded packages and generates Rd code for their list, sorted and sectioned as needed based on the attributes.
3. The ergm-terms.Rd calls \Sexpr[stage=render,results=rd]{.gen_term_docs()}.

I see the following upsides and downsides relative to the Roxygen approach:

• Does not require learning the Roxygen extension API.
• Should be able to generate term documentation dynamically, with entries added as new packages are loaded.
  • Though it should be possible to generate aliases (i.e., so that ?absdiff brings up the help for the terms), I suspect that that can only be done at the build or the installation stage, which means that those can't be dynamically updated.
• Does require writing raw Rd (rather than Markdown) code. (It may be worth seeing if Roxygen exports the function it uses to convert Markdown to Rd.)
• Less amenable to other preprocessing, such as being able to create a separate help file for each term, as opposed to a wall of text.
  • Code in .gen_term_docs() could be run before build as a poor man's Roxygen, however.

@martinamorris , @mbojan , @chad-klumb , @drh20drh20 , @sgoodreau , @CarterButts , @handcock , any thoughts?

[krivit]

For comparison, I imagine documentation for customised Roxygen would look something like this:

#' @docType ergmTerm
#' @usage absdiff(attr, pow=1)
#' @title Absolute difference
#' @details The \code{attr} argument specifies a quantitative attribute (see \NodalAttr for details). This term adds one network statistic to the model equaling the sum of \code{abs(attr[i]-attr[j])^pow} for all edges (i,j)  in the network.
#' @keywords binary, dyad-independent, frequently-used, directed, undirected, quantitative nodal attribute
InitErgmTerm.absdiff <- function(nw, arglist, ..., version=packageVersion("ergm")) {
  ETC...
}

[mbojan]

I think I Iike Roxygen more than the idea from #28 (comment). I think we can use @family for all the tagging/grouping. What would we need the custom Roxygen API for?

Is the idea to still have all the terms documented on a single page, grouped somehow or each one having its own?

I'm not a big fan of the current setup with one big page because its cumbersome to scroll/search through.

[krivit]

Roxygen API is designed for documenting functions, and it wouldn't know what to do with InitErgmTerm.*() functions.

I am having trouble envisioning how to use Roxygen here without extensions. Can I ask you to prototype it for 2-3 terms (e.g., edges and absdiff) in a branch?

[mbojan]

Sure, I'll have a look.

Are we aiming at one big page or separate ones with lots of interlinks?

[krivit]

I was thinking either one big page or both. (Alternatively, the one big page could be an index page with brief term descriptions linking to separate ones.)

[mbojan]

Or one big vignette and separate Rd files?

[martinamorris]

I like some version of both. The one big page makes searching within page easy.

[krivit]

There is already an ergm-term-crossRef.Rmd vignette written by @skyebend that indexes the terms by parsing the ergm-terms.Rd file.

In any case, I am still not sure if one can use unmodified Roxygen to get this to work. In particular, @family doesn't create an index page. Rather, it cross-links all members of a given family with each other.

[mbojan]

Pavel: I was thinking either one big page or both. (Alternatively, the one big page could be an index page with brief term descriptions linking to separate ones.)

Martina: I like some version of both. The one big page makes searching within page easy.

The question is if user asks ?absdiff what should open? At this moment one gets the "ergm-terms" page. We may keep the "ergm-terms" more or less as it is now but write documentation in Roxygen next to the initErgmTerm.*() functions. We won't need @family but I think the issue will be to ensure the alphabetic ordering of the terms in the Rd output. There is @order but I'm not sure it will work because we are not documenting real R objects and it seems it only accept numbers as a basis for sorting.

On the other hand if we want to have individual pages for the terms (?absdiff will open its own man page) I think it could mimic a man page of a standard R function with Usage etc. inserted as a @section with preformatted content (instead of @usage directly), use some Roxygen template and so on. I'm not yet sure what would be the best way to auto-build the "index page".

There is already an ergm-term-crossRef.Rmd vignette written by @skyebend that indexes the terms by parsing the ergm-terms.Rd file.

Right! Forgot about that.

In any case, I am still not sure if one can use unmodified Roxygen to get this to work. In particular, @family doesn't create an index page. Rather, it cross-links all members of a given family with each other.

I think I saw some code snippet somewhere with which one can dump the list of family members to Rd...

[krivit]

Here's what would work nicely, I think:

• A page for each term. For some of them, we have to be careful with aliases, because, for example hamming and edges are both a term and a constraint, so currently a disambiguation page is used.
• An index page (updated dynamically) with:
  • All terms, in alphabetical order, indicating their package, keywords, and title.
  • For each package, a list of terms it exports.
  • For each keyword, a list of terms with that keyword.

In other words, much of what @skyebend 's vignette does, but integrated into the R's help system and updated as more packages are loaded.

If an acceptable formatting could be produced for each term using Roxygen, we can then piggyback on @skyebend 's code to scan through all the help pages with an appropriate title/keyword, parse their term information, and put them in the index using the Dynamic Pages method.

This would probably give us the best of both worlds: the term writer uses Roxygen and Rmarkdown, but the end-user sees a detailed and self-updating index.

Lastly, I think @family is less than ideal, because every term doc will have a list of all other terms in it, unless there is a way to suppress that behaviour.

[martinamorris]

I like this as a general proposal, it seems to optimize across the multiple search desiderata.

But I'm not quite sure what the index would look like to the user. I can imagine having an Rmd to be knitted to html with sections and a floating TOC -- that would make it easy to navigate.

[mbojan]

Here's what would work nicely, I think:

• A page for each term. For some of them, we have to be careful with aliases, because, for example hamming and edges are both a term and a constraint, so currently a disambiguation page is used.

• An index page (updated dynamically) with:

• All terms, in alphabetical order, indicating their package, keywords, and title.

  • For each package, a list of terms it exports.
  • For each keyword, a list of terms with that keyword.

That sounds good.

WRT @family I was thinking of using it for "tagging" groups of terms e.g.

@family terms for directed networks
@family dyad-independent terms

and so on, and indeed one will get a list of terms by each "family".

I'm anyway looking into Roxygen API if there is any promising value for effort of creating our own tags.

[krivit]

WRT @family I was thinking of using it for "tagging" groups of terms

Unfortunately, it'll do more than that. According to the Roxygen2 docs, @family will "cross-reference each function to every other function within the family". That means that every term will have a link to every other term in the package. @concept might work better.

[mbojan]

I used it in statnet.data to create families "directed networks", "undirected networks" and "bipartite networks". I think it is useful because you can see what other datasets of similar type are available and you can jump to their man page directly. If we make families for, say "dyad-independent terms", "node-covariate effects", "dyadic covariate effects" and so on (will have to carefully pick the family names though) one can open, say, absdiff and will have links to nodematch, dyadcov and so on. Isn't that useful? The @concept on the other hand AFAIK only allows for pages to be found by help.search(), doesn't it?

[krivit]

OK, I see how that could work. It might still make things a bit crowded, but as long as the crowing is out of the way, it shouldn't be too much of a problem.

[krivit]

Question for everyone, but particularly @martinamorris , @chad-klumb , how valuable would it be to have this type of documentation and indexing for the proposals? We are currently doing it for statistics, constraints, and references.

[martinamorris]

Valuable.

[sgoodreau]

+1

[chad-klumb]

probably worth having

[krivit]

OK. We need to figure out how to organise it, since unlike statistics, constraints, and references, they are not function-alikes that take argument. Can I ask you to prototype what you want to see?

[krivit]

Now that the workshops are out of the way, I would like to get this across the finish line and merge. @joycecheng is working on porting other packages in the suite (with tergm being next). However, since the change doesn't break any of them, we can merge as soon as we can be confident that the new documentation system works for at least one external package.

I have some further questions for discussion, that I will post in separate subthreads after this one. Again, the current draft of ergm with the new documentation system is in https://github.com/joycecheng/ergm/tree/ergm-term-index; please install it, play around with it, and provide feedback.

@martinamorris , @mbojan , @CarterButts , @handcock , @drh20drh20 , @chad-klumb , @sgoodreau

[mbojan]

@krivit @joycecheng , I can't install on Windows because I'm getting

Error:  'names' attribute [5] must be the same length as the vector [0]

during ** installing help indices. CI on Windows fails with the same error (https://github.com/joycecheng/ergm/runs/2734281348)

[krivit]

@mbojan , I think both @joycecheng and I use Linux. Can I trouble you to try debugging that issue?

[mbojan]

c.f. #338

[krivit]

Now fixed in the branch. @ windows users, please provide feedback.

[mbojan]

All works for me. Issue closed.

[krivit]

1. Currently, ?ergmTerm will get you a listing of visible terms, and ergmTerm?edges will get you the term's specific documentation. This is nice and unambiguous, but do we want something shorter and/or not mixed-case? Suggestions welcome.

[sgoodreau]

these are short enough in my mind. maybe make all lowercase instead of mixed case, but no big deal either way.

[martinamorris]

agree they are short enough, given the need for unambiguous reference. it's a bit odd not to be using ergm-term, just from habit. if we wanted consistency with something, we might use ?ErgmTerm, which matches InitErgmTerm. but i don't have a strong preference.

[krivit]

As a follow-up, what about constraints (ergmConstraint?edges) and references (ergmReference?Poisson)? Would those benefit from shortening?

[martinamorris]

will there be tab completion? if so, i'd leave them long. if not, i can't see a good abbreviation for constraints, but reference can be ref.

[krivit]

I am not 100% sure. Help topics don't get completed in baseline R, AFAIK, only functions and variables.

[krivit]

2. Do we want term-only help, such as ?triangles to still work? My own preference would be to deprecate that and have ?termname take you to a page that tells you to use ergmTerm?termname. Any thoughts?

[sgoodreau]

I agree with deprecating these.

[martinamorris]

what SMG said

[krivit]

3. In addition to the term index in ?ergmTerm (or whatever we call it), what additional information do we want? Should we just copy over everything that's currently in ergm-terms.Rd that's not term-specific?

[martinamorris]

yes, to start. we can edit as needed after.

[krivit]

@joycecheng , can you please do that, if you haven't already?

[krivit]

4. Joyce has gotten the terms vignette to work again, but do we want to keep it around, since we have essentially the same info in a dynamic index? If so, do we want to have ergm suggest more packages so that the index could host their terms as well?

[martinamorris]

the vignette was nicely organized, and might still have value as a comprehensive source of info. we may want to add to it some discussion of the ergm.ego terms and temporally aware terms in tergm. so, basically, use the existing vignette as a basis for a more complete resource.

[joycecheng]

The vignette and the dynamic pages are generated from the same code (aside from the terms table which has more information than the dynamic index table). It should be pretty trivial to maintain both of them.

[krivit]

5. Right now, the code lists all terms it can find, even if the package is neither loaded nor attached (but is installed). Do we want that? The options I can see:

1. List the terms in such a package alongside loaded terms, but mark them in some way to show that they are presently unloaded.
2. List the terms in such a package alongside loaded terms, but mark the loaded terms instead.
3. List the terms in such a package separately, as opposed to as a part of any of the indices. This would work best with Provide a mechanism for providing concept abbreviations and descriptions dynamically. #343 .
4. Don't list the terms, but list currently unloaded packages that appear to contain terms. This would work best with Provide a mechanism for providing concept abbreviations and descriptions dynamically. #343 .

Any thoughts?

[mbojan]

I have ~650 packages installed. I took the new indexing a fat couple of seconds of intense HD whirling to scan all the installed packages. I hope CRAN will be OK with scanning the installed packages like that. I can imagine it might be quite a while if run on, say, a cluster used by a scientifically diverse community of ppl that has half of CRAN packages installed...

Can it be rationalized by e.g. building db of Rd files only for reverse dependencies of ergm? For example with something like:

srch <- function(pkg="ergm", ...) {
  revdeps <-  tools::dependsOnPkgs(pkg, dependencies = "strong")
  utils::hsearch_db(package=revdeps, ...)
}

There are some additional arguments to hsearch_db() with which one can limit the results too. @krivit ?

From the options I think I like (2) most.

[krivit]

@mbojan , I've incorporated the optimisation. How is it now?

[mbojan]

I think it is quicker.

[joycecheng]

I think I am on a later version of tools and had to remove dependencies='strong'. Looks like there was a breaking change and the dependencies values are now different: https://rdrr.io/r/tools/dependsOnPkgs.html

Does that still work for you?

[mbojan]

I like the whole setup a lot. I'm a bit concerned with default font size. On my machine the text in the 'term' column is very small. On the verge of readability. See this screenshot of ?ergmConstraint:

[krivit]

I've un-shrunk it.

[mbojan]

Much better now, I think.

[mbojan]

I noticed that on ?ergmConstraint the local links in the "Jump to category" list do not work. While the links look OK, e.g. the first one

<a href="#cat_bipartite" onclick="window.parent.helpNavigate(this.href); return false">bipartite</a>

The category headers (to which these should lead, right?) don't have the proper id:

<a id="bipartite" onclick="window.parent.helpNavigate(this.href); return false">bipartite</a>

The id should be cat_bipartite isn't it?

[krivit]

@joycecheng , can you please take a look?

[mbojan]

Created joycecheng#3

[krivit]

@mbojan , we are putting tickets on statnet/ergm and adding them to the term documentation project, since joycecheng/ergm may disappear in the future.

[mbojan]

Ok, sorry. Can we move the issue to start/ergm?. I don't think I have req privileges

[mbojan]

Yeah, the new default seems equivalent to the old "strong". śr., 7 lip 2021, 02:28 użytkownik Joyce Cheng ***@***.***> napisał:

…

I think I am on a later version of tools and had to remove dependencies='strong'. Looks like there was a breaking change and the dependencies values are now different: https://rdrr.io/r/tools/dependsOnPkgs.html Does that still work for you? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#274 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAE3NHV2RWBYSPZ2OZPOGSLTWONUPANCNFSM43WTXASA> .

[krivit]

Next discussion question: Package index.

Right now, the Roxygen block is parked above the InitErgm*() functions, which means that the HTML index (the R's one, not ours) will contain a line for each term name (e.g., edges-ergmTerm) and a line for the InitErgm*() function. This pollutes the index. There are several approaches to this:

1. Insert a NULL between the Roxygen block and the InitErgm*() function. This will get rid of the InitErgm* line in the index, since it will no longer be aliased.
2. Mark the term indexes with keyword internal. This will keep them out of the index altogether, which may be a good idea (if we have a compact term index), but it will also keep them out of the manual.

Any preferences?

[krivit]

@martinamorris , @mbojan , @CarterButts , @handcock , @drh20drh20 , @chad-klumb , @sgoodreau, I think we are at a point where we can begin merging this code into master for all of the packages involved, since it's a net improvement to what we have now. If you have any objections to merging the new documentation infrastructure as is, please let me know in the next few days.

[krivit]

@martinamorris (and anybody else), for the avoidance of doubt, remotes::install_github("joycecheng/ergm@ergm-term-index") should now work regardless of what other packages you have installed.

[martinamorris]

@chad-klumb do we need to install tergm (4.0-2375 -> 599bd07d0...) [GitHub] also for this to work?

[chad-klumb]

In principle I don't think it should be necessary.

[krivit]

tergm has been ported as well, so if you run remotes::install_github("joycecheng/tergm@ergm-term-index"), it should add those terms to dynamic docs as well.

[martinamorris]

And what's the syntax for finding the dynamic specific terms?

[martinamorris]

Ok, it installs now on my windows machine. And I've taken a look at:

?ergmTerm
ergmTerm?edges
search.ergmTerms

They look good, but I also have suggestions about organization for the ?ergmTerm page, and, one potentially big task but would make for really helpful help, examples on the individual terms pages. Since they now each have their own page, is it possible to give them examples?

[martinamorris]

It would also help to alias "bin" and "binary" if possible:

> search.ergmTerms("binary")
Found  3  matching ergm terms:
B(formula, form)
    Wrap binary terms for use in valued models

mutual(same=NULL, by=NULL, diff=FALSE, keep=NULL, levels=NULL)
    Mutuality

mutual(form="min",threshold=0)
    Mutuality

[martinamorris]

Actually, bin doesn't seem to work much better.

• We need a list of keywords in the docs somewhere that we can link to in the help pages.
• And we need some way of not having the operator terms be the first item that shows up in the queries.

> search.ergmTerms("binary")
Found  3  matching ergm terms:
B(formula, form)
    Wrap binary terms for use in valued models

mutual(same=NULL, by=NULL, diff=FALSE, keep=NULL, levels=NULL)
    Mutuality

mutual(form="min",threshold=0)
    Mutuality
> search.ergmTerms("bin")
Found  16  matching ergm terms:
B(formula, form)
    Wrap binary terms for use in valued models

b1starmix(k, attr, base=NULL, diff=TRUE)
    Mixing matrix for k-stars centered on the first mode of a bipartite network

mutual(same=NULL, by=NULL, diff=FALSE, keep=NULL, levels=NULL)
    Mutuality

mutual(form="min",threshold=0)
    Mutuality

nodefactor(attr, base=1, levels=-1)
    Factor attribute effect

nodefactor(attr, base=1, levels=-1, form="sum")
    Factor attribute effect

nodeifactor(attr, base=1, levels=-1)
    Factor attribute effect for in-edges

nodeifactor(attr, base=1, levels=-1, form="sum")
    Factor attribute effect for in-edges

nodemix(attr, base=NULL, b1levels=NULL, b2levels=NULL, levels=NULL, levels2=-1)
    Nodal attribute mixing

nodemix(attr, base=NULL, b1levels=NULL, b2levels=NULL, levels=NULL, levels2=-1, form="sum")
    Nodal attribute mixing

nodeofactor(attr, base=1, levels=-1)
    Factor attribute effect for out-edges

nodeofactor(attr, base=1, levels=-1, form="sum")
    Factor attribute effect for out-edges

Prod(formulas, label)
    A product (or an arbitrary power combination) of one or more formulas

Prod(formulas, label)
    A product (or an arbitrary power combination) of one or more formulas

Sum(formulas, label)
    A sum (or an arbitrary linear combination) of one or more formulas

Sum(formulas, label)
    A sum (or an arbitrary linear combination) of one or more formulas

[krivit]

With the new documentation infrastructure having been merged into mainline ergm, I am going to declare this discussion concluded; the rest will be handled with individual tickets. A big thank you to everyone who contributed!