Visualization Package

The visualization package provides plotting functions for YSocial simulation analysis, using matplotlib and plotly for creating informative visualizations.

Global Trends

Functions for visualizing aggregate statistics and trends.

Global Trends Visualization Functions

This module provides visualization functions for aggregate statistics and trends across the entire YSocial simulation. It includes functions for analyzing content creation, user activity, reactions, hashtags, emotions, topics, and engagement patterns over time.

Functions:

• daily_contents_trends: Posts, articles, shares, and comments per day

• contents_per_user_distributions: Distribution of content creation per user

• daily_reactions_trends: Reactions distribution over time

• trending_hashtags: Most popular hashtags

• trending_emotions: Most expressed emotions

• tending_topics: Most discussed topics

• comments_per_post_distribution: Distribution of comment counts

Example

Visualizing global trends:

from ysights import YDataHandler
from ysights.viz import (
    daily_contents_trends,
    contents_per_user_distributions,
    trending_hashtags,
    trending_emotions
)

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

# Daily content trends
fig = daily_contents_trends(ydh)
fig.suptitle('Content Production Over Time')
fig.show()

# Content distribution per user
fig = contents_per_user_distributions(ydh)
fig.show()

# Top 10 trending hashtags
fig = trending_hashtags(ydh, top_n=10)
fig.show()

# Emotion distribution
fig = trending_emotions(ydh)
fig.show()

See also

• ysights.viz.topics_viz: Topic-specific visualizations

• ysights.viz.recommendations: Recommendation system visualizations

ysights.viz.global_trends.daily_contents_trends(YDH)

Plot the distribution of posts, articles, shares, and comments per day. This function retrieves the count of posts, articles, shares, and comments from the database, grouped by day, and plots them on a single graph.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations

Returns:

A matplotlib figure object containing the plot of daily content distributions.

ysights.viz.global_trends.daily_reactions_trends(YDH, smooth_days=None)

Plot the distribution of reactions per day. This function retrieves the count of reactions from the database, grouped by day, and plots them on a single graph.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• smooth_days – If specified, the data will be smoothed over this number of days.

Returns:

A matplotlib figure object containing the plot of daily reaction distributions.

ysights.viz.global_trends.contents_per_user_distributions(YDH)

Plot the distribution of posts, articles, shares, and comments per user. This function retrieves the count of posts, articles, shares, and comments from the database, grouped by user, and plots them on a single graph.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations

Returns:

A matplotlib figure object containing the plot of content distributions per user.

ysights.viz.global_trends.trending_hashtags(YDH, limit=10, leaning=None)

Plot the top trending hashtags over time. This function retrieves the top trending hashtags from the database, grouped by day, and plots them on a single graph.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• limit – The number of top trending hashtags to plot

• leaning – Optional parameter to filter hashtags by user leaning (e.g., ‘democrat’, ‘republican’). If None, all hashtags are considered.

Returns:

A matplotlib figure object containing the plot of trending hashtags.

ysights.viz.global_trends.trending_emotions(YDH, limit=10, leaning=None)

Plot the top trending hashtags over time. This function retrieves the top trending hashtags from the database, grouped by day, and plots them on a single graph.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• limit – The number of top trending hashtags to plot

• leaning – Optional parameter to filter hashtags by user leaning (e.g., ‘democrat’, ‘republican’). If None, all hashtags are considered.

Returns:

A matplotlib figure object containing the plot of trending hashtags.

ysights.viz.global_trends.tending_topics(YDH, limit=10, leaning=None)

Plot the top trending topics over time. This function retrieves the top trending topics from the database, grouped by day, and plots them on a single graph.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• limit – The number of top trending topics to plot

• leaning – Optional parameter to filter topics by user leaning (e.g., ‘democrat’, ‘republican’). If None, all topics are considered.

Returns:

A matplotlib figure object containing the plot of trending topics.

ysights.viz.global_trends.comments_per_post_distribution(YDH)

Plot the distribution of comments per post. This function retrieves the count of comments for each post from the database, and plots the distribution on a histogram.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations

Returns:

A matplotlib figure object containing the histogram of comments per post.

Topic Visualizations

Functions for visualizing topic evolution and density.

Topic Visualization Functions

This module provides visualization functions for analyzing topic dynamics and evolution in YSocial simulations. It focuses on temporal patterns of interest and topic density across different user groups.

Functions:

• topic_density_temporal_evolution: Visualize topic density over time as a heatmap

Example

Visualizing topic evolution:

from ysights import YDataHandler
from ysights.viz import topic_density_temporal_evolution

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

# Visualize all topics over time
fig = topic_density_temporal_evolution(ydh, min_days=15)
fig.show()

# Filter by user leaning
fig_left = topic_density_temporal_evolution(ydh, min_days=10, leaning='left')
fig_left.update_layout(title="Topics: Left-leaning Users")
fig_left.show()

See also

• ysights.algorithms.topics: Topic analysis algorithms

