netpol 0.1.0__tar.gz

netpol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alessiogandelli
+
+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.

netpol-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: netpol
+Version: 0.1.0
+Summary: Measure polarization in (multilayer) social networks via latent-ideology scoring and Hartigan's dip test.
+License: MIT
+License-File: LICENSE
+Keywords: polarization,social-networks,networkx,multilayer,ideology,dip-test,correspondence-analysis
+Author: alessiogandelli
+Author-email: alessiogandelli99@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Dist: diptest (>=0.8)
+Requires-Dist: networkx (>=3.0)
+Requires-Dist: numpy (>=1.24)
+Requires-Dist: pandas (>=2.0)
+Project-URL: Homepage, https://github.com/alessiogandelli/netpol
+Project-URL: Repository, https://github.com/alessiogandelli/netpol
+Description-Content-Type: text/markdown
+
+# netpol
+
+Measure polarization in (multilayer) social networks.
+
+Given a network -- or a `dict` of per-layer networks -- `netpol` selects the
+top influencers, scores every user on a **bipolar latent-ideology axis** via
+correspondence analysis, and tests whether the resulting score distribution is
+multimodal (polarized) using **Hartigan's dip test**, with optional
+**Benjamini-Hochberg FDR correction** across layers.
+
+The method follows Falkenberg et al. (2021) and Flamino et al. (2021).
+
+## Install
+
+```bash
+pip install netpol
+```
+
+For local development:
+
+```bash
+git clone https://github.com/alessiogandelli/netpol && cd netpol
+poetry install
+poetry run pytest
+```
+
+## Edge convention
+
+Fixed and non-negotiable:
+
+> `a -> b` means **"a retweets/endorses b"**.
+
+Pass `networkx.DiGraph`s only (undirected graphs and `MultiDiGraph`s raise
+`TypeError`).  A multilayer network is just `dict[layer_id, DiGraph]`.
+
+## Quickstart
+
+```python
+import networkx as nx
+from netpol import LatentIdeologyScorer, PolarizationConfig, analyze_layers
+
+def layer():                       # two camps, each retweeting one influencer
+    g = nx.DiGraph()
+    for i in range(100):
+        g.add_edge(f"c1_{i}", "inf_1")
+        g.add_edge(f"c2_{i}", "inf_2")
+    return g
+
+config = PolarizationConfig(n_influencers=2, min_edges=1)
+results = analyze_layers({"l1": layer()}, config, LatentIdeologyScorer(min_sources=1))
+print(results["l1"].is_polarized)   # True
+```
+
+See `examples/quickstart.py` for a runnable version.
+
+## How it works
+
+Per layer:
+
+1. **Select influencers** -- top `n_influencers` nodes by `in_degree`
+   (configurable) with deterministic tie-breaking.
+2. **Build the interaction table** -- one row per edge *into* an influencer
+   (`['influencer', 'user']`), self-loops excluded.
+3. **Score users** -- correspondence analysis maps each user to a score in
+   `[-1, 1]` on a bipolar ideology axis (the `IdeologyScorer` plug point; the
+   built-in `LatentIdeologyScorer` is deterministic).
+4. **Test for polarization** -- Hartigan's dip test on the score distribution.
+
+Across layers, `analyze_layers` applies Benjamini-Hochberg FDR correction to
+the per-layer p-values and re-evaluates `is_polarized` against the adjusted
+values.
+
+## API
+
+- `PolarizationConfig` -- frozen config dataclass (see `netpol/config.py`).
+- `analyze_layer(graph, config, scorer=None)` -> `LayerResult`
+- `analyze_layers(layers, config, scorer=None)` -> `dict[layer_id, LayerResult]`
+- `LatentIdeologyScorer(min_sources=2, max_sources=None)` -- built-in scorer.
+- `IdeologyScorer` -- `Protocol` to plug in your own scoring.
+- `LayerResult` -- `layer_id`, `n_nodes`, `n_edges`, `influencers`, `scores`,
+  `dip_statistic`, `p_value`, `adjusted_p_value`, `is_polarized`, `skip_reason`.
+
+## What this does / doesn't do (yet)
+
+Does:
+
+- Faithful, deterministic implementation of the latent-ideology + dip-test
+  pipeline (single-layer and multilayer).
+- FDR correction, explicit `skip_reason` on every failure path (no silent
+  `except`), directed-graph validation, `min_edges` guardrail.
+
+Does **not** do yet (see [`docs/DEBATES.md`](docs/DEBATES.md) for the open
+questions and `[REVISIT]` items):
+
+- Effect-size / separation measure paired with the dip test.
+- Score normalization across layers for comparison.
+- Multivariate modality testing for `ideology_dimensions > 1`.
+- Influencer-selection scope beyond per-layer (global/hybrid), adaptive pool
+  sizing, or authority/HITS ranking.
+
+## References
+
+- M. Falkenberg et al., "Growing polarisation around climate change on social
+  media", arXiv:2112.12137 (2021).
+- J. Flamino et al., "Shifting polarization and Twitter news influencers
+  between two US presidential elections", arXiv:2111.02505 (2021).
+
+## License
+
+MIT. See `LICENSE`.
+

