feat: add H.nodes.pos stat accessor for node positions (#624) by leotrs · Pull Request #728 · xgi-org/xgi

leotrs · 2026-05-28T10:33:30Z

Summary

Closes #624. Adds pos as a first-class stat on NodeView and DiNodeView — a discoverable shortcut for the conventional \"pos\" node attribute that xgi's drawing functions use.

Why promote pos to a stat? It's already a privileged attribute name in the library (the whole reason the issue exists), and the descriptor pattern from #699 means it now appears in dir(), tab completion, and IDE autocomplete. So the natural call site becomes:

xgi.draw(H, pos=H.nodes.pos.asdict())

This is what the original issue asked for, achieved without adding a new top-level helper. Nodes without a \"pos\" attribute map to None (same as attrs(\"pos\") does today).

Changes

xgi/stats/nodestats.py: new pos function (3-line body, full docstring)
xgi/stats/dinodestats.py: same, for DiHypergraph
xgi/core/views.py: register on NodeView and DiNodeView
xgi/core/views.pyi: type stubs
xgi/drawing/draw.py: point the pos parameter docstring at H.nodes.pos.asdict()
docs/source/api/stats.rst: list it under both node-stats sections
docs/source/stats_cheatsheet.rst: add a row
tutorials/recipes/recipes.ipynb: new recipe showing the layout-store-redraw pattern

Test plan

New test_pos_stat covers Hypergraph + DiHypergraph, with and without the attribute set, and equivalence to attrs(\"pos\")
Full test suite passes (411 passed, 6 skipped)
Doctest on the new pos function passes

Add _stat_property non-data descriptor to expose built-in stats as class-level attributes on NodeView, EdgeView, DiNodeView, and DiEdgeView. Stats now appear in dir(), IDE autocomplete, and Jupyter tab completion. __getattr__ remains as fallback for user-defined stats registered via @nodestat_func. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add .pyi stub file declaring built-in stats as typed attributes on NodeView, EdgeView, DiNodeView, and DiEdgeView. This enables static analysis tools (Pylance, PyCharm, mypy) to provide autocomplete and type checking for the stats interface. Also adds py.typed marker and configures pyproject.toml to include stub files in package distributions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ckstart - Revise "XGI in 5 minutes" to introduce the stats interface after the histogram section: shows stat objects, output formats, filtering. - Add stats cheat sheet page with quick reference for all stats, output formats, filter modes, custom stats, and visualization integration. - Link the orphaned quickstart.ipynb from the Getting Started index. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ubuntu-20.04 has been deprecated by ReadTheDocs, causing build failures. Closes #702 Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: make built-in stats discoverable in dir() and IDE autocomplete

- Add outputs to new stats cells in 5-minute notebook - Use smaller H (20 nodes, seeded) for stats demo instead of H_new (50 nodes) - Fix filter threshold to produce meaningful results - Move stats cheat sheet from top nav to User Guides page Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Stats reference page now links to cheat sheet and tutorial - Focus tutorial 6 links to cheat sheet Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

H.nodes.degree? now shows the actual degree docstring instead of the generic NodeStat class docstring. Closes #357 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update using-xgi.rst * Fix issues with PR --------- Co-authored-by: Nicholas Landry <nicholas.landry.91@gmail.com>

feat: forward stat function docstrings to stat objects

docs: introduce stats earlier, add cheat sheet, link quickstart

feat: add type stubs for stats on view classes

* docs: automated the generation of the "Using XGI" page * Response to review: added docs and fixed formatting * docs: change reverse-alphabetical to alphabetical * response to review * Update generate_using_xgi.py

v0.10.2

Add fields for Python and xgi versions in bug report template.

Update issue templates

Adds an empties parameter to cleanup() on Hypergraph, DiHypergraph, and SimplicialComplex. Defaults to False (matching the convention of other cleanup flags), so empty edges are removed by default. Closes #570 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Several stats are thin wrappers around xgi.algorithms functions but were carrying their own copies of the formulas, references, and notes. Those copies had drifted from the originals. Rewrites the wrapper stat docstrings to point at the algorithm via See Also rather than re-explaining. Adds a short stat-accessor note to each algorithm so users discover both calling conventions from either direction. Affects clustering_coefficient, local_clustering_coefficient, two_node_clustering_coefficient, clique_eigenvector_centrality, h_eigenvector_centrality, z_eigenvector_centrality, node_edge_centrality, katz_centrality, and the local simpliciality stats. Closes #621 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

A common confusion is that H.edges[0] returns the empty attribute dict rather than the members of edge 0. The behavior is correct but the docstring did not point users at the actual member-access methods. Add an upfront note and concrete examples showing both attribute access and the alternatives (.members, .memberships). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

feat: add empties option to cleanup methods (#570)

docs: deduplicate stats docstrings and link to algorithms (#621)

H.nodes? and H.edges? are common discovery moves; surface the attr-vs-member distinction in the class docstrings where users will actually encounter it (per Max's review on #727). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs: clarify that H.edges[idx] returns attributes, not members

Adds a `pos` stat on NodeView (and DiNodeView) as a discoverable shortcut for the conventional "pos" node attribute used by xgi's drawing functions. Equivalent to `H.nodes.attrs("pos")` but visible in dir(), tab completion, and IDE autocomplete. Usage: xgi.draw(H, pos=H.nodes.pos.asdict()) Also: - Updated type stubs (views.pyi) - Added entries to the stats reference page and cheat sheet - Added a recipe to tutorials/recipes/recipes.ipynb - Pointed the draw() docstring at H.nodes.pos.asdict() Closes #624 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

review-notebook-app · 2026-05-28T10:33:36Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

codecov · 2026-05-28T10:37:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.69%. Comparing base (bd8a39e) to head (7fce343).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #728   +/-   ##
=======================================
  Coverage   93.68%   93.69%           
=======================================
  Files          66       66           
  Lines        5213     5219    +6     
=======================================
+ Hits         4884     4890    +6     
  Misses        329      329

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

leotrs and others added 30 commits March 31, 2026 06:40

fix: update ReadTheDocs OS from ubuntu-20.04 to ubuntu-24.04 (#703)

a833e81

ubuntu-20.04 has been deprecated by ReadTheDocs, causing build failures. Closes #702 Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Merge pull request #699 from xgi-org/stats-discoverability

50db714

feat: make built-in stats discoverable in dir() and IDE autocomplete

Merge branch 'main' into docs-quick-wins

bfb6fa2

docs: add cross-links between stats reference, tutorial, and cheat sheet

935def0

- Stats reference page now links to cheat sheet and tutorial - Focus tutorial 6 links to cheat sheet Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: forward stat function docstrings to stat objects

a6c8df3

H.nodes.degree? now shows the actual degree docstring instead of the generic NodeStat class docstring. Closes #357 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update using-xgi.rst (#698)

47b49ab

* Update using-xgi.rst * Fix issues with PR --------- Co-authored-by: Nicholas Landry <nicholas.landry.91@gmail.com>

Add missing link to paper

53163bd

Merge pull request #708 from xgi-org/stats-docstring-forwarding

fa7de97

feat: forward stat function docstrings to stat objects

Merge pull request #701 from xgi-org/docs-quick-wins

285693d

docs: introduce stats earlier, add cheat sheet, link quickstart

Merge pull request #700 from xgi-org/stats-type-stubs

fbcda0c

feat: add type stubs for stats on view classes

docs: automated the generation of the "Using XGI" page (#710)

b8164bc

* docs: automated the generation of the "Using XGI" page * Response to review: added docs and fixed formatting * docs: change reverse-alphabetical to alphabetical * response to review * Update generate_using_xgi.py

small formatting fix to "Projects using XGI" page

b7d0f92

Merge pull request #716 from xgi-org/dev

03ebe7f

v0.10.2

format: isort and black

2a9f195

add refs to "Using XGI"

18bddba

Up-version and update changelog

a61d670

Fix: broken link

de7e67b

Added links to "Using XGI" page

b537296

Update issue templates

fbf42ab

docs: add python version fields to issue template

f07672d

Add fields for Python and xgi versions in bug report template.

Merge pull request #722 from xgi-org/docs/add_issue_templates

b7a899d

Update issue templates

Merge pull request #725 from xgi-org/remove-empty-edges

23afad9

feat: add empties option to cleanup methods (#570)

Merge pull request #726 from xgi-org/stats-docstring-deduplication

e2ccb1f

docs: deduplicate stats docstrings and link to algorithms (#621)

leotrs and others added 3 commits May 28, 2026 08:58

Merge pull request #727 from xgi-org/docs-edges-getitem

bd8a39e

docs: clarify that H.edges[idx] returns attributes, not members

leotrs mentioned this pull request May 28, 2026

feat: add with_positions option to ring_lattice (#623) #729

Open

2 tasks

leotrs changed the base branch from main to dev May 29, 2026 12:38

leotrs mentioned this pull request May 29, 2026

docs: clarify that H.edges[idx] returns attributes, not members #727

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add H.nodes.pos stat accessor for node positions (#624)#728

feat: add H.nodes.pos stat accessor for node positions (#624)#728
leotrs wants to merge 33 commits into
devfrom
stats-pos-accessor

leotrs commented May 28, 2026

Uh oh!

review-notebook-app Bot commented May 28, 2026

Uh oh!

codecov Bot commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

leotrs commented May 28, 2026

Summary

Changes

Test plan

Uh oh!

review-notebook-app Bot commented May 28, 2026

Uh oh!

codecov Bot commented May 28, 2026

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants