Can't replicate directed functionality of deprecated random_tree

[rossbar]

The deprecated random_tree function supported the create_using kwarg to allow the creation of directed trees:

>>> G = nx.random_tree(10, create_using=nx.DiGraph, seed=42)
>>> G.edges
OutEdgeView([(0, 6), (0, 4), (1, 5), (1, 8), (2, 1), (3, 7), (3, 2), (4, 3), (8, 9)])

The random_labeled_tree function is the recommended replacement for the deprecated random_tree fn, but it doesn't support the create_using kwarg. AFAICT, the only way to replicate the current behavior of random_tree is to create a DiGraph from the generated edges manually:

>>> H = nx.random_labeled_tree(10, seed=42)  # Undirected
>>> DH = nx.DiGraph()
>>> DH.add_edges_from(H)

I'm mostly just raising for visibility - I don't recall if this was an explicit decision to remove create_using support - @vigna . From a user perspective it'd be convenient to be able to replicate existing functionality with as little code modification as possible.

[vigna]

#6758 (comment)

[dschult]

To summarize (hopefully correctly). There are multiple ways to define uniformly chosen random directed trees in the literature. Even the definition of a directed tree varies (arborescence vs polytree for example, see wikipedia trees). Each definition of directed tree has a different set of probabilities due to different restrictions on directions of edges. So, if we want random directed trees we should at least use separate functions for them -- and probably multiple separate functions.

The above-linked comments do mention that we could include an example in the doc_string for turning the random tree into a DFS-oriented directed tree (an arborescence). I don't see that. But I suspect that is probably the best way to help users who want to replicate what was previously available via random_tree with create_using=DiGraph. It might also be good to mention the difficulty in defining a uniformly chosen random directed tree, though it might be hard to write it in a short yet understandable manner.