netpol-0.1.0/README.md

@@ -0,0 +1,110 @@
+# netpol
+
+Measure polarization in (multilayer) social networks.
+
+Given a network -- or a `dict` of per-layer networks -- `netpol` selects the
+top influencers, scores every user on a **bipolar latent-ideology axis** via
+correspondence analysis, and tests whether the resulting score distribution is
+multimodal (polarized) using **Hartigan's dip test**, with optional
+**Benjamini-Hochberg FDR correction** across layers.
+
+The method follows Falkenberg et al. (2021) and Flamino et al. (2021).
+
+## Install
+
+```bash
+pip install netpol
+```
+
+For local development:
+
+```bash
+git clone https://github.com/alessiogandelli/netpol && cd netpol
+poetry install
+poetry run pytest
+```
+
+## Edge convention
+
+Fixed and non-negotiable:
+
+> `a -> b` means **"a retweets/endorses b"**.
+
+Pass `networkx.DiGraph`s only (undirected graphs and `MultiDiGraph`s raise
+`TypeError`).  A multilayer network is just `dict[layer_id, DiGraph]`.
+
+## Quickstart
+
+```python
+import networkx as nx
+from netpol import LatentIdeologyScorer, PolarizationConfig, analyze_layers
+
+def layer():                       # two camps, each retweeting one influencer
+    g = nx.DiGraph()
+    for i in range(100):
+        g.add_edge(f"c1_{i}", "inf_1")
+        g.add_edge(f"c2_{i}", "inf_2")
+    return g
+
+config = PolarizationConfig(n_influencers=2, min_edges=1)
+results = analyze_layers({"l1": layer()}, config, LatentIdeologyScorer(min_sources=1))
+print(results["l1"].is_polarized)   # True
+```
+
+See `examples/quickstart.py` for a runnable version.
+
+## How it works
+
+Per layer:
+
+1. **Select influencers** -- top `n_influencers` nodes by `in_degree`
+   (configurable) with deterministic tie-breaking.
+2. **Build the interaction table** -- one row per edge *into* an influencer
+   (`['influencer', 'user']`), self-loops excluded.
+3. **Score users** -- correspondence analysis maps each user to a score in
+   `[-1, 1]` on a bipolar ideology axis (the `IdeologyScorer` plug point; the
+   built-in `LatentIdeologyScorer` is deterministic).
+4. **Test for polarization** -- Hartigan's dip test on the score distribution.
+
+Across layers, `analyze_layers` applies Benjamini-Hochberg FDR correction to
+the per-layer p-values and re-evaluates `is_polarized` against the adjusted
+values.
+
+## API
+
+- `PolarizationConfig` -- frozen config dataclass (see `netpol/config.py`).
+- `analyze_layer(graph, config, scorer=None)` -> `LayerResult`
+- `analyze_layers(layers, config, scorer=None)` -> `dict[layer_id, LayerResult]`
+- `LatentIdeologyScorer(min_sources=2, max_sources=None)` -- built-in scorer.
+- `IdeologyScorer` -- `Protocol` to plug in your own scoring.
+- `LayerResult` -- `layer_id`, `n_nodes`, `n_edges`, `influencers`, `scores`,
+  `dip_statistic`, `p_value`, `adjusted_p_value`, `is_polarized`, `skip_reason`.
+
+## What this does / doesn't do (yet)
+
+Does:
+
+- Faithful, deterministic implementation of the latent-ideology + dip-test
+  pipeline (single-layer and multilayer).
+- FDR correction, explicit `skip_reason` on every failure path (no silent
+  `except`), directed-graph validation, `min_edges` guardrail.
+
+Does **not** do yet (see [`docs/DEBATES.md`](docs/DEBATES.md) for the open
+questions and `[REVISIT]` items):
+
+- Effect-size / separation measure paired with the dip test.
+- Score normalization across layers for comparison.
+- Multivariate modality testing for `ideology_dimensions > 1`.
+- Influencer-selection scope beyond per-layer (global/hybrid), adaptive pool
+  sizing, or authority/HITS ranking.
+
+## References
+
+- M. Falkenberg et al., "Growing polarisation around climate change on social
+  media", arXiv:2112.12137 (2021).
+- J. Flamino et al., "Shifting polarization and Twitter news influencers
+  between two US presidential elections", arXiv:2111.02505 (2021).
+
+## License
+
+MIT. See `LICENSE`.

