Describe#

Generate methods-section text and citations for a backbone – the counterpart of the narrative option of Neal’s Backbone 3.0. See the Validating a Backbone tutorial for a worked example, and From a hairball to a backbone, end to end for its place at the end of the whole workflow.

Methods-section text and citations for a backbone.

describe_backbone() is the counterpart of the narrative option of Neal’s Backbone 3.0 R package: it returns a short methods paragraph naming the method and its null model, the parameters, the multiple-testing correction, how much of the network was kept, and the papers to cite (including this package and its version).

The text is built from one registry, METHODS, which maps the name of every public scoring or extraction function to a one-sentence description and the keys of its references in REFERENCES (taken from the functions’ own References sections). The coverage policy is:

  • Described: every public function of the statistical, structural, proximity, hybrid, bipartite, hypergraph, unweighted and temporal modules that scores edges (or nodes, pairs or hyperedges) or extracts a backbone, including the bipartite projections. Short aliases such as disparity or svh and the method names accepted by the dispatch wrappers ("global", "simple", …) are resolved through ALIASES.

  • Not described (EXCLUDED, with the reason for each): the dispatch wrappers (describe the method they dispatch to), null-model building blocks (bicm, fastball), hypergraph helpers that are not backbones, result classes, and the temporal-network format conversions of temporal (that module also holds the temporal backbone methods, so it is not a helper module).

  • The helper modules filters, measures, hypergraph_io, visualization, describe and convert are not methods and are skipped.

SCORE_KEYS maps each static weighted or unweighted method to the edge attribute a cut uses (its p-value, score or *_keep flag); backbone_stability() reads it to apply the same cut to every snapshot.

The test suite checks that every public name falls in one of these groups, so a new method cannot be added without a registry entry.

Methods currently in the registry:

nx_backbone.describe_backbone(method, *, alpha=None, mtc='none', signed=False, original=None, backbone=None, style='text', **params)[source]#

Write a methods paragraph and citations for a backbone.

The counterpart of the narrative option of Neal’s Backbone 3.0: the returned text names the method and its null model (or criterion), lists the parameters, states the multiple-testing correction, reports how much of the network the backbone keeps (via measures) and cites the method’s papers and this package, with its installed version.

Parameters:
methodstring or callable

Name of a backbone function such as "disparity_filter", a short alias such as "disparity" or "svh", a method name accepted by backbone() such as "global", or the function itself. Every described method is listed in nx_backbone.describe.METHODS.

alphafloat or None, optional (default=None)

Significance level the p-values were compared with. Only valid for methods that produce p-values.

mtcstring, optional (default=”none”)

Multiple-testing correction applied before thresholding, as passed to threshold_filter() (see adjust_pvalues()).

signedbool, optional (default=False)

Whether a two-tailed (signed) test was run. Only valid for methods that take a signed argument.

originalgraph or iterable of hyperedges, optional

The input network. With backbone, the share of edges, nodes and weight kept is reported. For a temporal method, the scored graph the method returned; the number of steps and the binning are read from its graph["temporal"] record (or that of backbone).

backbonegraph, iterable of hyperedges or result object, optional

The extracted backbone.

style{“text”, “markdown”, “bibtex”}, optional (default=”text”)

"text" and "markdown" return the paragraph followed by a reference list; "bibtex" returns only the BibTeX entries.

**params

Other parameters used (for example s=0.5 or weight="weight"); they are listed in the paragraph. A weight entry also names the edge attribute used for the weight share. Parameters that change the null model get a sentence of their own: a of disparity_filter() (with a="ml" the estimate is read from backbone.graph["disparity_a"]) and unit of the count-based scorers. Weight transforms recorded by transform_weights() in the graph attributes of backbone (or else original) are reported too.

Returns:
descriptionstring

The paragraph and reference list, or BibTeX entries.

Raises:
ValueError

If method is not described in the registry, style or mtc is unknown, or alpha, mtc or signed is given for a method that does not support it.

TypeError

If original or backbone has the wrong type for the method.

See also

threshold_filter

Apply alpha and mtc to a scored graph.

compare_backbones

Compare several backbones on the same measures.

Notes

The package is cited without a year (“n.d.”) because the version, not the date, identifies the code; CITATION.cff in the repository carries the same metadata.

Examples

