commenting and cleaning

SiobhanPowell · Oct 22, 2021 · 3da5ce4 · 3da5ce4
1 parent f26953a
commit 3da5ce4
Show file tree

Hide file tree

Showing 11 changed files with 391 additions and 113 deletions.
diff --git a/ProcessingForPaper/1_calculate_driver_feature_vectors.ipynb b/ProcessingForPaper/1_calculate_driver_feature_vectors.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/ProcessingForPaper/2_cluster_drivers.ipynb b/ProcessingForPaper/2_cluster_drivers.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/ProcessingForPaper/3_fit_sessions_model_gmms.ipynb b/ProcessingForPaper/3_fit_sessions_model_gmms.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/ProcessingForPaper/4_validation_plots.ipynb b/ProcessingForPaper/4_validation_plots.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -280,25 +293,6 @@
     "    return end_times, load"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": 14,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# # 1, 2 is good, 6 is good, 10 is good, 13 is good\n",
-    "# drivers = key_driver_info[key_driver_info['Dend Cluster Number']==15]['Unique Driver ID'].values\n",
-    "# subset = df[df['Driver ID'].isin(drivers)]\n",
-    "\n",
-    "# print(np.unique(subset[subset['start_day']==51]['Driver ID']).shape)\n",
-    "# print(subset[subset['start_day']==51]['start_datetime'].values[0])\n",
-    "# print(subset[subset['start_day']==51]['start_weekday'].values[0])\n",
-    "# print(len(drivers))\n",
-    "# all_loads = raw_data_load(subset[subset['start_day']==51])\n",
-    "# # total_all_loads = raw_data_load(df.loc[(df['start_day']==51)&(df['Driver ID'].isin(key_driver_info['Unique Driver ID'].values))])\n",
-    "# plotting(all_loads, set_ymax=40, locs=np.arange(0, 40, 10))"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/ProcessingForPaper/5_plots_of_data_and_groups.ipynb b/ProcessingForPaper/5_plots_of_data_and_groups.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

diff --git a/ProcessingForPaper/6_timing_plot.ipynb b/ProcessingForPaper/6_timing_plot.ipynb
@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\"\"\"\n",
+    "SPEECh: Scalable Probabilistic Estimates of EV Charging\n",
+    "\n",
+    "Code first published in October 2021.\n",
+    "\n",
+    "Developed by Siobhan Powell ([email protected]).\n",
+    "\"\"\""
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -540,98 +553,13 @@
     "    results.to_csv('ProcessingForPaper/time_results.csv')"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# total_evs = 1e9\n",
-    "\n",
-    "# tic = time.time()\n",
-    "# model = SPEECh(data)\n",
-    "# config = SPEEChGeneralConfiguration(model)\n",
-    "# new_weights_pg = dict(zip(counts_df['AC Cluster Number'], counts_df['Scen1']))\n",
-    "# config.change_pg(new_weights=new_weights_pg)\n",
-    "# config.num_evs(total_evs)\n",
-    "# config.groups()\n",
-    "# config.change_ps_zg(data.cluster_reorder_dendtoac[3], 'Home', 'weekday', base_weights3)\n",
-    "# config.change_ps_zg(data.cluster_reorder_dendtoac[4], 'Home', 'weekday', base_weights4)\n",
-    "# config.change_ps_zg(data.cluster_reorder_dendtoac[5], 'Home', 'weekday', base_weights5)\n",
-    "# config.run_all(weekday=weekday_option)\n",
-    "# toc = time.time()\n",
-    "# print(toc-tic)\n",
-    "# results.loc[i+1, 'Time'] = toc-tic\n",
-    "# results.loc[i+1, 'Number of EVs'] = total_evs\n"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Plot results: "
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": 8,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "104.78948941628138"
-      ]
-     },
-     "execution_count": 8,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "(toc-tic)/60"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 15,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "9.860000000000001"
-      ]
-     },
-     "execution_count": 15,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "591.6/60"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 16,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "49.43333333333333"
-      ]
-     },
-     "execution_count": 16,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "2966/60"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": 9,

diff --git a/ProcessingForPaper/7_produce_dataset.ipynb b/ProcessingForPaper/7_produce_dataset.ipynb
diff --git a/README.md b/README.md
@@ -1,29 +1,51 @@
 # SPEECh
 ## Scalable Probabilistic Estimates of Electric Vehicle Charging
 
-Primary Contact: Siobhan Powell.
+Primary Contact: Siobhan Powell. Email: siobhan (dot) powell (at) stanford (dot) edu
 
-Email: siobhan (dot) powell (at) stanford (dot) edu
+Publication: 
 
-Publications: 
 S. Powell, G. V. Cezar, R. Rajagopal, "Scalable Probabilistic Estimates of Electric Vehicle Charging Given Observed Driver Behavior", submitted.
 
-If you use the project or this code, please cite us: [citation example]. 
+Citations for code and data:
 