netpol-0.1.0/netpol/__init__.py

@@ -0,0 +1,35 @@
+"""netpol -- measure polarization in (multilayer) social networks.
+
+Given a network (or a ``dict`` of per-layer networks), the pipeline selects
+top influencers, scores every user on a bipolar latent-ideology axis via
+correspondence analysis, and tests whether the resulting score distribution
+is multimodal (polarized) using Hartigan's dip test with optional FDR
+correction across layers.
+
+Edge convention: ``a -> b`` means "a retweets/endorses b".
+"""
+
+from netpol.bimodality import apply_fdr_correction, dip_test
+from netpol.config import PolarizationConfig
+from netpol.edges import build_influencer_edges
+from netpol.ideology import LatentIdeologyScorer
+from netpol.influencers import select_influencers
+from netpol.layer_result import LayerResult
+from netpol.pipeline import analyze_layer, analyze_layers
+from netpol.scoring import IdeologyScorer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PolarizationConfig",
+    "LayerResult",
+    "IdeologyScorer",
+    "LatentIdeologyScorer",
+    "select_influencers",
+    "build_influencer_edges",
+    "dip_test",
+    "apply_fdr_correction",
+    "analyze_layer",
+    "analyze_layers",
+    "__version__",
+]

netpol-0.1.0/netpol/bimodality.py

