Pull request #226: updates to documentation & Updated Factory dict me…

…thod to deepcopy dict Merge in HYP/hypernetx from updating-documentation to master * commit 'd7b2c06e019ef79259ebfe4071ac25bfdb2fc91d': bump: version 2.3.12 → 2.3.13 Updating factory dict method to deepcopy dict updates to documentation
pnnl · Jan 31, 2025 · bc07b3e · bc07b3e
2 parents 17484bf + d7b2c06
commit bc07b3e
Show file tree

Hide file tree

Showing 13 changed files with 93 additions and 45 deletions.
diff --git a/.cz.toml b/.cz.toml
@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.3.12"
+version = "2.3.13"
 version_provider = "poetry"
 version_files = [
     "pyproject.toml",

diff --git a/docs/source/algorithms/hypergraph_modularity_and_clustering.rst b/docs/source/algorithms/hypergraph_modularity_and_clustering.rst
@@ -5,7 +5,7 @@
 Modularity and Clustering
 =========================
 
-.. image:: images/ModularityScreenShot.png
+.. image:: ../images/ModularityScreenShot.png
    :width: 300px
    :align: right
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -19,14 +19,14 @@
 import os
 
 
-__version__ = "2.3.12"
+__version__ = "2.3.13"
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath("../../hypernetx"))
-
+sys.path.insert(0, os.path.abspath("../.."))
 
 # -- Project information -----------------------------------------------------
 

diff --git a/docs/source/core.rst b/docs/source/core.rst
@@ -1,12 +1,26 @@
 .. _core:
 
 ==================
-HyperNetX Packages
+HyperNetX
 ==================
 
+HyperNetX is a Python package designed for the creation, manipulation, and analysis of hypergraphs. This documentation provides a detailed reference for the core components of the library. These components are:
+
+*   **Hypergraphs:** This section documents the core data structures and classes used to represent hypergraphs within HyperNetX. It includes detailed API documentation for classes such as `Hypergraph`, `PropertyStore`, `IncidenceStore`, and `HypergraphView`, along with their associated methods and attributes.
+
+*   **Algorithms:** This section documents the algorithms implemented in HyperNetX for analyzing hypergraphs. It provides API documentation for functions related to connectivity, distance, centrality, community detection, and other hypergraph metrics.
+
+*   **Drawing:** This section documents the tools provided by HyperNetX for visualizing hypergraphs. It includes API documentation for functions and classes related to layout algorithms, rendering options, and other visualization utilities.
+
+*   **Reports:** This section documents the functionality for generating reports and summaries of hypergraph data. It provides API documentation for functions that calculate statistical information and other relevant metrics.
+
+For detailed API documentation of each component, please explore the following sections:
+
 .. toctree::
+    :maxdepth: 1
+    :titlesonly:
 
-   Hypergraphs <classes/modules.rst>
-   Algorithms <algorithms/modules.rst>
-   Drawing <drawing/modules.rst>
-   Reports <reports/modules.rst>
+    Hypergraphs <classes/modules.rst>
+    Algorithms <algorithms/modules.rst>
+    Drawing <drawing/modules.rst>
+    Reports <reports/modules.rst>
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -1,32 +1,5 @@
 .. _glossary:
 
-===================
-HNX Data Structures
-===================
-
-..  figure:: images/code_structure.png
-   :width: 300px
-   :align: right
-
-   Code structure for HNX.
-
-The HNX library centers around the idea of a :term:`hypergraph`.  
-There are many definitions of a *hypergraph*. In HNX a hypergraph
-is a tuple of three sets, :math:`H =  (V, E, \mathcal{I})`. 
-
-- :math:`V`, a set of *nodes* (aka hypernodes, vertices), distinguished by unique identifiers
-- :math:`E` a set of *edges* (aka hyperedges), distinguished by  unique identifiers
-- :math:`\mathcal{I}`, a set of *incidences*, which form a subset of :math:`E \times V`, distinguished by the pairing of unique identifiers of edges in :math:`E` and nodes in :math:`V`
-
-The incidences :math:`\mathcal{I}` can be described by a Boolean function, :math:`\mathcal{I}_B : E \times V \rightarrow \{0, 1\}`, indicating whether or not a pair is included in the hypergraph.
-
-In HNX we instantiate :math:`H =  (V, E, \mathcal{I})` using three *hypergraph views.* We can visualize this through a high 
-level diagram of our current code structure shown in Fig. 1. Here we begin with data (e.g., data frame, dictionary, 
-list of lists, etc.) that is digested via the appropriate factory method to construct property stores for nodes, 
-edges, and incidences as well as an incidence store that captures the hypergraph structure. 
-These four objects are then used to create three hypergraph views that the hypergraph object 
-uses to access and analyze the hypergraph structure and attributes.
-
 
 =====================
 Glossary of HNX terms

