feat: igraph_joint_degree_distribution

[szhorvat]

Docs and implementation are complete, but no tests yet.

I'd like to have #2419 merged before adding tests and finalizing the cross referencing of docs.

The following is a nice visual illustration of why we need the joint degree distribution (and not joint degree matrix) for statistical applications dealing with degree correlations.

Join degree matrix of a large undirected Erdős-Rényi graph:

Joint degree distribution of the same:

[codecov]

Codecov Report

Merging #2422 (af0ebc8) into master (e6b49f4) will increase coverage by 0.04%.
Report is 1 commits behind head on master.
The diff coverage is 86.66%.

@@            Coverage Diff             @@
##           master    #2422      +/-   ##
==========================================
+ Coverage   83.68%   83.73%   +0.04%     
==========================================
  Files         377      377              
  Lines       62137    62401     +264     
==========================================
+ Hits        52001    52252     +251     
- Misses      10136    10149      +13     

Files	Coverage Δ
src/properties/degrees.c	90.45% <25.00%> (+0.07%)	⬆️
src/misc/mixing.c	93.38% <89.10%> (-2.53%)	⬇️

... and 6 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e6b49f4...af0ebc8. Read the comment docs.

[szhorvat]

Here's a thought: Perhaps we should generalize this to work with arbitrary integer "vertex types", which can be used in place of the degrees? Then supplying in- or out-degrees would be just one choice.

[szhorvat]

Here's a thought: Perhaps we should generalize this to work with arbitrary integer "vertex types", which can be used in place of the degrees? Then supplying in- or out-degrees would be just one choice.

This is now implemented as igraph_mixing_matrix(). I believe this name is used in the social sciences, but perhaps it is not the best fit here, given that it is a counterpart of igraph_joint_degree_distribution() and not igraph_joint_degree_matrix(). I would rather go with igraph_joint_type_distribution(). Calling it "joint distribution" encodes the fact that it is over ordered pairs.

@mbojan, perhaps you have some input on this function and its naming?

[mbojan]

@szhorvat , I didn't have time to study what you did in detail but if, in principle, you take an edge list (two-column matrix), replace node ids with corresponding values of some node attribute[s] (perhaps distinct attributes for source and target nodes in a digraph) and finally aggregate it by counting the unique combinations of values then indeed it is the contact layer of the mixing matrix. Thus function name seems appropriate.

[ntamas]

Does it make sense to have to_types for undirected graphs? I would assume it does as each undirected edge is counted in "both" directions and the types of the vertices can then differ in both configurations, but I wonder whether it would really make a difference.

[szhorvat]

Good question. The matrix would be different, since the row and column counts may not be the same anymore. Is it a useful matrix? I am not sure. I would leave it as-is.

[mbojan]

Approaches to MM of undirected graphs vary. In https://mbojan.github.io/netseg/reference/mixingm.html I count each edge once (so the sum of contact layer of MM is a proper edge count) and fold all counts to upper triangle so that lower triangle is all 0s. On the other hand https://github.com/statnet/network/blob/5fb95d2feddfd2a0fa3f234a102fe2992203c7c7/R/misc.R#L120 returns always a symmetric matrix, but then all the between-group ties are counted twice.

[szhorvat]

I renamed the second function to igraph_joint_type_distribution() for consistency with joint_degree_distribution(), but left the term "mixing matrix" in the short description for the sake of searchability in the index.

Test for igraph_joint_degree_distribution() is added. One more piece is missing, a test for igraph_joint_type_distribution(). But that function is almost certainly fine, since it shares an implementation with igraph_joint_degree_distribution().

[szhorvat]

@ntamas This is now ready for review (and hopefully merging, assuming tests pass). I'd like this in the next release.

[szhorvat]

There's a small bug in the one feature I didn't test ...

[szhorvat]

It's good now.

[ntamas]

Thanks a lot!

[szhorvat]

@ntamas Thanks! AFAIC we're good to release 0.10.8. The one thing I'd do beforehand is check on why Travis is not working, and if easy, run the Travis tests once (it's exotic hardware and old compilers, so it's good to run a test before release).