modify: cleanup project structure and docs
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tongnian0613/TrafficSafeAnalyzer.git
|
||||
cd TrafficSafeAnalyzer
|
||||
```
|
||||
|
||||
If you already have the repository, pull the latest changes instead:
|
||||
|
||||
```bash
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
## 2. Create a dedicated environment
|
||||
|
||||
### Option A: Built-in virtual environment
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
```
|
||||
|
||||
### Option B: Conda environment
|
||||
|
||||
```bash
|
||||
conda create -n trafficsa python=3.8 -y
|
||||
conda activate trafficsa
|
||||
```
|
||||
|
||||
## 3. Install project dependencies
|
||||
|
||||
Install the full dependency set listed in `requirements.txt`:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
If you prefer a minimal installation before pulling in extras, install the core stack first:
|
||||
|
||||
```bash
|
||||
pip install streamlit pandas numpy matplotlib plotly scikit-learn statsmodels scipy
|
||||
```
|
||||
|
||||
Then add optional packages as needed (Excel readers, auto-refresh, OpenAI integration):
|
||||
|
||||
```bash
|
||||
pip install streamlit-autorefresh openpyxl xlrd cryptography openai
|
||||
```
|
||||
|
||||
## 4. Verify the setup
|
||||
|
||||
1. Ensure the environment is still active (`which python` should point to `.venv` or the conda env).
|
||||
2. Launch the Streamlit app:
|
||||
|
||||
```bash
|
||||
streamlit run app.py
|
||||
```
|
||||
|
||||
3. 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.
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Usage Guide
|
||||
|
||||
TrafficSafeAnalyzer delivers accident analytics and decision support through a Streamlit interface. This guide walks through the daily workflow, expected inputs, and where to find generated artefacts.
|
||||
|
||||
## Start the app
|
||||
|
||||
1. Activate your virtual or conda environment.
|
||||
2. From the project root, run:
|
||||
|
||||
```bash
|
||||
streamlit run app.py
|
||||
```
|
||||
|
||||
3. Open `http://localhost:8501`. Keep the terminal running while you work in the browser.
|
||||
|
||||
## Load input data
|
||||
|
||||
Use the sidebar form labelled “数据与筛选”.
|
||||
|
||||
- **Accident data (`.xlsx`)** — columns should include at minimum:
|
||||
- `事故时间` (timestamp)
|
||||
- `所在街道` (region or district)
|
||||
- `事故类型`
|
||||
- `事故数`/`accident_count` (if absent, the loader aggregates counts)
|
||||
- **Strategy data (`.xlsx`)** — include:
|
||||
- `发布时间`
|
||||
- `交通策略类型`
|
||||
- optional descriptors such as `策略名称`, `策略内容`
|
||||
- Select the global filters (region, date window, strategy filter) and click `应用数据与筛选`.
|
||||
- Uploaded files are cached. Upload a new file or press “Rerun” to refresh after making edits.
|
||||
- Sample datasets for rapid smoke testing live in `sample/事故/*.xlsx` (accidents) and `sample/交通策略/*.xlsx` (strategies); copy them before making modifications.
|
||||
|
||||
> Tip: `services/io.py` performs validation; rows missing key columns are dropped with a warning in the Streamlit log.
|
||||
|
||||
## Navigate the workspace
|
||||
|
||||
- **🏠 总览 (Overview)** — KPI cards, time-series plot, filtered table, and download buttons for HTML (`overview_series.html`), CSV (`filtered_view.csv`), and run metadata (`run_metadata.json`).
|
||||
- **📈 预测模型 (Forecast)** — choose an intervention date and horizon, compare ARIMA / KNN / GLM / SVR forecasts, and export `arima_forecast.csv`（提交后结果会在同一数据集下保留，便于调整其他控件）。
|
||||
- **📊 模型评估 (Model evaluation)** — run rolling-window backtests, inspect RMSE/MAE/MAPE, and download `model_evaluation.csv`.
|
||||
- **⚠️ 异常检测 (Anomaly detection)** — isolation forest marks outliers on the accident series; tweak contamination via the main page controls.
|
||||
- **📝 策略评估 (Strategy evaluation)** — Aggregates metrics per strategy type, recommends the best option, writes `strategy_evaluation_results.csv`, and updates `recommendation.txt`.
|
||||
- **⚖️ 策略对比 (Strategy comparison)** — side-by-side metrics for selected strategies, useful for “what worked best last month” reviews.
|
||||
- **🧪 情景模拟 (Scenario simulation)** — apply intervention models (persistent/decay, lagged effects) to test potential roll-outs.
|
||||
- **🔍 GPT 分析** — enter your own OpenAI-compatible API key and base URL in the sidebar to generate narrative insights. Keys are read at runtime only.
|
||||
- **📍 事故热点 (Hotspot)** — reuse the already uploaded accident data to identify high-risk intersections and produce targeted mitigation ideas; no separate hotspot upload is required.
|
||||
|
||||
Each tab remembers the active filters from the sidebar so results stay consistent.
|
||||
|
||||
## Downloaded artefacts
|
||||
|
||||
Generated files are saved to the project root unless you override paths in the code:
|
||||
|
||||
- `overview_series.html`
|
||||
- `filtered_view.csv`
|
||||
- `run_metadata.json`
|
||||
- `arima_forecast.csv`
|
||||
- `model_evaluation.csv`
|
||||
- `strategy_evaluation_results.csv`
|
||||
- `recommendation.txt`
|
||||
|
||||
After a session, review and archive these outputs under `docs/` or a dated folder as needed.
|
||||
|
||||
## Operational tips
|
||||
|
||||
- **Auto refresh**: enable from the sidebar (requires `streamlit-autorefresh`). Set the interval in seconds for live dashboards.
|
||||
- **Logging**: set `LOG_LEVEL=DEBUG` before launch to see detailed diagnostics in the terminal and Streamlit log.
|
||||
- **Reset filters**: choose “全市” and the full date span, then re-run the sidebar form.
|
||||
- **Common warnings**:
|
||||
- *“数据中没有检测到策略”*: verify the strategy Excel file and column names.
|
||||
- *ARIMA failures*: shorten the horizon or ensure at least 10 historical data points before the intervention date.
|
||||
- *Hotspot data issues*: ensure the accident workbook includes `事故时间`, `所在街道`, `事故类型`, and `事故具体地点` so intersections can be resolved.
|
||||
|
||||
Need deeper integration or batch automation? Extract the core functions from `services/` and orchestrate them in a notebook or scheduled job.
|
||||
|
||||
Reference in New Issue
Block a user