ysights.algorithms.topics

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

Functions

`adoption_rate`(YDH)	Calculate the adoption rate of topics over time.
`peak_engagement_time`(YDH)	Identify peak engagement times for topics.
`topic_spread`(YDH)	Analyze the spread of topics across the social network.

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