directedstructure 0.2.3__tar.gz → 0.3.0__tar.gz

{directedstructure-0.2.3 → directedstructure-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: directedstructure
-Version: 0.2.3
+Version: 0.3.0
 Summary: Infer communities, hierarchies, and their connection in directed graphs
 Author-Email: Maximilian Jerdee <mjerdee@santafe.edu>
 License-Expression: MIT
@@ -117,25 +117,44 @@ result = ds.fit(
 ### Inspect results
 
 ```python
-# Per-node hierarchy scores: posterior mean and uncertainty
-scores = result.score_means    # np.ndarray, shape [n_nodes]
-uncertainty = result.score_stds  # np.ndarray, shape [n_nodes]
+# 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 parameter summary: mean and std of each inferred parameter
-net_df = result.network_properties()
+# 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)
 
-# Integer community labels for the consensus sample
-partition = result.consensus_partition()
+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}]")
 
-# n×n co-assignment frequency matrix
-comatrix = result.coincidence_matrix()
+# 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())
 
-# High-level summary dict
-print(result.summary)
-# {'num_samples': 500, 'mean_num_groups': 3.2, 'mdl_value': 412.1}
+# 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
+# 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
@@ -143,9 +162,24 @@ samples_df = result.samples_df()
 ```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
 ```
 

{directedstructure-0.2.3 → directedstructure-0.3.0}/README.md

@@ -85,25 +85,44 @@ result = ds.fit(
 ### Inspect results
 
 ```python
-# Per-node hierarchy scores: posterior mean and uncertainty
-scores = result.score_means    # np.ndarray, shape [n_nodes]
-uncertainty = result.score_stds  # np.ndarray, shape [n_nodes]
+# 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 parameter summary: mean and std of each inferred parameter
-net_df = result.network_properties()
+# 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)
 
-# Integer community labels for the consensus sample
-partition = result.consensus_partition()
+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}]")
 
-# n×n co-assignment frequency matrix
-comatrix = result.coincidence_matrix()
+# 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())
 
-# High-level summary dict
-print(result.summary)
-# {'num_samples': 500, 'mean_num_groups': 3.2, 'mdl_value': 412.1}
+# 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
+# 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
@@ -111,9 +130,24 @@ samples_df = result.samples_df()
 ```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
 ```
 

{directedstructure-0.2.3 → directedstructure-0.3.0}/bindings/python/bindings.cpp

@@ -78,6 +78,9 @@ public:
         fill("H_A_G_b",           [](const SampleState& s){ return s.H_A_G_b; });
         fill("H_Adir_G_A_s_nu",   [](const SampleState& s){ return s.H_Adir_G_A_s_nu; });
         fill("H_s_G_b_depths",    [](const SampleState& s){ return s.H_s_G_b_depths; });
+        fill("two_layer_mode",    [](const SampleState& s){ return s.two_layer_mode; });
+        fill("weighted_SBM",      [](const SampleState& s){ return s.weighted_SBM; });
+        fill("H_W",               [](const SampleState& s){ return s.H_W; });
         fill("chain_id",          [](const SampleState& s){ return s.chain_id; });
         fill("beta",              [](const SampleState& s){ return s.beta; });
 
@@ -100,12 +103,104 @@ public:
         return d;
     }
 
+    py::dict network_properties_dict(double prob = 0.90) const {
+        auto r = FitResult::network_properties(prob);
+        py::dict d;
+        d["parameter"] = py::cast(r.parameter);
+        d["mean"]      = py::cast(r.mean);
+        d["std"]       = py::cast(r.std);
+        d["hdi_lo"]    = py::cast(r.hdi_lo);
+        d["hdi_hi"]    = py::cast(r.hdi_hi);
+        return d;
+    }
+
+    py::dict node_properties_dict(const std::string& mode = "auto") const {
+        auto r = FitResult::node_properties(mode);
+        py::dict d;
+        d["mode_used"]        = py::cast(r.mode_used);
+        d["score_mean"]       = py::cast(r.score_mean);
+        d["score_std"]        = py::cast(r.score_std);
+        d["group"]            = py::cast(r.group);
+        d["group_score_mean"] = py::cast(r.group_score_mean);
+        return d;
+    }
+
     py::object coincidence_matrix_numpy() const {
         auto flat = coincidence_matrix();
         int n = num_nodes_;
         py::module_ np = py::module_::import("numpy");
         return np.attr("reshape")(py::cast(flat), py::make_tuple(n, n));
     }
