Algorithms Package

The algorithms package provides analysis functions for YSocial simulation data, including profile similarity, recommendation metrics, and topic analysis.

Profile Analysis

Functions for analyzing agent profiles and interest similarity.

Agent Profile Analysis

This module provides functions for analyzing agent interest profiles and their similarity within social networks. It helps understand how agents’ interests align with their network neighbors and community structure.

Example

Analyzing profile similarity in a social network:

from ysights import YDataHandler
from ysights.algorithms.profiles import profile_topics_similarity

# Initialize data handler and extract network
ydh = YDataHandler('path/to/database.db')
network = ydh.social_network()

# Calculate interest similarity between neighbors
similarities = profile_topics_similarity(ydh, network, limit=2)

# Analyze results
for agent_id, similarity_score in similarities.items():
    print(f"Agent {agent_id} has {similarity_score:.2%} interest overlap with neighbors")

ysights.algorithms.profiles.profile_topics_similarity(YDH, g, limit=2, from_round=None, to_round=None)[source]

Compute interest-based similarity between agents and their network neighbors.

This function calculates how well each agent’s interests align with those of their neighbors in the social network. It filters out rare interests, normalizes interest distributions, and computes the fraction of neighbors sharing the agent’s most frequent interests.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations
g (networkx.Graph) – Social network graph where nodes represent agents and edges represent connections
limit (int) – Minimum count threshold for including an interest (interests appearing fewer times are filtered out)
from_round (int, optional) – Starting round for filtering interests (inclusive), None for no lower bound
to_round (int, optional) – Ending round for filtering interests (inclusive), None for no upper bound

Returns:

Dictionary mapping agent IDs to their similarity scores with neighbors. Similarity score represents the fraction of neighbors sharing at least one of the agent’s most frequent interests (range: 0.0 to 1.0)

Return type:

dict[int, float]

Example:

from ysights import YDataHandler
from ysights.algorithms.profiles import profile_topics_similarity
import networkx as nx

# Initialize data handler and extract social network
ydh = YDataHandler('path/to/database.db')
network = ydh.social_network()

# Calculate similarity for all agents
similarities = profile_topics_similarity(ydh, network, limit=2)

# Find agents with high neighbor similarity
high_similarity = {k: v for k, v in similarities.items() if v > 0.7}
print(f"{len(high_similarity)} agents have >70% interest overlap with neighbors")

# Calculate for specific time period
early_sim = profile_topics_similarity(ydh, network, limit=2,
                                     from_round=0, to_round=500)
late_sim = profile_topics_similarity(ydh, network, limit=2,
                                    from_round=500, to_round=1000)

# Compare evolution
for agent_id in early_sim:
    if agent_id in late_sim:
        change = late_sim[agent_id] - early_sim[agent_id]
        if abs(change) > 0.2:
            print(f"Agent {agent_id} similarity changed by {change:.2%}")

Note

Interests are normalized per agent, so agents with many posts don’t dominate the similarity calculation
The limit parameter helps focus on significant interests by filtering out occasional or accidental topic matches
Agents with no qualifying interests (after filtering) are excluded from results

See also

ysights.models.YDataHandler.YDataHandler.agent_interests(): Get agent interests ysights.models.YDataHandler.YDataHandler.social_network(): Extract social network

Recommender Metrics

Metrics for evaluating recommendation system performance.

Recommender System Metrics

This module provides metrics for analyzing recommendation system behavior and content distribution in YSocial simulations. It includes functions for measuring engagement momentum, personalization balance, and sentiment diffusion.

These metrics help evaluate how well recommendation algorithms balance between popular and niche content, how personalized the recommendations are for each user, and how emotional content spreads through the network.

Example

Analyzing recommendation system performance:

from ysights import YDataHandler
from ysights.algorithms.recommenders import engagement_momentum, personalization_balance_score

# Initialize data handler
ydh = YDataHandler('path/to/database.db')

# Calculate engagement momentum for posts
momentum = engagement_momentum(ydh, time_window_rounds=24)

# Analyze top posts by momentum
top_posts = sorted(momentum.items(), key=lambda x: x[1], reverse=True)[:10]
for post_id, score in top_posts:
    print(f"Post {post_id}: momentum score {score:.2f}")

# Calculate personalization balance for users
balance = personalization_balance_score(ydh, time_window_rounds=24, alpha=0.5)
avg_balance = sum(balance.values()) / len(balance)
print(f"Average personalization balance: {avg_balance:.3f}")

ysights.algorithms.recommenders.engagement_momentum(YDH, time_window_rounds=24)[source]

Calculate the engagement momentum for each post based on the number of recommendations over time. This function aggregates the number of recommendations for each post across time slots defined by the specified time window in rounds. The momentum is calculated using an exponential decay function to give more weight to recent recommendations. The momentum for each post is defined as the sum of the number of recommendations in each time slot, weighted by an exponential decay factor based on the slot index.

The formula used is:

momentum(post_id) = sum(exp(-0.1 * slot) * count)

where slot is the time slot index and count is the number of recommendations in that slot.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations
time_window_rounds (int) – the number of rounds to consider for each time slot

Returns:

