If you use the simulator for academic work please cite the following papers:
Tested with Python 3.12.3 and the uv package manager.
Follow these steps to set up the project.
Step 1: Install uv. uv is a fast Python package and environment manager. Install it using one of the following methods:
macOS / Linux (bash/zsh):
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iexAlternative (if you already have Python and pip):
pip install uvStep 2: Fix permissions (if needed):t
Sometimes uv needs to create a folder under ~/.local/share/uv/python (macOS/Linux) or %LOCALAPPDATA%\uv\python (Windows).
If this folder was created by another tool (e.g. sudo), you may see an error like:
error: failed to create directory ... Permission denied (os error 13)To fix it, ensure you own the directory:
mkdir -p ~/.local/share/uv
chown -R "$(id -un)":"$(id -gn)" ~/.local/share/uv
chmod -R u+rwX ~/.local/share/uv# Create directory if it doesn't exist
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\uv"
# Ensure you (the current user) own it
# (usually not needed, but if permissions are broken)
icacls "$env:LOCALAPPDATA\uv" /grant "$($env:UserName):(OI)(CI)F"Step 3: After installing, verify:
uv --versionStep 4: Clone the repository:
git clone https://github.com/Shaadalam9/multiped-learning
cd multipedStep 5: Ensure correct Python version. If you don’t already have Python 3.12.3 installed, let uv fetch it:
uv python install 3.12.3The repo should contain a .python-version file so uv will automatically use this version.
Step 6: Create and sync the virtual environment. This will create .venv in the project folder and install dependencies exactly as locked in uv.lock:
uv sync --frozenStep 7: Activate the virtual environment:
macOS / Linux (bash/zsh):
source .venv/bin/activateWindows (PowerShell):
.\.venv\Scripts\Activate.ps1Windows (cmd.exe):
.\.venv\Scripts\activate.batStep 8: Ensure that dataset are present. Place required datasets (including mapping.csv) into the data/ directory:
Step 9: Run the code:
python3 analysis.pyConfiguration of the project needs to be defined in multiped/config. Please use the default.config file for the required structure of the file. If no custom config file is provided, default.config is used. The config file has the following parameters:
mapping: CSV file that contains all data found in the videos.plotly_template: Template used to make graphs in the analysis.output: Directory where analysis results and intermediate output files will be saved.figures: Directory where final figures and plots are stored.data: Directory containing all raw and processed data files used in the analysis.intake_questionnaire: CSV file containing participant responses from the intake (pre-experiment) questionnaire.post_experiment_questionnaire: CSV file containing participant responses from the post-experiment questionnaire.compare_trial: Reference trial against which all other trials are compared during t-tests in the analysis.kp_resolution: Time bin size, in milliseconds, used for storing keypress data, which controls the resolution of keypress event logs.yaw_resolution: Time bin size, in milliseconds, used for storing yaw (head rotation) data, controlling the resolution of HMD orientation data.smoothen_signal: Boolean toggle to enable or disable signal smoothing for data analysis.freq: Frequency parameter used by the One Euro Filter for signal smoothing.mincutoff: Minimum cutoff frequency for the One Euro Filter.beta: Beta value controlling the speed-versus-smoothness tradeoff in the One Euro Filter.font_family: Font family to be used in all generated figures for visual consistency.font_size: Font size to be applied to all text in generated figures.p_value: p-value threshold to be used for statistical significance testing (e.g., in t-tests).
Trial level distribution of the fraction of time spent in the unsafe zone. Larger values indicate that participants spent more of the trial in a state classified as unsafe.
Trial level distribution of the mean continuous unsafety signal. Larger values indicate greater average perceived unsafety during the trial.
Trial level distribution of peak unsafety, summarised by the ninety fifth percentile of the trigger signal within each trial.
Trial level distribution of the maximum rate of increase in the continuous unsafety signal. Larger values indicate sharper escalations in perceived unsafety.
Trial level distribution of the time to the first unsafe button press. Smaller values indicate faster commitment to an unsafe response.
Trial level distribution of the time to the first release from an unsafe button press. Smaller values indicate faster disengagement from the unsafe response.
Trial level distribution of the interval between the first unsafe button press and the first release. Larger values indicate that an initial unsafe commitment was maintained for longer once initiated.
Trial level distribution of the average duration of unsafe bouts within a trial.
Trial level distribution of average absolute head yaw. Larger values indicate that participants looked further away from straight ahead on average.
Trial level distribution of the fraction of time that head yaw remained within fifteen degrees of straight ahead.
Trial level distribution of head yaw variability. Larger values indicate more variable head orientation within the trial.
Trial level distribution of the entropy of head yaw. Larger values indicate less stereotyped visual scanning patterns.
Trial level distribution of average head turning speed.
Trial level distribution of the number of head turns crossing the fifteen degree threshold.
Trial level distribution of the average time spent in head turn states beyond fifteen degrees.
Trial level distribution of average head yaw speed during the one second window before the first unsafe button press.
Trial level distribution of the delay between a threshold crossing head turn and the first unsafe button press.
Trial level distribution of net head yaw change during the one second window before the first unsafe button press.
Trial level distribution of average head yaw speed during the two second window before the first unsafe button press.
Trial level distribution of mean head yaw during the two second window before the first unsafe button press.
Trial level distribution of mean head yaw during the earlier pre press window from two to one seconds before the first unsafe button press.
Trial level distribution of mean head yaw in the one second window before and after the first unsafe button release.
Trial level distribution of the strongest cross correlation between head yaw speed and the first derivative of the trigger signal within a trial.
Trial level distribution of the lag at which the cross correlation between head yaw speed and the first derivative of the trigger signal is strongest.
Trial level distribution of net head yaw change during the one second window before the first unsafe button release.
Trial level distribution of Q1 ratings across the randomised and fixed order datasets.
Trial level distribution of Q2 ratings across the randomised and fixed order datasets.
Trial level distribution of Q3 ratings across the randomised and fixed order datasets.
Trial level association between Q3 ratings and unsafety volatility. The figure shows whether higher subjective ratings are aligned with more variable continuous unsafety responses.
Trial level association between Q3 ratings and the number of transitions in the trigger signal.
Trial level association between Q2 ratings and the fraction of trial time spent in the unsafe zone.
Trial level association between average absolute head yaw and average continuous unsafety.
Trial level association between the fraction of time looking forward within fifteen degrees and the fraction of time spent in the unsafe zone.
Trial level association between average head turning speed and the steepest increase in the trigger signal.
Trial level association between average head yaw speed in the one second before first press and the latency to the first unsafe press.
Trial level coupling between head yaw variability and volatility of the continuous unsafety signal.
Trial level association between the fraction of time looking forward within fifteen degrees and Q3 ratings.
Head orientation summary by experimental context. The figure shows how the proportion of forward looking behaviour varies across condition combinations.
Head orientation summary by experimental context with an explicit camera or visibility breakdown.
Curves show the mean probability of missing first press latency across participants at each trial position for the randomised and fixed order datasets. Shaded bands indicate ninety five percent confidence intervals.
Curves show the mean probability of missing first release latency across participants at each trial position for the randomised and fixed order datasets. Shaded bands indicate ninety five percent confidence intervals.
Average trial composition by trial position across participants for the yielding factor. For each trial position, the curves show the proportion of participants who encountered a yielding trial.
Average trial composition by trial position across participants for the eHMI factor. For each trial position, the curves show the proportion of participants who encountered an eHMI on trial.
Participant level carryover of previous trial yielding on Q3 ratings.
Participant level early to late drift in Q3 ratings. Positive values indicate higher Q3 ratings later in the session than earlier in the session.
Participant level linear slope of Q3 over trial position.
Participant level carryover of previous trial yielding on unsafety volatility.
Participant level carryover of previous trial yielding on mean continuous unsafety.
Participant level carryover of previous trial eHMI status on Q3 ratings.
Participant level carryover of previous trial camera or visibility condition on Q3 ratings.
Participant level carryover of previous trial pedestrian distance on Q3 ratings.
Within participant reliability of mean continuous unsafety for odd and even trial splits.
Within participant reliability of mean continuous unsafety for early and late trial halves.
Within participant reliability of Q3 ratings for odd and even trial splits.
Within participant reliability of Q3 ratings for early and late trial halves.
Participant level comparison of mean continuous unsafety using break aligned trial segments.
Participant level comparison of unsafety volatility using break aligned trial segments.
Participant level comparison of Q3 ratings using break aligned trial segments.
Descriptive time on task curve for mean continuous unsafety over trial position by dataset.
Descriptive time on task curve for Q3 over trial position by dataset.
Descriptive time on task curve for unsafety volatility over trial position by dataset.
Exposure based learning curve for Q3 as a function of cumulative yielding exposure.
Exposure based learning curve for Q3 as a function of cumulative eHMI exposure.
Forest summary of exposure interaction effects from the mixed effects models.
ROC AUC by signal and dataset for discriminating yielding versus non yielding trials. The dashed reference line indicates chance performance at AUC equals zero point five.
Receiver operating characteristic curves for the strongest yielding versus non yielding signals, shown separately by dataset.
Forest plot of dataset by condition interaction coefficients from the primary mixed effects models.
Forest plot of dataset by trial position interaction coefficients from the learning models.
Forest plot of dataset interactions for lag and switch terms in the sequential models.
Descriptive means plot for mean continuous unsafety by dataset and yielding condition.
Descriptive means plot for mean continuous unsafety by dataset and eHMI condition.
Mean trajectory of mean continuous unsafety over trial position by dataset, shown as a descriptive companion to the mixed effects learning model.
Descriptive lag scatter for mean continuous unsafety, showing the relation between the current trial and the immediately previous trial by dataset.
Equivalence plot for the dataset by yielding interaction coefficient on mean continuous unsafety, showing the confidence interval relative to the equivalence bounds.
Participant level distribution of baseline mean mean continuous unsafety computed from the first main trials of the session.
Descriptive means plot for number of trigger transitions by dataset and yielding condition.
Descriptive means plot for number of trigger transitions by dataset and eHMI condition.
Mean trajectory of number of trigger transitions over trial position by dataset, shown as a descriptive companion to the mixed effects learning model.
Descriptive lag scatter for number of trigger transitions, showing the relation between the current trial and the immediately previous trial by dataset.
Equivalence plot for the dataset by yielding interaction coefficient on number of trigger transitions, showing the confidence interval relative to the equivalence bounds.
Descriptive means plot for Q3 rating by dataset and yielding condition.
Descriptive means plot for Q3 rating by dataset and eHMI condition.
Mean trajectory of Q3 rating over trial position by dataset, shown as a descriptive companion to the mixed effects learning model.
Descriptive lag scatter for Q3 rating, showing the relation between the current trial and the immediately previous trial by dataset.
Equivalence plot for the dataset by yielding interaction coefficient on Q3 rating, showing the confidence interval relative to the equivalence bounds.
Participant level distribution of baseline mean Q3 rating computed from the first main trials of the session.
Descriptive means plot for head yaw standard deviation by dataset and yielding condition.
Descriptive means plot for head yaw standard deviation by dataset and eHMI condition.
Mean trajectory of head yaw standard deviation over trial position by dataset, shown as a descriptive companion to the mixed effects learning model.
Descriptive lag scatter for head yaw standard deviation, showing the relation between the current trial and the immediately previous trial by dataset.
Equivalence plot for the dataset by yielding interaction coefficient on head yaw standard deviation, showing the confidence interval relative to the equivalence bounds.
Participant level distribution of baseline mean head yaw standard deviation computed from the first main trials of the session.
Descriptive means plot for fraction of trial time in unsafe zone by dataset and yielding condition.
Descriptive means plot for fraction of trial time in unsafe zone by dataset and eHMI condition.
Mean trajectory of fraction of trial time in unsafe zone over trial position by dataset, shown as a descriptive companion to the mixed effects learning model.
Descriptive lag scatter for fraction of trial time in unsafe zone, showing the relation between the current trial and the immediately previous trial by dataset.
Equivalence plot for the dataset by yielding interaction coefficient on fraction of trial time in unsafe zone, showing the confidence interval relative to the equivalence bounds.
Participant level distribution of baseline mean fraction of trial time in unsafe zone computed from the first main trials of the session.
Participant level distribution of post break reset for Q3 ratings by ordering group.
Participant level distribution of post break reset for unsafety volatility by ordering group.
Participant level distribution of post break reset for number of trigger transitions by ordering group.
Participant level distribution of post break reset for mean continuous unsafety by ordering group.
Participant level distribution of post break reset for head yaw standard deviation by ordering group.
Participant level distribution of carryover of previous trial yielding for number of trigger transitions by ordering group.
Participant level distribution of carryover of previous trial camera or visibility condition for unsafety volatility by ordering group.
Participant level distribution of carryover of previous trial camera or visibility condition for number of trigger transitions by ordering group.
Participant level distribution of carryover of previous trial camera or visibility condition for mean continuous unsafety by ordering group.
Participant level distribution of carryover of previous trial camera or visibility condition for head yaw standard deviation by ordering group.
Participant level distribution of carryover of previous trial pedestrian distance for unsafety volatility by ordering group.
Participant level distribution of carryover of previous trial pedestrian distance for number of trigger transitions by ordering group.
Participant level distribution of carryover of previous trial pedestrian distance for mean continuous unsafety by ordering group.
Participant level distribution of carryover of previous trial pedestrian distance for head yaw standard deviation by ordering group.
Participant level distribution of carryover of previous trial eHMI status for unsafety volatility by ordering group.
Participant level distribution of carryover of previous trial eHMI status for number of trigger transitions by ordering group.
Participant level distribution of carryover of previous trial eHMI status for mean continuous unsafety by ordering group.
Participant level distribution of carryover of previous trial eHMI status for head yaw standard deviation by ordering group.
Participant level distribution of carryover of previous trial yielding for head yaw standard deviation by ordering group.
Participant level distribution of early to late drift for unsafety volatility by ordering group.
Participant level distribution of early to late drift for number of trigger transitions by ordering group.
Participant level distribution of early to late drift for mean continuous unsafety by ordering group.
Participant level distribution of early to late drift for head yaw standard deviation by ordering group.
Participant level distribution of linear slope for unsafety volatility by ordering group.
Participant level distribution of linear slope for number of trigger transitions by ordering group.
Participant level distribution of linear slope for mean continuous unsafety by ordering group.
Participant level distribution of linear slope for head yaw standard deviation by ordering group.
Participant level distribution of late minus early change in the interquartile range of Q3 ratings by ordering group.
Participant level distribution of late minus early change in the standard deviation of Q3 ratings by ordering group.
Participant level distribution of mean within condition standard deviation of Q3 ratings by ordering group.
Participant level distribution of weighted within condition standard deviation of Q3 ratings by ordering group.
Participant level distribution of absolute dissociation between standardised Q2 ratings and unsafe time by ordering group.
Participant level distribution of participant level Fisher z correlation between Q2 and mean unsafety by ordering group.
Participant level distribution of participant level Fisher z correlation between Q2 and unsafe time fraction by ordering group.
Participant level distribution of participant level Fisher z correlation between Q3 and first release latency in yielding trials by ordering group.
Participant level distribution of participant level Fisher z correlation between Q3 and trigger transitions by ordering group.
Participant level distribution of participant level Fisher z correlation between Q3 and unsafety volatility by ordering group.
Participant level distribution of participant level Fisher z correlation between forward looking fraction and Q3 by ordering group.
Participant level distribution of participant level Fisher z correlation between head yaw variability and unsafety volatility by ordering group.
Descriptive time on task curve for number of trigger transitions over trial position by dataset.
Descriptive time on task curve for head yaw standard deviation over trial position by dataset.
Trial level distribution of the fraction of samples in which participants looked approximately forward.
Trial level distribution of mean head yaw by dataset.
Trial level distribution of head yaw standard deviation by dataset.
Participant level distribution of baseline mean forward looking fraction within fifteen degrees computed from the first main trials of the session.