A computational modeling framework for pedestrian moving-obstacle avoidance behavior in the Bai movObst2 experiment, based on dynamical systems approaches (Fajen-style steering and Cohen-style avoidance). This project includes ODE simulation, model fitting via optimization, data import pipelines, and analysis notebooks.
We welcome contributions — whether you want to fix bugs, extend models, add analyses, or improve documentation. See Contributing for how to get involved.
This repository implements modeling and analysis specifically for the Bai movObst2 experiments (movObst2a, movObst2b):
- Approach models (goal-directed steering):
fajen_approach,fajen_approach2,acceleration_approach,jerk_approach - Avoidance models (obstacle evasion):
cohen_avoid,cohen_avoid2,cohen_avoid3,cohen_avoid4,perpendicular_avoid,cohen_avoid_heading,cohen_avoid4_heading - ODE simulation of combined approach + avoidance dynamics
- Model fitting via differential evolution, dual annealing, Nelder–Mead, and related methods
- VR experiment scripts (
movObst2a,movObst2b) for data collection (requires WorldViz Vizard)
├── requirements.txt
├── README.md
└── Bai_movObst2/
├── packages/
│ ├── ode_simulator.py # ODE integration & trajectory simulation
│ ├── models.py # Approach and avoidance model definitions
│ ├── helper.py # Geometry, plotting, and utilities
│ └── data_container.py # Data loading and preprocessing
├── parameters.py # Trained model parameters and bounds
├── fitting.py # Model fitting via scipy.optimize
├── movObst2a.py # VR experiment (moving obstacle)
├── movObst2b.py # VR experiment variant
├── movObst2_inputGenerator.py
├── vizconnect_config.py # Vizard connection config
├── import_data_*.ipynb # Raw data → processed Data objects
├── simulation.ipynb # Run simulations and visualize trajectories
├── analysis.ipynb # Statistical analysis and plots
├── start_fitting_cross_validation.bat
├── start_fitting_individual.bat
└── fitting_cmd_input.txt # Example fitting command
- Python 3.8+
- NumPy, SciPy, scikit-learn, Matplotlib
-
Clone the repository
git clone <repository-url> cd <repository-name>
-
Create a virtual environment (recommended)
python -m venv venv # Windows venv\Scripts\activate # Linux/macOS source venv/bin/activate
-
Install dependencies
pip install -r requirements.txt
Or manually:
pip install numpy scipy scikit-learn matplotlib
-
Data layout
Place raw experiment data underRaw_Data/relative to this project. The notebooks and scripts expect pickle files such asBai_movObst2_data_30Hz.pickle,Cohen_movObst2_data.pickle, etc.
Use Bai_movObst2/simulation.ipynb to:
- Load data with
load_data('Bai_movObst2_data')(or another dataset) - Run simulations with
ODESimulatorand fitted models fromparameters.py - Visualize trajectories with
sim.play()
Bai_movObst2/fitting.py supports command-line arguments for experiment, subjects, and models.
Example: fit avoidance model (all subjects)
python Bai_movObst2/fitting.py --experiment_name Bai_movObst2 \
--approach_experiment Bai_movObst2 \
--subject all \
--t_start obst_onset \
--t_end obst_out \
--ps trial \
--method differential_evolution \
--approach_model fajen_approach2 \
--avoid_model cohen_avoid4 \
--training_model cohen_avoid4Example: leave-one-subject-out cross-validation
Use negative subject indices to exclude subjects (e.g. --subject -0 excludes subject 0). The batch file start_fitting_cross_validation.bat runs multiple subjects in parallel.
Key arguments
| Argument | Description |
|---|---|
--experiment_name |
Bai_movObst2, Cohen_movObst2, etc. |
--approach_experiment |
Experiment used for approach model parameters |
--subject |
Subject ID, all, or negative for cross-validation |
--t_start / --t_end |
Time window, e.g. obst_onset, obst_out, dtheta*dpsi_onset |
--method |
differential_evolution, dual_annealing, nelder-mead, shgo, basinhopping |
--approach_model |
fajen_approach, fajen_approach2, acceleration_approach, jerk_approach |
--avoid_model |
cohen_avoid, cohen_avoid2, cohen_avoid3, cohen_avoid4, perpendicular_avoid, etc. |
--training_model |
Model being fitted (same as approach or avoidance) |
Bai_movObst2/import_data_bai_movObst2.ipynb
Convert raw CSV/experiment output toDataobjects and save as pickle files.Bai_movObst2/analysis.ipynb
Run statistics, model comparisons, MDS, and plots.
- Raw data should be placed in
Raw_Data/(or the path used infitting.pyand notebooks). - The
Dataclass inBai_movObst2/packages/data_container.pyhandles trial metadata, trajectories, and derived quantities. - Preprocessed data files (
.pickle) are produced by the import notebooks.
We welcome contributions from the community. Here is how you can help.
- Fork the repository and create a new branch for your changes.
- Discuss large changes by opening an issue first.
- Implement your changes with clear, documented code.
- Test your changes (e.g. run
fitting.pyor relevant notebooks). - Submit a pull request with a concise description of the change.
- Models: New approach/avoidance models in
packages/models.pyand wiring inode_simulator.py - Fitting: New optimization methods or metrics in
fitting.py - Analysis: New analyses, plots, or metrics in
analysis.ipynb - Documentation: README, docstrings, tutorials, and examples
- Data: Bug fixes or extensions in
data_container.pyand import notebooks - VR experiments: Fixes or extensions for
movObst2a,movObst2b(Vizard-specific)
- Use PEP 8 style conventions.
- Add docstrings for new functions and classes.
- Keep commits focused and messages descriptive.
- Use the GitHub issue tracker for bugs, feature requests, and questions.
- Include:
- Clear description of the problem or request
- Steps to reproduce (for bugs)
- Environment (OS, Python version)
- Relevant output or error messages
See LICENSE for details.
This work builds on dynamical systems models of steering and obstacle avoidance by Fajen and Warren, and Cohen and collaborators. Created by Jiuyang Bai.