Algorithms Package

The algorithms package provides analysis functions for YSocial simulation data, including profile similarity, recommendation metrics, topic lifecycle analysis, and higher-level content dynamics helpers.

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.

The implementation summarizes sentiment at the post level and then projects it onto recommendation exposure events so the result captures both content polarity and how often that polarity is surfaced by the recommender layer.

Parameters:: YDH (YDataHandler) – YDataHandler instance for database operations
Returns:: Sentiment diffusion metrics.
Return type:: dict

Example:

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

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

diffusion = sentiment_diffusion_metrics(ydh)
print(diffusion["sentiment_label_counts"])
print(diffusion["recommendation_sentiment_counts"])

See also

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

Topic Analysis

Functions for analyzing topic dynamics and evolution. The topic module now exposes implemented lifecycle entry points backed by YDataHandler.topic_lifecycle.

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.

All public helpers in this module are implemented on top of the topic lifecycle summaries exposed by ysights.models.YDataHandler.

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
spread = topics.topic_spread(ydh)

# Calculate adoption rates
rates = topics.adoption_rate(ydh)
print(f"Adoption rates available for {len(rates)} topics")

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 lifecycle summaries keyed by topic identifier.
Return type:: dict

Example:

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

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

# Analyze topic spread
results = topic_spread(ydh)
print(results)

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 rates keyed by topic identifier.
Return type:: dict

Example:

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

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

# Calculate adoption rates
rates = adoption_rate(ydh)
print(f"Average adoption rate: {sum(rates.values()) / len(rates):.3f}")

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 periods keyed by topic identifier.
Return type:: dict

Example:

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

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

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

See also

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

Performance and Reporting

The recommendation and reporting helpers are documented through the model layer, which now exposes cached summaries, exports, and benchmark utilities.