pvdata 0.2.1
High-performance toolkit for photovoltaic data processing, PV simulation, and time series analysis
License: MIT
Requires Python: >=3.8
Keywords: photovoltaic, solar, data, parquet, analysis, time-series, timeseries, compression, data-processing

# pvdata - Photovoltaic Data Toolkit

[![Tests](https://img.shields.io/badge/tests-135%20passed-brightgreen)](https://github.com/pvdata/pvdata)
[![Coverage](https://img.shields.io/badge/coverage-87%25-green)](https://github.com/pvdata/pvdata)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## ✨ 核心特性

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

## 📦 安装

### 从源码安装

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

# 安装
pip install -e .
```

### 开发模式安装

```bash
pip install -e ".[dev]"
```

## 🚀 快速开始

### 1. 基础读写

```python
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. 批量转换

```python
# 批量转换整个目录
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. 时间序列处理

```python
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 系统模拟

```python
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. 高级用法

```python
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 模块 (✅ 已实现)

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

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

- [x] **TimeSeriesResampler**: 时间序列重采样
  - 灵活频率转换 (5min → 1h → 1D)
  - 多种聚合方法 (mean/sum/min/max)
  - 缺失值填充 (ffill/bfill/interpolate)

- [x] **TimeSeriesAggregator**: 时间聚合
  - 按日/月聚合
  - 滚动窗口计算
  - 自定义聚合策略

- [x] **TimeSeriesAnalyzer**: 时间序列分析
  - 数据质量分析
  - 频率自动检测
  - 间隙（Gap）检测
  - 缺失率统计

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

- [x] **calculate_pv_potential**: 一键光伏发电潜力计算
  - POA 辐照度计算（6种散射模型）
  - 电池温度计算（SAPM + Prilliman 热惯性）
  - DC 功率计算（CEC 单二极管模型）
  - 转换效率计算
  - 支持 21,500+ CEC 数据库组件

- [x] **ModuleConfig**: 智能组件配置
  - 从 CEC 数据库自动加载
  - 自动推断安装方式（4种标准类型）
  - 自动推断组件质量（unit_mass）
  - 温度参数验证（T_NOCT 校验）

- [x] **分步计算函数**:
  - `calculate_poa_irradiance()` - POA 辐照度
  - `calculate_cell_temperature()` - 电池温度
  - `calculate_dc_power()` - DC 功率
  - `calculate_efficiency()` - 转换效率

### 配置系统 (✅ 已实现)

- [x] **ParquetConfig**: Parquet 配置预设
- [x] **DTypeMapper**: 智能数据类型映射
- [x] **ConfigManager**: 全局配置管理

### 工具模块 (✅ 已实现)

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

## 📖 使用示例

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

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

## 🧪 运行测试

```bash
# 运行所有测试
pytest

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

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

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

当前测试状态：
- ✅ **135 个测试**全部通过
- ✅ **87% 代码覆盖率**
- ✅ 所有模块功能验证

## 🛠️ 开发

### 代码质量工具

```bash
# 代码格式化
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 (当前)

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

### 未来计划

考虑根据需求添加：
- [ ] 空间数据处理
- [ ] 数据质量分析
- [ ] 统计分析模块
- [ ] 查询优化器

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

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

## 📧 支持

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

---

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