+
+    py::tuple getstate() const {
+        py::list lst;
+        for (const auto& s : samples_) {
+            py::dict d;
+            d["chain_id"]          = s.chain_id;
+            d["beta"]              = s.beta;
+            d["partition"]         = s.partition;
+            d["scores"]            = s.scores;
+            d["num_groups"]        = s.num_groups;
+            d["density_in"]        = s.density_in;
+            d["density_out"]       = s.density_out;
+            d["variation_in"]      = s.variation_in;
+            d["variation_out"]     = s.variation_out;
+            d["degree_correction"] = s.degree_correction;
+            d["individual_depth"]  = s.individual_depth;
+            d["group_depth"]       = s.group_depth;
+            d["ties_parameter"]    = s.ties_parameter;
+            d["H_A_b"]             = s.H_A_b;
+            d["H_b"]               = s.H_b;
+            d["H_M"]               = s.H_M;
+            d["H_k"]               = s.H_k;
+            d["H_A_G_k_M_b"]       = s.H_A_G_k_M_b;
+            d["H_A_G_b"]           = s.H_A_G_b;
+            d["H_Adir_G_A_s_nu"]   = s.H_Adir_G_A_s_nu;
+            d["H_s_G_b_depths"]    = s.H_s_G_b_depths;
+            d["two_layer_mode"]    = s.two_layer_mode;
+            d["weighted_SBM"]      = s.weighted_SBM;
+            d["H_W"]               = s.H_W;
+            lst.append(d);
+        }
+        return py::make_tuple(num_nodes_, lst);
+    }
+
+    static FitResultNative setstate(py::tuple state) {
+        int num_nodes = state[0].cast<int>();
+        auto lst = state[1].cast<py::list>();
+        std::vector<SampleState> samples;
+        samples.reserve(py::len(lst));
+        for (auto item : lst) {
+            auto d = item.cast<py::dict>();
+            SampleState s;
+            s.chain_id          = d["chain_id"].cast<int>();
+            s.beta              = d["beta"].cast<double>();
+            s.partition         = d["partition"].cast<std::vector<int>>();
+            s.scores            = d["scores"].cast<std::vector<double>>();
+            s.num_groups        = d["num_groups"].cast<int>();
+            s.density_in        = d["density_in"].cast<double>();
+            s.density_out       = d["density_out"].cast<double>();
+            s.variation_in      = d["variation_in"].cast<double>();
+            s.variation_out     = d["variation_out"].cast<double>();
+            s.degree_correction = d["degree_correction"].cast<double>();
+            s.individual_depth  = d["individual_depth"].cast<double>();
+            s.group_depth       = d["group_depth"].cast<double>();
+            s.ties_parameter    = d["ties_parameter"].cast<double>();
+            s.H_A_b             = d["H_A_b"].cast<double>();
+            s.H_b               = d["H_b"].cast<double>();
+            s.H_M               = d["H_M"].cast<double>();
+            s.H_k               = d["H_k"].cast<double>();
+            s.H_A_G_k_M_b       = d["H_A_G_k_M_b"].cast<double>();
+            s.H_A_G_b           = d["H_A_G_b"].cast<double>();
+            s.H_Adir_G_A_s_nu   = d["H_Adir_G_A_s_nu"].cast<double>();
+            s.H_s_G_b_depths    = d["H_s_G_b_depths"].cast<double>();
+            s.two_layer_mode    = d.contains("two_layer_mode") ? d["two_layer_mode"].cast<bool>() : false;
+            s.weighted_SBM      = d.contains("weighted_SBM")  ? d["weighted_SBM"].cast<bool>()   : false;
+            s.H_W               = d.contains("H_W")           ? d["H_W"].cast<double>()           : 0.0;
+            samples.push_back(std::move(s));
+        }
+        return FitResultNative(FitResult(num_nodes, std::move(samples)));
+    }
 };
 
 // ---------------------------------------------------------------------------
