-Master branch: [](https://travis-ci.org/NREL/rdtools)
-Development branch: [](https://travis-ci.org/NREL/rdtools)
+Master branch:
+[](https://travis-ci.org/NREL/rdtools)
-RdTools is a set of Python tools for analysis of photovoltaic data.
-In particular, PV production data is evaluated over several years
-to obtain rates of performance degradation over time. RdTools can
-handle both high frequency (hourly or better) or low frequency (daily, weekly, etc.)
-datasets. Best results are obtained with higher frequency data.
+Development branch:
+[](https://travis-ci.org/NREL/rdtools)
-Full examples are worked out in the example notebooks in [rdtools/docs](./docs/degradation_example.ipynb).
+RdTools is an open-source library to support reproducible technical analysis of
+time series data from photovoltaic energy systems. The library aims to provide
+best practice analysis routines along with the building blocks for users to
+tailor their own analyses.
+Current applications include the evaluation of PV production over several years to obtain
+rates of performance degradation and soiling loss. RdTools can handle
+both high frequency (hourly or better) or low frequency (daily, weekly,
+etc.) datasets. Best results are obtained with higher frequency data.
-## Workflow
-
-0. Import and preliminary calculations
-1. Normalize data using a performance metric
-2. Filter data that creates bias
-3. Aggregate data
-4. Analyze aggregated data to estimate the degradation rate
-
-
-
-
-## Degradation Results
-
-The preferred method for degradation rate estimation is the year-on-year (YOY) approach,
-available in `degradation.degradation_year_on_year`. The YOY calculation yields in a distribution
-of degradation rates, the central tendency of which is the most representative of the true
-degradation. The width of the distribution provides information about the uncertainty in the
-estimate via a bootstrap calculation. The [example notebook](./docs/degradation_example.ipynb) uses the output of `degradation.degradation_year_on_year()`
-to visualize the calculation.
-
-
-
-
-Two workflows are available for system performance ratio calculation, and illustrated in an example notebook.
-The sensor-based approach assumes that site irradiance and temperature sensors are calibrated and in good repair.
-Since this is not always the case, a 'clear-sky' workflow is provided that is based on
-modeled temperature and irradiance. Note that site irradiance data is still required to identify
-clear-sky conditions to be analyzed. In many cases, the 'clear-sky' analysis can identify conditions
-of instrument errors or irradiance sensor drift, such as in the above analysis.
-
-
-## Install RdTools using pip
-
-RdTools can be installed automatically into Python from PyPI using the command line:
-`pip install rdtools`
-
-Alternatively it can be installed manually using the command line:
-
-1. Download a [release](https://github.com/NREL/rdtools/releases) (Or to work with a development version, clone or download the rdtools repository).
-2. Navigate to the repository: `cd rdtools`
-3. Install via pip: `pip install .`
-
-On some systems installation with `pip` can fail due to problems installing requirements. If this occurs, the requirements specified in `setup.py` may need to be separately installed (for example by using `conda`) before installing `rdtools`.
-
-RdTools currently runs in both Python 2.7 and 3.6.
-
-## Usage and examples
-
-
-Full workflow examples are found in the notebooks in [rdtools/docs](./docs/degradation_example.ipynb). The examples are designed to work with python 3.6. For a consistent experience, we recommend installing the packages and versions documented in `docs/notebook_requirements.txt`. This can be achieved in your environment by first installing RdTools as described above, then running `pip install -r docs/notebook_requirements.txt` from the base directory.
-
-The following functions are used for degradation analysis:
+RdTools can be installed automatically into Python from PyPI using the
+command line:
```
-import rdtools
+pip install rdtools
```
-The most frequently used functions are:
+For API documentation and full examples, please see the [documentation](https://rdtools.readthedocs.io).
-```Python
-normalization.normalize_with_pvwatts(energy, pvwatts_kws)
- '''
- Inputs: Pandas time series of raw energy, PVwatts dict for system analysis
- (poa_global, P_ref, T_cell, G_ref, T_ref, gamma_pdc)
- Outputs: Pandas time series of normalized energy and POA insolation
- '''
-```
-
-```Python
-filtering.poa_filter(poa); filtering.tcell_filter(Tcell); filtering.clip_filter(power);
-filtering.csi_filter(insolation, clearsky_insolation)
- '''
- Inputs: Pandas time series of raw data to be filtered.
- Output: Boolean mask where `True` indicates acceptable data
- '''
-```
-
-```Python
-aggregation.aggregation_insol(normalized, insolation, frequency='D')
- '''
- Inputs: Normalized energy and insolation
- Output: Aggregated data, weighted by the insolation.
- '''
-```
-
-```Python
-degradation.degradataion_year_on_year(aggregated)
- '''
- Inputs: Aggregated, normalized, filtered time series data
- Outputs: Tuple: `yoy_rd`: Degradation rate
- `yoy_ci`: Confidence interval `yoy_info`: associated analysis data
- '''
-```
+RdTools currently is tested on Python 3.6+.
## Citing RdTools
-The underlying workflow of RdTools has been published in several places. If you use RdTools in a published work, please cite the following:
+The underlying workflow of RdTools has been published in several places. If you use RdTools in a published work, please cite the following as appropriate:
- - D. Jordan, C. Deline, S. Kurtz, G. Kimball, M. Anderson, "Robust PV Degradation Methodology and Application",
- IEEE Journal of Photovoltaics, 2017
+ - D. Jordan, C. Deline, S. Kurtz, G. Kimball, M. Anderson, "Robust PV Degradation Methodology and Application", IEEE Journal of Photovoltaics, 8(2) pp. 525-531, 2018
+ - M. G. Deceglie, L. Micheli and M. Muller, "Quantifying Soiling Loss Directly From PV Yield," in IEEE Journal of Photovoltaics, 8(2), pp. 547-551, 2018
- RdTools, version x.x.x, https://github.com/NREL/rdtools, [DOI:10.5281/zenodo.1210316](https://doi.org/10.5281/zenodo.1210316)
*(be sure to include the version number used in your analysis)*
-
## References
The clear sky temperature calculation, `clearsky_temperature.get_clearsky_tamb()`, uses data
@@ -124,10 +44,10 @@ https://neo.sci.gsfc.nasa.gov/view.php?datasetId=MOD_LSTN_CLIM_M
Other useful references which may also be consulted for degradation rate methodology include:
- - D. C. Jordan, M. G. Deceglie, S. R. Kurtz, “PV degradation methodology comparison — A basis for a standard”, in 43rd IEEE Photovoltaic Specialists Conference, Portland, OR, USA, 2016, DOI: 10.1109/PVSC.2016.7749593.
+ - D. C. Jordan, M. G. Deceglie, S. R. Kurtz, "PV degradation methodology comparison — A basis for a standard", in 43rd IEEE Photovoltaic Specialists Conference, Portland, OR, USA, 2016, DOI: 10.1109/PVSC.2016.7749593.
- Jordan DC, Kurtz SR, VanSant KT, Newmiller J, Compendium of Photovoltaic Degradation Rates, Progress in Photovoltaics: Research and Application, 2016, 24(7), 978 - 989.
- D. Jordan, S. Kurtz, PV Degradation Rates – an Analytical Review, Progress in Photovoltaics: Research and Application, 2013, 21(1), 12 - 29.
- - E. Hasselbrink, M. Anderson, Z. Defreitas, M. Mikofski, Y.-C.Shen, S. Caldwell, A. Terao, D. Kavulak, Z. Campeau, D. DeGraaff, “Validation of the PVLife model using 3 million module-years of live site data”, 39th IEEE Photovoltaic Specialists Conference, Tampa, FL, USA, 2013, p. 7 – 13, DOI: 10.1109/PVSC.2013.6744087.
+ - E. Hasselbrink, M. Anderson, Z. Defreitas, M. Mikofski, Y.-C.Shen, S. Caldwell, A. Terao, D. Kavulak, Z. Campeau, D. DeGraaff, "Validation of the PVLife model using 3 million module-years of live site data", 39th IEEE Photovoltaic Specialists Conference, Tampa, FL, USA, 2013, p. 7 – 13, DOI: 10.1109/PVSC.2013.6744087.
## Further Instructions and Updates
diff --git a/docs/degradation_and_soiling_example.ipynb b/docs/degradation_and_soiling_example.ipynb
new file mode 100644
index 00000000..cf4de875
--- /dev/null
+++ b/docs/degradation_and_soiling_example.ipynb
@@ -0,0 +1,834 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Degradation and soiling example with clearsky workflow\n",
+ "\n",
+ "\n",
+ "This juypter notebook is intended to the RdTools analysis workflow. In addition, the notebook demonstrates the effects of changes in the workflow. For a consistent experience, we recommend installing the specific versions of packages used to develop this notebook. This can be achieved in your environment by running `pip install -r requirements.txt` followed by `pip install -r docs/notebook_requirements.txt` from the base directory. (RdTools must also be separately installed.)\n",
+ "\n",
+ "The calculations consist of several steps illustrated here:\n",
+ "| \n", + " | start | \n", + "end | \n", + "slope | \n", + "slope_low | \n", + "slope_high | \n", + "inferred_start_loss | \n", + "inferred_end_loss | \n", + "length | \n", + "valid | \n", + "
|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", + "2008-11-13 00:00:00+09:30 | \n", + "2008-12-11 00:00:00+09:30 | \n", + "-0.001403 | \n", + "-0.004020 | \n", + "0.000000 | \n", + "1.021948 | \n", + "0.982670 | \n", + "28 | \n", + "True | \n", + "
| 1 | \n", + "2008-12-12 00:00:00+09:30 | \n", + "2009-01-01 00:00:00+09:30 | \n", + "-0.000641 | \n", + "-0.002886 | \n", + "0.000000 | \n", + "0.990297 | \n", + "0.977467 | \n", + "20 | \n", + "True | \n", + "
| 2 | \n", + "2009-01-02 00:00:00+09:30 | \n", + "2009-03-20 00:00:00+09:30 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.981110 | \n", + "0.995768 | \n", + "77 | \n", + "False | \n", + "
| 3 | \n", + "2009-03-21 00:00:00+09:30 | \n", + "2009-03-24 00:00:00+09:30 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.987695 | \n", + "1.023433 | \n", + "3 | \n", + "False | \n", + "
| 4 | \n", + "2009-03-25 00:00:00+09:30 | \n", + "2009-05-28 00:00:00+09:30 | \n", + "-0.000559 | \n", + "-0.000880 | \n", + "-0.000244 | \n", + "1.039308 | \n", + "1.003510 | \n", + "64 | \n", + "True | \n", + "
| \n", + " | start | \n", + "end | \n", + "slope | \n", + "slope_low | \n", + "slope_high | \n", + "inferred_start_loss | \n", + "inferred_end_loss | \n", + "length | \n", + "valid | \n", + "
|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", + "2010-02-25 00:00:00-07:00 | \n", + "2010-03-07 00:00:00-07:00 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.0 | \n", + "0.669120 | \n", + "0.896014 | \n", + "10 | \n", + "False | \n", + "
| 1 | \n", + "2010-03-08 00:00:00-07:00 | \n", + "2010-03-11 00:00:00-07:00 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.0 | \n", + "1.048615 | \n", + "1.011925 | \n", + "3 | \n", + "False | \n", + "
| 2 | \n", + "2010-03-12 00:00:00-07:00 | \n", + "2010-04-08 00:00:00-07:00 | \n", + "-0.002423 | \n", + "-0.005208 | \n", + "0.0 | \n", + "1.058734 | \n", + "0.993322 | \n", + "27 | \n", + "True | \n", + "
| 3 | \n", + "2010-04-09 00:00:00-07:00 | \n", + "2010-04-11 00:00:00-07:00 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.0 | \n", + "1.045265 | \n", + "1.045265 | \n", + "2 | \n", + "False | \n", + "
| 4 | \n", + "2010-04-12 00:00:00-07:00 | \n", + "2010-04-20 00:00:00-07:00 | \n", + "0.000000 | \n", + "0.000000 | \n", + "0.0 | \n", + "1.036445 | \n", + "1.026461 | \n", + "8 | \n", + "False | \n", + "