directedstructure 0.1.1__tar.gz → 0.3.0__tar.gz

directedstructure-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: release
+
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - published
+  pull_request:
+    paths:
+      - .github/workflows/release.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 3
+
+jobs:
+  make_sdist:
+    name: Make SDist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    name: Wheel on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14, ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel==2.20
+
+      - name: Build wheels
+        env:
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_WINDOWS: AMD64
+        run: cibuildwheel --output-dir wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: wheelhouse/*.whl
+
+  upload_all:
+    needs: [build_wheels, make_sdist]
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

{directedstructure-0.1.1 → directedstructure-0.3.0}/.gitignore

@@ -169,6 +169,8 @@ cython_debug/
 
 # setuptools_scm
 src/*/_version.py
+python/directedstructure/src/directedstructure/_version.py
+python/directedstructure/src/directedstructure/_version.pyi
 
 
 # ruff

directedstructure-0.3.0/CMakeLists.txt

@@ -0,0 +1,66 @@
+cmake_minimum_required(VERSION 3.15...3.26)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+option(BUILD_TESTING "Build Catch2-based native tests" OFF)
+
+set(PYBIND11_FINDPYTHON ON)
+find_package(pybind11 CONFIG REQUIRED)
+
+# Build a reusable core library so other language bindings can link against it
+add_library(directedstructure_core STATIC
+    src/MCMC_core.cpp
+    src/MCMC_proposals.cpp
+    src/MCMC_bookkeeping.cpp
+    src/helpers.cpp
+    src/globals.cpp
+    src/fit_result.cpp
+    src/fit.cpp)
+target_include_directories(directedstructure_core PUBLIC ${CMAKE_SOURCE_DIR}/src)
+set_target_properties(directedstructure_core PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_compile_features(directedstructure_core PUBLIC cxx_std_17)
+target_compile_options(directedstructure_core PRIVATE -O3 -march=native)
+
+# Python bindings: a small pybind11 module that links to the core library
+pybind11_add_module(MCMC_core MODULE bindings/python/bindings.cpp)
+target_link_libraries(MCMC_core PRIVATE directedstructure_core)
+target_include_directories(MCMC_core PRIVATE ${CMAKE_SOURCE_DIR}/src)
+target_compile_features(MCMC_core PRIVATE cxx_std_17)
+set_target_properties(
+  MCMC_core PROPERTIES LIBRARY_OUTPUT_DIRECTORY
+                         ${CMAKE_SOURCE_DIR}/python/directedstructure/src/directedstructure)
+install(TARGETS MCMC_core LIBRARY DESTINATION ${SKBUILD_PROJECT_NAME})
+
+if(BUILD_TESTING)
+  enable_testing()
+
+  find_package(Catch2 3 QUIET)
+  if(NOT Catch2_FOUND)
+    include(FetchContent)
+    FetchContent_Declare(
+      Catch2
+      GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+      GIT_TAG v3.7.1
+      GIT_SHALLOW TRUE
+    )
+    FetchContent_MakeAvailable(Catch2)
+    list(APPEND CMAKE_MODULE_PATH "${catch2_SOURCE_DIR}/extras")
+  endif()
+
+  add_executable(mcmc_core_test
+    tests/mcmc_core_test.cpp
+    src/MCMC_core.cpp
+    src/MCMC_proposals.cpp
+    src/MCMC_bookkeeping.cpp
+    src/helpers.cpp
+    src/globals.cpp
+    src/fit_result.cpp
+    src/fit.cpp
+  )
+  target_include_directories(mcmc_core_test PRIVATE tests src)
+  target_compile_features(mcmc_core_test PRIVATE cxx_std_17)
+  target_compile_options(mcmc_core_test PRIVATE -Wall -Wextra)
+  target_link_libraries(mcmc_core_test PRIVATE Catch2::Catch2WithMain)
+
+  include(CTest)
+  add_test(NAME mcmc_core_test COMMAND mcmc_core_test)
+endif()

directedstructure-0.3.0/Makefile

@@ -0,0 +1,102 @@
+# Makefile to build the pybind11 extension module and the C++ test harness
+
+PYTHON ?= python3
+CXX ?= g++
+BUILD_DIR := build
+SRC_DIR := src
+PKG_DIR := $(SRC_DIR)/directedstructure
+MODULE_NAME := MCMC_core
+EXT_SUFFIX := $(shell $(PYTHON) -c "import sysconfig; print(sysconfig.get_config_var('EXT_SUFFIX') or '')")
+PYBIND11_INCLUDES := $(shell $(PYTHON) -m pybind11 --includes 2>/dev/null)
+# Prefer embed flags so executables link against libpython; fall back to standard ldflags
+PY_LDFLAGS := $(shell $(PYTHON)-config --embed --ldflags 2>/dev/null || $(PYTHON)-config --ldflags 2>/dev/null || python3-config --embed --ldflags 2>/dev/null || python3-config --ldflags 2>/dev/null || echo "")
+MKDIR_P := mkdir -p
+
+CXXFLAGS := -std=c++17 -Wall -Wextra -O3 -march=native -fPIC -I$(SRC_DIR) -DDIRECTEDSTRUCTURE_PYBIND
+DEBUG_CXXFLAGS := -std=c++17 -Wall -Wextra -O0 -g -fPIC -I$(SRC_DIR) -DDIRECTEDSTRUCTURE_PYBIND
+TEST_CXXFLAGS := -std=c++17 -Wall -Wextra -O3 -march=native -fPIC -I$(SRC_DIR)
+TEST_DEBUG_CXXFLAGS := -std=c++17 -Wall -Wextra -O0 -g -fPIC -I$(SRC_DIR)
+
+SOURCES := $(SRC_DIR)/MCMC_core.cpp \
+		   $(SRC_DIR)/MCMC_proposals.cpp \
+		   $(SRC_DIR)/MCMC_bookkeeping.cpp \
+		   $(SRC_DIR)/MCMC_merge_split.cpp \
+		   $(SRC_DIR)/consensus.cpp \
+		   $(SRC_DIR)/helpers.cpp
+OBJECTS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%.o,$(SOURCES))
+TEST_CORE_OBJECTS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%_test.o,$(SOURCES))
+
+TEST_SOURCES := tests/mcmc_core_test.cpp
+TEST_OBJECTS := $(patsubst tests/%.cpp,$(BUILD_DIR)/tests_%.o,$(TEST_SOURCES))
+DEBUG_OBJECTS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%_debug.o,$(SOURCES))
+DEBUG_TEST_CORE_OBJECTS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%_test_debug.o,$(SOURCES))
+
+MODULE_TARGET := $(PKG_DIR)/$(MODULE_NAME)$(EXT_SUFFIX)
+TEST_BIN := $(BUILD_DIR)/mcmc_core_test
+TEST_BIN_DEBUG := $(BUILD_DIR)/mcmc_core_test_debug
+CSV_BIN := AddHealth_analysis/run_sampler_to_csv
+
+.PHONY: all clean test csv
+
+all: $(MODULE_TARGET) $(TEST_BIN)
+
+$(BUILD_DIR):
+	$(MKDIR_P) $(BUILD_DIR)
+
+$(PKG_DIR):
+	$(MKDIR_P) $(PKG_DIR)
+
+$(BUILD_DIR)/%.o: $(SRC_DIR)/%.cpp | $(BUILD_DIR)
+	$(CXX) $(CXXFLAGS) $(PYBIND11_INCLUDES) -c $< -o $@
+
+$(BUILD_DIR)/tests_%.o: tests/%.cpp | $(BUILD_DIR)
+	$(CXX) $(TEST_CXXFLAGS) -c $< -o $@
+
+$(BUILD_DIR)/addhealth_%.o: AddHealth_analysis/%.cpp | $(BUILD_DIR)
+	$(CXX) $(TEST_CXXFLAGS) -c $< -o $@
+
+$(BUILD_DIR)/%_test.o: $(SRC_DIR)/%.cpp | $(BUILD_DIR)
+	$(CXX) $(TEST_CXXFLAGS) -c $< -o $@
+
+$(MODULE_TARGET): $(OBJECTS) | $(PKG_DIR)
+	$(CXX) $(CXXFLAGS) -shared $^ -o $@ $(PY_LDFLAGS)
+
+$(TEST_BIN): $(TEST_OBJECTS) $(TEST_CORE_OBJECTS) | $(BUILD_DIR)
+	$(CXX) $(TEST_CXXFLAGS) $^ -o $@
+
+$(CSV_BIN): $(BUILD_DIR)/addhealth_run_sampler_to_csv.o $(TEST_CORE_OBJECTS)
+	$(CXX) $(TEST_CXXFLAGS) $^ -o $@
+
+# Debug build for valgrind
+$(BUILD_DIR)/%_debug.o: $(SRC_DIR)/%.cpp | $(BUILD_DIR)
+	$(CXX) $(DEBUG_CXXFLAGS) $(PYBIND11_INCLUDES) -c $< -o $@
+
+$(BUILD_DIR)/tests_%_debug.o: tests/%.cpp | $(BUILD_DIR)
+	$(CXX) $(TEST_DEBUG_CXXFLAGS) -c $< -o $@
+
+$(BUILD_DIR)/%_test_debug.o: $(SRC_DIR)/%.cpp | $(BUILD_DIR)
+	$(CXX) $(TEST_DEBUG_CXXFLAGS) -c $< -o $@
+
+DEBUG_TEST_OBJECTS := $(patsubst tests/%.cpp,$(BUILD_DIR)/tests_%_debug.o,$(TEST_SOURCES))
+
+$(TEST_BIN_DEBUG): $(DEBUG_TEST_OBJECTS) $(DEBUG_TEST_CORE_OBJECTS) | $(BUILD_DIR)
+	$(CXX) $(TEST_DEBUG_CXXFLAGS) $(DEBUG_TEST_OBJECTS) $(DEBUG_TEST_CORE_OBJECTS) -o $@
+
+clean:
+	rm -rf $(BUILD_DIR) $(MODULE_TARGET)
+	rm -f $(PKG_DIR)/$(MODULE_NAME)*.so $(PKG_DIR)/$(MODULE_NAME)*.pyd
+	rm -f $(PKG_DIR)/$(MODULE_NAME)*.dll
+	rm -f $(PKG_DIR)/$(MODULE_NAME)*.dylib
+	rm -f $(PKG_DIR)/$(MODULE_NAME)*.pdb
+	rm -f $(PKG_DIR)/$(MODULE_NAME)*.exp
+
+# Run the C++ harness
+test: $(TEST_BIN)
+	./$(TEST_BIN)
+
+# Build the C++ sampler-to-CSV binary only
+csv: $(CSV_BIN)
+
+# Run with valgrind (requires valgrind to be installed)
+test-valgrind: $(TEST_BIN_DEBUG)
+	valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes --verbose ./$(TEST_BIN_DEBUG)