@@ -0,0 +1,64 @@
+"""Bimodality / multimodality statistics.
+
+Hartigan's dip test detects deviations from unimodality; this is the
+"polarization signal" used by the pipeline.  Multiple-comparisons handling
+(Benjamini-Hochberg) is kept here as a dependency-free helper so it can be
+applied across layers at the orchestration level.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import diptest
+
+
+def dip_test(scores: np.ndarray) -> tuple[float, float]:
+    """Hartigan's dip test on a 1-D score distribution.
+
+    Args:
+        scores: 1-D array of ideology scores.
+
+    Returns:
+        ``(dip_statistic, p_value)``.
+
+    Raises:
+        ValueError: if ``len(scores) < 4`` (too little data for a meaningful
+            dip test).
+    """
+    scores = np.asarray(scores, dtype=float).ravel()
+    if len(scores) < 4:
+        raise ValueError(
+            f"dip test requires at least 4 scores, got {len(scores)}"
+        )
+    dip, p_value = diptest.diptest(scores)
+    return float(dip), float(p_value)
+
+
+def apply_fdr_correction(pvalues: dict) -> dict:
+    """Benjamini-Hochberg FDR correction, dependency-free.
+
+    Args:
+        pvalues: Mapping ``key -> raw p-value``.
+
+    Returns:
+        Mapping ``key -> adjusted p-value``.  Handles ``{}`` and single-entry
+        inputs without error.
+    """
+    if not pvalues:
+        return {}
+
+    keys = list(pvalues.keys())
+    values = np.asarray([pvalues[k] for k in keys], dtype=float)
+
+    n = len(values)
+    order = np.argsort(values)
+    adjusted = np.empty(n, dtype=float)
+    running_min = np.inf
+    for rank in range(n - 1, -1, -1):
+        idx = order[rank]
+        q = values[idx] * n / (rank + 1)
+        running_min = min(running_min, q)
+        adjusted[idx] = running_min
+    adjusted = np.minimum(adjusted, 1.0)
+
+    return {k: float(a) for k, a in zip(keys, adjusted)}

netpol-0.1.0/netpol/config.py

@@ -0,0 +1,59 @@
+"""Configuration for a polarization analysis run.
+
+A ``PolarizationConfig`` captures every decision that shapes what a run
+counts as "polarized": how influencers are chosen, how many, the ideology
+dimensionality, and how significance is handled.  These are methodological
+choices, not implementation details -- see ``DEBATES.md`` for the reasoning
+and open questions behind each default.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class PolarizationConfig:
+    """Immutable configuration for :func:`netpol.pipeline.analyze_layers`.
+
+    Attributes:
+        influencer_strategy: How to rank nodes when selecting influencers.
+            One of ``"degree"`` (in + out degree) or ``"in_degree"`` (authority
+            in a retweet network: "gets retweeted a lot").
+        n_influencers: Number of top influencers to select per layer.
+        ideology_dimensions: Number of latent-ideology dimensions to compute.
+            Default 1 -- a single bipolar axis with scores in ``[-1, 1]``.
+        significance_level: p-value threshold for the dip test.
+        fdr_correction: Apply Benjamini-Hochberg correction across layers.
+        min_edges: Layers with fewer directed edges than this are skipped
+            before scoring (with a ``skip_reason``), instead of crashing.
+        exclude_layers: Layer ids to skip entirely (e.g. a "misc/no topic"
+            layer).  Replaces the hard-coded ``l != -1`` of the original
+            script.
+        random_seed: Reserved for future deterministic scoring.  Note: the
+            built-in scorer is already deterministic (see ``DEBATES.md``).
+    """
+
+    influencer_strategy: str = "in_degree"
+    n_influencers: int = 30
+    ideology_dimensions: int = 1
+    significance_level: float = 0.05
+    fdr_correction: bool = True
+    min_edges: int = 10
+    exclude_layers: tuple = field(default_factory=tuple)
+    random_seed: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.influencer_strategy not in {"degree", "in_degree"}:
+            raise ValueError(
+                f"influencer_strategy must be 'degree' or 'in_degree', "
+                f"got {self.influencer_strategy!r}"
+            )
+        if self.n_influencers <= 0:
+            raise ValueError("n_influencers must be > 0")
+        if self.ideology_dimensions < 1:
+            raise ValueError("ideology_dimensions must be >= 1")
+        if not 0 < self.significance_level < 1:
+            raise ValueError("significance_level must be in (0, 1)")
+        if self.min_edges < 0:
+            raise ValueError("min_edges must be >= 0")

netpol-0.1.0/netpol/edges.py

