Add an orbit-aware triad and quad census

[jhollway]

node_x_triad() and node_x_tetrad() count the motif types a node takes part
in, not the orbit it occupies within them. In the path i -> k -> j all three
nodes return a profile of one 021C triad, although i sends, k mediates and
j receives.

node_in_motif() therefore cannot recover role equivalence in Burt's sense.
Its documentation now says so, following the review on #18, but the capability
itself is still missing.

An orbit-aware census would close the gap:

Ortmann, Mark, and Ulrik Brandes. 2017. "Efficient orbit-aware triad and quad
census in directed and undirected graphs". Applied Network Science 2(1): 13.
https://doi.org/10.1007/s41109-017-0027-2

@Kaladani reports in #18 (comment)
that on the flattened networkers data the orbit census recovers local role
similarity well, though it is probably too fine grained there. They have an Rcpp
implementation in a local clone of develop, and plan undirected and tetrad/quad
versions that also take covariate labels into account.

Points to settle

• Compiled code. @Kaladani's view is that this cannot be fast enough without
  C++. That would make it netrics's first compiled code, so it needs a
  src/, Rcpp/cpp11 in Imports, and the extra CRAN build surface that
  brings. Worth deciding before the implementation lands.
• Naming. The four families are fixed, so an orbit census is a motif:
  node_x_orbit() alongside node_x_triad() and node_x_tetrad().
• Whether node_in_motif() should use it. Once the census exists,
  node_in_motif() could take an argument choosing between the type census and
  the orbit census, or a separate membership could be added. The former keeps
  the family smaller.
• Covariate labels. @Kaladani's planned version takes these into account,
  which no current node_x_*() does, so the return shape needs thought.

[Kaladani]

Sounds good. I am already working on it "locally".

Compiled Code. Indeed settling the c++ question might be important. I will do it locally anyway (since I need the functionality myself), but I am unsure if it also the way to go for netrics. Alternatively, we could make this a mini-package that works like an add-on. I am not sure what would be better. I have made a comparison of R and c++ implementation, which a) shows drastic differences and b) for a 500 node network the R version did not even finish under 30 minutes on my system (Macbook Pro).

library(bench)

g_test <- igraph::sample_gnp(n = 50, p = 0.2, directed = TRUE)

# Run the benchmark
bm <- bench::mark(
  cpp_engine = directed_triad_orbits(g_test, engine = "cpp"),
  r_engine   = directed_triad_orbits(g_test, engine = "r"),
  check      = TRUE,
  iterations = 10
)

print(bm)

[# A tibble: 2 × 13
  expression      min   median `itr/sec` mem_alloc `gc/sec` n_itr  n_gc total_time result          memory               time            gc               
  <bch:expr> <bch:tm> <bch:tm>     <dbl> <bch:byt>    <dbl> <int> <dbl>   <bch:tm> <list>          <list>               <list>          <list>           
1 cpp_engine   10.4ms   10.5ms      93.9     157KB      0      10     0      106ms <dbl [50 × 36]> <Rprofmem [356 × 3]> <bench_tm [10]> <tibble [10 × 3]>
2 r_engine     79.9ms   86.9ms      11.6     373KB     20.8    10    18      864ms <dbl [50 × 36]> <Rprofmem [228 × 3]> <bench_tm [10]> <tibble [10 × 3]>]

And it would be much worse for the orbit-aware quad/tetrard census but of course there could be some clever matrix algebra tricks, that would just use BLAS instead of our own c++ code.

Naming/Usage. Since motif and orbit-aware motif can exist for all node set sizes (dyads, triads, quads, ...), it's probably not the best idea to have a spearate orbit function. Should all of these motifs become a "orbit = TRUE" argument? Internally, it would of course be cleaner to have two separate functions that are called by node_x_triad() etc.

On a practical note: How do you handle "feature"-development like this: Create a separate branch (potentially directly from this issue) or do I make a pull request from an external fork? I have read the contributing guidelines and I might have missed which "style" of branching/forking is preferred.

[Kaladani]

This might warrant a separate issue, but it's closely tied to what I am using the census for, so
noting it here first.

Once the orbit census exists, the natural next step is a role-similarity matrix computed from
it; and that step is the one stage of the pipeline with no public accessor. The chain is

census  →  proximity  →  clustering  →  membership

and netrics exports every stage but one: The proximity matrix is built inside the cluster_*() functions (cluster_hierarchical() a correlation matrix, cluster_cosine() a cosine one) and consumed there. Nothing returns it. (attr(out, "hc")$distances belongs to the step after, not to this one.) - see also the comment in the PR here.

So the pipeline runs census → clustering → membership with no exit in the middle, and for example for my analysis, the middle is often what you want: to inspect it and to ask whether an attribute structures it (assortativity, O/E mixing, influence/selection analysis etc.).

The suggestion would be to factor that step out into a proximity_*() family taking a motif
matrix and returning the node-by-node matrix, following the <argument>_<value> convention:
proximity_correlation() and proximity_cosine() from the existing code, with room for
proximity_jaccard(), proximity_ruzicka(), proximity_overlap(). These would be thin
wrappers over manynet::to_correlation() / to_cosine() today, and over new
manynet::to_jaccard()-style kernels once those exist — the public names wouldn't move, only
the bodies. For practical purposes I'd implement the missing kernels inside netrics for now.

[jhollway]

Agreed on the missing stage, and I have opened #29 to carry it, together with the
one-step comparison from the PR review, since the two touch the same functions. The
transpose bug is fixed on develop and goes out in 1.0.1; there is a proximity
branch for the rest.

One correction before you write anything. The extra kernels already exist upstream.
manynet::to_proximity() offers 24 measures, manynet:::.proj_measures:

manynet:::.proj_measures
#>  [1] "count"     "jaccard"   "rand"      "pearson"   "yule"      "match"
#>  [7] "overlap"   "crossmin"  ...        "euclidean" "manhattan" "hamming"
#> [22] "cosine"    "spearman"  "kendall"

So jaccard, ruzicka-adjacent and overlap are all there.

The block is somewhere else. to_proximity() aborts on a rectangular matrix, because
it reads one as a two-mode network:

`to_proximity()` compares the nodes of a one-mode network on their ties to one
another. Use `to_mode1()` or `to_mode2()` to compare the nodes of a two-mode network
on their affiliations.

to_correlation() and to_cosine() reach the same kernels through .project() and
so never hit that guard, which is why those two are the only ones usable on a census
today.

That makes the upstream ask on {manynet} a narrow one: let to_proximity() accept
a plain node-by-feature profile matrix rather than only a network-shaped one. Once it
does, proximity_*() here is thin dispatch over kernels that already exist, and no
numerical code needs writing in netrics at all. Worth raising there first, I think,
rather than implementing kernels here that we would then remove.

On the naming, proximity_*() works for me and fits the family rule, since it is
named for what it returns. It does contradict a paragraph in CONTRIBUTING that
rejected a similarity family on the grounds that these measures belong to {manynet}
and are only ever consumed through distance =. That paragraph weighed the naming
and not the missing accessor, so I will rewrite it rather than leave the two at odds.

The open question is what happens to distance = once the comparison is one-step: it
has no work left. Deprecating it is the clean answer, but it may be worth keeping for
proximities that are already distances rather than similarities. Views welcome on #29.