GSM-Degroot package
Description: Python code with a prototype implementation of the GSM-Degroot model (i.e. a Degroot-based model with a global steering mechanism) and the experiments appearing in the associated paper.
I. Model
1) DGSM_matrix_form.
This file contains functions that simulate the model:
- model_non_SBM() for graphs of the type : Barabasi-Albert (BA), Watts-Strogatz (WS), grid, Erdos-Renyi (ER).
- model_SBM() for SBM graphs.
- model_non_SBM_robust() and model_SBM_robust() in case the parameters cause numerical errors.
The above functions generate M runs of the model and output metrics averaged over those M runs. The metrics generated are:
- S_ts: the number of agents in state 1 as a function of time,
- max_end/min_end: the maximal/minimal opinion in last period,
- pol_end: the difference between the two,
- max_pol: the maximal difference between maximum and minimum taken across,
- max_pol: the time at which it is reached.
2) DGSM_matrix_form_batched.
Computes the same as the previous file but uses a thread for each of the M runs.
NB: To perform a run of the model, it is enough to call the function model_non_SBM() / model_SBM() with the desired parameters.
II. Figures
Get_curves. This file generates the model for various values of gamma, mu, and the network parameter, depending of the network type, for all network types considered. The file generates Fig. 6 and can be used to generate Figs. 2, 3, 5, 7.
III. Parameter optimization
1) Get_TS. This file generates the 85 time series used for optimization. It requires the data in json format to be in the directory.
2) Optimization. This file runs the whole optimization process over the input time-series. Starting by generating the time-series by using the file Get_TS. The optimization is done by running the SBM version of the model and varying the parameters mu, gamma, and r. The starting point is a grid-search, and then performs simulated annealing initialized with the parameters identified previously by the grid-search. The best parameters are identified and saved for each language and social movement.
3) Cost_maps. For each time-series, this file performs a grid-search and gets the fitting costs associated to each triplet of parameters on the grid. This generates the cost maps necessary to perform the bootstrap analysis (see Appendix B. V in the paper).
4) Bootstrap comparison. This file computes the bootstrap metric that compares the variance of the set of top q best performing parameters (q is between 0 and 1) to the variance of a set of q parameters taken at random. For each data set, this metric is obtained for q between 10^(-4) and 2*10^(-2). Fig. 9 shows the outcome of this process for the MeToo and BLM data sets.
IV. Data acquisition
The data used in the paper are provided in the /Data folder. The data have been acquired by the authors using the publicly available tool storywrangler, as described in the paper.
V. Contribution, availability, and how to cite
The contributors to implementation are Ivan Conjeaud and Argyris Kalogeratos. Contacts: name.surname@ens-paris-saclay.fr.
The official distribution of this package is at this web page.
This work can be properly cited by mentioning the original published paper it refers to:
Ivan Conjeaud, Philipp Lorenz-Spreen, and Argyris Kalogeratos, “DeGroot-Based Opinion Formation Under a Global Steering Mechanism,” in IEEE Transactions on Computational Social Systems, vol. 11, no. 3, pp. 4040-4057, 2024.
To ensure accessibility, the text of the paper is also available in the public domain on arxiv.
VI. License
Copyright (C) 2020-2025, Ivan Conjeaud and Argyris Kalogeratos. This package is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this software in the file LICENSE.txt. If not, see here.
Brief overview of the GNU GPL:
- Provides copyright protection: True
- Can be used in commercial applications: True
- Bug fixes / extensions must be released to the public domain: True
- Provides an explicit patent license: False
- Can be used in proprietary (closed source) applications: False
- Is a viral license: True
Other resources for the license:
