hons 0.1.0__tar.gz

hons-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Russell J. Funk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hons-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include examples/concept_network.py
+recursive-include tests *.py
+
+include examples/network_demo.py
+include docs/network_demo.png
+include docs/hons_logo.png

hons-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: hons
+Version: 0.1.0
+Summary: Select network thresholds using persistent homology.
+Author-email: "Russell J. Funk" <rfunk@umn.edu>
+License-Expression: MIT
+Project-URL: Source, https://github.com/rfunklab/hons
+Project-URL: Issues, https://github.com/rfunklab/hons/issues
+Keywords: persistent homology,network thresholding,topological data analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26.4
+Requires-Dist: pandas<4,>=2.1.4
+Requires-Dist: gudhi<3.12,>=3.10.1
+Requires-Dist: networkx<4,>=3.2
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.8; extra == "plot"
+Dynamic: license-file
+
+# Higher-order network selection
+
+<img src="https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/hons_logo.png" alt="HONS logo" width="300">
+
+Network thresholding helps researchers extract interpretable structure from dense relational data by removing nodes or edges according to their properties. Choosing the cutoffs is harder: a ground-truth network is rarely available, thresholds are often selected by trial and error, and small changes can produce substantially different networks. Criteria based on individual nodes or edges can also overlook connections that contribute to higher-order structure.
+
+**HONS selects thresholds for numerical node attributes or edge weights using the network's cycles and cavities.** These features depend on how groups of connections fit together, beyond counts of nodes, edges or triangles. HONS uses persistent homology to measure those features across a grid of candidate thresholds and selects the network whose topological representation changes least under nearby threshold changes. Minimum feature-count constraints let researchers specify how many cycles and cavities candidate networks must contain.
+
+## Install
+
+Use Python 3.11–3.13:
+
+```sh
+pip install hons
+```
+
+For plotting, run `pip install "hons[plot]"`.
+
+## NetworkX example
+
+The main demo starts with a generated NetworkX graph containing three connected structures and extra connections. Each node has an assigned numerical `weight` to threshold, and each edge has an entry value called `filtration`. In an application, you would supply a measured node or edge attribute, such as frequency or contact duration:
+
+```python
+import hons
+
+network = hons.example_network()
+selected = hons.threshold(
+    network,
+    node_attribute="weight",
+    lower=[0, 1, 2, 3, 4],
+    upper=[4, 5, 6, 7, 9],
+    filtration_range=(0, 1),
+    constraints=(50, 25),
+)
+
+print(network.number_of_nodes(), network.number_of_edges())    # 29 143
+print(selected.number_of_nodes(), selected.number_of_edges())  # 18 41
+```
+
+![Input network and selected network](https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/network_demo.png)
+
+Both objects are ordinary NetworkX graphs. The input remains unchanged, and the selected graph retains its node and edge attributes in their original units. Run `python examples/network_demo.py` from a source checkout to recreate the plot.
+
+The example selects nodes with `weight` between **4 and 7**, inclusive. The selected network has five positive-lifetime H1 features and three H2 features across its filtration. H1 features describe cycles; H2 features describe cavities. `constraints=(50, 25)` requires their counts to reach at least the 50th and 25th percentiles, respectively, among selectable candidate networks.
+
+## Choose candidate thresholds
+
+The `lower` and `upper` arrays define the search grid in the units of the attribute you want to threshold. The numbers above are choices for this small example. Choose bounds that cover the plausible cutoffs for your network; explicit lists, `numpy.linspace` and `numpy.geomspace` are all suitable ways to construct a grid. Grid range and spacing affect which settings are compared and which setting can be selected.
+
+Supply increasing arrays with at least two lower bounds and one upper bound. HONS evaluates every lower/upper combination. The smallest lower bound supplies a neighboring value for the score and is excluded from selection. Bounds are inclusive. A lower bound above its paired upper bound removes all nodes in node-filtering mode or all edges in edge-filtering mode.
+
+Use `node_attribute="name"` to select an induced subgraph, or `edge_attribute="name"` to filter edges while preserving all nodes. The input must be a simple, undirected NetworkX graph. HONS returns `None` when no candidate meets both feature-count constraints.
+
+## Specify the filtration
+
+A filtration describes the order in which connections enter the topology calculation. Each edge needs a finite numerical entry value: a time, a distance or another quantity appropriate to your application. Smaller values enter earlier. All vertices are present at the start, and a clique enters when its last edge enters. The attribute used to remove nodes or edges and the entry values used for persistence have separate roles.
+
+HONS accepts entry values in their original units and converts them internally to 0–1 for the persistence images. By default, the conversion uses the minimum and maximum edge values in the full input graph. Every candidate uses that same range. Set `filtration_range=(start, stop)` when you have a known observation window or want to use a fixed range across multiple input graphs. For example, use `filtration="first_seen", filtration_range=(1920, 2021)` for edges dated by first appearance. The demo explicitly uses its generating interval, `(0, 1)`.
+
+The fixed image grid and Gaussian width apply to this normalized scale. A change of units, with the range changed accordingly, preserves the calculation. A different definition of entry order can change the result. For a strength-based filtration in which stronger edges should enter earlier, use negative strength as the entry value. A zero-width normalization range maps entry values to zero. An empty input graph defaults to a 0–1 range.
+
+## Example application: scientific concepts
+
+The paper applies HONS to concepts that co-occur in scientific articles. In this application, nodes represent concepts, document frequency supplies the attribute to threshold, and an edge's first co-occurrence year supplies its entry value. `examples/concept_network.py` shows how to prepare generated article–concept records as an ordinary NetworkX graph and pass that graph to HONS. This example uses a fixed observation window across candidates. The paper's empirical analysis dates each retained network from its earliest retained concept; the replication repository preserves that preparation in the saved diagrams.
+
+| Example | Purpose | Command from a source checkout |
+| --- | --- | --- |
+| `network_demo.py` | Select from an existing graph and draw the before/after comparison. | `python examples/network_demo.py` |
+| `concept_network.py` | Prepare article–concept records for the same general API. | `python examples/concept_network.py` |
+
+The separate [hons-replication](https://github.com/rfunklab/hons-replication) repository reproduces calculations from the paper's saved persistence diagrams and demonstrates edge-weight thresholding on an open workplace contact network.
+
+## Inspect the calculation
+
+Set `return_details=True` to return `(selected, details)`. `details["grid"]` contains thresholds, network sizes, feature counts and scores; `details["filtration_range"]` records the range used for normalization. The dictionary also includes normalized persistence diagrams, image vectors and near-ties. The selected graph's `graph["hons"]` attribute records its bounds, score and feature counts.
+
+The calculation uses H1 and H2 persistence images, a 20 × 20 sampling grid per dimension, Gaussian standard deviation 0.1, lifetime weights and coefficients in Z/11Z. Essential features are included in selection; infinite deaths become 1.00001 for imaging. Neighboring image distances are divided by their parameter separations, averaged in each direction and combined by the Euclidean norm. Dense graphs can be expensive because computing H2 requires clique expansion through tetrahedra.
+
+For an existing grid of persistence diagrams, use `rho`, `objective` and `select` directly. Diagrams are pandas DataFrames with `dimension`, `birth` and `death` columns and must use a common normalized scale. Dictionary keys are `(upper_index, lower_index)`. The `persistence` helper accepts node identifiers and an edge-to-entry-value mapping; supply common `start` and `stop` bounds when comparing multiple networks. Exact minima follow sorted cell order, with near-ties reported within an absolute score tolerance of 1e-12.
+
+Run the tests from a source checkout with `python -m unittest discover -s tests`.
+
+## Paper and license
+
+Adam Schroeder, Russell Funk, Jingyi Guan, Taylor Okonek and Lori Ziegelmeier. *Higher-Order Network Structure Inference: A Topological Approach to Network Selection*.
+
+The MIT [license](LICENSE) applies to this repository's code, documentation and original assets. Contact Russell Funk at rfunk@umn.edu.

hons-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Higher-order network selection
+
+<img src="https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/hons_logo.png" alt="HONS logo" width="300">
+
+Network thresholding helps researchers extract interpretable structure from dense relational data by removing nodes or edges according to their properties. Choosing the cutoffs is harder: a ground-truth network is rarely available, thresholds are often selected by trial and error, and small changes can produce substantially different networks. Criteria based on individual nodes or edges can also overlook connections that contribute to higher-order structure.
+
+**HONS selects thresholds for numerical node attributes or edge weights using the network's cycles and cavities.** These features depend on how groups of connections fit together, beyond counts of nodes, edges or triangles. HONS uses persistent homology to measure those features across a grid of candidate thresholds and selects the network whose topological representation changes least under nearby threshold changes. Minimum feature-count constraints let researchers specify how many cycles and cavities candidate networks must contain.
+
+## Install
+
+Use Python 3.11–3.13:
+
+```sh
+pip install hons
+```
+
+For plotting, run `pip install "hons[plot]"`.
+
+## NetworkX example
+
+The main demo starts with a generated NetworkX graph containing three connected structures and extra connections. Each node has an assigned numerical `weight` to threshold, and each edge has an entry value called `filtration`. In an application, you would supply a measured node or edge attribute, such as frequency or contact duration:
+
+```python
+import hons
+
+network = hons.example_network()
+selected = hons.threshold(
+    network,
+    node_attribute="weight",
+    lower=[0, 1, 2, 3, 4],
+    upper=[4, 5, 6, 7, 9],
+    filtration_range=(0, 1),
+    constraints=(50, 25),
+)
+
+print(network.number_of_nodes(), network.number_of_edges())    # 29 143
+print(selected.number_of_nodes(), selected.number_of_edges())  # 18 41
+```
+
+![Input network and selected network](https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/network_demo.png)
+
+Both objects are ordinary NetworkX graphs. The input remains unchanged, and the selected graph retains its node and edge attributes in their original units. Run `python examples/network_demo.py` from a source checkout to recreate the plot.
+
+The example selects nodes with `weight` between **4 and 7**, inclusive. The selected network has five positive-lifetime H1 features and three H2 features across its filtration. H1 features describe cycles; H2 features describe cavities. `constraints=(50, 25)` requires their counts to reach at least the 50th and 25th percentiles, respectively, among selectable candidate networks.
+
+## Choose candidate thresholds
+
+The `lower` and `upper` arrays define the search grid in the units of the attribute you want to threshold. The numbers above are choices for this small example. Choose bounds that cover the plausible cutoffs for your network; explicit lists, `numpy.linspace` and `numpy.geomspace` are all suitable ways to construct a grid. Grid range and spacing affect which settings are compared and which setting can be selected.
+
+Supply increasing arrays with at least two lower bounds and one upper bound. HONS evaluates every lower/upper combination. The smallest lower bound supplies a neighboring value for the score and is excluded from selection. Bounds are inclusive. A lower bound above its paired upper bound removes all nodes in node-filtering mode or all edges in edge-filtering mode.
+
+Use `node_attribute="name"` to select an induced subgraph, or `edge_attribute="name"` to filter edges while preserving all nodes. The input must be a simple, undirected NetworkX graph. HONS returns `None` when no candidate meets both feature-count constraints.
+
+## Specify the filtration
+
+A filtration describes the order in which connections enter the topology calculation. Each edge needs a finite numerical entry value: a time, a distance or another quantity appropriate to your application. Smaller values enter earlier. All vertices are present at the start, and a clique enters when its last edge enters. The attribute used to remove nodes or edges and the entry values used for persistence have separate roles.
+
+HONS accepts entry values in their original units and converts them internally to 0–1 for the persistence images. By default, the conversion uses the minimum and maximum edge values in the full input graph. Every candidate uses that same range. Set `filtration_range=(start, stop)` when you have a known observation window or want to use a fixed range across multiple input graphs. For example, use `filtration="first_seen", filtration_range=(1920, 2021)` for edges dated by first appearance. The demo explicitly uses its generating interval, `(0, 1)`.
+
+The fixed image grid and Gaussian width apply to this normalized scale. A change of units, with the range changed accordingly, preserves the calculation. A different definition of entry order can change the result. For a strength-based filtration in which stronger edges should enter earlier, use negative strength as the entry value. A zero-width normalization range maps entry values to zero. An empty input graph defaults to a 0–1 range.
+
+## Example application: scientific concepts
+
+The paper applies HONS to concepts that co-occur in scientific articles. In this application, nodes represent concepts, document frequency supplies the attribute to threshold, and an edge's first co-occurrence year supplies its entry value. `examples/concept_network.py` shows how to prepare generated article–concept records as an ordinary NetworkX graph and pass that graph to HONS. This example uses a fixed observation window across candidates. The paper's empirical analysis dates each retained network from its earliest retained concept; the replication repository preserves that preparation in the saved diagrams.
+
+| Example | Purpose | Command from a source checkout |
+| --- | --- | --- |
+| `network_demo.py` | Select from an existing graph and draw the before/after comparison. | `python examples/network_demo.py` |
+| `concept_network.py` | Prepare article–concept records for the same general API. | `python examples/concept_network.py` |
+
+The separate [hons-replication](https://github.com/rfunklab/hons-replication) repository reproduces calculations from the paper's saved persistence diagrams and demonstrates edge-weight thresholding on an open workplace contact network.
+
+## Inspect the calculation
+
+Set `return_details=True` to return `(selected, details)`. `details["grid"]` contains thresholds, network sizes, feature counts and scores; `details["filtration_range"]` records the range used for normalization. The dictionary also includes normalized persistence diagrams, image vectors and near-ties. The selected graph's `graph["hons"]` attribute records its bounds, score and feature counts.
+
+The calculation uses H1 and H2 persistence images, a 20 × 20 sampling grid per dimension, Gaussian standard deviation 0.1, lifetime weights and coefficients in Z/11Z. Essential features are included in selection; infinite deaths become 1.00001 for imaging. Neighboring image distances are divided by their parameter separations, averaged in each direction and combined by the Euclidean norm. Dense graphs can be expensive because computing H2 requires clique expansion through tetrahedra.
+
+For an existing grid of persistence diagrams, use `rho`, `objective` and `select` directly. Diagrams are pandas DataFrames with `dimension`, `birth` and `death` columns and must use a common normalized scale. Dictionary keys are `(upper_index, lower_index)`. The `persistence` helper accepts node identifiers and an edge-to-entry-value mapping; supply common `start` and `stop` bounds when comparing multiple networks. Exact minima follow sorted cell order, with near-ties reported within an absolute score tolerance of 1e-12.
+
+Run the tests from a source checkout with `python -m unittest discover -s tests`.
+
+## Paper and license
+
+Adam Schroeder, Russell Funk, Jingyi Guan, Taylor Okonek and Lori Ziegelmeier. *Higher-Order Network Structure Inference: A Topological Approach to Network Selection*.
+
+The MIT [license](LICENSE) applies to this repository's code, documentation and original assets. Contact Russell Funk at rfunk@umn.edu.

hons-0.1.0/examples/concept_network.py

@@ -0,0 +1,76 @@
+"""Prepare article/concept records for the general NetworkX thresholding API."""
+from itertools import combinations, product
+from pathlib import Path
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+import hons
+
+
+def to_network(records):
+  """Count articles per concept and date edges by first co-occurrence."""
+  if records.groupby("article_id").year.nunique().ne(1).any():
+    raise ValueError("Each article must have one publication year.")
+  records = records.drop_duplicates(["article_id", "concept"])
+  counts = records.groupby("concept").article_id.nunique()
+  graph = nx.Graph()
+  graph.add_nodes_from((concept, {"frequency": int(count)}) for concept, count in counts.items())
+  for _, group in records.groupby("article_id", sort=False):
+    year = float(group.year.iloc[0])
+    for a, b in combinations(group.concept, 2):
+      previous = graph.get_edge_data(a, b, {}).get("first_seen", year)
+      graph.add_edge(a, b, first_seen=min(year, previous))
+  return graph
+
+
+def example_data():
+  """Create an octahedral network, a square, and a frequent connecting concept."""
+  articles = []
+  groups = [("x0", "x1"), ("y0", "y1"), ("z0", "z1")]
+  for group_a, group_b in combinations(groups, 2):
+    for a, b in product(group_a, group_b):
+      articles.append((2000 + len(articles) % 4, [a, b]))
+  articles.append((2008, ["x0", "x1"]))
+  for concept in ("x0", "x1", "y0", "y1", "z0", "z1"):
+    articles.append((2010, ["hub", concept]))
+  for year, pair in [(2000, ["s0", "s1"]), (2001, ["s1", "s2"]),
+                     (2002, ["s2", "s3"]), (2003, ["s3", "s0"]),
+                     (2008, ["s0", "s2"])]:
+    articles.append((year, pair))
+
+  # singleton articles vary document frequencies without introducing edges
+  frequencies = {"x0": 8, "x1": 8, "y0": 6, "y1": 6, "z0": 5,
+                 "z1": 5, "hub": 11, "s0": 4, "s1": 3, "s2": 4, "s3": 3}
+  for concept, frequency in frequencies.items():
+    current = sum(concept in concepts for _, concepts in articles)
+    for _ in range(frequency - current):
+      articles.append((2000, [concept]))
+  return pd.DataFrame(
+    [(f"a{i:03d}", year, concept)
+     for i, (year, concepts) in enumerate(articles) for concept in concepts],
+    columns=["article_id", "year", "concept"]
+  )
+
+
+def main():
+  records = example_data()
+  network = to_network(records)
+  selected, details = hons.threshold(
+    network, node_attribute="frequency", filtration="first_seen",
+    filtration_range=(records.year.min(), records.year.max()),
+    lower=[1, 3, 5, 7], upper=[7, 9, 12],
+    constraints=(50, 50), return_details=True,
+  )
+  output = Path(__file__).resolve().parent / "output" / "concept_network"
+  output.mkdir(parents=True, exist_ok=True)
+  records.to_csv(output / "articles.csv", index=False)
+  details["grid"].to_csv(output / "grid.csv", index=False)
+  print(f"{records.article_id.nunique()} articles; {len(network)} concepts; "
+        f"{len(details['grid'])} candidate networks.")
+  print(selected.graph["hons"] if selected is not None else "No feasible selection.")
+
+
+if __name__ == "__main__":
+  main()

hons-0.1.0/examples/network_demo.py

@@ -0,0 +1,29 @@
+"""Select a NetworkX graph and draw the input and output with shared positions."""
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import networkx as nx
+
+import hons
+
+network = hons.example_network()
+selected = hons.threshold(network, node_attribute="weight",
+                          lower=[0, 1, 2, 3, 4], upper=[4, 5, 6, 7, 9],
+                          filtration_range=(0, 1), constraints=(50, 25))
+positions = nx.spring_layout(network, seed=7)
+fig, axes = plt.subplots(1, 2, figsize=(10, 4.5), layout="constrained")
+for ax, graph, title in zip(axes, [network, selected], ["Input network", "Selected network"]):
+  nx.draw_networkx_edges(graph, positions, ax=ax, edge_color="#b5c2c8", width=.7)
+  nx.draw_networkx_nodes(graph, positions, ax=ax, node_size=95,
+                        node_color="#f07967" if graph is selected else "#24495b",
+                        edgecolors="#173645", linewidths=.6)
+  ax.set_title(f"{title}\n{len(graph)} nodes, {graph.number_of_edges()} edges")
+  ax.set_xlim(-1.2, 1.2)
+  ax.set_ylim(-1.2, 1.2)
+  ax.axis("off")
+output = Path(__file__).resolve().parents[1] / "docs"
+output.mkdir(exist_ok=True)
+fig.savefig(output / "network_demo.png", dpi=180)
+plt.close(fig)
+print(selected.graph["hons"])
+print(f"Saved {output / 'network_demo.png'}")

hons-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hons"
+version = "0.1.0"
+description = "Select network thresholds using persistent homology."
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Russell J. Funk", email = "rfunk@umn.edu"}]
+keywords = ["persistent homology", "network thresholding", "topological data analysis"]
+classifiers = ["Intended Audience :: Science/Research", "Topic :: Scientific/Engineering", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13"]
+dependencies = ["numpy>=1.26.4,<3", "pandas>=2.1.4,<4", "gudhi>=3.10.1,<3.12", "networkx>=3.2,<4"]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.8,<4"]
+
+[project.urls]
+Source = "https://github.com/rfunklab/hons"
+Issues = "https://github.com/rfunklab/hons/issues"
+
+[tool.setuptools]
+py-modules = ["hons"]
+package-dir = {"" = "src"}

hons-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hons-0.1.0/src/hons.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: hons
+Version: 0.1.0
+Summary: Select network thresholds using persistent homology.
+Author-email: "Russell J. Funk" <rfunk@umn.edu>
+License-Expression: MIT
+Project-URL: Source, https://github.com/rfunklab/hons
+Project-URL: Issues, https://github.com/rfunklab/hons/issues
+Keywords: persistent homology,network thresholding,topological data analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26.4
+Requires-Dist: pandas<4,>=2.1.4
+Requires-Dist: gudhi<3.12,>=3.10.1
+Requires-Dist: networkx<4,>=3.2
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.8; extra == "plot"
+Dynamic: license-file
+
+# Higher-order network selection
+
+<img src="https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/hons_logo.png" alt="HONS logo" width="300">
+
+Network thresholding helps researchers extract interpretable structure from dense relational data by removing nodes or edges according to their properties. Choosing the cutoffs is harder: a ground-truth network is rarely available, thresholds are often selected by trial and error, and small changes can produce substantially different networks. Criteria based on individual nodes or edges can also overlook connections that contribute to higher-order structure.
+
+**HONS selects thresholds for numerical node attributes or edge weights using the network's cycles and cavities.** These features depend on how groups of connections fit together, beyond counts of nodes, edges or triangles. HONS uses persistent homology to measure those features across a grid of candidate thresholds and selects the network whose topological representation changes least under nearby threshold changes. Minimum feature-count constraints let researchers specify how many cycles and cavities candidate networks must contain.
+
+## Install
+
+Use Python 3.11–3.13:
+
+```sh
+pip install hons
+```
+
+For plotting, run `pip install "hons[plot]"`.
+
+## NetworkX example
+
+The main demo starts with a generated NetworkX graph containing three connected structures and extra connections. Each node has an assigned numerical `weight` to threshold, and each edge has an entry value called `filtration`. In an application, you would supply a measured node or edge attribute, such as frequency or contact duration:
+
+```python
+import hons
+
+network = hons.example_network()
+selected = hons.threshold(
+    network,
+    node_attribute="weight",
+    lower=[0, 1, 2, 3, 4],
+    upper=[4, 5, 6, 7, 9],
+    filtration_range=(0, 1),
+    constraints=(50, 25),
+)
+
+print(network.number_of_nodes(), network.number_of_edges())    # 29 143
+print(selected.number_of_nodes(), selected.number_of_edges())  # 18 41
+```
+
+![Input network and selected network](https://raw.githubusercontent.com/rfunklab/hons/a763c0b43e692ad65491f555a7ab080b6846567b/docs/network_demo.png)
+
+Both objects are ordinary NetworkX graphs. The input remains unchanged, and the selected graph retains its node and edge attributes in their original units. Run `python examples/network_demo.py` from a source checkout to recreate the plot.
+
+The example selects nodes with `weight` between **4 and 7**, inclusive. The selected network has five positive-lifetime H1 features and three H2 features across its filtration. H1 features describe cycles; H2 features describe cavities. `constraints=(50, 25)` requires their counts to reach at least the 50th and 25th percentiles, respectively, among selectable candidate networks.
+
+## Choose candidate thresholds
+
+The `lower` and `upper` arrays define the search grid in the units of the attribute you want to threshold. The numbers above are choices for this small example. Choose bounds that cover the plausible cutoffs for your network; explicit lists, `numpy.linspace` and `numpy.geomspace` are all suitable ways to construct a grid. Grid range and spacing affect which settings are compared and which setting can be selected.
+
+Supply increasing arrays with at least two lower bounds and one upper bound. HONS evaluates every lower/upper combination. The smallest lower bound supplies a neighboring value for the score and is excluded from selection. Bounds are inclusive. A lower bound above its paired upper bound removes all nodes in node-filtering mode or all edges in edge-filtering mode.
+
+Use `node_attribute="name"` to select an induced subgraph, or `edge_attribute="name"` to filter edges while preserving all nodes. The input must be a simple, undirected NetworkX graph. HONS returns `None` when no candidate meets both feature-count constraints.
+
+## Specify the filtration
+
+A filtration describes the order in which connections enter the topology calculation. Each edge needs a finite numerical entry value: a time, a distance or another quantity appropriate to your application. Smaller values enter earlier. All vertices are present at the start, and a clique enters when its last edge enters. The attribute used to remove nodes or edges and the entry values used for persistence have separate roles.
+
+HONS accepts entry values in their original units and converts them internally to 0–1 for the persistence images. By default, the conversion uses the minimum and maximum edge values in the full input graph. Every candidate uses that same range. Set `filtration_range=(start, stop)` when you have a known observation window or want to use a fixed range across multiple input graphs. For example, use `filtration="first_seen", filtration_range=(1920, 2021)` for edges dated by first appearance. The demo explicitly uses its generating interval, `(0, 1)`.
+
+The fixed image grid and Gaussian width apply to this normalized scale. A change of units, with the range changed accordingly, preserves the calculation. A different definition of entry order can change the result. For a strength-based filtration in which stronger edges should enter earlier, use negative strength as the entry value. A zero-width normalization range maps entry values to zero. An empty input graph defaults to a 0–1 range.
+
+## Example application: scientific concepts
+
+The paper applies HONS to concepts that co-occur in scientific articles. In this application, nodes represent concepts, document frequency supplies the attribute to threshold, and an edge's first co-occurrence year supplies its entry value. `examples/concept_network.py` shows how to prepare generated article–concept records as an ordinary NetworkX graph and pass that graph to HONS. This example uses a fixed observation window across candidates. The paper's empirical analysis dates each retained network from its earliest retained concept; the replication repository preserves that preparation in the saved diagrams.
+
+| Example | Purpose | Command from a source checkout |
+| --- | --- | --- |
+| `network_demo.py` | Select from an existing graph and draw the before/after comparison. | `python examples/network_demo.py` |
+| `concept_network.py` | Prepare article–concept records for the same general API. | `python examples/concept_network.py` |
+
+The separate [hons-replication](https://github.com/rfunklab/hons-replication) repository reproduces calculations from the paper's saved persistence diagrams and demonstrates edge-weight thresholding on an open workplace contact network.
+
+## Inspect the calculation
+
+Set `return_details=True` to return `(selected, details)`. `details["grid"]` contains thresholds, network sizes, feature counts and scores; `details["filtration_range"]` records the range used for normalization. The dictionary also includes normalized persistence diagrams, image vectors and near-ties. The selected graph's `graph["hons"]` attribute records its bounds, score and feature counts.
+
+The calculation uses H1 and H2 persistence images, a 20 × 20 sampling grid per dimension, Gaussian standard deviation 0.1, lifetime weights and coefficients in Z/11Z. Essential features are included in selection; infinite deaths become 1.00001 for imaging. Neighboring image distances are divided by their parameter separations, averaged in each direction and combined by the Euclidean norm. Dense graphs can be expensive because computing H2 requires clique expansion through tetrahedra.
+
+For an existing grid of persistence diagrams, use `rho`, `objective` and `select` directly. Diagrams are pandas DataFrames with `dimension`, `birth` and `death` columns and must use a common normalized scale. Dictionary keys are `(upper_index, lower_index)`. The `persistence` helper accepts node identifiers and an edge-to-entry-value mapping; supply common `start` and `stop` bounds when comparing multiple networks. Exact minima follow sorted cell order, with near-ties reported within an absolute score tolerance of 1e-12.
+
+Run the tests from a source checkout with `python -m unittest discover -s tests`.
+
+## Paper and license
+
+Adam Schroeder, Russell Funk, Jingyi Guan, Taylor Okonek and Lori Ziegelmeier. *Higher-Order Network Structure Inference: A Topological Approach to Network Selection*.
+
+The MIT [license](LICENSE) applies to this repository's code, documentation and original assets. Contact Russell Funk at rfunk@umn.edu.

hons-0.1.0/src/hons.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+docs/hons_logo.png
+docs/network_demo.png
+examples/concept_network.py
+examples/network_demo.py
+src/hons.py
+src/hons.egg-info/PKG-INFO
+src/hons.egg-info/SOURCES.txt
+src/hons.egg-info/dependency_links.txt
+src/hons.egg-info/requires.txt
+src/hons.egg-info/top_level.txt
+tests/test_concept_example.py
+tests/test_filtration.py
+tests/test_method.py
+tests/test_network_api.py
+tests/test_properties.py

hons-0.1.0/src/hons.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hons-0.1.0/src/hons.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy<3,>=1.26.4
+pandas<4,>=2.1.4
+gudhi<3.12,>=3.10.1
+networkx<4,>=3.2
+
+[plot]
+matplotlib<4,>=3.8

hons-0.1.0/src/hons.egg-info/top_level.txt

@@ -0,0 +1 @@
+hons