@@ -0,0 +1,39 @@
+"""Build the influencer-user interaction table.
+
+Edge convention (fixed, stated here and in the README):
+
+    ``a -> b`` means "a retweets/endorses b".
+
+Given a list of influencer ids, this module produces the long-form table of
+interactions that the ideology scorer consumes: one row per edge *into* an
+influencer, with columns ``['influencer', 'user']`` (``user`` is the retweeter,
+``influencer`` is the retweeted account).
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import pandas as pd
+
+
+def build_influencer_edges(
+    graph: nx.DiGraph, influencers: list
+) -> pd.DataFrame:
+    """Return a DataFrame of ``(influencer, user)`` rows for edges into influencers.
+
+    One row per edge ``user -> influencer`` where ``influencer`` is in
+    ``influencers``.  Self-loops are excluded.  No deduplication and no
+    special-casing of influencer-influencer edges -- influencer selection and
+    edge construction are fully decoupled.
+
+    Implemented as a single list comprehension feeding one ``pd.DataFrame``
+    call; do not regress this to the ``pd.concat``-in-a-loop pattern.
+    """
+    influencer_set = set(influencers)
+    rows = [
+        {"influencer": u, "user": v}
+        for u in influencers
+        for v in graph.predecessors(u)
+        if v != u
+    ]
+    return pd.DataFrame(rows, columns=["influencer", "user"])

netpol-0.1.0/netpol/ideology.py

@@ -0,0 +1,158 @@
+"""Built-in latent-ideology scorer.
+
+Implements correspondence analysis (CA) to map retweet patterns onto a
+bipolar ideology axis, following the method of Falkenberg et al. (2021) and
+Flamino et al. (2021).  This is a self-contained, deterministic rewrite of the
+approach, maintained here rather than depending on the external
+``latent-ideology`` package.
+
+Method
+------
+1. From the ``(influencer, user)`` interaction table, build a weighted
+   ``user x influencer`` adjacency matrix ``A`` (weight = number of retweets).
+2. Keep only users who retweeted at least ``min_sources`` distinct
+   influencers (the ``n`` threshold of the original method) and, optionally,
+   only the top ``max_sources`` influencers by total interactions.
+3. Correspondence analysis: standardize ``A`` to residuals
+   ``S = Dr^-1/2 (P - r c^T) Dc^-1/2`` and take its truncated SVD.
+4. Row scores ``X = Dr^-1/2 U`` are rescaled to ``[-1, 1]`` per dimension.
+
+Deviations from the reference implementation, for reproducibility: SVD is
+computed with ``numpy.linalg.svd`` (deterministic LAPACK) instead of
+``sklearn``'s ``randomized_svd`` (``random_state=None``, non-deterministic).
+
+References
+----------
+- M. Falkenberg et al., "Growing polarisation around climate change on social
+  media", arXiv:2112.12137 (2021).
+- J. Flamino et al., "Shifting polarization and Twitter news influencers
+  between two US presidential elections", arXiv:2111.02505 (2021).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from netpol.scoring import IdeologyScorer
+
+
+class LatentIdeologyScorer(IdeologyScorer):
+    """Correspondence-analysis ideology scorer.
+
+    Args:
+        min_sources: Minimum number of *distinct* influencers a user must have
+            retweeted to be scored.  Users below this threshold are dropped.
+            This is the ``n`` parameter of the original method (default 2).
+        max_sources: If set, restrict to the top ``max_sources`` influencers by
+            total interactions (the original ``m`` parameter).  ``None`` keeps
+            all influencers present in the interaction table.
+    """
+
+    def __init__(self, min_sources: int = 2, max_sources: int | None = None):
+        if min_sources < 1:
+            raise ValueError("min_sources must be >= 1")
+        if max_sources is not None and max_sources < 2:
+            raise ValueError("max_sources must be >= 2 or None")
+        self.min_sources = min_sources
+        self.max_sources = max_sources
+
+    def score(self, edges: pd.DataFrame, n_dimensions: int) -> pd.DataFrame:
+        if edges is None or edges.empty:
+            raise ValueError("cannot score an empty interaction table")
+        if "influencer" not in edges.columns or "user" not in edges.columns:
+            raise ValueError("edges must have 'influencer' and 'user' columns")
+        if n_dimensions < 1:
+            raise ValueError("n_dimensions must be >= 1")
+
+        adjacency, influencers = self._build_adjacency(edges)
+        n_users, n_influencers = adjacency.shape
+
+        if n_users < 2:
+            raise ValueError(
+                f"need at least 2 users after filtering, got {n_users}"
+            )
+        if n_influencers < 2:
+            raise ValueError(
+                f"need at least 2 influencers, got {n_influencers}"
+            )
+
+        scores = self._correspondence_scores(adjacency, n_dimensions)
+        return pd.DataFrame(
+            scores,
+            index=adjacency.index,
+            columns=[f"score_{d + 1}" for d in range(scores.shape[1])],
+        )
+
+    # -- helpers ---------------------------------------------------------
+
+    def _build_adjacency(self, edges: pd.DataFrame) -> tuple[pd.DataFrame, list]:
+        """Return the (users x influencers) weighted adjacency matrix.
+
+        Users touching fewer than ``min_sources`` distinct influencers are
+        dropped; empty influencer columns are removed afterwards.
+        """
+        df = edges[["user", "influencer"]].copy()
+
+        # count distinct influencers per user, drop users below threshold
+        distinct = df.groupby("user")["influencer"].nunique()
+        keep_users = distinct[distinct >= self.min_sources].index
+        df = df[df["user"].isin(keep_users)]
+
+        if self.max_sources is not None:
+            top = (
+                df.groupby("influencer")
+                .size()
+                .sort_values(ascending=False)
+                .head(self.max_sources)
+                .index
+            )
+            df = df[df["influencer"].isin(top)]
+
+        # weighted user x influencer matrix (count of interactions)
+        weighted = (
+            df.groupby(["user", "influencer"]).size().reset_index(name="weight")
+        )
+        matrix = weighted.pivot(
+            index="user", columns="influencer", values="weight"
+        ).fillna(0.0)
+
+        # drop influencer columns left with no interactions after filtering
+        matrix = matrix.loc[:, (matrix != 0).any(axis=0)]
+        return matrix, list(matrix.columns)
+
+    @staticmethod
+    def _correspondence_scores(
+        adjacency: pd.DataFrame, n_dimensions: int
+    ) -> np.ndarray:
+        A = adjacency.to_numpy(dtype=float)
+        total = A.sum()
+        if total <= 0:
+            raise ValueError("adjacency matrix has no interactions")
+
+        P = A / total
+        r = P.sum(axis=1)  # row (user) masses
+        c = P.sum(axis=0)  # column (influencer) masses
+
+        Dr_inv_sqrt = np.diag(np.power(r, -0.5))
+        Dc_inv_sqrt = np.diag(np.power(c, -0.5))
+
+        S = Dr_inv_sqrt @ (P - np.outer(r, c)) @ Dc_inv_sqrt
+
+        k = min(n_dimensions, min(S.shape) - 1)
+        if k < 1:
+            raise ValueError("matrix too small for any ideology dimension")
+
+        U, _, _ = np.linalg.svd(S, full_matrices=False)
+        X = Dr_inv_sqrt @ U[:, :k]
+
+        # scale each dimension into [-1, 1]
+        scaled = np.empty_like(X)
+        for d in range(k):
+            span = X[:, d].max() - X[:, d].min()
+            if span == 0:
+                raise ValueError(
+                    f"degenerate score distribution in dimension {d + 1}"
+                )
+            scaled[:, d] = -1 + 2 * (X[:, d] - X[:, d].min()) / span
+        return scaled

