Docs spiff up (#202)

* change error message in Hypergraph.__getattr__ and add docstring for the returned function
* docs: added refs for two existing but missing functions
Co-authored-by: Maxime Lucas <ml.maximelucas@gmail.com>

README.md

@@ -74,9 +74,9 @@ Leo Torres <leo@leotrs.com>
 
 Iacopo Iacopini <iacopiniiacopo@gmail.com>
 
-Maxime Lucas <maxime.lucas@isi.it>
+Maxime Lucas <maxime.lucas@centai.eu>
 
-Giovanni Petri <giovanni.petri@isi.it>
+Giovanni Petri <giovanni.petri@centai.eu>
 
 Alice Patania <apatania@uvm.edu>
 

docs/source/api/classes/xgi.classes.function.rst

@@ -23,6 +23,8 @@
    .. autofunction:: is_possible_order
    .. autofunction:: is_uniform
    .. autofunction:: max_edge_order
+   .. autofunction:: maximal_simplices
+   .. autofunction:: num_edges_order
    .. autofunction:: set_edge_attributes
    .. autofunction:: set_node_attributes
    .. autofunction:: unique_edge_sizes

docs/source/index.rst

@@ -48,6 +48,21 @@ The Comple\ **X** **G**\ roup **I**\ nteractions `(XGI) <https://github.com/Comp
 library provides data structures and algorithms for modeling and analyzing complex systems
 with group (higher-order) interactions.
 
+Many datasets can be represented as graphs, where pairs of entities (or nodes) are
+related via links (or edges).  Examples are road networks, energy grids, social
+networks, neural networks, etc.  However, in many other datasets, more than two entities
+can be related at a time.  For example, many scientists (entities) can collaborate on a
+scientific article together (links), and multiple email accounts (entities) can all
+participate on the same email thread (links).  In this latter case, graphs no longer
+present a viable alternative to represent such datasets.  It is for this kind of
+datasets, where the interactions are given among groups of more than two entities (also
+called higher-order interactions), that XGI was designed for.
+
+XGI is implemented in pure Python and is designed to seamlessly interoperate with the
+rest of the Python scientific stack (numpy, scipy, pandas, matplotlib, etc).  XGI is
+designed and developed by network scientists with the needs of network scientists in
+mind.
+
 - Repository: https://github.com/ComplexGroupInteractions/xgi
 - PyPI: https://pypi.org/project/xgi/
 - Documentation: https://xgi.readthedocs.io/
@@ -74,7 +89,7 @@ If that command does not work, you may try the following instead
 
    pip install -e .\[all\]
 
-XGI was developed and tested for Python 3.7-3.10 on Mac OS, Windows, and Ubuntu.
+XGI was developed and tested for Python 3.7-3.11 on Mac OS, Windows, and Ubuntu.
 
 
 Academic References
@@ -92,6 +107,10 @@ Academic References
 * `What are higher-order networks? <https://arxiv.org/abs/2104.11329>`_, Christian Bick,
   Elizabeth Gross, Heather A. Harrington, Michael T. Schaub.
 
+* `From networks to optimal higher-order models of complex systems
+  <https://www.nature.com/articles/s41567-019-0459-y>`_, Renaud Lambiotte, Martin
+  Rosvall, and Ingo Scholtes.
+
 
 Contributing
 ============

xgi/classes/hypergraph.py

@@ -74,7 +74,7 @@ class Hypergraph:
     Unique IDs are assigned to each node and edge internally and are used to refer to
     them throughout.
 
-    The `attr` keyword arguments are added as hypergraph attributes. To add node or ede
+    The `attr` keyword arguments are added as hypergraph attributes. To add node or edge
     attributes see :meth:`add_node` and :meth:`add_edge`.
 
     In addition to the methods listed in this page, other methods defined in the `stats`
@@ -191,17 +191,23 @@ def __setitem__(self, attr, val):
 
     def __getattr__(self, attr):
         stat = getattr(self.nodes, attr, None)
+        word = "nodes"
         if stat is None:
             stat = getattr(self.edges, attr, None)
+            word = "edges"
         if stat is None:
+            word = None
             raise AttributeError(
-                f'stat "{attr}" not among available node or edge stats'
+                f"{attr} is not a method of Hypergraph or a recognized NodeStat or EdgeStat"
             )
 
         def func(node=None, *args, **kwargs):
             val = stat(*args, **kwargs).asdict()
             return val if node is None else val[node]
 
+        func.__doc__ = f"""Equivalent to H.{word}.{attr}.asdict(). For accepted *args and
+        **kwargs, see documentation of H.{word}.{attr}."""
+
         return func
 
     def __lshift__(self, H2):

xgi/stats/__init__.py

@@ -483,7 +483,7 @@ def nodestat_func(func):
 
     >>> H.my_degree()
     Traceback (most recent call last):
-    AttributeError: stat "my_degree" not among available node or edge stats
+    AttributeError: my_degree is not a method of Hypergraph or a recognized NodeStat or EdgeStat
     >>> H.nodes.my_degree
     Traceback (most recent call last):
     AttributeError: Stat 'my_degree' not defined