a dictionary with post IDs as keys and their engagement momentum as values

ysights.algorithms.recommenders.personalization_balance_score(YDH, time_window_rounds=24, alpha=0.5)[source]

Calculate the personalization balance score for each user based on their posts and interests. The balance score is a combination of the match rate and niche rate, where the match rate is the ratio of posts that match the user’s interests to the total number of posts, and the niche rate is the ratio of popular posts in the user’s interest slots to the total number of posts. The function retrieves user posts and interests from the database, calculates the match and niche rates, and combines them using the specified alpha parameter to produce a balance score for each user.

The balance score is defined as:

balance_score(user) = alpha * match_rate(user) + (1 - alpha) * niche_rate(user)

This function is useful for evaluating how well the content of posts aligns with the interests of the users, providing a measure of content personalization and relevance.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations
time_window_rounds (int) – the number of rounds to consider for each time slot
alpha – the weight for the match rate in the balance score calculation

Returns:

a dictionary with user IDs as keys and their personalization balance scores as values

ysights.algorithms.recommenders.sentiment_diffusion_metrics(YDH)[source]

Calculate sentiment diffusion metrics across the network.

This function will analyze how emotional content (positive, negative, neutral) spreads through the social network and recommendation system, helping understand the dynamics of emotional contagion in the simulation.

Parameters:: YDH (YDataHandler) – YDataHandler instance for database operations
Returns:: Sentiment diffusion metrics (to be implemented)
Return type:: None

Example:

from ysights import YDataHandler
from ysights.algorithms.recommenders import sentiment_diffusion_metrics

ydh = YDataHandler('path/to/database.db')

# Calculate sentiment diffusion (function to be implemented)
# diffusion = sentiment_diffusion_metrics(ydh)
# print(f"Positive sentiment spread rate: {diffusion['positive']}")
# print(f"Negative sentiment spread rate: {diffusion['negative']}")

Note

This function is currently a placeholder and needs to be implemented.

See also

engagement_momentum(): Calculate post engagement momentum personalization_balance_score(): Measure content personalization

Topic Analysis

Functions for analyzing topic dynamics and evolution.

Topic Analysis Algorithms

This module provides functions for analyzing topic-related dynamics in YSocial simulations. These functions help understand how topics spread, how quickly they are adopted, and when engagement peaks occur.

The module is currently under development and contains placeholder functions for: - Topic spread analysis - Adoption rate calculations - Peak engagement time detection

Example

Basic usage of topic analysis functions:

from ysights import YDataHandler
from ysights.algorithms import topics

# Initialize data handler
ydh = YDataHandler('path/to/database.db')

# Analyze topic spread (to be implemented)
# spread = topics.topic_spread(ydh)

# Calculate adoption rates (to be implemented)
# rates = topics.adoption_rate(ydh)

ysights.algorithms.topics.topic_spread(YDH)[source]

Analyze the spread of topics across the social network.

This function will analyze how topics diffuse through the network over time, identifying patterns of information spread and influence.

Parameters:: YDH (YDataHandler) – YDataHandler instance for database operations
Returns:: Topic spread analysis results (to be implemented)
Return type:: None

Example:

from ysights import YDataHandler
from ysights.algorithms.topics import topic_spread

ydh = YDataHandler('path/to/database.db')

# Analyze topic spread (function to be implemented)
# results = topic_spread(ydh)

Note

This function is currently a placeholder and needs to be implemented.

See also

adoption_rate(): Calculate topic adoption rates peak_engagement_time(): Find peak engagement times

ysights.algorithms.topics.adoption_rate(YDH)[source]

Calculate the adoption rate of topics over time.

This function will measure how quickly agents adopt and engage with different topics in the simulation, providing insights into topic popularity and virality.

Parameters:: YDH (YDataHandler) – YDataHandler instance for database operations
Returns:: Topic adoption rate metrics (to be implemented)
Return type:: None

Example:

from ysights import YDataHandler
from ysights.algorithms.topics import adoption_rate

ydh = YDataHandler('path/to/database.db')

# Calculate adoption rates (function to be implemented)
# rates = adoption_rate(ydh)
# print(f"Average adoption rate: {rates}")

Note

This function is currently a placeholder and needs to be implemented.

See also

topic_spread(): Analyze topic spread patterns peak_engagement_time(): Find peak engagement times

ysights.algorithms.topics.peak_engagement_time(YDH)[source]

Identify peak engagement times for topics.

This function will determine when topics receive the most attention and engagement from agents, helping to understand temporal patterns in topic dynamics.

Parameters:: YDH (YDataHandler) – YDataHandler instance for database operations
Returns:: Peak engagement time analysis (to be implemented)
Return type:: None

Example:

from ysights import YDataHandler
from ysights.algorithms.topics import peak_engagement_time

ydh = YDataHandler('path/to/database.db')

# Find peak engagement times (function to be implemented)
# peaks = peak_engagement_time(ydh)
# for topic, peak_time in peaks.items():
#     print(f"Topic {topic} peaked at {peak_time}")

Note

This function is currently a placeholder and needs to be implemented.

See also

topic_spread(): Analyze topic spread patterns adoption_rate(): Calculate topic adoption rates