🇯🇵 日本語版 README
session-visualizer lets you watch an operant session while it runs: the cumulative record, reinforcer marks, the session state, and optional light model fits, served over HTTP to a browser, a notebook, or operantkit-frontend. It is for people who run sessions with OperantKit and want a live view without risking the session's timing. It attaches to a session in the same Python process, or follows the log file that another process or machine is writing.
- The session never waits for the display. Events go into a bounded queue; if the viewer falls behind, events are dropped from the view and counted, never delayed.
- Same view for local and remote sessions. Attach to a session in your own program, or follow an OKL or JSONL log file as it grows.
- A documented HTTP interface. Snapshots, a live stream, and cumulative-record figures; see the HTTP API reference.
The view is not a record: use session-recorder for the durable log and session-analyzer for final analyses. Notes for AI coding agents are in AGENTS.md.
Python 3.11 or newer. session-visualizer is not on PyPI yet, so pip install session-visualizer does not work today. Install it and the OperantKit packages it needs from GitHub without dependency resolution, then add the third-party libraries. fastapi, sse-starlette, and uvicorn are needed only for the HTTP server; session-runner only for the example below.
G=git+https://github.com/OperantKit
pip install --no-deps $G/contingency-dsl-py $G/contingency-py $G/experiment-core \
$G/session-recorder $G/session-runner $G/session-analyzer $G/session-visualizer
pip install numpy scipy matplotlib fastapi sse-starlette uvicornpip check reports version mismatches between these development builds; they do not affect the examples below.
Run a short FR 3 session, record it to an OKL file, and watch it at the same time:
from contingency import ScheduleBuilder
from experiment_core import ReinforcementCountExit
from session_recorder import OklSink
from session_runner import SessionConfig, SessionRunner, tee
from session_visualizer import LiveAggregator, NonBlockingEventSink
sink = NonBlockingEventSink(maxsize=4096) # emit() never waits; drops and counts when full
aggregator = LiveAggregator(sink)
aggregator.start() # background thread builds the snapshot
log = OklSink("fr3.txt")
log.write_header(session_name="fr3", clock_type="VirtualClock", session_start=0.0)
runner = SessionRunner(
SessionConfig(name="fr3", schedule=ScheduleBuilder.fr(3), exit_condition=ReinforcementCountExit(count=3)),
sink=tee(log, sink), # record and watch at once
)
runner.start(start_time=0.0)
t = 0.0
while not runner.is_finished:
t += 1.0
if runner.is_reinforcing:
runner.end_reinforcement(t)
else:
runner.handle_response(t)
aggregator.stop() # final drain
snapshot = aggregator.snapshot()
print(snapshot.state, len(snapshot.response_times), snapshot.reinforcement_times)
# FINISHED 9 (3.0, 7.0, 11.0)
print(snapshot.sink_stats)
# SinkStats(emitted=23, enqueued=23, dropped=0)snapshot.response_times and snapshot.reinforcement_times are what the cumulative-record panel draws; sink_stats.dropped tells you whether the viewer fell behind. To see the same session in a browser, serve the log file:
session-visualizer tail fr3.txt --port 8765http://127.0.0.1:8765/snapshot then returns the same counts (9 responses, 3 reinforcers, state FINISHED), and http://127.0.0.1:8765/figure/cumulative-record returns the cumulative record as a PNG.
When the session runs in another process or on another machine, follow the log it writes. The HTTP interface is the same as for a session in your own process.
session-visualizer tail session.txt # OKL log written by session-recorder
session-visualizer tail events.jsonl --format jsonl # plain JSONL from your own program
session-visualizer tail session.txt --from-end # skip events written before the viewer startedInstalling watchdog (pip install watchdog) lets the tail react to file changes instead of polling, which lowers the delay. From Python, LogTailSource does the same with OKLTailReader (default) or JSONLTailReader.
from contingency import ScheduleBuilder
from experiment_core import Session
from session_visualizer import LiveAggregator, NonBlockingEventSink, SessionEventBridge
sink = NonBlockingEventSink(maxsize=4096)
aggregator = LiveAggregator(sink)
aggregator.start()
session = Session(ScheduleBuilder.fr(3))
bridge = SessionEventBridge(session, sinks=[sink]) # add an OklSink here to record as well
session.start(0.0)
bridge.sync() # call after every session operationWith session-runner, pass the sink as sink=, as in the example above. To serve it over HTTP, build the app with session_visualizer.server.build_app(aggregator) and run it with uvicorn.
/snapshot (current state as JSON), /events (a server-sent-events stream of snapshots), /figure/cumulative-record, /figure/irt-coded-cumulative-record, /figure/response-rate, /theme.json, and POST /suggest (the analyses worth showing for a contingency-dsl expression, from session-analyzer's analysis suggestions). Parameters and response formats are in the HTTP API reference.
| What | When | Where |
|---|---|---|
| Cumulative record, response marks, state | Every update | LiveAggregator snapshot |
| Moving-window rate, IRT descriptives, log-log generalized-matching slope | On a periodic tick (for example 10 s or 1 min) | PeriodicTicker with light fits (FitThrottle, compute_fits) |
| Non-linear demand curve, EM bout decomposition, bootstrap confidence intervals | After the session | session-analyzer |
The boundary is CPU cost, not whether a measure can be computed: a generalized-matching slope over a few dozen reinforcers is cheap enough for the periodic tick; a demand-curve fit with bootstrap is not.
| Extra | Adds | Purpose |
|---|---|---|
[fit] |
numpy, scipy |
Light periodic fits |
[server] |
fastapi, sse-starlette, uvicorn |
HTTP server |
[stream] |
watchdog |
File-change signals for tail |
[realtime] |
nothing | Installs no packages |
[full] |
[fit], [server], [stream], [realtime] |
Everything above |
session-visualizer replay events.jsonl --speed 4replays a JSONL log at four times wall-clock speed and prints the final counts.
- The live view drops events when its queue is full, by design. It is not a record of the session.
replayreads JSONL only, not OKL.session-visualizer servestarts a server with an empty view, for a program that attaches its own events; to watch a session from the command line, usetail.
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/pytestEvery python block in this README and README.ja.md is run by tests/test_readme_examples.py.
MIT (declared in pyproject.toml; the repository has no LICENSE file).