Social Networks

Social Network Base Class

class econsimulacra.social_networks.base.SocialNetwork(config, registered_classes, prng)[source]

Bases: object

Social Network class.

The SocialNetwork class represents a social network environment where agents can tweet messages and follow/unfollow other agents.

Parameters:
add_agent(agent_id, agent_name)[source]

Add a new agent to the SocialNetwork.

Parameters:

  • agent_id (int) – The agent ID for the agent to be added.

  • agent_name (str)

Return type:

None

Note

See also: econsimulacra.envs.base.Environment._generate_agents

tweet(agent_id, message)[source]

Append a new message to the agent’s existing tweet. This represents the agent tweeting a message in the social network.

Parameters:

  • agent_id (int) – The agent ID of the agent that tweeted.

  • message (str) – The content of the tweet.

Return type:

None

Note

See also: econsimulacra.envs.base.Environment._act_in_social_network

follow_agent(agent_id, target_agent_id)[source]

Update the social network to reflect that the agent with agent_id follows the agent with target_agent_id.

Parameters:

  • agent_id (int) – The agent IDthat wants to follow another agent.

  • target_agent_id (int) – The agent ID to be followed.

Return type:

None

Note

See also: econsimulacra.envs.base.Environment._act_in_social_network

unfollow_agent(agent_id, target_agent_id)[source]

Update the social network to reflect that the agent with agent_id unfollows the agent with target_agent_id.

Parameters:

  • agent_id (int) – The agent IDthat wants to unfollow another agent.

  • target_agent_id (int) – The agent ID to be unfollowed.

Return type:

None

Note

See also: econsimulacra.envs.base.Environment._act_in_social_network

get_followers(agent_id)[source]

Get the agent IDs that follow the agent with the given agent_id.

Parameters:

agent_id (int) – The agent ID for which to get the followers.

Returns:

A set of agent IDs that follow the given agent.

Return type:

set[int]

get_num_followers(agent_id)[source]

Get the number of followers for the agent with the given agent_id.

Parameters:

agent_id (int) – The agent ID for which to get the number of followers.

Returns:

The number of followers for the given agent.

Return type:

int

get_follow_cap()[source]

Get the follow cap of the social network.

Returns:

The follow cap of the social network, or None if not set.

Return type:

int, optional

get_allowed_num_follows(agent_id)[source]

Get the allowed number of follows for the agent with the given agent_id, which is the remaining number of follows the agent can make before reaching the follow cap.

Parameters:

agent_id (int) – The agent ID for which to get the allowed number of follows.

Returns:

The allowed number of follows for the given agent, or None if there is no follow cap.

Return type:

int, optional

get_follows(agent_id)[source]

Get the agent IDs that the agent with the given agent_id follows.

Parameters:

agent_id (int) – The agent ID for which to get the follows.

Returns:

A set of agent IDs that the given agent follows.

Return type:

set[int]

get_num_follows(agent_id)[source]

Get the number of follows for the agent with the given agent_id.

Parameters:

agent_id (int) – The agent ID for which to get the number of follows.

Returns:

The number of follows for the given agent.

Return type:

int

get_tweet(agent_id)[source]

Get the latest tweet of the agent with the given agent_id.

Parameters:

agent_id (int) – The agent ID for which to get the latest tweet.

Returns:

The latest tweet of the given agent.

Return type:

str

Get a list of recommended agent IDs for the agent with the given agent_id to follow, based on the recommender system.

Parameters:

agent_id (int) – The agent ID for which to get the recommended follows.

Returns:

A list of recommended agent IDs for the given agent to follow.

Return type:

list[int]

Note

The recommendations are generated based on the recommender system’s algorithm. See also: econsimulacra.social_networks.recsys.RecommenderSystem, econsimulacra.envs.obs_providers.RecommendedFollowsProvider

Recommender System

class econsimulacra.social_networks.recsys.RecommenderSystem(config, prng)[source]

Bases: ABC

Base class for recommender systems in the social network environment (abstract class).

