ysights.algorithms.recommenders

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}")

Functions

`engagement_momentum`(YDH[, time_window_rounds])	Calculate the engagement momentum for each post based on the number of recommendations over time.
`personalization_balance_score`(YDH[, ...])	Calculate the personalization balance score for each user based on their posts and interests.
`sentiment_diffusion_metrics`(YDH)	Calculate sentiment diffusion metrics across the network.

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.