A disparity-filter backbone of Les Misérables at alpha = 0.05:

>>> import networkx as nx
>>> import nx_backbone as nb
>>> G = nx.les_miserables_graph()
>>> scored = nb.disparity_filter(G)
>>> bb = nb.threshold_filter(scored, "disparity_pvalue", 0.05)
>>> text = nb.describe_backbone(
...     "disparity_filter", alpha=0.05, original=G, backbone=bb
... )
>>> print(text)
We extracted the backbone with the disparity filter (Serrano et al.,
2009), which tests each edge's weight against a null model in which
each node's strength is spread uniformly at random over its edges.
Edges were kept if their p-value was below alpha = 0.05, without
correction for multiple comparisons. The backbone retains 9 of 254
edges (3.5%) and 10 of 77 non-isolated nodes (13.0%), and 17.1% of the
total edge weight. Backbones were computed with nx-backbone
version ... (Keegan, n.d.).

References

Keegan, B. C. (n.d.). nx-backbone: Backbone extraction algorithms
for complex networks (Version ...) [Python package].
https://github.com/brianckeegan/nx-backbone
Serrano, M. A., Boguñá, M., & Vespignani, A. (2009). Extracting the
multiscale backbone of complex weighted networks. Proceedings of the
National Academy of Sciences, 106(16), 6483-6488.
https://doi.org/10.1073/pnas.0808904106

The BibTeX entries for an L-Spar backbone:

>>> print(nb.describe_backbone("lspar", s=0.5, style="bibtex"))
@inproceedings{satuluri2011,
  author = {Satuluri, V. and Parthasarathy, S. and Ruan, Y.},
  title = {Local graph sparsification for scalable clustering},
  booktitle = {Proceedings of the ACM SIGMOD International Conference on Management of Data},
  pages = {721--732},
  year = {2011},
  doi = {10.1145/1989323.1989399}
}

@misc{keegan_nx_backbone,
  author = {Keegan, Brian C.},
  title = {nx-backbone: Backbone extraction algorithms for complex networks},
  version = {...},
  url = {https://github.com/brianckeegan/nx-backbone},
  note = {Python package}
}

Registry#

The registry is importable from nx_backbone.describe for building reference lists; it is not part of the top-level namespace.

nx_backbone.describe.METHODS#

Registry of every described method: function name -> Method.

nx_backbone.describe.ALIASES#

Other accepted names (short aliases and dispatch-wrapper method names).

nx_backbone.describe.EXCLUDED#

Public names in the method modules that are deliberately not described.

nx_backbone.describe.SCORE_KEYS#

Edge attribute that a cut on each static method’s output uses: a p-value (cut with threshold_filter(..., mode="below")), another score (cut with mode="above") or a *_keep flag (boolean_filter).

nx_backbone.describe.REFERENCES#

Bibliography of every method in METHODS and every correction in adjust_pvalues(), keyed by BibTeX key.

class nx_backbone.describe.Method(label, summary, refs=(), kind='weighted', test=False, builtin_mtc=None)[source]#

Bases: object

Registry entry for one backbone method.

label

Name of the method as it reads in a sentence (“the disparity filter”).

summary

Relative clause describing what the method scores and against which null model or criterion (“which tests …”).

refs

Keys into REFERENCES.

kind

Input the method takes: "weighted", "unweighted", "bipartite" (agent-pair projection), "hypergraph" or "temporal" (snapshots, events or spans).

test

Whether the method yields p-values to compare with alpha.

builtin_mtc

Correction the method applies itself ("bh" for SVH/SVC), in which case mtc must stay "none".

class nx_backbone.describe.Reference(key, kind, authors, year, title, venue='', volume='', number='', pages='', doi='', eprint='')[source]#

Bases: object

A bibliography entry, rendered as an in-text citation, text or BibTeX.

kind is the BibTeX entry type ("article", "inproceedings", "book" or "misc"); venue is the journal, proceedings or publisher. eprint is an arXiv identifier.

key#
kind#
authors#
year#
title#
venue = ''#
volume = ''#
number = ''#
pages = ''#
doi = ''#
eprint = ''#
cite()[source]#

In-text citation such as "Serrano et al., 2009".

text(markdown=False)[source]#

Full reference in APA-like style.

bibtex()[source]#

BibTeX entry.