Logit Graph

Fit, simulate, and compare logit graph models against ER / WS / BA using spectral GIC.

Installation · Quickstart · Examples · Docs · API · Changelog · Contributing · Issues · Releases

Scikit-learn-style API · leave-one-out (full conditional) offset logit · reproducible GIC (random_state) · on PyPI as logit-graph

Why Logit Graph?

pip install "logit-graph>=0.1.3"

Pipeline

flowchart LR
  G["Real graph G"] --> AIC["select_d_ensemble\n→ d̂"]
  AIC --> SIG["estimate_sigma_from_graph\n→ σ̂"]
  SIG --> CMP["GraphModelComparator"]
  CMP --> LG["LG @ d̂"]
  CMP --> BL["ER / WS / BA"]
  LG --> GIC["Spectral GIC\n(lower = better)"]
  BL --> GIC

flowchart LR
  SIM["simulate_graph\n(n, d, σ)"] --> ADJ["Adjacency"]
  ADJ --> AIC2["select_d_ensemble"]
  AIC2 --> EST["estimate_sigma_from_graph"]
  EST --> REC["Recover d̂, σ̂"]

Results at a glance

Reproducible comparison on SNAP Facebook ego 686 (random_state=0, logit-graph>=0.1.3):

Full walkthrough: examples/pypi_fit_real_network.ipynb

Installation

pip install logit-graph
# reproducible GIC comparisons:
pip install "logit-graph>=0.1.3"

Development (uses uv + Makefile):

git clone https://github.com/mbottoni/logit-graph.git && cd logit-graph
make install-dev
make test

See CONTRIBUTING.md for the full workflow.

Quickstart (60 seconds)

Paper-consistent mode: feature_mode="incremental", β=1.

Simulate and recover d̂, σ̂:

from logit_graph import simulate_graph, select_d_ensemble, estimate_sigma_from_graph

adj, meta = simulate_graph(
    200, 1, sigma=-4.0, n_iter=30_000,
    feature_mode="incremental", target_density=0.10, seed=42, return_meta=True,
)
d_hat, _ = select_d_ensemble([adj], [0, 1, 2, 3], "incremental")
sigma_hat = estimate_sigma_from_graph(adj, d_hat, "incremental")
print(f"d̂={d_hat}, σ̂={sigma_hat:.3f}")

Compare on a real network:

import networkx as nx
from logit_graph import GraphModelComparator, select_d_ensemble, estimate_sigma_from_graph

G = nx.convert_node_labels_to_integers(nx.read_edgelist("686.edges", nodetype=int))
adj = nx.to_numpy_array(G)
d_hat, _ = select_d_ensemble([adj], [0, 1, 2, 3], "incremental")

comparator = GraphModelComparator(
    d_list=[d_hat],
    lg_params={"max_iterations": 5000, "patience": 500, "check_interval": 50,
               "min_gic_threshold": 5, "er_p": 0.05, "edge_delta": None},
    other_models=["ER", "WS", "BA"],
    random_state=0,
).compare(G, "facebook_686")

print(comparator.summary_df.sort_values("gic_value"))

→ Full API reference

Examples

Self-contained notebooks under examples/ — install from PyPI, fetch data when needed.

jupyter notebook examples/pypi_estimate_d_sigma.ipynb
jupyter notebook examples/pypi_fit_real_network.ipynb

Batch platform runs (repo + local data): notebooks/refactors/ — Facebook, Twitter, G+, Twitch.

Experiments

Each experiment is a reproducible make target (fixed seeds, BLAS threads pinned) that writes artifacts to a gitignored runs/ directory. Every target has a fast -quick smoke variant; run make help for the full list with timings. Real-network experiments expect their data under data/ (gitignored) — each script prints the path it needs if the files are missing.

Naming convention. All current experiments use the equilibrium Logit-Graph and carry the lg- prefix (Makefile targets lg-*, scripts scripts/**/run_lg_*.py). Experiments for the new temporal Logit-Graph use the tlg- prefix.

Temporal Logit-Graph (tlg- prefix)

Experiments on the growth/temporal model logit(P[edge forms at t]) = σ + α·D(t−1).

Robust ANOVA on σ̂ (single-graph dyadic-robust Wald)

Tests whether the Logit-Graph intercept σ (baseline edge log-odds) differs across groups, using one graph per group with a dyadic-cluster-robust SE — no re-subsampling of a single graph, so the p-values have a genuine sampling interpretation.

Paper-figure simulations (recover known parameters)

Experiments that simulate graphs from the equilibrium Logit-Graph at known parameters and recover them.

Model selection on real networks (spectral GIC)

Rank Logit-Graph against ER / WS / BA on real graphs. Two flavors per dataset:

• make lg-gic-<dataset> — LG vs baselines scored by spectral GIC.
• make lg-gic-<dataset>-closedform — closed-form (moment-matched) baselines vs fixed-grid search, with a fairly-scored LG.

<dataset> ∈ facebook-ego, arxiv, twitch, twitter, gplus, connectomes (animal), human-connectomes (OASIS-3) — both flavors available. facebook (full MUSAE page–page graph) is GIC-only (make lg-gic-facebook).

Core API

Project layout

logit-graph/
├── src/logit_graph/     # package source
├── examples/            # PyPI-friendly tutorials
├── notebooks/           # research & batch notebooks
├── tests/               # pytest suite
├── docs/API.md          # detailed API reference
└── pyproject.toml

Community & GitHub

Suggested repo topics (set under About on GitHub):
graph-generation, networkx, statistical-modeling, random-graphs, python, pypi, graph-neural-networks, network-science

Troubleshooting

• Non-reproducible GIC? Use logit-graph>=0.1.3 and GraphModelComparator(..., random_state=0).
• Slow fits? Reduce max_iterations / patience; compare fewer baselines; set OPENBLAS_NUM_THREADS=1.
• Optional PyTorch backend — install [torch] extra; statsmodels/sklearn used by default.

Citation

@software{ottoni2025logitgraph,
  author  = {Ottoni, Maruan},
  title   = {Logit Graph: probabilistic logit-based graph modeling and selection},
  year    = {2025},
  url     = {https://github.com/mbottoni/logit-graph}
}

A formal publication citation will be added when available.