directedstructure-0.3.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: directedstructure
+Version: 0.3.0
+Summary: Infer communities, hierarchies, and their connection in directed graphs
+Author-Email: Maximilian Jerdee <mjerdee@santafe.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/maxjerdee/directedstructure
+Project-URL: Bug Tracker, https://github.com/maxjerdee/directedstructure/issues
+Project-URL: Discussions, https://github.com/maxjerdee/directedstructure/discussions
+Project-URL: Changelog, https://github.com/maxjerdee/directedstructure/releases
+Requires-Python: <3.14,>=3.10
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas<3.0,>=2.2.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: tqdm>=4.65.0
+Description-Content-Type: text/markdown
+
+# directedstructure
+
+[![Documentation Status][rtd-badge]][rtd-link]
+[![PyPI version][pypi-version]][pypi-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+
+<!-- SPHINX-START -->
+
+<!-- prettier-ignore-start -->
+[actions-badge]:            https://github.com/maxjerdee/directedstructure/workflows/CI/badge.svg
+[actions-link]:             https://github.com/maxjerdee/directedstructure/actions
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/directedstructure
+[conda-link]:               https://github.com/conda-forge/directedstructure-feedstock
+[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
+[github-discussions-link]:  https://github.com/maxjerdee/directedstructure/discussions
+[pypi-link]:                https://pypi.org/project/directedstructure/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/directedstructure
+[pypi-version]:             https://img.shields.io/pypi/v/directedstructure
+[rtd-badge]:                https://readthedocs.org/projects/directedstructure/badge/?version=latest
+[rtd-link]:                 https://directedstructure.readthedocs.io/en/latest/?badge=latest
+
+<!-- prettier-ignore-end -->
+
+### Infer communities, hierarchies, and their connection in directed graphs
+
+##### Maximilian Jerdee, Elizabeth Bruch, Mark Newman
+
+This Python package uses Bayesian inference to identify communities and hierarchies of nodes in a directed network, as well as measure the interaction between those structures.
+
+We model community structure using a stochastic block model, hierarchy structure with a Bradley-Terry model, and their interaction according to our work (link forthcoming).
+
+## Installation
+
+```bash
+pip install directedstructure
+```
+
+Or build locally by cloning this repository and running
+
+```bash
+pip install .
+```
+
+in the base directory (requires a C++ compiler).
+
+## Usage
+
+The public API has three objects: `Config`, `fit`, and `Result`.
+
+### Load a network
+
+```python
+import directedstructure as ds
+import networkx as nx
+
+G = nx.read_gml("examples/data/networks/friends.gml")
+```
+
+Edges may carry a `type` attribute (`'dominant'` or `'neutral'`) to distinguish directed pairwise comparisons from symmetric ties. If no type information is provided all edges are treated as dominant.
+
+### Configure the model
+
+```python
+config = ds.Config(
+    groups_model="general_canonical",   # community structure preset
+    hierarchy_model="bradley_terry_ties",  # auto-selected if omitted
+    interaction="coupled",              # coupling between communities and hierarchy
+)
+```
+
+`Config` is a frozen dataclass — see the API docs for the full list of parameters (mixing variation, degree correction, individual/group depth, etc.).
+
+### Run inference
+
+```python
+result = ds.fit(
+    config, G,
+    num_samples=1000,       # posterior samples to collect
+    sweeps_per_sample=10,   # MCMC sweeps between samples
+    timeout=60.0,           # wall-clock limit in seconds
+    seed=42,
+)
+```
+
+### Inspect results
+
+```python
+# A concise summary is printed by the result itself
+print(result)
+# directedstructure.Result(n=62, samples=1000, mean_groups=3.2, mdl=412.100)
+
+# Network-level posterior summary: columns parameter, mean, std, hdi_lo, hdi_hi
+# Includes ICC (intraclass correlation) and sigma_T.
+# Computed in C++ without materialising the full samples DataFrame.
+npdf = result.network_properties_df()          # default 90% HDI
+npdf90 = result.network_properties_df(prob=0.90)
+
+icc_row = npdf[npdf["parameter"] == "ICC"].iloc[0]
+print(f"ICC = {icc_row['mean']:.3f}  90% HDI [{icc_row['hdi_lo']:.3f}, {icc_row['hdi_hi']:.3f}]")
+
+# Per-node posterior summary: columns node, score_mean, score_std, group, group_score_mean
+# For n ≤ 3000 uses the consensus partition (posterior summary);
+# for larger networks falls back to the MDL partition with a warning.
+node_df = result.node_properties_df()                    # auto
+node_df = result.node_properties_df(partition="consensus")  # always consensus
+node_df = result.node_properties_df(partition="mdl")        # always MDL (free)
+
+print(node_df.sort_values("score_mean", ascending=False).head())
+
+# Minimum description length value (model comparison)
+print(result.mdl_value)
+
+# n×n co-assignment frequency matrix (posterior)
+comatrix = result.coincidence_matrix()
+
+# Full posterior samples DataFrame (all parameters + per-node groups/scores)
+samples_df = result.samples_df()
+
+# Posterior-predictive probability of each directed outcome between two nodes.
+# Returns {"a_to_b": ..., "tie": ..., "b_to_a": ...}, values sum to 1.
+p = result.direction_probabilities("Spain", "Morocco")
+
+# Set ties_allowed=False for standard Bradley-Terry (no tie term).
+p = result.direction_probabilities("Spain", "Morocco", ties_allowed=False)
+# {"a_to_b": ..., "b_to_a": ...}
+```
+
+### Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+# Node scores ranked within each inferred community (±1 std error bars,
+# group mean line, communities labeled G1/G2/…)
+fig, ax = ds.plot_node_properties(result)
+plt.savefig("node_scores.png")
+
+# Adjacency matrix of G reordered by inferred community, with colored
+# community strips on the top and left edges.
+# G can be any graph — it does not have to be the graph used in fit().
+fig, ax = ds.plot_adjacency_matrix(result, G, cmap="Greens", title="Network")
+plt.savefig("adjacency.png")
+
+# Compose both panels side by side
+fig, axes = plt.subplots(1, 2, figsize=(12, 5))
+ds.plot_node_properties(result, ax=axes[0])
+ds.plot_adjacency_matrix(result, G, ax=axes[1])
+fig.tight_layout()
+plt.savefig("combined.png")
+
+fig, ax = ds.plot_MCMC_entropy(result)   # convergence diagnostic
+```
+
+Export the graph with inferred attributes for use in Gephi or other tools:
+
+```python
+ds.write_gml_with_inferences(G, "output.gml", result)
+```
+
+### Fixing model components
+
+Pass fixed values in `Config` to test submodels. For example, to fix group structure from node attributes and infer hierarchy only:
+
+```python
+config = ds.Config(group_attribute="department", interaction="independent")
+result = ds.fit(config, G)
+```
+
+Or fix the number of groups:
+
+```python
+config = ds.Config(num_groups=4)
+result = ds.fit(config, G)
+```
+
+### Parallel tempering
+
+For complex posteriors, enable parallel tempering:
+
+```python
+result = ds.fit(config, G, num_tempering_chains=4, beta=1.0)
+```
+
+Further usage examples can be found in the `examples/python/` directory of the
+repository and the [package documentation][rtd-link].

directedstructure-0.3.0/README.md

@@ -0,0 +1,185 @@
+# directedstructure
+
+[![Documentation Status][rtd-badge]][rtd-link]
+[![PyPI version][pypi-version]][pypi-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+
+<!-- SPHINX-START -->
+
+<!-- prettier-ignore-start -->
+[actions-badge]:            https://github.com/maxjerdee/directedstructure/workflows/CI/badge.svg
+[actions-link]:             https://github.com/maxjerdee/directedstructure/actions
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/directedstructure
+[conda-link]:               https://github.com/conda-forge/directedstructure-feedstock
+[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
+[github-discussions-link]:  https://github.com/maxjerdee/directedstructure/discussions
+[pypi-link]:                https://pypi.org/project/directedstructure/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/directedstructure
+[pypi-version]:             https://img.shields.io/pypi/v/directedstructure
+[rtd-badge]:                https://readthedocs.org/projects/directedstructure/badge/?version=latest
+[rtd-link]:                 https://directedstructure.readthedocs.io/en/latest/?badge=latest
+
+<!-- prettier-ignore-end -->
+
+### Infer communities, hierarchies, and their connection in directed graphs
+
+##### Maximilian Jerdee, Elizabeth Bruch, Mark Newman
+
+This Python package uses Bayesian inference to identify communities and hierarchies of nodes in a directed network, as well as measure the interaction between those structures.
+
+We model community structure using a stochastic block model, hierarchy structure with a Bradley-Terry model, and their interaction according to our work (link forthcoming).
+
+## Installation
+
+```bash
+pip install directedstructure
+```
+
+Or build locally by cloning this repository and running
+
+```bash
+pip install .
+```
+
+in the base directory (requires a C++ compiler).
+
+## Usage
+
+The public API has three objects: `Config`, `fit`, and `Result`.
+
+### Load a network
+
+```python
+import directedstructure as ds
+import networkx as nx
+
+G = nx.read_gml("examples/data/networks/friends.gml")
+```
+
+Edges may carry a `type` attribute (`'dominant'` or `'neutral'`) to distinguish directed pairwise comparisons from symmetric ties. If no type information is provided all edges are treated as dominant.
+
+### Configure the model
+
+```python
+config = ds.Config(
+    groups_model="general_canonical",   # community structure preset
+    hierarchy_model="bradley_terry_ties",  # auto-selected if omitted
+    interaction="coupled",              # coupling between communities and hierarchy
+)
+```
+
+`Config` is a frozen dataclass — see the API docs for the full list of parameters (mixing variation, degree correction, individual/group depth, etc.).
+
+### Run inference
+
+```python
+result = ds.fit(
+    config, G,
+    num_samples=1000,       # posterior samples to collect
+    sweeps_per_sample=10,   # MCMC sweeps between samples
+    timeout=60.0,           # wall-clock limit in seconds
+    seed=42,
+)
+```
+
+### Inspect results
+
+```python
+# A concise summary is printed by the result itself
+print(result)
+# directedstructure.Result(n=62, samples=1000, mean_groups=3.2, mdl=412.100)
+
+# Network-level posterior summary: columns parameter, mean, std, hdi_lo, hdi_hi
+# Includes ICC (intraclass correlation) and sigma_T.
+# Computed in C++ without materialising the full samples DataFrame.
+npdf = result.network_properties_df()          # default 90% HDI
+npdf90 = result.network_properties_df(prob=0.90)
+
+icc_row = npdf[npdf["parameter"] == "ICC"].iloc[0]
+print(f"ICC = {icc_row['mean']:.3f}  90% HDI [{icc_row['hdi_lo']:.3f}, {icc_row['hdi_hi']:.3f}]")
+
+# Per-node posterior summary: columns node, score_mean, score_std, group, group_score_mean
+# For n ≤ 3000 uses the consensus partition (posterior summary);
+# for larger networks falls back to the MDL partition with a warning.
+node_df = result.node_properties_df()                    # auto
+node_df = result.node_properties_df(partition="consensus")  # always consensus
+node_df = result.node_properties_df(partition="mdl")        # always MDL (free)
+
+print(node_df.sort_values("score_mean", ascending=False).head())
+
+# Minimum description length value (model comparison)
+print(result.mdl_value)
+
+# n×n co-assignment frequency matrix (posterior)
+comatrix = result.coincidence_matrix()
+
+# Full posterior samples DataFrame (all parameters + per-node groups/scores)
+samples_df = result.samples_df()
+
+# Posterior-predictive probability of each directed outcome between two nodes.
+# Returns {"a_to_b": ..., "tie": ..., "b_to_a": ...}, values sum to 1.
+p = result.direction_probabilities("Spain", "Morocco")
+
+# Set ties_allowed=False for standard Bradley-Terry (no tie term).
+p = result.direction_probabilities("Spain", "Morocco", ties_allowed=False)
+# {"a_to_b": ..., "b_to_a": ...}
+```
+
+### Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+# Node scores ranked within each inferred community (±1 std error bars,
+# group mean line, communities labeled G1/G2/…)
+fig, ax = ds.plot_node_properties(result)
+plt.savefig("node_scores.png")
+
+# Adjacency matrix of G reordered by inferred community, with colored
+# community strips on the top and left edges.
+# G can be any graph — it does not have to be the graph used in fit().
+fig, ax = ds.plot_adjacency_matrix(result, G, cmap="Greens", title="Network")
+plt.savefig("adjacency.png")
+
+# Compose both panels side by side
+fig, axes = plt.subplots(1, 2, figsize=(12, 5))
+ds.plot_node_properties(result, ax=axes[0])
+ds.plot_adjacency_matrix(result, G, ax=axes[1])
+fig.tight_layout()
+plt.savefig("combined.png")
+
+fig, ax = ds.plot_MCMC_entropy(result)   # convergence diagnostic
+```
+
+Export the graph with inferred attributes for use in Gephi or other tools:
+
+```python
+ds.write_gml_with_inferences(G, "output.gml", result)
+```
+
+### Fixing model components
+
+Pass fixed values in `Config` to test submodels. For example, to fix group structure from node attributes and infer hierarchy only:
+
+```python
+config = ds.Config(group_attribute="department", interaction="independent")
+result = ds.fit(config, G)
+```
+
+Or fix the number of groups:
+
+```python
+config = ds.Config(num_groups=4)
+result = ds.fit(config, G)
+```
+
+### Parallel tempering
+
+For complex posteriors, enable parallel tempering:
+
+```python
+result = ds.fit(config, G, num_tempering_chains=4, beta=1.0)
+```
+
+Further usage examples can be found in the `examples/python/` directory of the
+repository and the [package documentation][rtd-link].