diff --git a/docs/source/hnx_data_structures.rst b/docs/source/hnx_data_structures.rst
@@ -0,0 +1,31 @@
+
+.. _hypconstructors:
+
+
+===================
+HNX Data Structures
+===================
+
+..  figure:: images/code_structure.png
+   :width: 300px
+   :align: right
+
+   Code structure for HNX.
+
+The HNX library centers around the idea of a :term:`hypergraph`.  
+There are many definitions of a *hypergraph*. In HNX a hypergraph
+is a tuple of three sets, :math:`H =  (V, E, \mathcal{I})`. 
+
+- :math:`V`, a set of *nodes* (aka hypernodes, vertices), distinguished by unique identifiers
+- :math:`E` a set of *edges* (aka hyperedges), distinguished by  unique identifiers
+- :math:`\mathcal{I}`, a set of *incidences*, which form a subset of :math:`E \times V`, distinguished by the pairing of unique identifiers of edges in :math:`E` and nodes in :math:`V`
+
+The incidences :math:`\mathcal{I}` can be described by a Boolean function, :math:`\mathcal{I}_B : E \times V \rightarrow \{0, 1\}`, indicating whether or not a pair is included in the hypergraph.
+
+In HNX we instantiate :math:`H =  (V, E, \mathcal{I})` using three *hypergraph views.* We can visualize this through a high 
+level diagram of our current code structure shown in Fig. 1. Here we begin with data (e.g., data frame, dictionary, 
+list of lists, etc.) that is digested via the appropriate factory method to construct property stores for nodes, 
+edges, and incidences as well as an incidence store that captures the hypergraph structure. 
+These four objects are then used to create three hypergraph views that the hypergraph object 
+uses to access and analyze the hypergraph structure and attributes.
+
diff --git a/docs/source/hypconstructors.rst b/docs/source/hypconstructors.rst
@@ -1,6 +1,8 @@
 
 .. _hypconstructors:
 
+
+
 =======================
 Hypergraph Constructors
 =======================

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -54,10 +54,8 @@ Contents
    Home <self>
    overview/index
    install
-   Glossary <glossary>
+   introduction
    core
-   A Gentle Introduction to Hypergraph Mathematics <hypergraph101>
-   Hypergraph Constructors <hypconstructors>
    Visualization Widget <widget>
    Modules <modules>
    Publications <publications>

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -5,6 +5,10 @@ Installing HyperNetX
 The recommended installation method for most users is to create a virtual environment
 and install HyperNetX from PyPi.
 
+.. code-block:: bash
+
+    pip install hypernetx
+
 .. _Github:  https://github.com/pnnl/HyperNetX
 
 HyperNetX may be cloned or forked from Github_.

diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -0,0 +1,26 @@
+.. _introduction:
+
+********************
+Introduction
+********************
+
+
+This documentation provides a comprehensive guide to the HyperNetworkX (HNX) library, a Python package for working with hypergraphs. This guide covers the mathematical foundations of hypergraphs, the key terminology used within HNX, the core data structures employed by the library, and practical methods for constructing hypergraphs. Specifically:
+
+*   **A Gentle Introduction to Hypergraph Mathematics:** This section provides a basic introduction to hypergraphs, explaining how they generalize traditional graphs and introducing key concepts like hyperedges, incidence matrices, and the duality of hypergraphs. It focuses on "gentle" hypergraphs (simple, finite, connected, etc.) to build a solid foundation before touching on more complex topics.
+
+*   **Glossary of HNX Terms:** This section offers a comprehensive glossary of terms used throughout the HNX library documentation. It defines key concepts related to hypergraphs, such as nodes, edges, incidences, various types of adjacency, connectivity, and distance, as well as HNX-specific terms like PropertyStore, IncidenceStore, and HypergraphView.
+
+*   **Data Structures:** This section describes the core data structures used within the HNX library to represent and manage hypergraphs. It explains how these structures organize nodes, edges, and incidences, and how they facilitate efficient access and manipulation of hypergraph data.
+
+*   **Hypergraph Constructors:** This section details the various ways to construct hypergraphs using the HNX library. It explains how to create hypergraphs from different data structures, including lists of lists, dictionaries, and Pandas DataFrames, and describes how to associate metadata and properties with nodes, edges, and incidences.
+
+For more detailed information on each of these areas, please explore the following sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   A Gentle Introduction to Hypergraph Mathematics <hypergraph101>
+   Glossary <glossary>
+   Data Structures <hnx_data_structures>
+   Hypergraph Constructors <hypconstructors>
diff --git a/hypernetx/__init__.py b/hypernetx/__init__.py
@@ -11,4 +11,4 @@
 from hypernetx.utils import *
 from hypernetx.utils.toys import *
 
-__version__ = "2.3.12"
+__version__ = "2.3.13"
diff --git a/hypernetx/classes/factory.py b/hypernetx/classes/factory.py
@@ -1,5 +1,5 @@
 import pandas as pd
-
+import copy
 from hypernetx import HyperNetXError
 
 
@@ -183,7 +183,7 @@ def dict_to_incidence_store_df(D):
 
 
 def dict_factory_method(
-    D,
+    Dct,
     level,
     use_indices=False,
     uid_cols=None,
@@ -199,7 +199,7 @@ def dict_factory_method(
     Parameters
     ----------
 
-    D : dictionary
+    Dct : dictionary
         dictionary of properties for either incidences, edges, or nodes
 
     level : int
@@ -233,7 +233,7 @@ def dict_factory_method(
     Pandas Dataframe of the property store in the correct format for HNX.
 
     '''
-
+    D = copy.deepcopy(Dct)
     # if no dictionary is provided set it to an empty dictionary.
     if D is None:
         DF = None

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hypernetx"
-version = "2.3.12"
+version = "2.3.13"
 description = "HyperNetX is a Python library for the creation and study of hypergraphs."
 authors = ["Brenda Praggastis <Brenda.Praggastis@pnnl.gov>", "Dustin Arendt <dustin.arendt@pnnl.gov>",
     "Sinan Aksoy <sinan.aksoy@pnnl.gov>", "Emilie Purvine <Emilie.Purvine@pnnl.gov>",