Fixed docstring and added hypergraph constructor rst page

docs/source/hypconstructors.rst

@@ -0,0 +1,159 @@
+
+.. _hypconstructors:
+
+=======================
+Hypergraph Constructors
+=======================
+
+An hnx.Hypergraph H = (V,E) references a pair of disjoint sets:
+V = nodes (vertices) and E = (hyper)edges.
+
+HNX allows for multi-edges by distinguishing edges by
+their identifiers instead of their contents. For example, if
+V = {1,2,3} and E = {e1,e2,e3},
+where e1 = {1,2}, e2 = {1,2}, and e3 = {1,2,3},
+the edges e1 and e2 contain the same set of nodes and yet
+are distinct and are distinguishable within H = (V,E).
+
+HNX provides methods to easily store and
+access additional metadata such as cell, edge, and node weights.
+Metadata associated with (edge,node) incidences
+are referenced as **cell_properties**.
+Metadata associated with a single edge or node is referenced
+as its **properties**.
+
+The fundamental object needed to create a hypergraph is a **setsystem**. The
+setsystem defines the many-to-many relationships between edges and nodes in
+the hypergraph. Cell properties for the incidence pairs can be defined within
+the setsystem or in a separate pandas.Dataframe or dict.
+Edge and node properties are defined with a pandas.DataFrame or dict.
+
+SetSystems
+----------
+There are five types of setsystems currently accepted by the library.
+
+1.  **iterable of iterables** : Barebones hypergraph, which uses Pandas default
+    indexing to generate hyperedge ids. Elements must be hashable.: ::
+
+    >>> H = Hypergraph([{1,2},{1,2},{1,2,3}])
+
+2.  **dictionary of iterables** : The most basic way to express many-to-many
+    relationships providing edge ids. The elements of the iterables must be
+    hashable): ::
+
+    >>> H = Hypergraph({'e1':[1,2],'e2':[1,2],'e3':[1,2,3]})
+
+3.  **dictionary of dictionaries**  : allows cell properties to be assigned
+    to a specific (edge, node) incidence. This is particularly useful when
+    there are variable length dictionaries assigned to each pair: ::
+
+    >>> d = {'e1':{ 1: {'w':0.5, 'name': 'related_to'},
+    >>>             2: {'w':0.1, 'name': 'related_to',
+    >>>                 'startdate': '05.13.2020'}},
+    >>>      'e2':{ 1: {'w':0.52, 'name': 'owned_by'},
+    >>>             2: {'w':0.2}},
+    >>>      'e3':{ 1: {'w':0.5, 'name': 'related_to'},
+    >>>             2: {'w':0.2, 'name': 'owner_of'},
+    >>>             3: {'w':1, 'type': 'relationship'}}
+
+    >>> H = Hypergraph(d, cell_weight_col='w')
+
+4.  **pandas.DataFrame** For large datasets and for datasets with cell
+    properties it is most efficient to construct a hypergraph directly from
+    a pandas.DataFrame. Incidence pairs are in the first two columns.
+    Cell properties shared by all incidence pairs can be placed in their own
+    column of the dataframe. Variable length dictionaries of cell properties
+    particular to only some of the incidence pairs may be placed in a single
+    column of the dataframe. Representing the data above as a dataframe df:
+
+    +-----------+-----------+-----------+-----------------------------------+
+    |   col1    |   col2    |   w       |  col3                             |
+    +-----------+-----------+-----------+-----------------------------------+
+    |   e1      |   1       |   0.5     | {'name':'related_to'}             |
+    +-----------+-----------+-----------+-----------------------------------+
+    |   e1      |   2       |   0.1     | {"name":"related_to",             |
+    |           |           |           |  "startdate":"05.13.2020"}        |
+    +-----------+-----------+-----------+-----------------------------------+
+    |   e2      |   1       |   0.52    | {"name":"owned_by"}               |
+    +-----------+-----------+-----------+-----------------------------------+
+    |   e2      |   2       |   0.2     |                                   |
+    +-----------+-----------+-----------+-----------------------------------+
+    |   ...     |   ...     |   ...     | {...}                             |
+    +-----------+-----------+-----------+-----------------------------------+
+
+    The first row of the dataframe is used to reference each column. ::
+
+    >>> H = Hypergraph(df,edge_col="col1",node_col="col2",
+    >>>                 cell_weight_col="w",misc_cell_properties="col3")
+
+5.  **numpy.ndarray** For homogeneous datasets given in a *n x 2* ndarray a
+    pandas dataframe is generated and column names are added from the
+    edge_col and node_col arguments. Cell properties containing multiple data
+    types are added with a separate dataframe or dict and passed through the
+    cell_properties keyword. ::
+
+    >>> arr = np.array([['e1','1'],['e1','2'],
+    >>>                 ['e2','1'],['e2','2'],
+    >>>                 ['e3','1'],['e3','2'],['e3','3']])
+    >>> H = hnx.Hypergraph(arr, column_names=['col1','col2'])
+
+
+Edge and Node Properties
+------------------------
+Properties specific to edges and/or node can be passed through the
+keywords: **edge_properties, node_properties, properties**.
+Properties may be passed as dataframes or dicts.
+The first column or index of the dataframe or keys of the dict keys
+correspond to the edge and/or node identifiers.
+If properties are specific to an id, they may be stored in a single
+object and passed to the **properties** keyword. For example:
+
++-----------+-----------+---------------------------------------+
+|   id      |   weight  |   properties                          |
++-----------+-----------+---------------------------------------+
+|   e1      |   5.0     |   {'type':'event'}                    |
++-----------+-----------+---------------------------------------+
+|   e2      |   0.52    |   {"name":"owned_by"}                 |
++-----------+-----------+---------------------------------------+
+|   ...     |   ...     |   {...}                               |
++-----------+-----------+---------------------------------------+
+|   1       |   1.2     |   {'color':'red'}                     |
++-----------+-----------+---------------------------------------+
+|   2       |   .003    |   {'name':'Fido','color':'brown'}     |
++-----------+-----------+---------------------------------------+
+|   3       |   1.0     |    {}                                 |
++-----------+-----------+---------------------------------------+
+
+A properties dictionary should have the format: ::
+
+    dp = {id1 : {prop1:val1, prop2,val2,...}, id2 : ... }
+
+A properties dataframe may be used for nodes and edges sharing ids
+but differing in cell properties by adding a level index using 0
+for edges and 1 for nodes:
+
++-----------+-----------+-----------+---------------------------+
+|  level    |   id      |   weight  |       properties          |
++-----------+-----------+-----------+---------------------------+
+|   0       |   e1      |   5.0     |   {'type':'event'}        |
++-----------+-----------+-----------+---------------------------+
+|   0       |   e2      |    0.52   |   {"name":"owned_by"}     |
++-----------+-----------+-----------+---------------------------+
+|   ...     |   ...     |    ...    |          {...}            |
++-----------+-----------+-----------+---------------------------+
+|   1       |   1.2     |   {'color':'red'}                     |
++-----------+-----------+-----------+---------------------------+
+|   2       |   .003    |   {'name':'Fido','color':'brown'}     |
++-----------+-----------+-----------+---------------------------+
+|   ...     |   ...     |    ...    |          {...}            |
++-----------+-----------+-----------+---------------------------+
+
+
+
+Weights
+-------
+The default key for cell and object weights is "weight". The default value
+is 1. Weights may be assigned and/or a new default prescribed in the
+constructor using **cell_weight_col** and **cell_weights** for incidence pairs,
+and using **edge_weight_prop, node_weight_prop, weight_prop,
+default_edge_weight,** and **default_node_weight** for node and edge weights.

docs/source/index.rst

@@ -16,28 +16,22 @@ Why hypergraphs?
 
 Like graphs, hypergraphs capture important information about networks and relationships.  But hypergraphs do more -- they model *multi-way* relationships, where ordinary graphs only capture two-way relationships. This library serves as a repository of methods and algorithms that have proven useful over years of exploration into what hypergraphs can tell us. 
 
-.. As both vertex adjacency and edge
-.. incidence are generalized to be quantities,
-.. hypergraph paths and walks thereby have both length and *width* because of these multiway connections. 
-.. Most graph metrics have natural generalizations to hypergraphs, but since
-.. hypergraphs are basically set systems, they also admit to the powerful tools of algebraic topology,
-.. including simplicial complexes and simplicial homology, to study their structure.
+As both vertex adjacency and edge
+incidence are generalized to be quantities,
+hypergraph paths and walks have both length and *width* because of these multiway connections. 
+Most graph metrics have natural generalizations to hypergraphs, but since
+hypergraphs are basically set systems, they also admit to the powerful tools of algebraic topology,
+including simplicial complexes and simplicial homology, to study their structure.
 
 
 Our community
 -------------
 
-..
-    TODO: Link to CONTRIBUTING is broken.
-
 We have a growing community of users and contributors. For the latest software updates, and to learn about the development team, see the  :ref:`library overview<overview>`.   Have ideas to share?  We'd love to hear from you!  Our `orientation for contributors <https://github.com/pnnl/HyperNetX/blob/master/CONTRIBUTING.md>`_ can help you get started.
 
 Our values
 -------------
 
-..
-    TODO: Link to CODE_OF_CONDUCT is broken.
-
 Our shared values as software developers guide us in our day-to-day interactions and decision-making. Our open source projects are no exception. Trust, respect, collaboration and transparency are core values we believe should live and breathe within our projects. Our community welcomes participants from around the world with different experiences, unique perspectives, and great ideas to share.  See our `code of conduct <https://github.com/pnnl/HyperNetX/blob/master/CODE_OF_CONDUCT.md>`_ to learn more.
 
 Contact us
@@ -58,7 +52,8 @@ Contents
    Glossary <glossary>
    core
    A Gentle Introduction to Hypergraph Mathematics <hypergraph101>
-   HyperNetX Visualization Widget <widget>
+   Hypergraph Constructors <hypconstructors>
+   Visualization Widget <widget>
    Algorithms: Modularity and Clustering <modularity>
    Publications <publications>
    license

hypernetx/classes/hypergraph.py

@@ -236,7 +236,7 @@ class Hypergraph:
     +-----------+-----------+---------------------------------------+
     |   2       |   .003    |   {'name':'Fido','color':'brown'}     |
     +-----------+-----------+---------------------------------------+
-    |   3       |   1.0     |    {}                                   |
+    |   3       |   1.0     |    {}                                 |
     +-----------+-----------+---------------------------------------+
 
     A properties dictionary should have the format: ::