@@ -116,6 +211,7 @@ PYBIND11_MODULE(MCMC_core, m) {
     // --- MCMC class (kept for testing / advanced use) ---
     py::class_<MCMC>(m, "MCMC")
         .def(py::init<
+                 std::vector<std::unordered_map<int, double>>,
                  std::vector<std::unordered_map<int, double>>,
                  std::vector<std::unordered_map<int, double>>,
                  std::vector<int>,
@@ -139,9 +235,11 @@ PYBIND11_MODULE(MCMC_core, m) {
                  const bool&,
                  int,
                  double,
-                 double> (),
+                 double,
+                 bool> (),
              py::arg("wins"),
              py::arg("ties"),
+             py::arg("group_adj") = std::vector<std::unordered_map<int, double>>{},
              py::arg("partition"),
              py::arg("partition_fixed") = false,
              py::arg("scores"),
@@ -163,7 +261,8 @@ PYBIND11_MODULE(MCMC_core, m) {
              py::arg("ties_parameter_fixed") = false,
              py::arg("seed") = 0,
              py::arg("density_in") = -1.0,
-             py::arg("density_out") = -1.0)
+             py::arg("density_out") = -1.0,
+             py::arg("weighted_SBM") = false)
            .def_readonly("num_groups",        &MCMC::num_groups)
            .def_readonly("partition",          &MCMC::partition)
            .def_readonly("scores",             &MCMC::scores)
@@ -181,8 +280,10 @@ PYBIND11_MODULE(MCMC_core, m) {
            .def_readonly("H_k",                &MCMC::H_k)
            .def_readonly("H_A_G_k_M_b",        &MCMC::H_A_G_k_M_b)
            .def_readonly("H_A_G_b",            &MCMC::H_A_G_b)
+           .def_readonly("H_W",                &MCMC::H_W)
            .def_readonly("H_Adir_G_A_s_nu",    &MCMC::H_Adir_G_A_s_nu)
            .def_readonly("H_s_G_b_depths",     &MCMC::H_s_G_b_depths)
+           .def_readonly("weighted_SBM",        &MCMC::weighted_SBM)
            .def_readonly("time_H_k",                    &MCMC::time_H_k)
            .def_readonly("time_H_M",                    &MCMC::time_H_M)
            .def_readonly("time_H_A_G_k_M_b",            &MCMC::time_H_A_G_k_M_b)
@@ -191,6 +292,7 @@ PYBIND11_MODULE(MCMC_core, m) {
            .def("MCMC_sweep", &MCMC::MCMC_sweep,
                 py::arg("beta") = 1.0,
                 py::arg("num_sweeps") = 1)
+           .def("calculate_H_M", &MCMC::calculate_H_M)
            .def("change_parameter", &MCMC::change_parameter,
                 py::arg("param_name"),
                 py::arg("new_value"));
@@ -204,13 +306,26 @@ PYBIND11_MODULE(MCMC_core, m) {
         .def("coincidence_matrix",  &FitResultNative::coincidence_matrix_numpy)
         .def("score_means",         &FitResultNative::score_means)
         .def("score_stds",          &FitResultNative::score_stds)
+        .def("parameter_means",     &FitResultNative::parameter_means)
+        .def("parameter_stds",      &FitResultNative::parameter_stds)
+        .def("direction_probabilities", &FitResultNative::direction_probabilities,
+             py::arg("node_a"), py::arg("node_b"), py::arg("ties_allowed") = true)
+        .def("network_properties",   &FitResultNative::network_properties_dict,
+             py::arg("prob") = 0.90)
+        .def("node_properties",     &FitResultNative::node_properties_dict,
+             py::arg("mode") = "auto")
         .def("samples_df",          &FitResultNative::samples_df)
-        .def("summary",             &FitResultNative::summary);
+        .def("summary",             &FitResultNative::summary)
+        .def("__getstate__",        &FitResultNative::getstate)
+        .def("__setstate__",        [](FitResultNative& self, py::tuple state) {
+            new (&self) FitResultNative(FitResultNative::setstate(state));
+        });
 
     // --- fit_backend: thin type-conversion wrapper around the C++ core fit() ---
     m.def("fit_backend", [](
         std::vector<std::unordered_map<int, double>> wins,
         std::vector<std::unordered_map<int, double>> ties,
+        std::vector<std::unordered_map<int, double>> group_adj,
         std::vector<int>    initial_partition,
         bool                partition_fixed,
         std::vector<double> initial_scores,
@@ -236,7 +351,8 @@ PYBIND11_MODULE(MCMC_core, m) {
         int    num_tempering_chains,
         int    seed,
         double timeout,
-        bool   show_progress
+        bool   show_progress,
+        bool   weighted_SBM
     ) {
         auto to_opt_d = [](py::object o) -> std::optional<double> {
             return o.is_none() ? std::nullopt : std::optional<double>(py::cast<double>(o));
@@ -248,6 +364,7 @@ PYBIND11_MODULE(MCMC_core, m) {
         FitParams params;
         params.wins                 = std::move(wins);
         params.ties                 = std::move(ties);
+        params.group_adj            = std::move(group_adj);
         params.initial_partition    = std::move(initial_partition);
         params.partition_fixed      = partition_fixed;
         params.initial_scores       = std::move(initial_scores);
@@ -273,41 +390,89 @@ PYBIND11_MODULE(MCMC_core, m) {
         params.num_tempering_chains = num_tempering_chains;
         params.seed                 = seed;
         params.timeout              = timeout;
+        params.weighted_SBM        = weighted_SBM;
 
-        // Progress reporting: drive a stderr thread from the on_sample callback.
+        // Progress reporting: phase-aware stderr display (pystan style).
         std::mutex mtx;
         std::condition_variable cv;
-        std::atomic<int> latest{0};
-        bool done = false;
+        std::atomic<int> warmup_done{0}, burn_done{0}, sample_done{0};
+        bool fit_finished = false;
         std::thread progress_thread;
 
         if (show_progress) {
-            params.on_sample = [&](int completed, int total) {
-                latest.store(completed, std::memory_order_relaxed);
+            params.on_warmup = [&](int completed, int) {
+                warmup_done.store(completed, std::memory_order_relaxed);
                 cv.notify_one();
-                (void)total;
             };
-            const int total = num_chains * samples_per_chain;
-            progress_thread = std::thread([&]() {
-                int last = -1;
-                auto emit = [&](int v) {
+            params.on_burn_in = [&](int completed, int) {
+                burn_done.store(completed, std::memory_order_relaxed);
+                cv.notify_one();
+            };
+            params.on_sample = [&](int completed, int) {
+                sample_done.store(completed, std::memory_order_relaxed);
+                cv.notify_one();
+            };
+
+            const int warmup_total = num_chains * param_warmup_sweeps;
+            const int burn_total   = num_chains * burn_sweeps;
+            const int sample_total = num_chains * samples_per_chain;
+
+            progress_thread = std::thread([&, warmup_total, burn_total, sample_total]() {
+                auto emit = [](const char* label, int cur, int total) {
+                    int pct = total > 0 ? static_cast<int>(100.0 * cur / total) : 100;
                     std::ostringstream ss;
-                    ss << '\r' << "Sampling progress: " << v << '/' << total
-                       << " (" << std::fixed << std::setprecision(1)
-                       << 100.0 * v / total << "%)";
+                    ss << '\r' << std::left  << std::setw(11) << label
+                       << std::right << std::setw(6) << cur << " / " << total
+                       << " [" << std::setw(3) << pct << "%]";
                     std::cerr << ss.str() << std::flush;
                 };
-                emit(0);
-                while (true) {
-                    std::unique_lock<std::mutex> lock(mtx);
-                    cv.wait_for(lock, std::chrono::milliseconds(100),
-                                [&]{ return done || latest.load() != last; });
-                    int cur = latest.load(std::memory_order_relaxed);
-                    bool stopping = done;
-                    lock.unlock();
-                    if (cur != last) { last = cur; emit(cur); }
-                    if (stopping) break;
+
+                auto run_phase = [&](std::atomic<int>& counter, int total,
+                                     const char* label) {
+                    if (total <= 0) return;
+                    emit(label, 0, total);
+                    int last = -1;
+                    while (true) {
+                        std::unique_lock<std::mutex> lock(mtx);
+                        cv.wait_for(lock, std::chrono::milliseconds(100),
+                            [&]{ return fit_finished || counter.load() != last; });
+                        int cur = counter.load(std::memory_order_relaxed);
+                        bool stopping = fit_finished;
+                        lock.unlock();
+                        if (cur != last) { emit(label, cur, total); last = cur; }
+                        if (cur >= total || stopping) break;
+                    }
+                    // Only print a final line if timeout ended the phase early.
+                    int final_cur = counter.load(std::memory_order_relaxed);
+                    if (final_cur < total)
+                        emit(label, final_cur, total);
+                    std::cerr << '\n' << std::flush;
+                };
+
+                // Show both param-warmup and burn-in under a single "Warmup:" line.
+                const int total_warmup_combined = warmup_total + burn_total;
+                if (total_warmup_combined > 0) {
+                    emit("Warmup:   ", 0, total_warmup_combined);
+                    int last = -1;
+                    while (true) {
+                        std::unique_lock<std::mutex> lock(mtx);
+                        int cur = warmup_done.load(std::memory_order_relaxed)
+                                + burn_done.load(std::memory_order_relaxed);
+                        cv.wait_for(lock, std::chrono::milliseconds(100),
+                            [&]{ return fit_finished || cur != last; });
+                        cur = warmup_done.load(std::memory_order_relaxed)
+                            + burn_done.load(std::memory_order_relaxed);
+                        bool stopping = fit_finished;
+                        lock.unlock();
+                        if (cur != last) { emit("Warmup:   ", cur, total_warmup_combined); last = cur; }
+                        if (cur >= total_warmup_combined || stopping) break;
+                    }
+                    int final_cur = warmup_done.load() + burn_done.load();
+                    if (final_cur < total_warmup_combined)
+                        emit("Warmup:   ", final_cur, total_warmup_combined);
+                    std::cerr << '\n' << std::flush;
                 }
+                run_phase(sample_done, sample_total, "Sampling: ");
             });
         }
 
@@ -317,16 +482,16 @@ PYBIND11_MODULE(MCMC_core, m) {
         }();
 
         if (progress_thread.joinable()) {
-            { std::lock_guard<std::mutex> lock(mtx); done = true; }
+            { std::lock_guard<std::mutex> lock(mtx); fit_finished = true; }
             cv.notify_all();
             progress_thread.join();
-            if (show_progress) std::cerr << '\n' << std::flush;
         }
 
         return FitResultNative(std::move(result));
     },
     py::arg("wins"),
     py::arg("ties"),
+    py::arg("group_adj")                  = std::vector<std::unordered_map<int, double>>{},
     py::arg("initial_partition"),
     py::arg("partition_fixed")           = false,
     py::arg("initial_scores"),
@@ -352,5 +517,6 @@ PYBIND11_MODULE(MCMC_core, m) {
     py::arg("num_tempering_chains")      = 1,
     py::arg("seed")                      = 0,
     py::arg("timeout")                   = 60.0,
-    py::arg("show_progress")             = false);
+    py::arg("show_progress")             = false,
+    py::arg("weighted_SBM")              = false);
 }

directedstructure-0.3.0/examples/python/example.py

@@ -0,0 +1,69 @@
+from pathlib import Path
+
+import networkx as nx
+import matplotlib.pyplot as plt
+
+import directedstructure as ds
+
+here = Path(__file__).resolve().parents[1]
+G = nx.read_gml(here / "data" / "networks" / "english-football-2025.gml", label="id")
+
+result = ds.fit(
+    ds.Config(),
+    G,
+    num_chains=1,
+    samples_per_chain=500,
+    burn_sweeps=500,
+    seed=1,
+    show_progress=True,
+)
+
+print("Nodes:", G.number_of_nodes())
+print("Edges:", G.number_of_edges())
+print(result)
+
+# Network-level posterior summary: mean, std, and 90% HDI for all parameters.
+# ICC and sigma_T are included. Computed in C++ — no samples_df() overhead.
+print("\nNetwork properties (90% HDI):")
+npdf = result.network_properties_df()
+print(npdf.to_string(index=False))
+
+# Per-node posterior summary: scores, community labels, group mean score.
+# Uses consensus partition for n ≤ 3000 (the Bayesian posterior summary).
+print("\nTop nodes by score:")
+node_df = result.node_properties_df()
+print(node_df.sort_values("score_mean", ascending=False).head().to_string(index=False))
+
+# Minimum description length (useful for model comparison)
+print(f"\nMDL value: {result.mdl_value:.3f}")
+
+# Full per-sample DataFrame — only materialise when raw samples are needed
+# (e.g. convergence diagnostics, joint distributions).
+samples_df = result.samples_df()
+
+# Node properties plot — scores ranked within each inferred community
+fig_a, _ = ds.plot_node_properties(result)
+fig_a.tight_layout()
+plot_a = Path(__file__).resolve().parent / "node_properties.png"
+fig_a.savefig(plot_a, dpi=150)
+plt.close(fig_a)
+print("Saved node properties plot to:", plot_a)
+
+# Adjacency matrix reordered by inferred community
+fig_b, _ = ds.plot_adjacency_matrix(result, G, title="english-football-2025")
+plot_b = Path(__file__).resolve().parent / "adjacency.png"
+fig_b.savefig(plot_b, dpi=150, bbox_inches="tight")
+plt.close(fig_b)
+print("Saved adjacency matrix to:", plot_b)
+
+# q trajectory convergence diagnostic
+fig, ax = plt.subplots(figsize=(8, 3))
+ax.plot(samples_df.index, samples_df["num_groups"], linewidth=1.5)
+ax.set_xlabel("Sample")
+ax.set_ylabel("q = num_groups")
+ax.set_title("q trajectory")
+fig.tight_layout()
+plot_path = Path(__file__).resolve().parent / "q_trajectory.png"
+fig.savefig(plot_path, dpi=150)
+plt.close(fig)
+print("Saved q trajectory to:", plot_path)

{directedstructure-0.2.3 → directedstructure-0.3.0}/python/directedstructure/src/directedstructure/__init__.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from ._version import version as __version__
 from .core import Config, Result, fit
-from .input_output import plot_node_properties, plot_MCMC_entropy, write_gml_with_inferences
+from .input_output import plot_node_properties, plot_adjacency_matrix, plot_MCMC_entropy, write_gml_with_inferences
 
 __all__ = [
     "__version__",
@@ -16,6 +16,7 @@ __all__ = [
     "Result",
     "fit",
     "plot_node_properties",
+    "plot_adjacency_matrix",
     "plot_MCMC_entropy",
     "write_gml_with_inferences",
 ]

{directedstructure-0.2.3 → directedstructure-0.3.0}/python/directedstructure/src/directedstructure/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.3'
-__version_tuple__ = version_tuple = (0, 2, 3)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'gbb517006b'
+__commit_id__ = commit_id = 'g297119596'