Installation Guide

This document explains how to set up TrafficSafeAnalyzer for local development and exploration. The application runs on Streamlit and officially supports Python 3.8.

Prerequisites

Python 3.8 (3.9+ is not yet validated; use 3.8 to avoid dependency issues)
Git
pip (bundled with Python)
Optional: Conda (for environment management) or Docker (for container-based runs)

1. Obtain the source code

git clone https://github.com/tongnian0613/TrafficSafeAnalyzer.git
cd TrafficSafeAnalyzer

If you already have the repository, pull the latest changes instead:

git pull origin main

2. Create a dedicated environment

Option A: Built-in virtual environment

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

Option B: Conda environment

conda create -n trafficsa python=3.8 -y
conda activate trafficsa

3. Install project dependencies

Install the full dependency set listed in requirements.txt:

pip install -r requirements.txt

If you prefer a minimal installation before pulling in extras, install the core stack first:

pip install streamlit pandas numpy matplotlib plotly scikit-learn statsmodels scipy

Then add optional packages as needed (Excel readers, auto-refresh, OpenAI integration):

pip install streamlit-autorefresh openpyxl xlrd cryptography openai

4. Verify the setup

Ensure the environment is still active (which python should point to .venv or the conda env).
Launch the Streamlit app:
```
streamlit run app.py
```
Open http://localhost:8501 in your browser. The home page should load without import errors.

Troubleshooting tips

Missing package: Re-run pip install -r requirements.txt.
Python version mismatch: Confirm python --version reports 3.8.x inside your environment.
OpenSSL or cryptography errors (macOS/Linux): Update the system OpenSSL libraries and reinstall cryptography.
Taking too long to install: if a dependency download stalls due to a firewall, retry using a mirror (-i https://pypi.tuna.tsinghua.edu.cn/simple) consistent with your environment policy.

After a successful launch, continue with the usage guide in docs/usage.md to load data and explore forecasts.

2.3 KiB Raw Blame History