Identify deprecated functions

[maelle]

• some with #' @keywords internal
• some listed in the internal section of the pkgdown reference DONE
• some have "removed from igraph" in their docs DONE

Functions with dots in their name that are not deprecated (or there is no alternative)

(This is a community-edited section.)

• get.edge.ids()
• as.igraph()
• ... ??

[maelle]

related #668

[szhorvat]

There is also the zzz-deprecate.R files.

A a general guideline, most functions with . in their name are deprecated. But there are a few with dots which aren't, which we should collect in this post. I will edit the ones I'm aware of into the top post.

There are also a few functions which are technically deprecated (they appear in zzz-deprecate.R), but there is no alternative that provides their functionality, see e.g. #588.

[maelle]

So some of them are deprecated and others are superseded (there's a replacement) according to the terminology of https://lifecycle.r-lib.org/articles/stages.html

[maelle]

From #662 (copying justifications/replacements)

erdos.renyi.game() should not be included. We have the consistently named sample_gnm and sample_gnp that provide the exact same functionality.

[maelle]

• layout.grid.3d uses .Deprecated

[maelle]

Not sure why handle_vertex_type_arg has #' @keywords internal @ntamas (tagging you because of git blame :innocent: )

[maelle]

• layout.reingold.tilford() -> layout_as_tree()
• layout.fruchterman.reingold.grid() -> layout_with_fr()
• layout.spring() -> layout_with_fr() (yes the same as above)
• layout.svd -> layout_with_fr() (yes the same as above a third time)

[szhorvat]

• layout.spring() -> layout_with_fr() (yes the same as above)

• layout.svd -> layout_with_fr() (yes the same as above a third time)

To be clear, these two were not the FR layout originally. The original methods have been removed. Once again, these names should IMO be removed for good. I will support all spring cleaning proposals :-)

But to be clear, this is not my decision.

[maelle]

@szhorvat is as.igraph() really deprecated?

[ntamas]

Hmm, maybe it's time to start a checklist? (I'll try to stick to the lifecycle terminology).

• [ ] layout.reingold.tilford() is deprecated, the replacement is layout_as_tree(). I would recommend officially marking it as deprecated with a warning, and then removing it in a future version.
• [ ] layout.fruchterman.reingold.grid() is deprecated; the grid-based FR layout is now provided by layout_with_fr(). Since the deprecation warning has already been in place for a while, I think we can safely remove the function now.
• [ ] layout.spring() and layout.svd() are deprecated without replacement. Right now they call layout_with_fr() instead, but this function is not a replacement. Since the warning has already been in place for a while, I think we can safely remove the functions now.
• [ ] layout.grid.3d()is now layout_on_grid(..., dim=3) and a deprecation warning has already been in place for a long while now. It's time to let go of the old function now.
• [ ] handle_vertex_type_arg() is an internal helper function and it is not meant to be public. I propose hiding it from the docs but keeping it as is.
• [ ] as.igraph(): I don't think that this function has ever been used seriously. The idea was to provide a generic function that other data types can implement to convert themselves to an appropriate igraph object that represents them to some extent. For instance, as.igraph.igraphHRG() allows an igraphHRG object (a hierarchical random graph model, which can incidentally be represented as a graph) to be converted to an igraph graph for plotting purposes. Since it's a generic function, there is a chance that other R packages have implemented this for their own data types. I wouldn't remove it and I would not mark it as deprecated either.
• [ ] get.edge.ids(): not deprecated, but I think we should have a proper underscored name for it and deprecate the dotted name.
• [ ] erdos.renyi.game(): as quoted above, it is deprecated; the replacements are sample_gnm() and sample_gnp(). An old alias of it is random.graph.game(), also deprecated. However, since there were no warnings for users of these functions, I propose marking as deprecated and adding a warning, but not removing them yet.
• [ ] vcount() and ecount(): these are currently marked in the documentation as being replaced by gorder() and gsize(), but I think the old names are better. I propose keeping both. If we really want to, we can say that vcount() superseded gorder() and ecount() superseded gsize() (or vice version).
• [ ] neighborhood() is currently in zzz-deprecate.R and it claims ego() as a replacement, but to be honest I like neighborhood() better; ego() is a term that's mostly used in social network analysis but nowhere else. neighborhood() is more generic. I propose declaring neighborhood() as the preferred variant and ego() as an alias to it.
• [ ] All nexus.*() functions can be removed.
• [ ] as.directed() and as.undirected() use the old dotted-style naming, but I think we should be consistent and use underscored names instead. We should mark the old names as deprecated and remove them in a future version.
• [ ] as.dendrogram(), as.hclust() and as.matrix() also use dotted names, but they are generic functions declared in other packages (e.g., stats) so I guess we must keep them as is.
• [ ] .igraph.progress() and .igraph.status() are internal functions and should not appear in the public docs.

