Aggregate-Load-Analysis

HPWH Monte Carlo + OCHRE Parsing + Visualization Toolkit

A collection of Python scripts used to parse OCHRE heat pump water heater data, run Monte Carlo sampling, compute confidence intervals, and generate plots + Word documents.

Authors: Jeff Dinsmore, Josephine DeLine, Dana Paresa, Joe_admin, ChatGPT

Table of Contents

• Get_marginal_load_final.py
• P95percent_confidence_data_by_time.py
• parse_OCHRE_data_final.py
• Plot_3D_surfaces_final.py
• plot_aggregate_load.py
• png_to_word.py

Description

This folder contains several standalone Python scripts used in an HPWH (heat pump water heater) workflow:

• parse_OCHRE_data_final.py converts raw OCHRE exports into a “ready” pivoted dataset (Homes × 15-minute time columns).
• Get_marginal_load_final.py runs Monte Carlo sampling for increasing fleet size (1…N units), aggregates sampled loads, and outputs time-series statistics (mean, quantiles, variance, etc.) for each fleet size.
• P95percent_confidence_data_by_time.py reads the Monte Carlo output files and, for each 15-minute time step, visualizes the mean and percentile bands vs number of units; it also writes a compact per-time summary CSV (P_mean_*) containing mean/95th/5th values.
• Plot_3D_surfaces_final.py creates 3D surfaces for the 97.5th percentile, mean, and 2.5th percentile across (time, units), including highlighted slices.
• plot_aggregate_load.py compares baseline vs controlled aggregate profiles for a chosen fleet size, computes energy metrics (kWh), and generates multiple plots (baseline, controlled, and differences).
• png_to_word.py interleaves baseline/control PNG figures into a formatted Word document grid for reporting.

Get_perunit_load_final.py

Purpose: Monte Carlo sampling of HPWH load profiles for fleet sizes 1…unit_runs, computing time-series statistics per fleet size. Inputs: A “ready” CSV with a Home column and 15-minute time columns (e.g., 00:00, 00:15, …). Outputs: CSV files for: 0.975 quantile, mean, 0.025 quantile variance, standard deviation, skew Notes: Uses a scaling to per-unit / per-fleet normalization (MCS_table.div(0.5 * N)), where 0.5 is a domain-specific scaling constant (HPWH case).

P95percent_confidence_data_by_time.py

Purpose: For each 15-minute time step, plot mean + percentile bands vs number of units, compute a linear fit, and export a compact CSV summary. Inputs: The Monte Carlo stats CSVs (97.5th, mean, 2.5th) and a ready CSV to determine the number of homes/rows available. Outputs: Appends rows to P_mean_control_1000.csv (or similar) with columns: time, P_mean_kW, 95th, 5th Notes: Produces per-time plots and a “CI width / mean (%)” curve on a secondary y-axis.

parse_OCHRE_data_final.py

Purpose: Convert raw OCHRE export data into a clean pivot table format for downstream Monte Carlo sampling. Inputs: Raw OCHRE CSV containing a Time column, Home, and Water Heating Electric Power (kW) (plus other columns). Outputs: A pivoted “ready” CSV where: rows = Home columns = hr_min in HH:MM format values = Water Heating Electric Power (kW) Notes: Creates the output folder if it doesn’t exist.

Plot_3D_surfaces_final.py

Purpose: Visualize 3D surfaces for percentile/mean load vs time and vs number of units. Inputs: Three CSVs (97.5th, mean, 2.5th) produced by the Monte Carlo pipeline. Outputs: Interactive 3D plot window (matplotlib). Notes: Includes example highlights for a specific N and a specific time slice.

plot_aggregate_load.py

Purpose: Compare baseline vs controlled HPWH aggregate load profiles for a selected fleet size and compute energy metrics. Inputs: P_mean_baseline_.csv and P_mean_control_.csv (generated by the confidence-by-time workflow). Outputs: Multiple plots: Controlled − Baseline Baseline − Controlled Overlay of Baseline vs Controlled Per-segment 15-minute energy bar plot Optional exported CSV for per-interval energy (e.g., segment_energy_baseline.csv) Notes: Includes helper functions for kWh computation and dynamic engineering unit scaling (kW/MW/GW).

png_to_word.py

Purpose: Build a Word doc that interleaves baseline/control PNG plots in a grid layout, page by page. Inputs: Two folders of PNGs (./baseline_images, ./control_images by default). Outputs: A Word document (default: baseline_control_interleaved.docx). Notes: Uses python-docx, sets 0.5" margins, and paginates after each filled grid.

Python Version Requirement

OCHRE is only compatible with specific Python versions:

• Supported: Python >= 3.9 and < 3.13

Check your version:

python --version

Warning: Python 3.13+ is not supported and may cause compatibility issues

Setup/Installation

1. Environment Setup

Recommended: Use WSL (Ubuntu) or a virtual environment

Create a virtual environment:

python3 -m venv .venv

Activate:

source .venv/bin/activate   # WSL / Linux
.venv\Scripts\activate      # Windows

---

2. Install Dependencies

WSL / Ubuntu:

sudo apt update
sudo apt install -y python3-pandas python3-numpy python3-matplotlib python3-sklearn python3-docx

Alternatively (pip):

pip install pandas numpy matplotlib scikit-learn python-docx

---

3. Install OCHRE

OCHRE can be installed using pip from the command line:

pip install ochre-nrel

Alternatively, you can install a specific branch (for development features):

pip install git+https://github.com/NREL/OCHRE@dev

---

4. Clone this repository

To get a local copy of this project, run:

git clone https://github.com/<your-username>/Aggregated-Load-Analysis.git

Then navigate into the project folder:

cd Aggregated_Load_Analysis

---

5. Required Modifications

This project requires modified versions of OCHRE source files.

After installing OCHRE, you must replace:

• waterheater.py
• analysis.py

with the versions provided in:

Aggregated_Load_Analysis/setup/

These modifications are required for the Monte Carlo and aggregation pipeline to work correctly.

---

6. Download RESTOCK data

Navigate to the data download script in the repository:

Aggregated_Load_Analysis/setup/downloadTestSet.py

Run or modify this script to select the desired dataset.

Instructions

1. Open downloadTestSet.py
2. Select the CSV file(s) corresponding to the desired buildings (examples are provided in the up06/ folder)
3. Modify the list of selected building CSVs in the script as needed
4. Run the script:

Output Location

Downloaded data will be saved to the OCHRE input directory:

ochre/defaults/input_files/bldg/

Only selected CSV files will be downloaded. Ensure the correct building IDs are specified before running the script.

Known Bugs

No known bugs at the this time.

Support and Contact Details Any known issues, please reach out to Jeff Dinsmore by email at hello@jeffdinsmore.com

Technologies Used

• Windows 11
• WSL/Ubuntu
• Python 3
• Pandas
• NumPy
• Matplotlib
• scikit-learn
• python-docx
• VS Code

License

Copyright (c) 2025 - , Jeff Dinsmore

This software is licensed under the GNU General Public License.