Awesome

Software Overview

• Jump to installation instructions.
• Demo the code by running the example notebooks on Binder.
• Read the documentation.
• Learn how to contribute.

OpenOA ¹ is a software framework written in Python for assessing wind plant performance using operational assessment (OA) methodologies that consume time series data from wind plants. The goal of the project is to provide an open source implementation of common data structures, analysis methods, and utility functions relevant to wind plant OA, while providing a platform to collaborate on new functionality.

Development of OpenOA was motivated by the Wind Plant Performance Prediction (WP3) Benchmark project ², led by the National Renewable Energy Laboratory (NREL), which focuses on quantifying and understanding differences between the expected and actual energy production of wind plants. To support the WP3 Benchmark project, OpenOA was initially developed to provide a baseline implementation of a long-term operational annual energy production (AEP) estimation method. It has since grown to incorporate several more OA analysis methods, lower-level utility functions, and a schema for time-series data from wind power plants.

Warning Warning OpenOA is a research software library and is released under a BSD-3 license. Please refer to the accompanying license file for the full terms. We encourage caution, use of best practices, and engagement with subject matter experts when performing any data analysis.

Included Analysis Methods

PlantData Schema

OpenOA contains a PlantData class, which is based on Pandas data frames and provides a standardized base schema to combine raw data from wind turbines, meteorological (met) towers, revenue meters, and reanalysis products, such as MERRA-2 or ERA5. Additionally, the PlantData class can perform some basic validation for the data required to perform the operational analyses.

Utility Functions

Lower-level utility modules are provided in the utils subpackage. They can also be used individually to support general wind plant data analysis activities. Some examples of utils modules include:

• Quality Assurance: This module provides quality assurance methods for identifying potential quality issues with SCADA data prior to importing it into a PlantData object.
• Filters: This module provides functions for flagging operational data based on a range of criteria (e.g., outlier detection).
• Power Curve: The power curve module contains methods for fitting power curve models to SCADA data.
• Imputing: This module provides methods for filling in missing data with imputed values.
• Met Data Processing: This module contains methods for processing meteorological data, such as computing air density and wind shear coefficients.
• Plotting: This module contains convenient functions for creating plots, such as power curve plots and maps showing the wind plant layout.

For further information about the features and citations, please see the OpenOA documentation website.

How to cite OpenOA

To cite analysis methods or individual features: Please cite the original authors of these methods, as noted in the documentation and inline comments.

To cite the open-source software framework as a whole, or the OpenOA open source development effort more broadly, please use citation ¹, which is provided below in BibTeX:

   @article{Perr-Sauer2021,
      doi = {10.21105/joss.02171},
      url = {https://doi.org/10.21105/joss.02171},
      year = {2021},
      publisher = {The Open Journal},
      volume = {6},
      number = {58},
      pages = {2171},
      author = {Jordan Perr-Sauer and Mike Optis and Jason M. Fields and Nicola Bodini and Joseph C.Y. Lee and Austin Todd and Eric Simley and Robert Hammond and Caleb Phillips and Monte Lunacek and Travis Kemper and Lindy Williams and Anna Craig and Nathan Agarwal and Shawn Sheng and John Meissner},
      title = {OpenOA: An Open-Source Codebase For Operational Analysis of Wind Farms},
      journal = {Journal of Open Source Software}
   }

Installation and Usage

Requirements

• Python 3.8-3.11 with pip.

We strongly recommend using the Anaconda Python distribution and creating a new conda environment for OpenOA. You can download Anaconda through their website.

After installing Anaconda, create and activate a new conda environment with the name "openoa-env":

conda create --name openoa-env python=3.10
conda activate openoa-env

Installation

Clone the repository and install the library and its dependencies using pip:

git clone https://github.com/NREL/OpenOA.git
cd OpenOA
pip install .

You should now be able to import OpenOA from the Python interpreter:

python
>>> import openoa
>>> openoa.__version__

Installation Options

There are a number of installation options that can be used, depending on the use case, which can be installed with the following pattern pip install "openoa[opt1,opt2]" (pip install .[opt1,opt2] is also allowed).

• develop: for linting, automated formatting, and testing
• docs: for building the documentation
• examples: for the full Jupyter Lab suite (also contains reanalysis and nrel-wind)
• reanalysis: for accessing and processing MERRA2 and ERA5 data
• nrel-wind: for accessing the NREL WIND Toolkit
• all: for the complete dependency stack

Important If using Python 3.11, install openoa only, then reinstall adding the modifiers to reduce the amount of time it takes for pip to resolve the dependency stack.

Common Installation Issues

• In Windows, you may get an error regarding geos_c.dll. To fix this, install Shapely using:

conda install Shapely

• In Windows, an ImportError regarding win32api can also occur. This can be resolved by fixing
• the version of pywin32 as follows:

pip install --upgrade pywin32==255

Example Notebooks and Data

Be sure to install OpenOA using the examples modifier from above. Such as: pip install ".[examples]"

The example data will be automatically extracted as needed by the tests. To manually extract the example data for use with the example notebooks, use the following command:

unzip examples/data/la_haute_borne.zip -d examples/data/la_haute_borne/

The example notebooks are located in the examples directory. We suggest installing the Jupyter notebook server to run the notebooks interactively. The notebooks can also be viewed statically on Read The Docs.

jupyter lab  # "jupyter notebook" is also ok if that's your preference

Open the URL printed to your command prompt in your favorite browser. Once Jupyter is open, navigate to the "examples" directory in the file explorer and open an example notebook.

Development

Please see the developer section of the contributing guide here, or on the documentation site for complete details.

Development dependencies are provided through the "develop" extra flag in setup.py. Here, we install OpenOA, with development dependencies, in editable mode, and activate the pre-commit workflow (note: this second step must be done before committing any changes):

cd OpenOA
pip install -e ".[develop, docs, examples]"
pre-commit install

Occasionally, you will need to update the dependencies in the pre-commit workflow, which will provide an error when this needs to happen. When it does, this can normally be resolved with the below code, after which you can continue with your normal git workflow:

pre-commit autoupdate
git add .pre-commit-config.yaml

Testing

Tests are written in the Python unittest or pytest framework and are run using pytest. There are two types of tests, unit tests (located in test/unit) run quickly and are automatically for every pull request to the OpenOA repository. Regression tests (located at test/regression) provide a comprehensive suite of scientific tests that may take a long time to run (up to 20 minutes on our machines). These tests should be run locally before submitting a pull request, and are run weekly on the develop and main branches.

To run all unit and regression tests:

pytest

To run unit tests only:

pytest --unit

To run all tests and generate a code coverage report

pytest --cov=openoa

Documentation

Documentation is automatically built by, and visible through Read The Docs.

You can build the documentation with sphinx, but will need to ensure Pandoc is installed on your computer first.

cd OpenOA
pip install -e ".[docs]"
cd sphinx
make html

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

References