netpol-0.1.0/netpol/influencers.py

@@ -0,0 +1,45 @@
+"""Influencer selection.
+
+Rank nodes by a centrality score, take the top ``n`` as "influencers" and
+return the rest as "users".  This is intentionally one small function rather
+than a plugin system -- see the engineering spec for when to grow it.
+
+Edge convention reminder: ``a -> b`` means "a retweets/endorses b", so
+``in_degree`` counts how often a node is retweeted (authority), while total
+``degree`` also counts how often it retweets others.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+
+def select_influencers(
+    graph: nx.DiGraph, strategy: str, n: int
+) -> tuple[list, list]:
+    """Split the nodes of ``graph`` into influencers and users.
+
+    Args:
+        graph: A directed graph.
+        strategy: ``"degree"`` (total degree) or ``"in_degree"``.
+        n: Number of influencers to select.
+
+    Returns:
+        ``(influencers, others)`` where ``influencers`` holds the top ``n``
+        nodes by the chosen score (descending) and ``others`` the rest.  Ties
+        are broken by the stringified node id, ascending, for determinism.
+        If ``n`` is greater than or equal to the node count, ``others`` is
+        empty (this does not raise).
+    """
+    if strategy == "degree":
+        scores = graph.degree()
+    elif strategy == "in_degree":
+        scores = graph.in_degree()
+    else:
+        raise ValueError(f"Unknown strategy: {strategy!r}")
+
+    ranked = sorted(scores, key=lambda item: (-item[1], str(item[0])))
+
+    influencers = [node for node, _ in ranked[:n]]
+    others = [node for node, _ in ranked[n:]]
+    return influencers, others

netpol-0.1.0/netpol/layer_result.py

@@ -0,0 +1,33 @@
+"""Result of analyzing a single layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Hashable
+
+import pandas as pd
+
+
+@dataclass
+class LayerResult:
+    """Outcome of running the polarization pipeline on one layer.
+
+    ``was_analyzed`` is True iff scoring completed and a dip test was run.
+    When a layer is skipped, ``skip_reason`` explains why (instead of the
+    original script's silent ``except: continue``).
+    """
+
+    layer_id: Hashable
+    n_nodes: int
+    n_edges: int
+    influencers: list
+    scores: pd.DataFrame | None = None
+    dip_statistic: float | None = None
+    p_value: float | None = None
+    adjusted_p_value: float | None = None
+    is_polarized: bool | None = None
+    skip_reason: str | None = None
+
+    @property
+    def was_analyzed(self) -> bool:
+        return self.skip_reason is None and self.p_value is not None

