clickstream_patterns

sqllocks_spindle.simulation.clickstream_patterns

Clickstream / web telemetry patterns — sessions, page views, funnels, bot traffic.

Generates realistic web analytics data that simulates user browsing behavior including multi-page sessions, conversion funnels, and bot/crawler traffic.

Usage::

from sqllocks_spindle.simulation.clickstream_patterns import (
    ClickstreamSimulator, ClickstreamConfig,
)

cfg = ClickstreamConfig(users=1000, duration_hours=24)
result = ClickstreamSimulator(config=cfg).run()

Classes

ClickstreamConfig dataclass

Configuration for :class:ClickstreamSimulator.

Parameters:

Name	Type	Description	Default
users	int	Number of distinct users to simulate.	1000
duration_hours	float	Total simulation window in hours.	24.0
avg_sessions_per_user	float	Average number of sessions each user starts.	2.5
avg_pages_per_session	float	Average page views for non-bounced sessions.	5.0
bounce_rate	float	Fraction of human sessions that are single-page bounces.	0.35
funnel_enabled	bool	Whether to track conversion funnel progression.	True
funnel_stages	list[str]	Ordered list of funnel stage names.	(lambda: ['landing', 'product', 'cart', 'checkout', 'confirmation'])()
funnel_drop_rate	float	Per-stage probability of a user abandoning.	0.4
bot_traffic_enabled	bool	Whether to inject bot/crawler sessions.	True
bot_fraction	float	Fraction of all sessions that come from bots.	0.15
bot_pages_per_session	int	Number of pages a bot crawls per session.	50
page_pool	list[str]	URL templates available for page views.	(lambda: ['/', '/products', '/products/{id}', '/cart', '/checkout', '/about', '/contact', '/blog', '/blog/{slug}', '/search', '/account', '/faq'])()
referrer_sources	list[str]	Traffic sources for session attribution.	(lambda: ['direct', 'google', 'bing', 'facebook', 'twitter', 'email', 'reddit'])()
device_types	list[str]	Device type labels for human sessions.	(lambda: ['desktop', 'mobile', 'tablet'])()
seed	int	Random seed for reproducibility.	42

ClickstreamResult dataclass

Result of :meth:ClickstreamSimulator.run.

Attributes:

Name	Type	Description
sessions	DataFrame	One row per session with metadata.
page_views	DataFrame	One row per page view with timestamps and dwell times.
funnels	DataFrame	Funnel progression records per session.
stats	dict[str, Any]	Summary statistics dictionary.

ClickstreamSimulator

Generate realistic web clickstream data.

Produces sessions, page views, conversion funnels, and bot traffic for a configurable number of users over a simulation window.

Parameters:

Name	Type	Description	Default
config	ClickstreamConfig | None	:class:ClickstreamConfig (uses defaults if None).	None

Example::

cfg = ClickstreamConfig(users=500, duration_hours=12)
sim = ClickstreamSimulator(cfg)
result = sim.run()
print(result.stats)

Methods:

run()

Execute the simulation and return a :class:ClickstreamResult.