• ysights.viz.global_trends: Aggregate trend visualizations

ysights.viz.topics_viz.topic_density_temporal_evolution(YDH, min_days=15, leaning=None)

Visualize the temporal evolution of topic density in a heatmap format. This function retrieves user interest data, aggregates it by interest and day, and generates a heatmap

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• min_days – Minimum number of days an interest must be present to be included in the heatmap

• leaning (str) – Optional parameter to filter interests by user leaning (e.g., ‘democrats’, ‘republican’, etc.)

Returns:

A Plotly heatmap figure showing the density of topics over time

Profile Visualizations

Functions for visualizing profile similarity analysis.

Profile Visualization Functions

This module provides visualization functions for analyzing agent profile similarity within social networks. It helps visualize how agent interests align with their network neighbors and how this varies with network position.

Functions:

• profile_similarity_distribution: Histogram of similarity values

• profile_similarity_vs_degree: Scatter plot of similarity vs. node degree

• binned_similarity_per_degree: Box plots of similarity by degree bins

Example

Visualizing profile similarity:

from ysights import YDataHandler
from ysights.algorithms import profile_topics_similarity
from ysights.viz import (
    profile_similarity_distribution,
    profile_similarity_vs_degree,
    binned_similarity_per_degree
)

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

# Calculate similarities
similarities = profile_topics_similarity(ydh, network)

# Distribution plot
fig = profile_similarity_distribution([similarities], ['All Users'])
fig.show()

# Similarity vs degree
fig = profile_similarity_vs_degree([similarities], [network], ['All Users'])
fig.show()

# Binned by degree
fig = binned_similarity_per_degree([similarities], [network], ['All Users'])
fig.show()

See also

• ysights.algorithms.profiles.profile_topics_similarity(): Calculate similarities

• ysights.viz.paradox_viz: Paradox visualizations

ysights.viz.profiles_viz.profile_similarity_distribution(similarities, population_names)

Plot the binned distribution of similarity values of the populations passed as a list of dictionaries.

Parameters:

• similarities (list[dict]) – list of dictionaries containing similarity values for each population

• population_names (list[str]) – list of names corresponding to each population in the similarities list

Returns:

ysights.viz.profiles_viz.profile_similarity_vs_degree(similarities, gs, population_names)

Plot a scatter plot of similarity values vs. node degree for each population.

Parameters:

• similarities (list[dict]) – list of dictionaries containing similarity values for each population

• gs (list) – list of graphs corresponding to each population in the similarities list

• population_names (list[str]) – list of names corresponding to each population in the similarities list

Returns:

matplotlib figure object

ysights.viz.profiles_viz.binned_similarity_per_degree(similarities, gs, population_names, bins=10)

Plot the binned similarity values per degree for each population.

Parameters:

• similarities (list[dict]) – list of dictionaries containing similarity values for each population

• gs (list) – list of graphs corresponding to each population in the similarities list

• population_names (list[str]) – list of names corresponding to each population in the similarities list

• bins – number of bins to use for the histogram

Returns:

matplotlib figure object

Recommendation Visualizations

Functions for visualizing recommendation system metrics.

Recommendation System Visualization Functions

This module provides visualization functions for analyzing recommendation system behavior in YSocial simulations. It helps visualize recommendation distributions, correlations with engagement metrics, and system balance.

Functions:

• recommendations_per_post_distribution: Distribution of recommendation counts

• recommendations_vs_reactions: Correlation between recommendations and reactions

• recommendations_vs_comments: Correlation between recommendations and comments

Example

Visualizing recommendation patterns:

from ysights import YDataHandler
from ysights.viz import (
    recommendations_per_post_distribution,
    recommendations_vs_reactions,
    recommendations_vs_comments
)

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

# Distribution of recommendations
fig = recommendations_per_post_distribution(ydh)
fig.show()

# Recommendations vs reactions
fig = recommendations_vs_reactions(ydh)
fig.show()

# Recommendations vs comments
fig = recommendations_vs_comments(ydh)
fig.show()

See also

• ysights.algorithms.recommenders: Recommendation system metrics

• ysights.viz.global_trends: Global content trends

ysights.viz.recommendations.recommendations_per_post_distribution(YDH)

Plot the distribution of recommendations per post.

Parameters:

YDH (YDataHandler) – YDataHandler instance for database operations

Returns:

a matplotlib figure showing the distribution of recommendations per post

ysights.viz.recommendations.recommendations_vs_reactions(YDH, density=False)

Plot the relationship between recommendations and reactions.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• density – if True, use hexbin plot for density visualization

Returns:

a matplotlib figure showing the relationship between recommendations and reactions

ysights.viz.recommendations.recommendations_vs_comments(YDH, density=False)

Plot the relationship between recommendations and comments.

Parameters:

• YDH (YDataHandler) – YDataHandler instance for database operations

• density – if True, use hexbin plot for density visualization

Returns:

a matplotlib figure showing the relationship between recommendations and comments