netpol-0.1.0/netpol/pipeline.py

@@ -0,0 +1,151 @@
+"""The polarization pipeline.
+
+Two layers, mirroring the API contract in the design spec:
+
+* ``analyze_layer`` -- the primitive: one directed graph in, one
+  ``LayerResult`` out.  Fully testable in isolation.
+* ``analyze_layers`` -- thin orchestration over ``dict[layer_id, DiGraph]``
+  that runs the primitive per layer and applies the one genuinely cross-layer
+  step: Benjamini-Hochberg FDR correction across all layers' p-values.
+
+Design constraints enforced here (see the engineering spec):
+
+* Directed graphs only -- ``TypeError`` on ``Graph``/``MultiDiGraph``.
+* No bare ``except:`` anywhere; every failure path sets a human-readable
+  ``skip_reason``.
+"""
+
+from __future__ import annotations
+
+from typing import Hashable
+
+import networkx as nx
+
+from netpol.bimodality import apply_fdr_correction, dip_test
+from netpol.config import PolarizationConfig
+from netpol.edges import build_influencer_edges
+from netpol.ideology import LatentIdeologyScorer
+from netpol.influencers import select_influencers
+from netpol.layer_result import LayerResult
+from netpol.scoring import IdeologyScorer
+
+
+def analyze_layer(
+    graph: nx.DiGraph,
+    config: PolarizationConfig,
+    ideology_scorer: IdeologyScorer | None = None,
+) -> LayerResult:
+    """Run the polarization pipeline on a single directed graph.
+
+    Args:
+        graph: A directed graph (``a -> b`` = "a retweets b").
+        config: Run configuration.
+        ideology_scorer: Optional scorer.  Defaults to
+            :class:`netpol.ideology.LatentIdeologyScorer`.
+
+    Returns:
+        A ``LayerResult``.  ``is_polarized`` reflects the raw p-value only;
+        FDR correction is applied later by ``analyze_layers``.
+    """
+    _require_digraph(graph)
+
+    result = LayerResult(
+        layer_id=None,
+        n_nodes=graph.number_of_nodes(),
+        n_edges=graph.number_of_edges(),
+        influencers=[],
+    )
+
+    if graph.number_of_edges() < config.min_edges:
+        result.skip_reason = (
+            f"below min_edges ({graph.number_of_edges()} < {config.min_edges})"
+        )
+        return result
+
+    influencers, _ = select_influencers(
+        graph, config.influencer_strategy, config.n_influencers
+    )
+    result.influencers = influencers
+
+    edges = build_influencer_edges(graph, influencers)
+    if edges.empty:
+        result.skip_reason = "no edges into selected influencers"
+        return result
+
+    scorer = ideology_scorer or LatentIdeologyScorer()
+
+    try:
+        scores = scorer.score(edges, config.ideology_dimensions)
+    except Exception as exc:  # scorer is a plug point; report, don't crash
+        result.skip_reason = f"scoring_failed: {type(exc).__name__}: {exc}"
+        return result
+
+    result.scores = scores
+
+    try:
+        dip, p_value = dip_test(scores["score_1"].to_numpy())
+    except Exception as exc:
+        result.skip_reason = f"dip_test_failed: {type(exc).__name__}: {exc}"
+        return result
+
+    result.dip_statistic = dip
+    result.p_value = p_value
+    result.is_polarized = p_value < config.significance_level
+    return result
+
+
+def analyze_layers(
+    layers: dict[Hashable, nx.DiGraph],
+    config: PolarizationConfig,
+    ideology_scorer: IdeologyScorer | None = None,
+) -> dict[Hashable, LayerResult]:
+    """Run ``analyze_layer`` per layer and apply FDR correction across layers.
+
+    Args:
+        layers: Mapping ``layer_id -> DiGraph``.
+        config: Run configuration.  ``exclude_layers`` entries are skipped
+            with a ``skip_reason``.
+        ideology_scorer: Optional scorer; defaults to the built-in one.
+
+    Returns:
+        Mapping ``layer_id -> LayerResult``.  When ``config.fdr_correction``
+        is True, ``adjusted_p_value`` is set on analyzed layers and
+        ``is_polarized`` is re-evaluated against the adjusted p-value.
+    """
+    results: dict[Hashable, LayerResult] = {}
+
+    for layer_id, graph in layers.items():
+        result = analyze_layer(graph, config, ideology_scorer)
+        result.layer_id = layer_id
+        if layer_id in config.exclude_layers:
+            result.skip_reason = "excluded by config.exclude_layers"
+            result.dip_statistic = None
+            result.p_value = None
+            result.scores = None
+            result.is_polarized = None
+        results[layer_id] = result
+
+    if config.fdr_correction:
+        raw = {
+            layer_id: r.p_value
+            for layer_id, r in results.items()
+            if r.p_value is not None
+        }
+        adjusted = apply_fdr_correction(raw)
+        for layer_id, r in results.items():
+            if r.p_value is None:
+                continue
+            r.adjusted_p_value = adjusted[layer_id]
+            r.is_polarized = adjusted[layer_id] < config.significance_level
+
+    return results
+
+
+def _require_digraph(graph: nx.DiGraph) -> None:
+    if isinstance(graph, nx.MultiDiGraph):
+        raise TypeError("MultiDiGraph is not supported")
+    if not isinstance(graph, nx.DiGraph):
+        raise TypeError(
+            "expected a networkx.DiGraph; undirected and multigraphs are not "
+            "supported (the edge direction encodes who retweets whom)"
+        )

