Spaces:

happynickamazon
/

zenvolt-api

Runtime error

App Files Files Community

zenvolt-api / README.md

happynickamazon

Upload folder using huggingface_hub

25853a2 verified 9 months ago

preview code

Raw History Blame Contribute Delete

8.32 kB

---
title: ZenVolt AI Trust Engine
emoji: 🔋
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---
# Battery State of Health (SOH) Prediction - Advanced ML Models

## Overview

This project implements an advanced machine learning pipeline for predicting Battery State of Health (SOH) using multiple models (Random Forest, XGBoost, LightGBM) with hyperparameter tuning, uncertainty quantification, and End-of-Life (EOL) prediction.

**SOH Definition**: `current_capacity / initial_capacity`

## Features

### 1. **Data Cleaning & Preprocessing**
- Missing value handling (forward fill, backward fill, median imputation)
- Outlier detection and capping using IQR method
- Duplicate removal

### 2. **Advanced Feature Engineering**
- **Statistical Features**: Mean, std, min, max, range, median per cycle for voltage, current, temperature
- **Rolling Features**: 5-cycle rolling averages and standard deviations
- **Temporal Features**: Cycles from start, cycles to end (supports timestamp data if available)
- **Physics-Informed Features**:
  - Energy throughput per cycle
  - Charge/discharge asymmetry
  - Power (voltage × current)
  - Temperature stress indicators
  - Capacity fade rate and acceleration
- **Degradation Features**: Capacity degradation rates, cumulative capacity loss

### 3. **Multiple ML Models with Hyperparameter Tuning**
- **Random Forest**: Grid search over n_estimators, max_depth, min_samples_split, min_samples_leaf
- **XGBoost**: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree
- **LightGBM**: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree, num_leaves
### 4. **Uncertainty Quantification**
- Prediction intervals (95% confidence) using Random Forest tree predictions
- Standard deviation of predictions across trees
### 5. **Early Stopping Detection (EOL Prediction)**
- Predicts when battery reaches 80% SOH (industry standard End-of-Life)
- Remaining Useful Life (RUL) prediction for each cycle
- Linear extrapolation from recent predictions
### 6. **Model Evaluation**
- R² Score, MAE, RMSE
- 5-fold cross-validation
- Model comparison table with R² improvements
### 7. **Visualizations**
- Model comparison: Predicted vs Actual SOH
- SOH vs Cycle Index (with uncertainty bands)
- Feature importance plots
- Residuals analysis
- EOL prediction visualization
- RUL prediction plots
## Dataset Requirements
### Expected CSV Format
Columns required:
- `cycle_index`: Cycle number
- `voltage`: Battery voltage (V)
- `current`: Battery current (A, positive for charge, negative for discharge)
- `temperature`: Battery temperature (°C)
- `capacity`: Battery capacity (Ah)

Optional columns (for enhanced temporal features):
- `timestamp` or `date`: Timestamp for each measurement

### Sample Data Format

```
cycle_index,voltage,current,temperature,capacity
1,4.2,1.5,25.0,2.0
1,4.1,1.5,25.1,2.0
...
2,4.2,1.5,25.0,1.98
...
```

## Public Battery Datasets

### NASA PCoE Battery Datasets

**Official Source**:
- NASA Open Data Portal: https://data.nasa.gov/dataset/Li-ion-Battery-Aging-Datasets/uj5r-zjdb/data
- Datasets: B0005, B0006, B0007, B0018 (run-to-failure cycling data)
- Format: `.mat` files (MATLAB format)

**CSV Conversions**:
- GitHub: `bnarms/NASA-Battery-Dataset` - Contains original .mat files and conversion scripts
- GitHub: `RyuMyunggi/NASA-battery-dataset-eda` - EDA and CSV conversion examples
- GitHub: `huzaifi18/RUL_prediction` - Pre-processed CSV files

**Conversion Script** (if using .mat files):
```python
import scipy.io
import pandas as pd
mat_data = scipy.io.loadmat('B0005.mat')
# Extract data and convert to CSV format
# Refer to NASA dataset documentation for structure
```

### CALCE Battery Datasets

**Official Sources**:
- Main page: https://calce.umd.edu/battery-data
- Data index: https://calce.umd.edu/data
- Format: Text/CSV files per experiment

