Update docs (#529)

* add docs on encapsulation DAG

* Add link to JOSS paper

* Updated `Using XGI`

* updated link to permalink

* add link to JOSS paper

* organized and alphabetized resources

* removed languages from index

* fix link

* update XGI-DATA table

* added gallery example

* Updated contributors

* add figure refs

* fix links

* Updated references

CITATION.cff

@@ -65,6 +65,6 @@ preferred-citation:
   start: 5162
   title: "XGI: A Python package for higher-order interaction networks"
   type: article
-  url: "https://joss.theoj.org/papers/10.21105/joss.05162"
+  url: "https://doi.org/10.21105/joss.05162"
   volume: 8
 title: "XGI: A Python package for higher-order interaction networks"

README.md

@@ -6,6 +6,7 @@
 [![Test Status](https://github.com/xgi-org/xgi/workflows/test/badge.svg?branch=main)](https://github.com/xgi-org/xgi/actions?query=workflow%3A%22test%22)
 [![codecov](https://codecov.io/gh/xgi-org/xgi/branch/main/graph/badge.svg?token=BI6TX2WDSG)](https://codecov.io/gh/xgi-org/xgi)
 [![Good First Issue](https://img.shields.io/badge/contribute-Good%20First%20Issue-forest)](https://github.com/xgi-org/xgi/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.05162/status.svg)](https://doi.org/10.21105/joss.03968)
 [![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/115)
 
 * [**Source**](../../)
@@ -85,7 +86,7 @@ Some concrete ways that you can get involved:
 
 
 ## How to Cite
-We acknowledge the importance of good software to support research, and we note that research becomes more valuable when it is communicated effectively. To demonstrate the value of XGI, we ask that you cite XGI in your work. You can cite XGI either by going to our repository page [repository page](../../) (if you haven't already) and clicking the "cite this repository" button on the right sidebar (which will generate a citation in your preferred format) or by copying the following BibTeX entry:
+We acknowledge the importance of good software to support research, and we note that research becomes more valuable when it is communicated effectively. To demonstrate the value of XGI, we ask that you cite the XGI [paper](https://doi.org/10.21105/joss.05162) in your work. You can cite XGI either by going to our repository page [repository page](../../) (if you haven't already) and clicking the "cite this repository" button on the right sidebar (which will generate a citation in your preferred format) or by copying the following BibTeX entry:
 ```
 @article{Landry_XGI_2023,
     author = {Landry, Nicholas W. and Lucas, Maxime and Iacopini, Iacopo and Petri, Giovanni and Schwarze, Alice and Patania, Alice and Torres, Leo},
@@ -98,7 +99,7 @@ We acknowledge the importance of good software to support research, and we note
     volume = {8},
     number = {85},
     pages = {5162},
-    url = {https://joss.theoj.org/papers/10.21105/joss.05162},
+    url = {https://doi.org/10.21105/joss.05162},
 }
 ```
 
@@ -114,11 +115,20 @@ The XGI package has been supported by NSF Grant 2121905, ["HNDS-I: Using Hypergr
 
 ## Other Resources
 This library may not meet your needs and if this is this case, consider checking out these other resources:
-* [HyperNetX](https://pnnl.github.io/HyperNetX): A Python package for representing, analyzing, and visualizing hypergraphs.
-* [Hypergraph Analysis Toolbox (HAT)](https://hypergraph-analysis-toolbox.readthedocs.io): A Python/Matlab package for hypergraph construction, visualization, and analysis (Especially for Pore-C data).
+
+**Julia**
+* [HyperGraphs.jl](https://github.com/lpmdiaz/HyperGraphs.jl): A Julia package for representing, analyzing, and generating hypergraphs which may be oriented and weighted.
+* [SimpleHypergraphs.jl](https://pszufe.github.io/SimpleHypergraphs.jl/v0.1): A Julia package for representing, analyzing, and generating hypergraphs.
+
+**Python**
+* [EasyGraph](https://easy-graph.github.io/): A Python package for analyzing undirected and directed networks as well as hypergraphs.
 * [halp](http://murali-group.github.io/halp): A Python package with directed and undirected hypergraph implementations and several algorithms.
+* [Hypergraph Analysis Toolbox (HAT)](https://hypergraph-analysis-toolbox.readthedocs.io): A Python/Matlab package for hypergraph construction, visualization, and analysis (Especially for Pore-C data).
+* [Hypergraphx](https://hypergraphx.readthedocs.io): A Python for representing, analyzing, and visualizing hypergraphs.
+* [HyperNetX](https://pnnl.github.io/HyperNetX): A Python package for representing, analyzing, and visualizing hypergraphs.
+* [NetworkX](https://networkx.org): A Python package for representing, analyzing, and visualizing networks.
 * [Reticula](https://docs.reticula.network): A Python package wrapping C++ functions for representing, analyzing, and visualizing temporal and static graphs and hypergraphs.
-* [SimpleHypergraphs.jl](https://pszufe.github.io/SimpleHypergraphs.jl/v0.1): A Julia package for representing, analyzing, and generating hypergraphs.
-* [HyperGraphs.jl](https://github.com/lpmdiaz/HyperGraphs.jl): A Julia package for representing, analyzing, and generating hypergraphs which may be oriented and weighted.
+
+
+**R**
 * [hyperG](https://cran.r-project.org/package=HyperG): An R package for storing and analyzing hypergraphs
-* [NetworkX](https://networkx.org): A Python package for representing, analyzing, and visualizing networks.

docs/source/_static/table.js

@@ -13,16 +13,15 @@ async function fetch_JSON_file(url) {
     }
  }
 
- function create_table(json_data) {
-    const body = document.body;
+function create_table(json_data) {
     const section = document.getElementById("network-statistics")
     const table = document.createElement('table');
     const table_header = document.createElement('thead')
     const table_body = document.createElement('tbody')
 
     // Create header row
     const header_row = document.createElement('tr');
-    const headers = ["Dataset", "|V|", "|E|", "|E<sub>unique</sub>|", "s<sub>max</sub>"]
+    const headers = ["Dataset", "|V|", "|E|", "|E<sup>*</sup>|", "s<sub>max</sub>"]
     const header_attrs = ["num-nodes", "num-edges", "num-unique-edges", "max-edge-size"]
 
     for (const i in headers) {

docs/source/api/convert.rst

@@ -9,6 +9,7 @@ convert package
 
    ~xgi.convert.bipartite_edges
    ~xgi.convert.bipartite_graph
+   ~xgi.encapsulation_dag
    ~xgi.convert.graph
    ~xgi.convert.higher_order_network
    ~xgi.convert.hyperedges

docs/source/api/convert/xgi.convert.encapsulation_dag.rst

@@ -0,0 +1,11 @@
+xgi.convert.encapsulation_dag
+=============================
+
+.. currentmodule:: xgi.convert.encapsulation_dag
+
+.. automodule:: xgi.convert.encapsulation_dag
+
+   .. rubric:: Functions
+
+   .. autofunction:: to_encapsulation_dag
+   .. autofunction:: empirical_subsets_filter

docs/source/contributors.rst

@@ -89,13 +89,34 @@ Contributors
         <a href="https://github.com/acombretrenouard">@acombretrenouard</a>
     </p>
 
+    <p>
+        <img src="https://github.com/aleable.png"
+            width="50" height="50" hspace="5"
+            style="border-radius: 50%; vertical-align: middle;"/>
+        <a href="https://github.com/aleable">@aleable</a>
+    </p>
+
     <p>
         <img src="https://github.com/arnaudon.png"
                 width="50" height="50" hspace="5"
                 style="border-radius: 50%; vertical-align: middle;"/>
         <a href="https://github.com/arnaudon">@arnaudon</a>
     </p>
 
+    <p>
+        <img src="https://github.com/colltoaction.png"
+            width="50" height="50" hspace="5"
+            style="border-radius: 50%; vertical-align: middle;"/>
+        <a href="https://github.com/colltoaction">@colltoaction</a>
+    </p>
+
+    <p>
+        <img src="https://github.com/doabell.png"
+            width="50" height="50" hspace="5"
+            style="border-radius: 50%; vertical-align: middle;"/>
+        <a href="https://github.com/doabell">@doabell</a>
+    </p>
+
     <p>
         <img src="https://github.com/goznalo-git.png"
             width="50" height="50" hspace="5"

docs/source/gallery.rst

@@ -7,11 +7,21 @@ Here are several examples of figures made using XGI:
 .. figure:: assets/images/XGI_2023_Fig2.png
     :width: 400
     :alt: Image of a hypergraph with nodes colored and sized by different properties.
+
+    A visualization of the email-enron dataset with hyperedges of sizes 2 and 3 (all isolated nodes removed). The nodes are colored by their degree and their size proportional to the Clique motif Eigenvector Centrality. (Fig. 2 in `XGI: A Python package for higher-order interaction networks <https://doi.org/10.21105/joss.05162>`_)
 
-    A visualization of the email-enron dataset with hyperedges of sizes 2 and 3 (all isolated nodes removed). The nodes are colored by their degree and their size proportional to the Clique motif Eigenvector Centrality.
 
 .. figure:: assets/images/Simpliciality_2023_Fig3.png
     :width: 400
+    :align: left
     :alt: Image of a hypergraph with nodes colored by their simpliciality measures.
+
+    The local (A) simplicial fraction, (B) edit simpliciality, and (C) face edit simpliciality of the email-enron dataset filtered to include interactions of sizes 2 and 3. The colors of the histogram bars match the node colors on their corresponding network visualization. Nodes for which the local simpliciality is undefined are colored in grey. (Fig. 3 in `The simpliciality of higher-order networks <https://doi.org/10.1140/epjds/s13688-024-00458-1>`_)
+
+
+.. figure:: assets/images/Filtering_2024_Fig1.png
+    :width: 400
+    :alt: Image of a hypergraph decomposed into various edge-based filterings.
+
+    An illustration of a hypergraph with hyperedges of sizes two through five, visualized using XGI. This hypergraph is decomposed using different types of filtering (uniform, GEQ, LEQ, and exclusion) for different filtering parameters, :math:`k`. (Fig. 1 in `Filtering higher-order datasets <https://doi.org/10.1088/2632-072X/ad253a>`_)
 
-    The local (A) simplicial fraction, (B) edit simpliciality, and (C) face edit simpliciality of the email-enron dataset filtered to include interactions of sizes 2 and 3. The colors of the histogram bars match the node colors on their corresponding network visualization. Nodes for which the local simpliciality is undefined are colored in grey.

docs/source/index.rst

@@ -135,7 +135,8 @@ How to Cite
 ===========
 We acknowledge the importance of good software to support research, and we note
 that research becomes more valuable when it is communicated effectively. To
-demonstrate the value of XGI, we ask that you cite XGI in your work.
+demonstrate the value of XGI, we ask that you cite the XGI
+`paper <https://doi.org/10.21105/joss.05162>`_ in your work.
 You can cite XGI either by going to our repository page
 `repository page <https://github.com/xgi-org/xgi>`_ and
 clicking the "cite this repository" button on the right sidebar (which will generate
@@ -154,7 +155,7 @@ a citation in your preferred format) or by copying the following BibTeX entry:
   volume = {8},
   number = {85},
   pages = {5162},
-  url = {https://joss.theoj.org/papers/10.21105/joss.05162},
+  url = {https://doi.org/10.21105/joss.05162},
   }
 
 

docs/source/using-xgi.rst

@@ -54,6 +54,19 @@ Yuanzhao Zhang, Maxime Lucas, and Federico Battiston, "Higher-order interactions
 Preprints
 =========
 
+2024
+----
+
+Gonzalo Contreras-Aso, Regino Criado, and Miguel Romance, "Beyond directed hypergraphs: heterogeneous hypergraphs and spectral centralities", arXiv:2403.11825 (2024).
+
+:bdg-link-primary-line:`Paper <https://arxiv.org/abs/2403.11825>`
+:bdg-link-primary-line:`Code <https://github.com/goznalo-git/DirectedHyperCentrality>`
+
+Maxime Lucas, Luca Gallo, Arsham Ghavasieh, Federico Battiston, and Manlio De Domenico, "Functional reducibility of higher-order networks", arXiv:2404.08547 (2024).
+
+:bdg-link-primary-line:`Paper <https://arxiv.org/abs/2404.08547>`
+:bdg-link-primary-line:`Code <https://github.com/maximelucas/hypergraph_reducibility>`
+
 2023
 ----
 
@@ -65,6 +78,7 @@ Gonzalo Contreras-Aso, Cristian Pérez-Corral, and Miguel Romance, "Uplifting ed
 Iacopo Iacopini, Márton Karsai, and Alain Barrat, "The temporal dynamics of group interactions in higher-order social networks", arXiv:2306.09967 (2023).
 
 :bdg-link-primary-line:`Paper <https://arxiv.org/abs/2306.09967>`
+:bdg-link-primary-line:`Code <https://github.com/iaciac/temporal-group-interactions>`
 
 Yuanzhao Zhang, Per Sebastian Skardal, Federico Battiston, Giovanni Petri, Maxime Lucas, "Deeper but smaller: Higher-order interactions increase linear stability but shrink basins", arXiv:2309.16581 (2023).
 

docs/source/xgi-data.rst

@@ -9,20 +9,20 @@ Dataset format
 
 The xgi-data format for higher-order datasets is a JSON data structure with the following structure:
 
-* "hypergraph-data": This tag accesses the attributes of the entire hypergraph dataset such as the authors or dataset name.
+* :code:`hypergraph-data`: This tag accesses the attributes of the entire hypergraph dataset such as the authors or dataset name.
 
-* "node-data": This tag accesses the nodes of the hypergraph and their associated properties as a dictionary where the keys are node IDs and the corresponding values are dictionaries. If a node doesn't have any properties, the associated dictionary is empty.
+* :code:`node-data`: This tag accesses the nodes of the hypergraph and their associated properties as a dictionary where the keys are node IDs and the corresponding values are dictionaries. If a node doesn't have any properties, the associated dictionary is empty.
 
-  * "name": This tag accesses the node's name if there is one that is different from the ID specified in the hyperedges.
+  * :code:`name`: This tag accesses the node's name if there is one that is different from the ID specified in the hyperedges.
   * Other tags are user-specified based on the particular attributes provided by the dataset.
 
-* "edge-data": This tag accesses the hyperedges of the hypergraph and their associated attributes.
+* :code:`edge-data`: This tag accesses the hyperedges of the hypergraph and their associated attributes.
 
-  * "name": This tag accesses the edge's name if one is provided.
-  * "timestamp": This is the tag specifying the time associated with the hyperedge if it is given. All times are stored in ISO8601 standard.
+  * :code:`name`: This tag accesses the edge's name if one is provided.
+  * :code:`timestamp`: This is the tag specifying the time associated with the hyperedge if it is given. All times are stored in ISO8601 standard.
   * Other tags are user-specified based on the particular attributes provided by the dataset.
 
-* "edge-dict": This tag accesses the edge IDs and the corresponding nodes which participate in that hyperedge.
+* :code:`edge-dict`: This tag accesses the edge IDs and the corresponding nodes which participate in that hyperedge.
 
 Loading datasets
 ----------------
@@ -42,12 +42,10 @@ Network Statistics
 
 .. raw:: html
 
-   <style>
-   
-   </style>
-
    <script type="text/javascript">
       display_table()
    </script>
 
-   <p>More details on individual datasets are available at the <a href="https://github.com/xgi-org/xgi-data">XGI-DATA page</a>.</p>
+   <p>More details on individual datasets are available at the <a href="https://github.com/xgi-org/xgi-data">XGI-DATA page</a>.</p>
+
+   <p>In this table, |V| denotes the number of nodes, |E| denotes the number of edges, |E<sup>*</sup>| denotes the number of unique edges, and s<sub>max</sub> denotes the maximum edge size.</p>