netpol-0.1.0/netpol/scoring.py

@@ -0,0 +1,40 @@
+"""The ideology-scoring plug point.
+
+The pipeline only depends on the ``IdeologyScorer`` protocol below, never on a
+specific implementation.  ``netpol`` ships a default implementation
+(``netpol.ideology.LatentIdeologyScorer``) that users can ignore, but the
+protocol lets them swap in their own correspondence-analysis code, a different
+method entirely, or a patched/expanded version of the built-in scorer.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import pandas as pd
+
+
+class IdeologyScorer(Protocol):
+    """Something that maps an influencer-user interaction table to scores.
+
+    Implementations receive the output of
+    :func:`netpol.edges.build_influencer_edges` and must return one row per
+    scored node, indexed by node id, with one column per dimension named
+    ``score_1`` ... ``score_n``.
+    """
+
+    def score(self, edges: pd.DataFrame, n_dimensions: int) -> pd.DataFrame:
+        """Compute per-node ideology scores.
+
+        Args:
+            edges: DataFrame with columns ``['influencer', 'user']``.
+            n_dimensions: Number of score dimensions to return.
+
+        Returns:
+            A DataFrame indexed by node id with columns
+            ``['score_1', ..., 'score_n']``.
+
+        Raises:
+            ValueError: if ``edges`` is empty or scoring cannot proceed.
+        """
+        ...

netpol-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[tool.poetry]
+name = "netpol"
+version = "0.1.0"
+description = "Measure polarization in (multilayer) social networks via latent-ideology scoring and Hartigan's dip test."
+authors = ["alessiogandelli <alessiogandelli99@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/alessiogandelli/netpol"
+repository = "https://github.com/alessiogandelli/netpol"
+keywords = [
+    "polarization",
+    "social-networks",
+    "networkx",
+    "multilayer",
+    "ideology",
+    "dip-test",
+    "correspondence-analysis",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+packages = [{ include = "netpol" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+networkx = ">=3.0"
+pandas = ">=2.0"
+numpy = ">=1.24"
+diptest = ">=0.8"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"