**Direct Access**:
- University of Michigan IoFT mirror: https://ioft-data.engin.umich.edu/calce-battery-datasets/
- Provides CSV-ready cycling data

### Stanford Battery Datasets

**Sources**:
- BEEP Project: https://tri-amdd.github.io/beep/ (includes Stanford aging datasets)
- GitHub: `petermattia/revisit-severson-et-al` - Conversion scripts
- Format: MATLAB/HDF5 (with CSV export tools)

**Access**:
1. Download from BEEP project
2. Use BEEP tools to export to CSV
3. Or use conversion scripts from the GitHub repo

## Usage

### Quick Start (Sample Data)

For testing, you can generate sample data:

```python
from download_battery_datasets import create_sample_battery_data
file_path = create_sample_battery_data('./data/sample_battery_data.csv', n_cycles=100)
```

### Google Colab

1. **Upload both files** to Google Colab:
   - `battery_soh_prediction.ipynb` (notebook)
   - `download_battery_datasets.py` (dataset downloader)

2. **Install dependencies**:
   ```python
   !pip install xgboost lightgbm scipy requests
   ```

3. **Choose a data source** (see Step 1 in the notebook):
   - **Option A**: Download public datasets
     ```python
     from download_battery_datasets import download_nasa_dataset
     file_path = download_nasa_dataset('B0005')
     ```
   - **Option B**: Generate sample data
     ```python
     from download_battery_datasets import create_sample_battery_data
     file_path = create_sample_battery_data('./data/sample_battery_data.csv')
     ```
   - **Option C**: Upload your CSV file
     ```python
     from google.colab import files
     uploaded = files.upload()
     file_path = list(uploaded.keys())[0]
     ```
4. **Run all cells** in the notebook

### Local Python Environment

1. **Install dependencies**:
   ```bash
   pip install pandas numpy scikit-learn matplotlib seaborn xgboost lightgbm scipy requests
   ```

2. **Download datasets** (optional):
   ```python
   from download_battery_datasets import download_nasa_dataset, create_sample_battery_data
   
   # Download NASA dataset
   file_path = download_nasa_dataset('B0005')
   
   # Or create sample data
   file_path = create_sample_battery_data('./data/sample_battery_data.csv')
   ```

3. **Run the Python script**:
   ```bash
   python battery_soh_prediction.py
   ```
   
   **Or use Jupyter**:
   ```bash
   jupyter notebook battery_soh_prediction.ipynb
   ```

## Output

The pipeline generates:

1. **Model Comparison Table**: R², MAE, RMSE for all models
2. **Best Model Selection**: Automatically selects model with highest Test R²
3. **Prediction Intervals**: 95% confidence intervals (Random Forest)
4. **EOL Prediction**: Cycle when battery reaches 80% SOH
5. **Visualizations**: 6 comprehensive plots saved as `battery_soh_prediction_results.png`

## Model Comparison

The code automatically compares:
- **Random Forest** (baseline)
- **XGBoost** (if available)
- **LightGBM** (if available)

Results include:
- Train R², Test R²
- Cross-validation R² (mean ± std)
- Test MAE, Test RMSE
- R² Improvement over baseline

## Notes

- **Time Series Splitting**: The 80/20 train-test split is done without shuffling to preserve time series order
- **Cross-Validation**: 5-fold CV is used for model evaluation
- **Hyperparameter Tuning**: Uses GridSearchCV with 3-fold CV
- **Feature Engineering**: All features are created at the cycle level (aggregated per cycle)
- **Uncertainty**: Currently implemented for Random Forest only (using tree variance)
- **EOL Threshold**: Set to 80% SOH (industry standard), can be modified in code

## Troubleshooting

### XGBoost/LightGBM Not Available
- Install: `pip install xgboost lightgbm`
- The code will automatically skip unavailable models

### Missing Columns Error
- Ensure your CSV has at least: `cycle_index`, `voltage`, `current`, `temperature`, `capacity`
- Column names are case-sensitive

### Out of Memory
- Reduce hyperparameter grid search space
- Use smaller dataset or sample data
- Reduce number of estimators in models

## Citation

If using public datasets, please cite the original sources:
- **NASA**: "Li-ion Battery Aging Datasets" - NASA Prognostics Center of Excellence
- **CALCE**: University of Maryland Center for Advanced Life Cycle Engineering
- **Stanford**: Severson et al. cycle-life prediction datasets