That's all that I've found in the docs so far.

[szhorvat]

• layout.fruchterman.reingold.grid() is deprecated without replacement. Right now it calls layout_with_fr() instead, but this function is not a replacement.

Isn't layout_with_fr(grid='grid') equivalent? It's not a direct renaming, but the functionality is provided.

---

layout.spring() and layout.svd() no longer provide their original functionality, so is it reasonable to keep them? They have been issuing warnings for a while now, so people who used them should have noticed that something changed.

---

I completely agree on ego(), it's specific to social sciences, and not widely used outside of that field. I wanted to bring this up too.

[ntamas]

Re layout.spring() and layout.svd(): I was advocating for removal as well, so +1.

Re layout_with_fr(): indeed, I did not notice the grid parameter, which means that the original functionality of layout.fruchterman.reingold.grid() is indeed provided. I'll update my comment above.

[maelle]

With all these deprecations it might be worth also creating a special article about them? Maybe even also published as a blog post if there's infrastructure for it? Tying together the new pkgdown website with its organized reference, with the deprecation changes (so communicating it as an increase in clarity).

Should all the removals be tied to a major version change?

For each function to be removed/deprecated I suggest to look at whether they're used in reverse dependencies (so at least those aren't broken by the update).

I find this Twitter thread also relevant https://twitter.com/hadleywickham/status/1582788323206012928

In any case I won't start implementation before #660 is merged. :innocent:

[ntamas]

660 is closed - shall we reopen it and consider for a merge?

[maelle]

oops I meant #662 that I need to fix up

[szhorvat]

I just recalled a problematic dotted name, subgraph.edges. There is no current underscore equivalent. The docs state thst subgraph (currently equivalent to induced_subgraph) is intended to be used as the future name of this functionality.

It would be good to discuss this again.

[ntamas]

That was writted / decided by Gábor and I'm not really sure whether I like it. induced_subgraph() is explicit and implies that the input is a vertex set and the result will be the induced subgraph. Similarly, the corresponding edge-based function should have a name that also emphasizes that the input must be an edge set. subgraph_edges() might not be the best name, but at least it includes "edges". subgraph() would leave no clue to the user as to whether it works with vertex or edge sets as input.

[szhorvat]

I agree.

In the C core, we recently deprecated subgraph_edges() in favour of subgraph_from_edges(). How about using that to make the name a bit more natural?

[krlmlr]

as.hclust() is a generic from the stats package, we can't change that.

[maelle]

Maybe come back to this issue after #697 is done.

[szhorvat]

There are still a bunch of functions using .Deprecated:

$ rg '\\.Deprecated'
iterators.R
532:    .Deprecated(".nei")
539:    .Deprecated(".innei")
546:    .Deprecated(".outnei")
563:    .Deprecated(".inc")
567:    .Deprecated(".inc")
583:    .Deprecated(".from")
599:    .Deprecated(".to")
880:    .Deprecated(".inc")
884:    .Deprecated(".inc")
897:    .Deprecated(".from")
910:    .Deprecated(".to")

layout.R
868:  .Deprecated("layout_on_grid", msg = paste0(

basic.R
63:  .Deprecated("ends", msg = paste(

[maelle]

rd file called layout.deprecated