ySights Documentation

ySights is a Python library for analyzing data generated by YSocial . It provides tools for extracting insights from social media simulation data, including agent behaviors, content dynamics, network structures, and recommendation system effects.

What is YSocial?

YSocial Twin is an open-source platform for simulating social media ecosystems. It enables researchers to model user interactions, content dissemination, and algorithmic influences in a controlled environment.

ySights complements YSocial by offering analysis and visualization capabilities for the generated data. ySights is natively integrated within YSocial Twin, allowing seamless data extraction and analysis.

For more information about the YSocial ecosystem, visit the GitHub repository and the official project website.

Features

  • Data Models: Comprehensive data models for agents, posts, simulation runs, and forum sessions

  • Network Analysis: Social, mention, thread, and conversation graph extraction

  • Algorithm Library: Profile similarity, topic lifecycle, moderation, reporting, and recommendation metrics

  • Analytical Surfaces: Time-series, user segmentation, community structure, and cross-experiment comparison

  • Visualization Tools: Rich visualization functions for simulation insights

  • Sphinx Documentation: Complete API reference with examples

Quick Start

from ysights import YDataHandler

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

# Get simulation time range
time_range = ydh.time_range()
print(f"Simulation: rounds {time_range['min_round']} to {time_range['max_round']}")

# Get all agents
agents = ydh.agents()
print(f"Total agents: {len(agents.get_agents())}")

# Extract social network
network = ydh.social_network()
print(f"Network: {network.number_of_nodes()} nodes, {network.number_of_edges()} edges")

# Build higher-level analysis
report = ydh.summary_report()
print(f"Posts: {report['post_count']}, topics: {report['topic_count']}")

# Inspect cached analytics and performance guidance
print(ydh.analysis_cache_info())
print(ydh.recommended_indexes()["count"], "index suggestions")

Installation

pip install ysights

or from source:

git clone https://github.com/YSocialTwin/ysights.git
cd ysights
pip install -e .

Contents

Tutorials

Module Documentation

Indices and tables