## License

This code is provided as-is for research and educational purposes.

	---
	title: ZenVolt AI Trust Engine
	emoji: 🔋
	colorFrom: green
	colorTo: blue
	sdk: docker
	app_port: 7860
	pinned: false
	---

	# Battery State of Health (SOH) Prediction - Advanced ML Models

	## Overview

	This project implements an advanced machine learning pipeline for predicting Battery State of Health (SOH) using multiple models (Random Forest, XGBoost, LightGBM) with hyperparameter tuning, uncertainty quantification, and End-of-Life (EOL) prediction.

	SOH Definition: `current_capacity / initial_capacity`

	## Features

	### 1. Data Cleaning & Preprocessing
	- Missing value handling (forward fill, backward fill, median imputation)
	- Outlier detection and capping using IQR method
	- Duplicate removal

	### 2. Advanced Feature Engineering
	- Statistical Features: Mean, std, min, max, range, median per cycle for voltage, current, temperature
	- Rolling Features: 5-cycle rolling averages and standard deviations
	- Temporal Features: Cycles from start, cycles to end (supports timestamp data if available)
	- Physics-Informed Features:
	- Energy throughput per cycle
	- Charge/discharge asymmetry
	- Power (voltage × current)
	- Temperature stress indicators
	- Capacity fade rate and acceleration
	- Degradation Features: Capacity degradation rates, cumulative capacity loss

	### 3. Multiple ML Models with Hyperparameter Tuning
	- Random Forest: Grid search over n_estimators, max_depth, min_samples_split, min_samples_leaf
	- XGBoost: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree
	- LightGBM: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree, num_leaves

	### 4. Uncertainty Quantification
	- Prediction intervals (95% confidence) using Random Forest tree predictions
	- Standard deviation of predictions across trees

	### 5. Early Stopping Detection (EOL Prediction)
	- Predicts when battery reaches 80% SOH (industry standard End-of-Life)
	- Remaining Useful Life (RUL) prediction for each cycle
	- Linear extrapolation from recent predictions

	### 6. Model Evaluation
	- R² Score, MAE, RMSE
	- 5-fold cross-validation
	- Model comparison table with R² improvements

	### 7. Visualizations
	- Model comparison: Predicted vs Actual SOH
	- SOH vs Cycle Index (with uncertainty bands)
	- Feature importance plots
	- Residuals analysis
	- EOL prediction visualization
	- RUL prediction plots

	## Dataset Requirements

	### Expected CSV Format

	Columns required:
	- `cycle_index`: Cycle number
	- `voltage`: Battery voltage (V)
	- `current`: Battery current (A, positive for charge, negative for discharge)
	- `temperature`: Battery temperature (°C)
	- `capacity`: Battery capacity (Ah)

	Optional columns (for enhanced temporal features):
	- `timestamp` or `date`: Timestamp for each measurement

	### Sample Data Format

	```
	cycle_index,voltage,current,temperature,capacity
	1,4.2,1.5,25.0,2.0
	1,4.1,1.5,25.1,2.0
	...
	2,4.2,1.5,25.0,1.98
	...
	```

	## Public Battery Datasets

	### NASA PCoE Battery Datasets

	Official Source:
	- NASA Open Data Portal: https://data.nasa.gov/dataset/Li-ion-Battery-Aging-Datasets/uj5r-zjdb/data
	- Datasets: B0005, B0006, B0007, B0018 (run-to-failure cycling data)
	- Format: `.mat` files (MATLAB format)

	CSV Conversions:
	- GitHub: `bnarms/NASA-Battery-Dataset` - Contains original .mat files and conversion scripts
	- GitHub: `RyuMyunggi/NASA-battery-dataset-eda` - EDA and CSV conversion examples
	- GitHub: `huzaifi18/RUL_prediction` - Pre-processed CSV files

	Conversion Script (if using .mat files):
	```python
	import scipy.io
	import pandas as pd

	mat_data = scipy.io.loadmat('B0005.mat')
	# Extract data and convert to CSV format
	# Refer to NASA dataset documentation for structure
	```

	### CALCE Battery Datasets

	Official Sources:
	- Main page: https://calce.umd.edu/battery-data
	- Data index: https://calce.umd.edu/data
	- Format: Text/CSV files per experiment

	Direct Access:
	- University of Michigan IoFT mirror: https://ioft-data.engin.umich.edu/calce-battery-datasets/
	- Provides CSV-ready cycling data

	### Stanford Battery Datasets

	Sources:
	- BEEP Project: https://tri-amdd.github.io/beep/ (includes Stanford aging datasets)
	- GitHub: `petermattia/revisit-severson-et-al` - Conversion scripts
	- Format: MATLAB/HDF5 (with CSV export tools)

	Access:
	1. Download from BEEP project
	2. Use BEEP tools to export to CSV
	3. Or use conversion scripts from the GitHub repo

	## Usage

	### Quick Start (Sample Data)

	For testing, you can generate sample data:

	```python
	from download_battery_datasets import create_sample_battery_data
	file_path = create_sample_battery_data('./data/sample_battery_data.csv', n_cycles=100)
	```

	### Google Colab

	1. Upload both files to Google Colab:
	- `battery_soh_prediction.ipynb` (notebook)
	- `download_battery_datasets.py` (dataset downloader)

	2. Install dependencies:
	```python
	!pip install xgboost lightgbm scipy requests
	```

	3. Choose a data source (see Step 1 in the notebook):
	- Option A: Download public datasets
	```python
	from download_battery_datasets import download_nasa_dataset
	file_path = download_nasa_dataset('B0005')
	```
	- Option B: Generate sample data
	```python
	from download_battery_datasets import create_sample_battery_data
	file_path = create_sample_battery_data('./data/sample_battery_data.csv')
	```
	- Option C: Upload your CSV file
	```python
	from google.colab import files
	uploaded = files.upload()
	file_path = list(uploaded.keys())[0]
	```

	4. Run all cells in the notebook

	### Local Python Environment

	1. Install dependencies:
	```bash
	pip install pandas numpy scikit-learn matplotlib seaborn xgboost lightgbm scipy requests
	```

	2. Download datasets (optional):
	```python
	from download_battery_datasets import download_nasa_dataset, create_sample_battery_data

	# Download NASA dataset
	file_path = download_nasa_dataset('B0005')

	# Or create sample data
	file_path = create_sample_battery_data('./data/sample_battery_data.csv')
	```

	3. Run the Python script:
	```bash
	python battery_soh_prediction.py
	```

	Or use Jupyter:
	```bash
	jupyter notebook battery_soh_prediction.ipynb
	```

	## Output

	The pipeline generates:

	1. Model Comparison Table: R², MAE, RMSE for all models
	2. Best Model Selection: Automatically selects model with highest Test R²
	3. Prediction Intervals: 95% confidence intervals (Random Forest)
	4. EOL Prediction: Cycle when battery reaches 80% SOH
	5. Visualizations: 6 comprehensive plots saved as `battery_soh_prediction_results.png`

	## Model Comparison

	The code automatically compares:
	- Random Forest (baseline)
	- XGBoost (if available)
	- LightGBM (if available)

	Results include:
	- Train R², Test R²
	- Cross-validation R² (mean ± std)
	- Test MAE, Test RMSE
	- R² Improvement over baseline

	## Notes

	- Time Series Splitting: The 80/20 train-test split is done without shuffling to preserve time series order
	- Cross-Validation: 5-fold CV is used for model evaluation
	- Hyperparameter Tuning: Uses GridSearchCV with 3-fold CV
	- Feature Engineering: All features are created at the cycle level (aggregated per cycle)
	- Uncertainty: Currently implemented for Random Forest only (using tree variance)
	- EOL Threshold: Set to 80% SOH (industry standard), can be modified in code

	## Troubleshooting

	### XGBoost/LightGBM Not Available
	- Install: `pip install xgboost lightgbm`
	- The code will automatically skip unavailable models

	### Missing Columns Error
	- Ensure your CSV has at least: `cycle_index`, `voltage`, `current`, `temperature`, `capacity`
	- Column names are case-sensitive

	### Out of Memory
	- Reduce hyperparameter grid search space
	- Use smaller dataset or sample data
	- Reduce number of estimators in models

	## Citation

	If using public datasets, please cite the original sources:
	- NASA: "Li-ion Battery Aging Datasets" - NASA Prognostics Center of Excellence
	- CALCE: University of Maryland Center for Advanced Life Cycle Engineering
	- Stanford: Severson et al. cycle-life prediction datasets

	## License

	This code is provided as-is for research and educational purposes.