pvdata 0.2.1

High-performance toolkit for photovoltaic data processing, PV simulation, and time series analysis

pvdata - Photovoltaic Data Toolkit

高性能光伏数据处理工具包，专为光伏数据的读取、写入、转换和时间序列分析而设计。

✨ 核心特性

• 🚀 极致性能: 2-46x 压缩比，4-64x 读取加速
• 💾 优化存储: 自动数据类型优化，节省 75% 内存
• ⚡ 批量处理: 并行转换，最高支持多核加速
• 📊 时间序列: 重采样、聚合、缺失值处理、间隙检测
• ☀️ PV 模拟: 基于 pvlib 的光伏发电潜力计算（21,500+ 组件数据库）
• 🛠️ 易于使用: 简洁直观的 API，智能默认配置
• ✅ 生产就绪: 87% 测试覆盖率，135 个测试全部通过

📦 安装

从源码安装

# 克隆仓库
cd pvdata
python -m venv venv
source venv/bin/activate

# 安装
pip install -e .

开发模式安装

pip install -e ".[dev]"

🚀 快速开始

1. 基础读写

import pvdata as pv

# CSV 读取（自动优化内存）
df = pv.read_csv('solar_data.csv')
# INFO: Memory optimization: 75.0% reduction (10 MB -> 2.5 MB)

# Parquet 写入（高压缩）
pv.write_parquet(df, 'solar_data.parquet', compression='zstd')
# INFO: Compression: 2.7x (2.5 MB -> 0.93 MB)

# Parquet 读取（极速）
df = pv.read_parquet('solar_data.parquet')

# 只读取需要的列（更快）
df = pv.read_parquet('solar_data.parquet', columns=['timestamp', 'power'])

2. 批量转换

# 批量转换整个目录
results = pv.batch_convert(
    'data/csv/',
    'data/parquet/',
    max_workers=4,  # 4核并行
    compression='zstd'
)

# 自动打印摘要:
# ============================================================
# Batch Conversion Summary
# ============================================================
# Total files:         10
# Successful:          10 ✓
# Compression ratio:   2.5x
# Space saved:         60.0%
# ============================================================

3. 时间序列处理

from pvdata.processing import TimeSeriesResampler, TimeSeriesAnalyzer

# 重采样到小时数据
resampler = TimeSeriesResampler()
df_hourly = resampler.resample(df, freq='1h', method='mean')

# 分析时间序列
analyzer = TimeSeriesAnalyzer()
stats = analyzer.analyze(df)
print(f"Missing rate: {stats['missing_rate']:.1f}%")

# 检测数据间隙
gaps = analyzer.find_gaps(df, expected_freq='5min')
print(f"Found {len(gaps)} gaps")

4. PV 系统模拟

from pvdata.pvsystem import calculate_pv_potential

# 一键计算光伏发电潜力
df_pv = calculate_pv_potential(
    df,  # 包含 GHI, DNI, DHI, Temperature, Wind Speed
    module='Canadian_Solar_Inc__CS5A_150M',  # CEC 数据库组件名
    surface_tilt=30,        # 倾斜角 30°
    surface_azimuth=180     # 正南方向
)

# 结果包含: POA 辐照度, 电池温度, DC 功率, 转换效率
print(df_pv[['poa_global', 'cell_temperature', 'dc_power', 'efficiency']].head())

# 计算日发电量
df_day = df_pv[df_pv['GHI'] > 50]
daily_kwh = (df_day['dc_power'].sum() * 10 / 60) / 1000  # 10分钟分辨率
print(f"Daily energy: {daily_kwh:.2f} kWh")

5. 高级用法

from pvdata.io import ParquetWriter, BatchConverter

# 自定义压缩配置
writer = ParquetWriter(
    compression='zstd',
    compression_level=9,  # 最大压缩
    optimize_dtypes=True
)
writer.write(df, 'output.parquet')

# 获取压缩统计
stats = writer.get_compression_stats()
print(f"压缩比: {stats['compression_ratio']:.1f}x")
print(f"节省空间: {stats['space_saved_pct']:.1f}%")

📊 性能基准

基于实际测试数据（10,000行，7列光伏数据）：

存储性能

格式	文件大小	压缩比	节省空间
CSV	1.12 MB	基准	-
Parquet (snappy)	0.16 MB	7.0x	85.7%
Parquet (zstd)	0.14 MB	8.0x	87.5%
Parquet (gzip)	0.14 MB	8.0x	87.5%

读取性能

操作	时间	加速
CSV 全读	11 ms	基准
Parquet 全读	2 ms	5.5x ⚡
Parquet 列投影	2 ms	5.5x ⚡

内存优化

数据类型	优化前	优化后	节省
整型 (int64)	8 bytes	1-2 bytes	75-87.5%
浮点 (float64)	8 bytes	4 bytes	50%
混合数据	1.18 MB	1.05 MB	11-75%