-Read more about the project here: https://energy.stanford.edu/bitsandwatts/research/ev50-flagship-project/long-range-planning-ev50-what-future-demand-charging. 
+Powell, Siobhan; Cezar, Gustavo Vianna; Rajagopal, Ram (2021), “SPEECh Original Model”, Mendeley Data, V1, doi: 10.17632/gvk34mybtb.1
+
+## About 
+
+Electric vehicles (EV) and EV charging stations are expected to multiply over the next decade. 
+Long-term planning for grid and charging network design depend on detailed forecasts of future charging demand. 
+SPEECh, Scalable Probabilistic Estimates of Electric Vehicle Charging, is a novel, probabilistic framework for 
+simulating very large-scale estimates of EV charging load that are grounded in real charging data and drivers' charging patterns. 
+You can learn more about SPEECh by reading the paper (listed above). 
+For more details about the larger project: https://energy.stanford.edu/bitsandwatts/research/ev50-flagship-project/long-range-planning-ev50-what-future-demand-charging. This project builds on earlier work in the SCRIPT project: https://github.com/slacgismo/SCRIPT-tool. 
 
 Project Advisors: Ram Rajagopal, Ines Azevedo, Gustavo Cezar, Liang Min. 
 
 Collaborators and Team: Charles Kolstad, Lesley Ryan, Noel Crisostomo, Matt Alexander, Eric Wood, Wahila Wilkie, the GISMo, S3L, and EV50 groups, and many more.
 
 Thank you to the many collaborators who have made this project possible.
 
+This repository contains: 
+- The model,
+- Examples demonstrating how to use the model and adjust assumptions to run new scenarios yourself,
+- Code to run an interactive application where you can do this ^ through an interface,
+- Code to help you apply the model to your own data set, and 
+- The code used for the paper.
+
+This README contains a short tutorial and useful instructions on all of the above elements. 
+
+## Data
+Two data sets have been posted in association with this repository: [link]
+1. The original model files are in the folder `Model Data`. You must download these and save them in the following folder structure to be able to run the model: `Data` > `Original16` > [files]. All GMM files (ending in `.p`) should be kept in a further subfolder: `Data` > `Original16` > `GMMs` > [files]. 
+2. The profiles used in Figure 4 are in the folder `Normalized Load Profiles`. They represent a typical weekday or weekend aggregate profile for each of the 16 driver groups. They are in units kW/driver: calculated by simulating the demand for 10000 drivers in each group and then normalizing the result by dividing by 10000. They are not scaled according to group weights. By weighting and combining these profiles you can approximate model results; this offers a simpler way to generate your own scenarios without running the original code.
+
 ## Interactive Application
 
 To run the interactive application locally:
 0. Make sure you have a working version of Python 3 (this code was tested with Python 3.7.4).
 1. Navigate to this folder in your terminal.
-2. Download the data folder from: https://s3.us-west-1.amazonaws.com/speech.data/Original16.zip. Store it in a subfolder called `Data`.
+2. Download the data folder and save it as described in step 1 of `Data` above.
 3. In a new virtual environment, run `pip install -r requirements.txt`. You can also run with the packages in your main system, but the `requirements.txt` file lists versions which we know will work with together in this code. 
 4. Run `flask run`.
 5. Go to `localhost:5000` in your browser.
@@ -125,3 +147,6 @@ This works with:
     json == 2.0.9
 ```    
 Python 3.7.4.
+
+## Funding Acknowledgements
+This work was funded by the Bits & Watts Initiative, by the California Energy Commission under grant EPC-16-057, and by the National Science Foundation through a CAREER award (\#1554178). 
diff --git a/RunPaperScenarios.py b/RunPaperScenarios.py
@@ -1,3 +1,12 @@
+"""
+SPEECh: Scalable Probabilistic Estimates of EV Charging
+Code first published in October 2021.
+Developed by Siobhan Powell ([email protected]).
+
+This script runs the scenarios and generates the plots shown in the Results Section of the paper
+`Scalable Probabilistic Estimates of Electric Vehicle Charging Given Observed Driver Behavior'.
+"""
+
 import pandas as pd
 import matplotlib.pyplot as plt
 import numpy as np

diff --git a/SimpleExample.py b/SimpleExample.py
@@ -1,4 +1,11 @@
-"""Demonstrate built-in plotting options. Make sure to close each figure after it opens to continue the script."""
+"""
+SPEECh: Scalable Probabilistic Estimates of EV Charging
+Code first published in October 2021.
+Developed by Siobhan Powell ([email protected]).
+
+This script demonstrates running the model, simple changes to behavioural component weights, and the use of built-in plotting options.
+Make sure to close each figure after it opens to continue the script.
+"""
 
 from speech import DataSetConfigurations
 from speech import SPEECh
@@ -13,11 +20,11 @@
 data = DataSetConfigurations('Original16', ng=16)
 model = SPEECh(data)
 config = SPEEChGeneralConfiguration(model)
-plots = Plotting(model, n=total_evs)  # plots total_evs (1000) in each group (i.e. ignores P(G))
+plots = Plotting(model, n=total_evs)  # plots total_evs
 plots.total(weekday='weekday', save_str='simple_example_plot.png')
 plots.pg()
 plots.sessions_components(g=1, cat='Work', weekday='weekday')
-plots.groups(save_string='simple_example_groups.png')
+plots.groups(save_string='simple_example_groups.png', n=total_evs) # plots total_evs in each group
 
 # Demonstration of changing group weights and behaviour weights:
 model = SPEECh(data)

diff --git a/app.py b/app.py
@@ -1,3 +1,10 @@
+"""
+SPEECh: Scalable Probabilistic Estimates of EV Charging
+Code first published in October 2021.
+Developed by Lesley Ryan and Siobhan Powell.
+
+This file is used to run the back-end of the interactive tool and website.
+"""
 from flask import Flask, render_template, request, jsonify
 import json
 import numpy as np