Pythagora: A Python Package for Modeling the Impact of Social Networks on Market Outcomes

Developed by Sarah T. Wilker, PhD & Annie K. Lamar, PhD

Citation

Wilker, S.T. and Lamar, A.K. Pythagora. Version 1.0.0. github.com/stwilker/pythagora. 2024.

Author Contributions

The below author contribution statement was developed based on the CRediT (Contributor Roles Taxonomy) framework.

S.T. Wilker: Conceptualization, Methodology, Software, Validation, Formal Analysis, Investigation, Data Curation, Writing - Original Draft, Writing - Review & Editing; A.K. Lamar: Software, Validation, Formal Analysis, Data Curation, Writing - Review & Editing, Visualization

Project Description

Pythagora is an agent-based modeling package that allows for the construction of experiments to test the impact of select types of social networks on production and consumption outcomes. Specifically, Pythagora simulates how individuals (agents) in small-world social networks and scale-free social networks (as well as control versions of these networks) buy and sell different items based on interactions within their social networks.

Agents in Pythagora have complex social lives: they belong to communities and are connected in social networks both inside and outside those communities. The purpose of this multidimensional social landscape is to test the impact of different types of social relationships on what individual agents buy and sell, and how these individual transactions build over time to create long-term production and consumption trends.

While Pythagora was designed to test popularity changes in pottery styles in the ancient Mediterranean world, it can be used to test popularity changes for any type of object during any time period.

Installation & Dependencies

To install Pythagora, you can use pip:

pip install pythagora

Pythagora also requires NetworkX (3.2), which can be installed by running this command:

pip install networkx==3.2

Quick Start

Pythagora allows you to customize your agent-based market simulations in several ways. There are two general network protocols to choose from: small-world and scale-free. Within each type of algorithm there are several adjustable parameters; detailed information about each parameter is available in the documentation.

The experiments class is the only class with which most users need to interact. You can change all experimental parameters in the main experiment function. The threshold values define at what points buyers decide to purchase (or not purchase) particular items available in the marketplace.

Every simulation will include agents (buyers and sellers), communities (groups to which buyers belong), and a market (groups of communities and items for sale). An epoch is a single market cycle; buyers enter the market with a purchasing intention and make their purchase. For analysis purposes, changes to the network and community structures are recorded as time steps in the data logs.

Small-World Simulation

The small-world simulation contains all the methods you will use to model how consumption practices change among communities of buyers as they move in and out of being in a small-world network. In practice, this means that buyers purchasing items go from being minimally connected (long path lengths and high clustering for individual communities) to being maximally connected (short path lengths and low clustering for individual communities).

Here is an example of how to run a small world simulation:

from pythagora import experiments

experiments.small_world_simulation (number_of_buyers=100,
                                    minimum_number_of_communities=3, 
                                    minimum_community_fill=3, 
                                    assemblage=['Item1', 'Item2', 'Item3', 'Item4'], 
                                    number_of_epochs=100, 
                                    upper_threshold=.66, 
                                    lower_threshold=.33, 
                                    death_threshold=0.01, 
                                    results_directory='results/', 
                                    probability_of_rewire=0.5, 
                                    community_start_structure="dense", 
                                    verbose=True)

This method call will run a small world experiment for 100 epochs. The results of the experiment will be placed in the directory indicated by the results_directory parameter.

Scale-Free Simulation

The scale-free simulation contains all the methods you will use to model how consumption practices change among communities of buyers as they join a scale-free social network (i.e., a network that grows through preferential attachment) and this network determines their purchasing behavior in the market space.

Here is an example of how to run a scale-free simulation:

from pythagora import experiments

experiments.scale_free_simulation(number_of_buyers=50,
                                  minimum_number_of_communities=5,
                                  minimum_community_fill=3, 
                                  assemblage=['Item1', 'Item2', 'Item3', 'Item4'], 
                                  number_of_epochs=100, 
                                  upper_threshold=.66, 
                                  lower_threshold=.33, 
                                  death_threshold=0.01, 
                                  results_directory='results/', 
                                  initial_set_size=15, 
                                  set_size=5, 
                                  community_bonus=1, 
                                  verbose=True)

This method call will run a small world experiment for 100 epochs. The results of the experiment will be placed in the directory indicated by the results_directory parameter.

Experimental Controls and Random Simulations

You can also run control experiments for both small world and scale free network protocols. Here is an example of how to run a control simulation for a small world network, which is initialized with a random graph rather than a predefined network structure.

from pythagora import experiments

experiments.control_simulation_small_world(number_of_buyers=50,
                                minimum_number_of_communities=3, 
                                minimum_community_fill=3, 
                                assemblage=['Item1', 'Item2', 'Item3', 'Item4'], 
                                epochs=100, 
                                upper_threshold=.66, 
                                lower_threshold=.33, 
                                death_threshold=0.01, 
                                results_directory='results/', 
                                rewire_prob=0.5, 
                                link_prob=0.5, 
                                verbose=True)