📚 完整功能列表

I/O 模块 (✅ 已实现)

• CSVReader: CSV 读取 + 自动类型优化
• ParquetReader: 高性能 Parquet 读取 + 列投影
• ParquetWriter: 多压缩算法写入 (zstd/snappy/gzip/brotli)
• BatchConverter: 批量 CSV → Parquet 转换（支持并行）
• BatchProcessor: 通用多文件批处理框架

时间序列处理 (✅ 已实现)

• TimeSeriesResampler: 时间序列重采样

  • 灵活频率转换 (5min → 1h → 1D)
  • 多种聚合方法 (mean/sum/min/max)
  • 缺失值填充 (ffill/bfill/interpolate)

• TimeSeriesAggregator: 时间聚合

  • 按日/月聚合
  • 滚动窗口计算
  • 自定义聚合策略

• TimeSeriesAnalyzer: 时间序列分析

  • 数据质量分析
  • 频率自动检测
  • 间隙（Gap）检测
  • 缺失率统计

PV 系统模拟 (✅ 已实现 - v0.2.0 新增)

• calculate_pv_potential: 一键光伏发电潜力计算

  • POA 辐照度计算（6种散射模型）
  • 电池温度计算（SAPM + Prilliman 热惯性）
  • DC 功率计算（CEC 单二极管模型）
  • 转换效率计算
  • 支持 21,500+ CEC 数据库组件

• ModuleConfig: 智能组件配置

  • 从 CEC 数据库自动加载
  • 自动推断安装方式（4种标准类型）
  • 自动推断组件质量（unit_mass）
  • 温度参数验证（T_NOCT 校验）

• 分步计算函数:

  • calculate_poa_irradiance() - POA 辐照度
  • calculate_cell_temperature() - 电池温度
  • calculate_dc_power() - DC 功率
  • calculate_efficiency() - 转换效率

配置系统 (✅ 已实现)

• ParquetConfig: Parquet 配置预设
• DTypeMapper: 智能数据类型映射
• ConfigManager: 全局配置管理

工具模块 (✅ 已实现)

• 日志系统: 完整的日志配置
• 错误处理: 自定义异常层次结构
• 装饰器: @measure_time, @log_execution, @handle_errors, @retry, @validate_args

📖 使用示例

查看 examples/ 目录获取更多示例：

• demo_io.py - I/O 操作演示
• demo_writer_batch.py - 写入和批处理演示
• demo_timeseries.py - 时间序列处理演示
• demo_config.py - 配置系统演示
• demo_logging_errors.py - 日志和错误处理演示

🧪 运行测试

# 运行所有测试
pytest

# 带覆盖率报告
pytest --cov=src/pvdata --cov-report=html

# 运行特定测试
pytest tests/test_io.py -v

# 查看覆盖率报告
open htmlcov/index.html

当前测试状态：

• ✅ 135 个测试全部通过
• ✅ 87% 代码覆盖率
• ✅ 所有模块功能验证

🛠️ 开发

代码质量工具

# 代码格式化
black src/ tests/

# 代码检查
flake8 src/ tests/

# 类型检查（可选）
mypy src/pvdata

项目结构

pvdata/
├── src/pvdata/              # 源代码
│   ├── io/                  # I/O 模块
│   │   ├── reader.py        # CSV/Parquet 读取器
│   │   ├── writer.py        # Parquet 写入器
│   │   ├── batch.py         # 批处理器
│   │   └── operations.py    # 便捷函数
│   ├── processing/          # 处理模块
│   │   └── timeseries.py    # 时间序列处理
│   ├── config/              # 配置模块
│   │   ├── parquet.py       # Parquet 配置
│   │   ├── dtype_mapper.py  # 类型映射
│   │   └── manager.py       # 配置管理
│   └── utils/               # 工具模块
│       ├── logger.py        # 日志
│       ├── exceptions.py    # 异常
│       └── decorators.py    # 装饰器
├── tests/                   # 测试
├── examples/                # 示例
└── docs/                    # 文档

📋 需求

• Python 3.8+
• pandas >= 1.5.0
• pyarrow >= 10.0.0
• numpy >= 1.21.0

开发依赖：

• pytest >= 7.0
• pytest-cov >= 4.0
• black >= 22.0
• flake8 >= 5.0

🗺️ 项目状态

v0.1.0 (当前)

• 项目初始化和结构
• 配置系统
• 日志和错误处理
• CSV/Parquet I/O
• 批量转换
• 时间序列处理
• 完整测试套件

未来计划

考虑根据需求添加：

• 空间数据处理
• 数据质量分析
• 统计分析模块
• 查询优化器

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

本项目专为光伏数据处理而开发，旨在解决建筑能源分析中的大规模数据处理挑战。

📧 支持

• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions

---

使用 pvdata，让光伏数据处理更高效！ ⚡🌞