saturation 1.1.0

服务区饱和度分析系统

服务区饱和度分析系统

本系统用于高速公路服务区饱和度分析，包含数据处理、聚类分析、分类判别、流量分析、饱和度分析和预测模型六个主要功能模块。通过系统封装的API接口，用户可以轻松地分析和预测服务区的饱和度情况。

1. 功能特点

• 数据处理：清洗和预处理原始ETC数据
• 聚类分析：对处理后的数据进行聚类分析
• 分类判别：基于聚类结果和速度数据进行分类判别
• 流量分析：分析车流量特征，计算不同类型车辆的流量
• 饱和度分析：计算服务区饱和度，评估服务区运营状态
• 预测模型：基于历史数据预测未来饱和度趋势

2. 安装方法

2.1 使用pip安装

pip install saturation

2.2 从源码安装

git clone <项目仓库URL>
cd 服务区饱和度分析
pip install -e .

3. 快速开始

3.1 基本用法

from saturation import analyze_saturation, predict_saturation

# 分析饱和度
result = analyze_saturation(
    ke_flow_filename="ke_flow1.csv", 
    huo_flow_filename="huo_flow1.csv"
)
print(f"饱和度分析结果保存在：{result}")

# 预测未来饱和度
prediction = predict_saturation(
    input_filename="flow-kehuo-adjusted.xlsx",
    epochs=100,
    batch_size=64
)
print(f"预测评估指标：RMSE={prediction['rmse']:.4f}, MAE={prediction['mae']:.4f}")

3.2 使用自定义路径

新版本支持自定义输入输出路径，您可以使用以下方式指定数据文件的路径：

from saturation import controller

# 方法1：使用全局设置
controller.set_data_dir("./my_data")
controller.set_output_dir("./my_results")

# 处理数据
processed_file = controller.process_data(
    input_file="G006550002000620010.csv",
    output_file="processed_data.csv"  # 可选，不指定则使用默认名称
)

# 分析饱和度
saturation_result = controller.analyze_saturation(
    ke_flow_file="ke_flow1.csv",
    huo_flow_file="huo_flow1.csv",
    output_file="saturation_result.csv"  # 可选
)

# 方法2：创建控制器实例
ctrl = controller.SaturationController(
    data_dir="./another_data_dir",
    output_dir="./another_output_dir"
)

# 使用控制器实例进行分析
result = ctrl.analyze_flow(
    input_file="speed_current.csv"
)

# 预测饱和度
prediction = ctrl.predict_saturation(
    input_file="flow-kehuo-adjusted.xlsx",
    output_model="my_model.h5",  # 可选，指定模型保存路径
    epochs=100,
    batch_size=64
)

3.3 使用高级API

from saturation import api

# 配置数据目录
data_dir = api.configure_data_directory('./my_data')

# 处理原始数据
api.process_raw_data(
    input_file="G006550002000620010.csv",
    data_dir=data_dir
)

# 分析车辆流量
api.analyze_flow(
    input_file="speed_current1.csv",
    data_dir=data_dir
)

# 分析饱和度
api.analyze_saturation_level(
    ke_flow_file="ke_flow1.csv",
    huo_flow_file="huo_flow1.csv",
    data_dir=data_dir
)

# 执行完整分析流程
results = api.run_complete_pipeline(
    input_file="G006550002000620010.csv",
    data_dir=data_dir
)

3.4 使用专门的流量分析API

from saturation import flow_api

# 分析内部和外部流量
inner_path, outer_path = flow_api.analyze_inner_outer_flow(
    input_file="speed_current.csv"
)

# 按车辆类型分析流量
ke_inner, ke_outer, huo_inner, huo_outer = flow_api.analyze_vehicle_type_flow(
    input_file="speed_current.csv"
)

3.5 使用专门的预测API

from saturation import prediction_api

# 预测未来饱和度
result = prediction_api.predict_future_saturation(
    input_file="flow-kehuo-adjusted.xlsx",
    epochs=100,
    batch_size=32
)

# 加载已有模型进行预测
predictions = prediction_api.load_model_and_predict(
    model_file="saturation_model.h5",
    input_file="new_data.xlsx"
)

# 使用自定义参数
result = prediction_api.run_prediction_with_custom_params(
    input_file="flow-kehuo-adjusted.xlsx",
    model_params={'lstm_units': 128, 'time_steps': 10},
    training_params={'epochs': 200}
)

4. 命令行工具

系统还提供了命令行工具，可以直接在终端中使用：

# 执行完整分析流程
saturation-analyze --all

# 仅执行饱和度分析
saturation-analyze --analyze

# 指定自定义路径
saturation-analyze --input my_data.csv --output my_results.csv

# 预测饱和度
saturation-predict --input flow-kehuo-adjusted.xlsx --epochs 100

# 分析流量
saturation-flow

5. 数据要求

系统需要在数据目录下存放以下格式的数据文件：

• 原始ETC数据：包含车辆ID、通过时间、车辆类型等信息
• 车辆通行数据：上下行车辆的匹配数据
• 流量数据：不同类型车辆的流量数据

5.1 车辆类型编码

编码	车辆类型
1-4	客车
11-16	货车
21-26	作业车

6. API参考文档

详细的API文档请参考 docs/user_guide.md

7. 示例代码

可以在 examples 目录下找到更多示例代码：

• basic_usage.py：基本使用示例
• advanced_analysis.py：高级分析示例
• custom_paths_example.py：自定义路径示例
• custom_prediction.py：自定义预测示例

8. 开发说明

8.1 目录结构

服务区饱和度分析/
├── result/              # 数据存储目录
├── saturation/          # 主程序包
│   ├── __init__.py      # 包初始化
│   ├── api.py           # 主API接口
│   ├── controller.py    # 控制器模块
│   ├── flow_api.py      # 流量分析专用API
│   ├── prediction_api.py # 预测专用API
│   ├── main.py          # 主程序入口
│   ├── flow.py          # 流量分析模块
│   ├── utils/           # 工具模块
│   │   ├── __init__.py
│   │   ├── file_utils.py # 文件操作工具
│   │   └── config.py    # 配置管理
│   ├── enJud/           # 入口判断模块
│   │   ├── __init__.py
│   │   ├── data_process.py  # 数据处理
│   │   ├── julei.py     # 聚类分析
│   │   ├── fenleipanbie.py  # 分类判别
│   │   └── ...
│   ├── satAna/          # 饱和度分析模块
│   │   ├── __init__.py
│   │   └── saturation.py  # 饱和度分析
│   └── pre/             # 预测模块
│       ├── __init__.py
│       ├── 预测模型.py   # 预测模型
│       └── *.h5         # 模型文件
├── examples/            # 示例代码
├── docs/                # 文档
└── setup.py             # 安装配置

8.2 依赖项

• Python 3.7+
• pandas
• numpy
• scikit-learn
• matplotlib
• tensorflow
• keras
• scipy
• scikit-fuzzy
• scikit-opt

9. 许可证

本项目遵循 MIT 许可证