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 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
+ }