glaurlex 0.1.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- glaurlex/__init__.py +10 -0
- glaurlex/core/__init__.py +10 -0
- glaurlex/core/graph.py +507 -0
- glaurlex/core/graph_compare.py +1030 -0
- glaurlex/core/groups.py +124 -0
- glaurlex/core/inference.py +626 -0
- glaurlex/core/io.py +255 -0
- glaurlex/core/metrics_catalog.py +361 -0
- glaurlex/core/stats.py +97 -0
- glaurlex/core/variables.py +102 -0
- glaurlex/py.typed +0 -0
- glaurlex-0.1.1.dist-info/METADATA +111 -0
- glaurlex-0.1.1.dist-info/RECORD +15 -0
- glaurlex-0.1.1.dist-info/WHEEL +4 -0
- glaurlex-0.1.1.dist-info/licenses/LICENSE +674 -0
glaurlex/__init__.py
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Lexical availability analysis: type statistics, co-occurrence graphs and inference."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
try:
|
|
6
|
+
__version__ = version("glaurlex")
|
|
7
|
+
except PackageNotFoundError:
|
|
8
|
+
__version__ = "0+unknown"
|
|
9
|
+
|
|
10
|
+
__all__ = ["__version__"]
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Computational core of GLAURLex.
|
|
2
|
+
|
|
3
|
+
Every function operates on in-memory objects (pandas DataFrames, NetworkX graphs)
|
|
4
|
+
and never writes to disk. The data contract shared by all modules is:
|
|
5
|
+
|
|
6
|
+
* topic frame: one row per response, columns ``informant_id``, ``pos`` (0-indexed
|
|
7
|
+
position within the informant's list) and ``type``;
|
|
8
|
+
* informants frame: one row per informant, keyed by ``informant_id``, plus any
|
|
9
|
+
sociolinguistic variables.
|
|
10
|
+
"""
|
glaurlex/core/graph.py
ADDED
|
@@ -0,0 +1,507 @@
|
|
|
1
|
+
"""Bigram co-occurrence graphs, node centralities, communities and graph-level metrics."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Callable, Hashable, Iterable, Mapping
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
import igraph as ig
|
|
10
|
+
import leidenalg
|
|
11
|
+
import networkx as nx
|
|
12
|
+
import numpy as np
|
|
13
|
+
import pandas as pd
|
|
14
|
+
|
|
15
|
+
ProgressCallback = Callable[[int, int], None]
|
|
16
|
+
"""Called as ``callback(done, total)``."""
|
|
17
|
+
|
|
18
|
+
BIGRAM_COLUMNS = ("type_1", "type_2", "count")
|
|
19
|
+
|
|
20
|
+
NODE_STATS_COLUMNS = (
|
|
21
|
+
"node",
|
|
22
|
+
"degree",
|
|
23
|
+
"degree_centrality",
|
|
24
|
+
"strength",
|
|
25
|
+
"betweenness",
|
|
26
|
+
"closeness",
|
|
27
|
+
"pagerank",
|
|
28
|
+
"eigenvector",
|
|
29
|
+
"clustering",
|
|
30
|
+
"strong_component_id",
|
|
31
|
+
"weak_component_id",
|
|
32
|
+
)
|
|
33
|
+
DIRECTED_NODE_STATS_COLUMNS = ("in_degree", "out_degree", "in_strength", "out_strength")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _ordered_components(components: Iterable[set[Hashable]]) -> list[set[Hashable]]:
|
|
37
|
+
return sorted(components, key=lambda comp: (-len(comp), min(str(n) for n in comp)))
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def bigrams_for_topic(df: pd.DataFrame) -> pd.DataFrame:
|
|
41
|
+
r"""Count consecutive type pairs within each informant's response list.
|
|
42
|
+
|
|
43
|
+
Parameters
|
|
44
|
+
----------
|
|
45
|
+
df : pandas.DataFrame
|
|
46
|
+
Topic frame with columns ``informant_id``, ``pos`` and ``type``.
|
|
47
|
+
|
|
48
|
+
Returns
|
|
49
|
+
-------
|
|
50
|
+
pandas.DataFrame
|
|
51
|
+
Columns ``type_1``, ``type_2`` and ``count``, one row per ordered pair
|
|
52
|
+
``(type at pos i, type at pos i + 1)`` observed for the same informant.
|
|
53
|
+
|
|
54
|
+
Notes
|
|
55
|
+
-----
|
|
56
|
+
Runs in :math:`O(R \log R)` for :math:`R` responses.
|
|
57
|
+
"""
|
|
58
|
+
if df.empty:
|
|
59
|
+
return pd.DataFrame(columns=list(BIGRAM_COLUMNS))
|
|
60
|
+
|
|
61
|
+
df = df[["informant_id", "pos", "type"]].sort_values(["informant_id", "pos"])
|
|
62
|
+
df = df.assign(type_2=df.groupby("informant_id")["type"].shift(-1)).dropna(subset=["type_2"])
|
|
63
|
+
if df.empty:
|
|
64
|
+
return pd.DataFrame(columns=list(BIGRAM_COLUMNS))
|
|
65
|
+
|
|
66
|
+
return (
|
|
67
|
+
df.groupby(["type", "type_2"])
|
|
68
|
+
.size()
|
|
69
|
+
.reset_index(name="count")
|
|
70
|
+
.rename(columns={"type": "type_1"})
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def bigrams_to_unordered(df_bigrams: pd.DataFrame) -> pd.DataFrame:
|
|
75
|
+
"""Merge ``(a, b)`` and ``(b, a)`` into one unordered pair, summing counts.
|
|
76
|
+
|
|
77
|
+
Parameters
|
|
78
|
+
----------
|
|
79
|
+
df_bigrams : pandas.DataFrame
|
|
80
|
+
Columns ``type_1``, ``type_2`` and ``count``.
|
|
81
|
+
|
|
82
|
+
Returns
|
|
83
|
+
-------
|
|
84
|
+
pandas.DataFrame
|
|
85
|
+
Same columns, with ``type_1 <= type_2`` compared as strings.
|
|
86
|
+
"""
|
|
87
|
+
if df_bigrams.empty:
|
|
88
|
+
return pd.DataFrame(columns=list(BIGRAM_COLUMNS))
|
|
89
|
+
|
|
90
|
+
first = df_bigrams["type_1"].astype(str).to_numpy()
|
|
91
|
+
second = df_bigrams["type_2"].astype(str).to_numpy()
|
|
92
|
+
swap = first > second
|
|
93
|
+
out = pd.DataFrame(
|
|
94
|
+
{
|
|
95
|
+
"type_1": np.where(swap, second, first),
|
|
96
|
+
"type_2": np.where(swap, first, second),
|
|
97
|
+
"count": df_bigrams["count"].to_numpy(),
|
|
98
|
+
}
|
|
99
|
+
)
|
|
100
|
+
return out.groupby(["type_1", "type_2"], dropna=False)["count"].sum().reset_index()
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _edgelist_to_graph(df_bigrams: pd.DataFrame, create_using: type[nx.Graph]) -> nx.Graph:
|
|
104
|
+
return nx.from_pandas_edgelist(
|
|
105
|
+
df_bigrams.rename(columns={"count": "weight"}),
|
|
106
|
+
source="type_1",
|
|
107
|
+
target="type_2",
|
|
108
|
+
edge_attr="weight",
|
|
109
|
+
create_using=create_using,
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def bigrams_to_dirgraph(df_bigrams: pd.DataFrame) -> nx.DiGraph:
|
|
114
|
+
"""Build a directed graph whose edge ``weight`` is the bigram count.
|
|
115
|
+
|
|
116
|
+
Parameters
|
|
117
|
+
----------
|
|
118
|
+
df_bigrams : pandas.DataFrame
|
|
119
|
+
Columns ``type_1``, ``type_2`` and ``count``.
|
|
120
|
+
|
|
121
|
+
Returns
|
|
122
|
+
-------
|
|
123
|
+
networkx.DiGraph
|
|
124
|
+
"""
|
|
125
|
+
return _edgelist_to_graph(df_bigrams, nx.DiGraph)
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def bigrams_to_undgraph(df_bigrams: pd.DataFrame) -> nx.Graph:
|
|
129
|
+
"""Build an undirected graph whose edge ``weight`` is the unordered bigram count.
|
|
130
|
+
|
|
131
|
+
Parameters
|
|
132
|
+
----------
|
|
133
|
+
df_bigrams : pandas.DataFrame
|
|
134
|
+
Columns ``type_1``, ``type_2`` and ``count``.
|
|
135
|
+
|
|
136
|
+
Returns
|
|
137
|
+
-------
|
|
138
|
+
networkx.Graph
|
|
139
|
+
"""
|
|
140
|
+
return _edgelist_to_graph(bigrams_to_unordered(df_bigrams), nx.Graph)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def build_cooccurrence_graph(df: pd.DataFrame, *, directed: bool) -> nx.Graph:
|
|
144
|
+
"""Build the weighted bigram co-occurrence graph of a topic frame.
|
|
145
|
+
|
|
146
|
+
Parameters
|
|
147
|
+
----------
|
|
148
|
+
df : pandas.DataFrame
|
|
149
|
+
Topic frame with columns ``informant_id``, ``pos`` and ``type``.
|
|
150
|
+
directed : bool
|
|
151
|
+
Return a :class:`networkx.DiGraph` when true, otherwise an undirected
|
|
152
|
+
graph with ``(a, b)`` and ``(b, a)`` merged.
|
|
153
|
+
|
|
154
|
+
Returns
|
|
155
|
+
-------
|
|
156
|
+
networkx.Graph or networkx.DiGraph
|
|
157
|
+
"""
|
|
158
|
+
bigrams = bigrams_for_topic(df)
|
|
159
|
+
return bigrams_to_dirgraph(bigrams) if directed else bigrams_to_undgraph(bigrams)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def node_stats(graph: nx.Graph) -> pd.DataFrame:
|
|
163
|
+
"""Compute per-node degree, centrality, clustering and component membership.
|
|
164
|
+
|
|
165
|
+
Parameters
|
|
166
|
+
----------
|
|
167
|
+
graph : networkx.Graph or networkx.DiGraph
|
|
168
|
+
Graph with an optional ``weight`` edge attribute.
|
|
169
|
+
|
|
170
|
+
Returns
|
|
171
|
+
-------
|
|
172
|
+
pandas.DataFrame
|
|
173
|
+
Columns listed in ``NODE_STATS_COLUMNS`` (plus
|
|
174
|
+
``DIRECTED_NODE_STATS_COLUMNS`` for directed graphs), sorted by
|
|
175
|
+
``strength`` and ``degree`` descending, then ``node`` ascending:
|
|
176
|
+
|
|
177
|
+
* ``degree``: unweighted degree; ``degree_centrality``: degree / (V - 1);
|
|
178
|
+
* ``strength``: weighted degree;
|
|
179
|
+
* ``betweenness``: unnormalized betweenness centrality;
|
|
180
|
+
* ``closeness``: closeness with the Wasserman-Faust correction;
|
|
181
|
+
* ``pagerank``: weighted PageRank, damping 0.85, tolerance 1e-6;
|
|
182
|
+
* ``eigenvector``: weighted eigenvector centrality (``max_iter=1000``);
|
|
183
|
+
* ``clustering``: weighted clustering coefficient;
|
|
184
|
+
* ``strong_component_id`` / ``weak_component_id``: 1-based component
|
|
185
|
+
index, components ordered by size descending.
|
|
186
|
+
|
|
187
|
+
Notes
|
|
188
|
+
-----
|
|
189
|
+
Betweenness dominates the cost at :math:`O(VE)` (Brandes, 2001).
|
|
190
|
+
"""
|
|
191
|
+
directed = graph.is_directed()
|
|
192
|
+
columns = list(NODE_STATS_COLUMNS) + (list(DIRECTED_NODE_STATS_COLUMNS) if directed else [])
|
|
193
|
+
if graph.number_of_nodes() == 0:
|
|
194
|
+
return pd.DataFrame(columns=columns)
|
|
195
|
+
|
|
196
|
+
if directed:
|
|
197
|
+
strong = _ordered_components(nx.strongly_connected_components(graph))
|
|
198
|
+
weak = _ordered_components(nx.weakly_connected_components(graph))
|
|
199
|
+
else:
|
|
200
|
+
strong = weak = _ordered_components(nx.connected_components(graph))
|
|
201
|
+
|
|
202
|
+
metrics: dict[str, Mapping[Hashable, Any]] = {
|
|
203
|
+
"degree": dict(graph.degree()),
|
|
204
|
+
"degree_centrality": nx.degree_centrality(graph),
|
|
205
|
+
"strength": dict(graph.degree(weight="weight")),
|
|
206
|
+
"betweenness": nx.betweenness_centrality(graph, normalized=False),
|
|
207
|
+
"closeness": nx.closeness_centrality(graph, wf_improved=True),
|
|
208
|
+
"pagerank": nx.pagerank(graph, weight="weight", alpha=0.85, tol=1e-6),
|
|
209
|
+
"eigenvector": nx.eigenvector_centrality(graph, weight="weight", max_iter=1000),
|
|
210
|
+
"clustering": nx.clustering(graph, weight="weight"),
|
|
211
|
+
"strong_component_id": partition_to_map(strong),
|
|
212
|
+
"weak_component_id": partition_to_map(weak),
|
|
213
|
+
}
|
|
214
|
+
if directed:
|
|
215
|
+
metrics |= {
|
|
216
|
+
"in_degree": dict(graph.in_degree()),
|
|
217
|
+
"out_degree": dict(graph.out_degree()),
|
|
218
|
+
"in_strength": dict(graph.in_degree(weight="weight")),
|
|
219
|
+
"out_strength": dict(graph.out_degree(weight="weight")),
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
nodes = list(graph.nodes())
|
|
223
|
+
out = pd.DataFrame(
|
|
224
|
+
{"node": nodes} | {name: [m[n] for n in nodes] for name, m in metrics.items()}
|
|
225
|
+
)
|
|
226
|
+
return out[columns].sort_values(["strength", "degree", "node"], ascending=[False, False, True])
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def community_leiden(graph: nx.Graph, seed: int = 42) -> list[set[Hashable]]:
|
|
230
|
+
"""Detect communities with the Leiden algorithm on the weighted graph.
|
|
231
|
+
|
|
232
|
+
Parameters
|
|
233
|
+
----------
|
|
234
|
+
graph : networkx.Graph or networkx.DiGraph
|
|
235
|
+
Directed graphs are converted to undirected first.
|
|
236
|
+
seed : int, default 42
|
|
237
|
+
Seed passed to :func:`leidenalg.find_partition`.
|
|
238
|
+
|
|
239
|
+
Returns
|
|
240
|
+
-------
|
|
241
|
+
list of set
|
|
242
|
+
One node set per community, ordered by size descending.
|
|
243
|
+
|
|
244
|
+
Notes
|
|
245
|
+
-----
|
|
246
|
+
Optimizes modularity (``ModularityVertexPartition``) as in Traag, Waltman
|
|
247
|
+
and van Eck (2019).
|
|
248
|
+
"""
|
|
249
|
+
undirected = graph.to_undirected() if graph.is_directed() else graph
|
|
250
|
+
if undirected.number_of_nodes() == 0:
|
|
251
|
+
return []
|
|
252
|
+
|
|
253
|
+
nodes = list(undirected.nodes())
|
|
254
|
+
index = {n: i for i, n in enumerate(nodes)}
|
|
255
|
+
edges = list(undirected.edges(data="weight", default=1.0))
|
|
256
|
+
ig_graph = ig.Graph(n=len(nodes), edges=[(index[u], index[v]) for u, v, _ in edges])
|
|
257
|
+
ig_graph.es["weight"] = [w for _, _, w in edges]
|
|
258
|
+
|
|
259
|
+
partition = leidenalg.find_partition(
|
|
260
|
+
ig_graph, leidenalg.ModularityVertexPartition, weights="weight", seed=seed
|
|
261
|
+
)
|
|
262
|
+
communities = [{nodes[i] for i in community} for community in partition]
|
|
263
|
+
return sorted(communities, key=len, reverse=True)
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def partition_to_map(communities: Iterable[Iterable[Hashable]]) -> dict[Hashable, int]:
|
|
267
|
+
"""Map each node to the 1-based index of the community that contains it.
|
|
268
|
+
|
|
269
|
+
Parameters
|
|
270
|
+
----------
|
|
271
|
+
communities : iterable of iterable
|
|
272
|
+
Disjoint node collections, e.g. the output of :func:`community_leiden`.
|
|
273
|
+
|
|
274
|
+
Returns
|
|
275
|
+
-------
|
|
276
|
+
dict
|
|
277
|
+
``node -> community index``, numbered in iteration order from 1.
|
|
278
|
+
"""
|
|
279
|
+
return {node: i for i, community in enumerate(communities, start=1) for node in community}
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
@dataclass(frozen=True)
|
|
283
|
+
class SmallWorld:
|
|
284
|
+
"""Small-world indices of a connected undirected graph.
|
|
285
|
+
|
|
286
|
+
Attributes
|
|
287
|
+
----------
|
|
288
|
+
swi, omega : float or None
|
|
289
|
+
Index value, ``None`` when undefined.
|
|
290
|
+
swi_error, omega_error : str or None
|
|
291
|
+
Reason code when the index is undefined: ``"zero_path_length"``,
|
|
292
|
+
``"zero_lattice_clustering"``, ``"zero_lattice_path_length"``,
|
|
293
|
+
``"zero_path_length_range"`` or ``"zero_clustering_range"``.
|
|
294
|
+
"""
|
|
295
|
+
|
|
296
|
+
swi: float | None
|
|
297
|
+
omega: float | None
|
|
298
|
+
swi_error: str | None
|
|
299
|
+
omega_error: str | None
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def small_world_indices(
|
|
303
|
+
graph: nx.Graph, *, n: int = 10, progress_cb: ProgressCallback | None = None
|
|
304
|
+
) -> SmallWorld:
|
|
305
|
+
r"""Compute the small-world propensity indices ω and SWI.
|
|
306
|
+
|
|
307
|
+
Parameters
|
|
308
|
+
----------
|
|
309
|
+
graph : networkx.Graph
|
|
310
|
+
Connected, undirected graph with at least four nodes.
|
|
311
|
+
n : int, default 10
|
|
312
|
+
Number of lattice and random reference graphs. Reference ``i`` uses
|
|
313
|
+
seed ``42 + i``.
|
|
314
|
+
progress_cb : callable, optional
|
|
315
|
+
Called with ``(i, n)`` before each reference pair and ``(n, n)`` at the end.
|
|
316
|
+
|
|
317
|
+
Returns
|
|
318
|
+
-------
|
|
319
|
+
SmallWorld
|
|
320
|
+
|
|
321
|
+
Raises
|
|
322
|
+
------
|
|
323
|
+
ValueError
|
|
324
|
+
If the graph is directed, has fewer than two nodes or is disconnected.
|
|
325
|
+
|
|
326
|
+
Notes
|
|
327
|
+
-----
|
|
328
|
+
With :math:`L, C` the average shortest path length and average clustering
|
|
329
|
+
of ``graph``, :math:`L_r, C_r` their means over the random references,
|
|
330
|
+
:math:`L_l` the mean path length over the lattice references and
|
|
331
|
+
:math:`C_l` the maximum lattice clustering,
|
|
332
|
+
|
|
333
|
+
.. math::
|
|
334
|
+
|
|
335
|
+
\omega = \frac{L_r}{L} - \frac{C}{C_l}, \qquad
|
|
336
|
+
\mathrm{SWI} = \frac{L - L_l}{L_r - L_l} \cdot \frac{C - C_r}{C_l - C_r}
|
|
337
|
+
|
|
338
|
+
(Telesford et al., 2011; Neal, 2017). References are built with
|
|
339
|
+
``lattice_reference(niter=5)`` and ``random_reference(niter=10)``; each
|
|
340
|
+
costs :math:`O(\mathrm{niter} \cdot E)` swaps plus an all-pairs shortest
|
|
341
|
+
path computation.
|
|
342
|
+
"""
|
|
343
|
+
if graph.is_directed():
|
|
344
|
+
msg = "small_world_indices requires an undirected graph"
|
|
345
|
+
raise ValueError(msg)
|
|
346
|
+
if graph.number_of_nodes() < 2:
|
|
347
|
+
msg = "small_world_indices requires at least two nodes"
|
|
348
|
+
raise ValueError(msg)
|
|
349
|
+
if not nx.is_connected(graph):
|
|
350
|
+
msg = "small_world_indices requires a connected graph"
|
|
351
|
+
raise ValueError(msg)
|
|
352
|
+
|
|
353
|
+
L = nx.average_shortest_path_length(graph)
|
|
354
|
+
C = nx.average_clustering(graph)
|
|
355
|
+
|
|
356
|
+
lattice_clustering: list[float] = []
|
|
357
|
+
lattice_paths: list[float] = []
|
|
358
|
+
random_clustering: list[float] = []
|
|
359
|
+
random_paths: list[float] = []
|
|
360
|
+
for i in range(n):
|
|
361
|
+
if progress_cb:
|
|
362
|
+
progress_cb(i, n)
|
|
363
|
+
lattice = nx.algorithms.smallworld.lattice_reference(graph, niter=5, seed=42 + i)
|
|
364
|
+
random = nx.algorithms.smallworld.random_reference(graph, niter=10, seed=42 + i)
|
|
365
|
+
lattice_clustering.append(nx.average_clustering(lattice))
|
|
366
|
+
random_clustering.append(nx.average_clustering(random))
|
|
367
|
+
lattice_paths.append(nx.average_shortest_path_length(lattice))
|
|
368
|
+
random_paths.append(nx.average_shortest_path_length(random))
|
|
369
|
+
if progress_cb:
|
|
370
|
+
progress_cb(n, n)
|
|
371
|
+
|
|
372
|
+
Cl = max(lattice_clustering, default=-1.0)
|
|
373
|
+
Cr = sum(random_clustering) / n if n else 0.0
|
|
374
|
+
Ll = sum(lattice_paths) / n if n else 0.0
|
|
375
|
+
Lr = sum(random_paths) / n if n else 0.0
|
|
376
|
+
|
|
377
|
+
omega: float | None = None
|
|
378
|
+
omega_error: str | None = None
|
|
379
|
+
if L == 0:
|
|
380
|
+
omega_error = "zero_path_length"
|
|
381
|
+
elif Cl <= 0:
|
|
382
|
+
omega_error = "zero_lattice_clustering"
|
|
383
|
+
else:
|
|
384
|
+
omega = (Lr / L) - (C / Cl)
|
|
385
|
+
|
|
386
|
+
swi: float | None = None
|
|
387
|
+
swi_error: str | None = None
|
|
388
|
+
if Ll == 0:
|
|
389
|
+
swi_error = "zero_lattice_path_length"
|
|
390
|
+
elif Lr - Ll == 0:
|
|
391
|
+
swi_error = "zero_path_length_range"
|
|
392
|
+
elif Cl - Cr == 0:
|
|
393
|
+
swi_error = "zero_clustering_range"
|
|
394
|
+
else:
|
|
395
|
+
swi = ((L - Ll) / (Lr - Ll)) * ((C - Cr) / (Cl - Cr))
|
|
396
|
+
|
|
397
|
+
return SmallWorld(swi=swi, omega=omega, swi_error=swi_error, omega_error=omega_error)
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def is_graph_connected(graph: nx.Graph) -> bool:
|
|
401
|
+
"""Return whether the graph is connected (weakly, for directed graphs).
|
|
402
|
+
|
|
403
|
+
Parameters
|
|
404
|
+
----------
|
|
405
|
+
graph : networkx.Graph or networkx.DiGraph
|
|
406
|
+
|
|
407
|
+
Returns
|
|
408
|
+
-------
|
|
409
|
+
bool
|
|
410
|
+
``False`` for the empty graph.
|
|
411
|
+
"""
|
|
412
|
+
if graph.number_of_nodes() == 0:
|
|
413
|
+
return False
|
|
414
|
+
if graph.is_directed():
|
|
415
|
+
return bool(nx.is_weakly_connected(graph))
|
|
416
|
+
return bool(nx.is_connected(graph))
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
def connected_components_sorted(graph: nx.Graph) -> list[set[Hashable]]:
|
|
420
|
+
"""Return the (weakly) connected components, largest first.
|
|
421
|
+
|
|
422
|
+
Parameters
|
|
423
|
+
----------
|
|
424
|
+
graph : networkx.Graph or networkx.DiGraph
|
|
425
|
+
|
|
426
|
+
Returns
|
|
427
|
+
-------
|
|
428
|
+
list of set
|
|
429
|
+
Ties in size are broken by the smallest node label as a string.
|
|
430
|
+
"""
|
|
431
|
+
if graph.number_of_nodes() == 0:
|
|
432
|
+
return []
|
|
433
|
+
if graph.is_directed():
|
|
434
|
+
return _ordered_components(nx.weakly_connected_components(graph))
|
|
435
|
+
return _ordered_components(nx.connected_components(graph))
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
def graph_stats(graph: nx.Graph, node_stats_df: pd.DataFrame) -> dict[str, float | int | None]:
|
|
439
|
+
"""Compute graph-level structural metrics.
|
|
440
|
+
|
|
441
|
+
Parameters
|
|
442
|
+
----------
|
|
443
|
+
graph : networkx.Graph or networkx.DiGraph
|
|
444
|
+
node_stats_df : pandas.DataFrame
|
|
445
|
+
Must contain ``degree`` and ``strength``; the output of
|
|
446
|
+
:func:`node_stats` qualifies.
|
|
447
|
+
|
|
448
|
+
Returns
|
|
449
|
+
-------
|
|
450
|
+
dict
|
|
451
|
+
``diameter`` and ``avg_path_length`` of the largest strongly
|
|
452
|
+
connected (directed) or connected (undirected) component;
|
|
453
|
+
``avg_clustering`` (weighted); ``avg_degree`` and ``avg_strength``;
|
|
454
|
+
``density``; ``components`` (weakly connected components for directed
|
|
455
|
+
graphs); ``assortativity`` (degree assortativity, ``None`` if undefined).
|
|
456
|
+
|
|
457
|
+
Notes
|
|
458
|
+
-----
|
|
459
|
+
``avg_degree`` and ``avg_strength`` are half the mean node degree and
|
|
460
|
+
strength, i.e. :math:`E/V` and :math:`W/V` for an undirected graph with
|
|
461
|
+
total weight :math:`W`, so that each edge is counted once.
|
|
462
|
+
"""
|
|
463
|
+
if graph.number_of_nodes() == 0:
|
|
464
|
+
return {
|
|
465
|
+
"diameter": 0,
|
|
466
|
+
"avg_clustering": 0.0,
|
|
467
|
+
"avg_degree": 0.0,
|
|
468
|
+
"avg_strength": 0.0,
|
|
469
|
+
"density": 0.0,
|
|
470
|
+
"components": 0,
|
|
471
|
+
"avg_path_length": 0.0,
|
|
472
|
+
"assortativity": None,
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
if graph.is_directed():
|
|
476
|
+
cores = list(nx.strongly_connected_components(graph))
|
|
477
|
+
n_components = nx.number_weakly_connected_components(graph)
|
|
478
|
+
else:
|
|
479
|
+
cores = list(nx.connected_components(graph))
|
|
480
|
+
n_components = len(cores)
|
|
481
|
+
largest = graph.subgraph(max(cores, key=len))
|
|
482
|
+
|
|
483
|
+
if largest.number_of_nodes() <= 1:
|
|
484
|
+
diameter, avg_path_length = 0, 0.0
|
|
485
|
+
else:
|
|
486
|
+
diameter = nx.diameter(largest)
|
|
487
|
+
avg_path_length = nx.average_shortest_path_length(largest)
|
|
488
|
+
|
|
489
|
+
try:
|
|
490
|
+
assortativity: float | None = float(nx.degree_assortativity_coefficient(graph))
|
|
491
|
+
except (nx.NetworkXError, ZeroDivisionError):
|
|
492
|
+
assortativity = None
|
|
493
|
+
|
|
494
|
+
return {
|
|
495
|
+
"diameter": diameter,
|
|
496
|
+
"avg_clustering": float(nx.average_clustering(graph, weight="weight")),
|
|
497
|
+
"avg_degree": float(node_stats_df["degree"].mean() / 2)
|
|
498
|
+
if "degree" in node_stats_df
|
|
499
|
+
else 0.0,
|
|
500
|
+
"avg_strength": (
|
|
501
|
+
float(node_stats_df["strength"].mean() / 2) if "strength" in node_stats_df else 0.0
|
|
502
|
+
),
|
|
503
|
+
"density": float(nx.density(graph)),
|
|
504
|
+
"components": n_components,
|
|
505
|
+
"avg_path_length": avg_path_length,
|
|
506
|
+
"assortativity": assortativity,
|
|
507
|
+
}
|