Recommender systems are responsible for generating personalized recommendations for agents in the social network, such as which other agents to follow. They can also implement event hooks to update their internal state based on changes in the social network, such as when agents follow or unfollow each other, or tweet. .get_recommendations(agent_id) is the only method that must be implemented by subclasses, while the event hooks are optional to implement based on the specific recommendation algorithm.

Parameters:

  • config (dict[str, Any])

  • prng (Random)

bind(social_network)[source]

Inject the social network instance into the recommender system.

Parameters:

social_network (SocialNetwork) – The social network instance to bind to the recommender system.

Return type:

None

Note

This method is called when the SocialNetwork is initialized, allowing the recommender system to access the social network’s state and subscribe to its events. See also: econsimulacra.envs.social_networks.base.SocialNetwork.__init__

abstractmethod get_recommendations(agent_id)[source]
Parameters:

agent_id (int)

Return type:

list[Any]

hook_add_agent(agent_id, agent_name)[source]

Event hook called when a new agent is added to the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that was added.

  • agent_name (str) – The name of the agent that was added.

Return type:

None

Note

See also:

econsimulacra.envs.social_networks.base.SocialNetwork.add_agent

hook_follow_agent(agent_id, target_agent_id)[source]

Event hook called when an agent follows another agent in the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that initiated the follow action.

  • target_agent_id (int) – The unique identifier of the agent that is being followed.

Return type:

None

Note

See also:

econsimulacra.envs.social_networks.base.SocialNetwork.follow_agent

hook_unfollow_agent(agent_id, target_agent_id)[source]

Event hook called when an agent unfollows another agent in the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that initiated the unfollow action.

  • target_agent_id (int) – The unique identifier of the agent that is being unfollowed.

Return type:

None

Note

See also:

econsimulacra.envs.social_networks.base.SocialNetwork.unfollow_agent

hook_tweet(agent_id, message)[source]

Event hook called when an agent tweets in the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that tweeted.

  • message (str) – The content of the tweet.

Return type:

None

Note

See also:

econsimulacra.envs.social_networks.base.SocialNetwork.tweet

class econsimulacra.social_networks.recsys.TwoHopRecommenderSystem(config, prng)[source]

Bases: RecommenderSystem

A simple recommender system that recommends agents based on two-hop connections in the social network.

Parameters:

  • config (dict[str, Any])

  • prng (Random)

hook_add_agent(agent_id, agent_name)[source]

Event hook called when a new agent is added to the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that was added.

  • agent_name (str) – The name of the agent that was added.

Return type:

None

hook_follow_agent(agent_id, target_agent_id)[source]

Event hook called when an agent follows another agent in the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that is following.

  • target_agent_id (int) – The unique identifier of the agent being followed.

Return type:

None

Note

When agent_id follows target_agent_id, we update the two-hop follow counts for agent_id -> target_agent_id -> X and X -> agent_id -> target_agent_id for all relevant intermediate agents X.

hook_unfollow_agent(agent_id, target_agent_id)[source]

Event hook called when an agent unfollows another agent in the social network.

Parameters:

  • agent_id (int) – The unique identifier of the agent that is unfollowing.

  • target_agent_id (int) – The unique identifier of the agent being unfollowed.

Return type:

None

Note

When agent_id unfollows target_agent_id, we update the two-hop follow counts for agent_id -> target_agent_id -> X and X -> agent_id -> target_agent_id for all relevant intermediate agents X.

get_recommendations(agent_id)[source]

Generate recommendations for the given agent based on two-hop connections.

Parameters:

agent_id (int) – The unique identifier of the agent for whom to generate recommendations.

Return type:

list[dict[str, Any]]

Note

The recommendation score for a candidate agent is based on: 1. The number of two-hop paths from the given agent to the candidate (higher is better). 2. The number of followers the candidate agent has (higher is better). 3. A random tie-breaker, when self.is_randomized is True (controlled by self.temperature).

Agents that are already followed by the given agent are excluded from the recommendations.