Bots Position Viewer

Part of the DIMS-network — see the DIMS Dashboard.

Interactive dashboard for exploring player movement data from the bots experiment — a study on human–bot detection in a two-player 2D grid game.

See deployed on huggingface Bots-viewer

---

What the experiment is about

Pairs of participants played 30-second rounds on a 10×10 grid. After each round, each player rated whether they thought their partner was a human or a bot (1 = definitely human, 5 = definitely bot) and how much they felt they were doing something together (1 = not at all, 5 = very much).

The dataset contains 521 rounds with two players each, recorded at 10 Hz (300 ticks per round).

---

Files

Path	Purpose
app.py	Dash dashboard (run this)
rqa_analysis.py	RQA / cRQA computation module — designed to be modified
assets/data/positions.csv	Raw movement data — 312 600 rows, 9 columns
assets/theme.css	Dark-theme CSS overrides
notebooks/lab04_rqa.ipynb	Tutorial notebook the analysis follows
requirements.txt	Python dependencies
Dockerfile	Container build (Hugging Face Spaces deploy)

---

Dataset columns

Column	Description
playerRoundId	Unique ID for a player within a round
roundId	Unique round identifier
tick	Timestep 0–299 (30 s at 10 Hz)
x, y	Position on the 10×10 grid
answer	Player's perception of partner: 1 (human) – 5 (bot)
partners_answer	Partner's same rating
togetherness	Felt sense of doing something together: 1 (no) – 5 (yes)
partners_togetherness	Partner's same rating

---

Setup

pip install -r requirements.txt

Note: PyRQA uses OpenCL for acceleration. On most machines it will fall back to CPU automatically. If you see OpenCL warnings, they are safe to ignore.

---

Running the dashboard

cd bots-viewer
python app.py            # opens at http://localhost:8051
python app.py --port 8055

Dashboard tabs

Tab	Shows
Trajectory	Animated player circles on the grid (Play/Pause + scrubber). Toggle the Trail button to overlay full paths. When both players share a cell, they split left/right.
RQA — Player 1/2	Recurrence plot (RP) for each player's x-coordinate + quantification metrics table
cRQA (cross)	Cross-recurrence plot between both players + metrics table

The sidebar lets you switch between coordinate modes (x, y, x+y) and tune all RQA/cRQA parameters live.

---

Running the batch analysis script

Computes RQA and cRQA for every round and saves a CSV of metrics:

python rqa_analysis.py
# → writes rqa_metrics_all.csv next to this file

python rqa_analysis.py --csv /path/to/positions.csv --out /path/to/output.csv

---

Modifying the analysis (rqa_analysis.py)

All tunable parameters are in the DEFAULT PARAMETERS block at the top of the file:

# RQA (single player)
RQA_EMBEDDING_DIM = 1     # phase-space embedding dimension
RQA_TIME_DELAY    = 1     # lag between embedded dimensions (ticks)
RQA_RADIUS        = 1.0   # FixedRadius threshold — raise for more recurrences

# cRQA (cross between two players)
CRQA_EMBEDDING_DIM = 3
CRQA_TIME_DELAY    = 5
CRQA_RADIUS        = 1.0

# Coordinate mode: 'x', 'y', or 'xy'
COORDINATE_MODE = 'x'

Aim for a recurrence rate between ~5% and ~20%. If RR is too low, increase the radius; if too high, decrease it.

For the 'xy' mode (2D positions), a radius of ~1.5 works well:

COORDINATE_MODE = 'xy'
RQA_RADIUS      = 1.5
CRQA_RADIUS     = 1.5

RQA metrics

Metric	Meaning
RR	Recurrence Rate — density of recurrent points
DET	Determinism — proportion of points on diagonal lines (predictability)
L	Average diagonal line length
L_max	Longest diagonal line
DIV	Divergence — 1 / L_max (related to Lyapunov exponent)
L_entr	Shannon entropy of diagonal line lengths
LAM	Laminarity — proportion of points on vertical lines (intermittency)
TT	Trapping Time — average vertical line length
V_max	Longest vertical line
V_entr	Shannon entropy of vertical line lengths

---

Reference

Parameters follow the tutorial notebook lab04_rqa.ipynb (CPM II course, 2025).
PyRQA documentation: https://pypi.org/project/PyRQA/8.1.0/