docs: add example for `consensus_tree()` (from `fit_hrg()` example)

[maelle]

@szhorvat I have two questions about consensus_tree()

1. The docs says it returns a list of two objects, where the first is an igraphHRGConsensus that is supposed to a be a list. What is returned is actually a list of three things: parents and weights supposedly for igraphHRGConsensus, and an igraphHRG (this is expected).

library("igraph")
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union

## A graph with two dense groups
g <- sample_gnp(10, p = 1 / 2) + sample_gnp(10, p = 1 / 2)
hrg <- fit_hrg(g)
hrg
#> Hierarchical random graph, at level 3:
#> g1        p=   0  
#> '- g5     p= 0.8  
#>    '- g6  p=   0  2  10 7  1  3 
#>    '- g13 p=   1  6  4  9  8  5 
#> '- g19    p=0.67  15
#>    '- g18 p=   0  19 13 17 11 12 18 16 14 20

## The consensus tree for it
tree <- consensus_tree(g, hrg = hrg, start = TRUE)
str(tree)
#> List of 3
#>  $ parents: num [1:23] 20 20 20 20 20 20 20 20 20 20 ...
#>  $ weights: num [1:3] 9847 8578 10000
#>  $ hrg    :List of 5
#>   ..$ left    : num [1:19] -5 7 11 10 -6 -12 0 -9 3 -14 ...
#>   ..$ right   : num [1:19] -19 8 -16 16 -13 2 6 5 -2 18 ...
#>   ..$ prob    : num [1:19] 0 1 0 0 0.8 ...
#>   ..$ edges   : num [1:19] 0 1 0 0 20 0 1 0 0 6 ...
#>   ..$ vertices: num [1:19] 20 2 4 2 10 5 2 4 3 8 ...

^{Created on 2024-08-20 with reprex v2.1.0}

1. There is a TODO for igraphHRGConsensus print method "TODO: print as a tree". How would that happen?

[aviator-app[bot]]

Current Aviator status

Aviator will automatically update this comment as the status of the PR changes. Comment /aviator refresh to force Aviator to re-examine your PR (or learn about other /aviator commands).

This pull request is currently open (not queued).

How to merge

To merge this PR, comment /aviator merge or add the mergequeue label.

---

See the real-time status of this PR on the Aviator webapp.

Use the Aviator Chrome Extension to see the status of your PR within GitHub.

[maelle]

@szhorvat friendly reminder :smile_cat:

[szhorvat]

@ntamas Can you help?

I haven't used this functionality much. If no one can chime in I'll come back to this next week.

[ntamas]

Sorry I'm not familiar with this either. From my vague recollection, the idea is that you fit the hierarchical random graph model multiple times to your input data (it's a stochastic process), then you get a bunch of model instances, and then there's this magic function that somehow creates a "consensus tree". I would need to read the paper to jog my memories.

[maelle]

Thanks both! So you don't know enough at this point to be surprised or not by the output of the function?

[maelle]

I can't find usage of the function (or of its previous name hrg.consensus) on GitHub.

[szhorvat]

Let's postpone this a bit until one of us can find the time to look at the functionality and understand it properly. That's going to take some time (and probably involves looking at the paper, as Tamás said).