+# OpenOA
------
+**A Python framework for wind plant operational assessment using time series data from wind plants.**
[](https://joss.theoj.org/papers/d635ef3c3784d49f6e81e07a0b35ff6b)
[](https://badge.fury.io/py/openoa)
[](https://opensource.org/licenses/BSD-3-Clause)
-[](https://gitter.im/NREL_OpenOA/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
-[](https://mybinder.org/v2/gh/NREL/OpenOA/main?filepath=examples)
-
[](https://openoa.readthedocs.io)
[](https://codecov.io/gh/NREL/OpenOA)
-[](https://pypi.org/project/WOMBAT/)
-[](https://github.com/pre-commit/pre-commit)
-[](https://github.com/psf/black)
-[](https://pycqa.github.io/isort/)
-
-[](#contributors-)
-
+
------
+---
-## Software Overview
+## Table of Contents
-- Jump to [installation instructions](#installation-and-usage).
-- Demo the code by running the [example notebooks on Binder](https://mybinder.org/v2/gh/NREL/OpenOA/main?filepath=examples).
-- Read the [documentation](https://openoa.readthedocs.io/en/latest/).
-- Learn how to [contribute](contributing.md).
+- [Quick Start](#quick-start)
+- [What is OpenOA?](#what-is-openoa)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage Examples](#usage-examples)
+- [Analysis Methods](#analysis-methods)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Citation](#citation)
-OpenOA [^1] 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
-[^2], 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.
+## Quick Start
-> **Warning**
-Warning OpenOA is a research software library and is released under a BSD-3 license. Please refer
-to the accompanying [license file](LICENSE.txt) for the full terms. We encourage caution, use of
-best practices, and engagement with subject matter experts when performing any data analysis.
+**Try OpenOA immediately without installation:**
+- π [Run example notebooks on Binder](https://mybinder.org/v2/gh/NREL/OpenOA/main?filepath=examples)
+**Install and run locally:**
-## Part of the WETO Stack
+```bash
+# Create conda environment (recommended)
+conda create --name openoa-env python=3.10
+conda activate openoa-env
+
+# Install OpenOA
+pip install openoa
-OpenOA is primarily developed with the support of the U.S. Department of Energy and is part of the [WETO Software Stack](https://nrel.github.io/WETOStack). For more information and other integrated modeling software, see:
+# Verify installation
+python -c "import openoa; print(f'OpenOA version: {openoa.__version__}')"
+```
-- [Portfolio Overview](https://nrel.github.io/WETOStack/portfolio_analysis/overview.html)
-- [Entry Guide](https://nrel.github.io/WETOStack/_static/entry_guide/index.html)
-- [Controls and Analysis Workshop](https://nrel.github.io/WETOStack/workshops/user_workshops_2024.html#wind-farm-controls-and-analysis)
+**Basic usage:**
+```python
+from openoa import PlantData
+from openoa.analysis import MonteCarloAEP
-### Included Analysis Methods
+# Load your wind plant data
+project = PlantData.from_dict({
+ "metadata": "path/to/metadata.yml",
+ "scada": "path/to/scada_data.csv",
+ "meter": "path/to/meter_data.csv",
+ "reanalysis": {"era5": "path/to/era5_data.csv"}
+})
-| Name | Description | Citations |
-| --- | --- | --- |
-| `MonteCarloAEP` | This routine estimates the long-term annual energy production (AEP) of a wind power plant (typically over 10-20 years) based on operational data from a shorter period of record (e.g., 1-3 years), along with the uncertainty. | [^3], [^4] |
-| `TurbineLongTermGrossEnergy`| This routine estimates the long-term turbine ideal energy (TIE) of a wind plant, defined as the long-term AEP that would be generated by the wind plant if all turbines operated normally (i.e., no downtime, derating, or severe underperformance, but still subject to wake losses and moderate performance losses), along with the uncertainty. | [^5] |
-| `ElectricalLosses`| The ElectricalLosses routine estimates the average electrical losses at a wind plant, along with the uncertainty, by comparing the energy produced at the wind turbines to the energy delivered to the grid. | [^5] |
-| `EYAGapAnalysis`| This class is used to perform a gap analysis between the estimated AEP from a pre-construction energy yield estimate (EYA) and the actual AEP. The gap analysis compares different wind plant performance categories to help understand the sources of differences between EYA AEP estimates and actual AEP, specifically availability losses, electrical losses, and TIE. | [^5] |
-| `WakeLosses`| This routine estimates long-term internal wake losses experienced by a wind plant and for each individual turbine, along with the uncertainty. | [^6]. Based in part on approaches in [^7], [^8], [^9] |
-| `StaticYawMisalignment`| The StaticYawMisalignment routine estimates the static yaw misalignment for individual wind turbines as a function of wind speed by comparing the estimated wind vane angle at which power is maximized to the mean wind vane angle at which the turbines operate. The routine includes uncertainty quantification. **Warning: This method has not been validated using data from wind turbines with known static yaw misalignments and the results should be treated with caution.** | Based in part on approaches in [^10], [^11], [^12], [^13], [^14] |
+# Run AEP analysis
+aep_analysis = project.MonteCarloAEP()
+aep_results = aep_analysis.run()
+```
-### 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.
+## What is OpenOA?
-### Utility Functions
+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.
-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:
+**Key Benefits:**
+- π **Standardized Analysis**: Implements industry-standard operational assessment methods
+- π¬ **Research-Grade**: Developed by NREL with peer-reviewed methodologies
+- π **Open Source**: BSD-3 licensed for broad accessibility
+- π **Uncertainty Quantification**: Built-in statistical analysis and confidence intervals
+- π§ **Extensible**: Modular design for custom analysis workflows
-- **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.
+> **β οΈ Important Notice**
+> OpenOA is research software released under a BSD-3 license. We encourage caution, use of best practices, and engagement with subject matter experts when performing any data analysis.
-For further information about the features and citations, please see the
-[OpenOA documentation website](https://openoa.readthedocs.io/en/latest/).
-## How to cite OpenOA
+---
-**To cite analysis methods or individual features:** Please cite the original authors of these
-methods, as noted in the [documentation](#included-analysis-methods) and inline comments.
+## Key Features
-**To cite the open-source software framework as a whole, or the OpenOA open source development
-effort more broadly,** please use citation [^1], which is provided below in BibTeX:
+### π― Analysis Methods
-```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}
- }
-```
+| Method | Purpose | Key Applications |
+|--------|---------|------------------|
+| **MonteCarloAEP** | Long-term annual energy production estimation with uncertainty | Performance assessment, financial modeling |
+| **TurbineLongTermGrossEnergy** | Turbine ideal energy calculation excluding downtime | Availability analysis, performance benchmarking |
+| **WakeLosses** | Internal wake loss estimation for wind plants | Layout optimization, performance validation |
+| **ElectricalLosses** | Electrical system loss quantification | Grid integration analysis |
+| **EYAGapAnalysis** | Pre-construction vs. operational performance comparison | Investment validation |
+| **StaticYawMisalignment** | Yaw misalignment detection and quantification | O&M optimization |
-## Installation and Usage
+### π Data Management
-### Requirements
+- **PlantData Schema**: Standardized data structure based on IEC 61400-25
+- **Automated Validation**: Built-in data quality checks and validation
+- **Multi-Source Integration**: SCADA, meteorological towers, revenue meters, reanalysis data
+- **Flexible Import**: Support for various data formats and naming conventions
+
+### π οΈ Utility Functions
-- Python 3.8-3.11 with pip.
+- **Quality Assurance**: SCADA data validation and flagging
+- **Power Curve Modeling**: Advanced curve fitting and analysis
+- **Data Imputation**: Missing data handling and interpolation
+- **Meteorological Processing**: Air density, wind shear calculations
+- **Visualization**: Publication-ready plots and plant layout maps
-We strongly recommend using the Anaconda Python distribution and creating a new conda environment
-for OpenOA. You can download Anaconda through
-[their website.](https://www.anaconda.com/products/individual)
+---
-> [!IMPORTANT]
-> In 2020, Anaconda has changed the Terms of Service for its commercial distribution, and so it is
-> recommended to use either [Miniforge Conda](https://github.com/conda-forge/miniforge), which
-> uses a BSD-3 clause license, or
-> [Miniconda](https://docs.anaconda.com/free/miniconda/index.html), the free tier of Anaconda,
-> depending on your organization's considerations.
+## Installation
+
+### Requirements
-After installing Anaconda (or alternative), create and activate a new conda environment with the
-name "openoa-env":
+- **Python**: 3.8 - 3.11
+- **Operating System**: Windows, macOS, Linux
+- **Package Manager**: pip (conda recommended for environment management)
+
+### Recommended Installation
+
+We strongly recommend using conda for environment management:
```bash
+# Install Miniforge (recommended) or Miniconda
+# Download from: https://github.com/conda-forge/miniforge
+
+# Create and activate environment
conda create --name openoa-env python=3.10
conda activate openoa-env
+
+# Install OpenOA
+pip install openoa
```
-### Installation
+### Installation Options
-Clone the repository and install the library and its dependencies using pip:
+Install additional features as needed:
```bash
-git clone https://github.com/NREL/OpenOA.git
-cd OpenOA
-pip install .
+# Core installation
+pip install openoa
+
+# With example notebooks and data access
+pip install "openoa[examples]"
+
+# With development tools
+pip install "openoa[develop]"
+
+# With documentation building tools
+pip install "openoa[docs]"
+
+# Complete installation
+pip install "openoa[all]"
```
-You should now be able to import OpenOA from the Python interpreter:
+### Common Installation Issues
+**Windows users:**
```bash
-python
->>> import openoa
->>> openoa.__version__
+# If you encounter geos_c.dll errors:
+conda install Shapely
+
+# If you encounter win32api errors:
+pip install --upgrade pywin32==255
```
-#### Installation Options
+### Verify Installation
-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).
+```bash
+python -c "import openoa; print(f'OpenOA version: {openoa.__version__}')"
+```
-- `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.
+## Usage Examples
-#### Common Installation Issues
+### Basic Wind Plant Analysis
-- In Windows, you may get an error regarding geos_c.dll. To fix this, install Shapely using:
+```python
+from openoa import PlantData
+from openoa.analysis import MonteCarloAEP
-```bash
-conda install Shapely
-```
+# Load project data
+project = PlantData.from_dict({
+ "metadata": "metadata.yml",
+ "scada": "scada_data.csv",
+ "meter": "meter_data.csv",
+ "reanalysis": {"era5": "era5_data.csv"}
+})
-- In Windows, an `ImportError` regarding win32api can also occur. This can be resolved by fixing
-- the version of pywin32 as follows:
+# Run AEP analysis
+aep = project.MonteCarloAEP()
+results = aep.run()
-```bash
-pip install --upgrade pywin32==255
+print(f"Annual Energy Production: {results.aep_GWh:.1f} GWh")
+print(f"Uncertainty (P90-P10): {results.aep_GWh_P90 - results.aep_GWh_P10:.1f} GWh")
```
-#### Example Notebooks and Data
+### Wake Loss Analysis
-Be sure to install OpenOA using the `examples` modifier from [above](#installation-options). Such
-as: `pip install ".[examples]"`
+```python
+from openoa.analysis import WakeLosses
-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:
+# Analyze wake losses
+wake_analysis = project.WakeLosses()
+wake_results = wake_analysis.run()
-```bash
-unzip examples/data/la_haute_borne.zip -d examples/data/la_haute_borne/
+print(f"Plant wake losses: {wake_results.wake_loss_total:.1%}")
```
-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](http://openoa.readthedocs.io/en/latest/examples).
+### Data Quality Assessment
-```bash
-jupyter lab # "jupyter notebook" is also ok if that's your preference
+```python
+from openoa.utils import qa
+
+# Run quality checks on SCADA data
+qa_results = qa.check_scada_data(project.scada)
+print(f"Data availability: {qa_results.availability:.1%}")
```
-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
+## Analysis Methods
-Please see the developer section of the contributing guide [here](contributing.md), or on the
-[documentation site](https://openoa.readthedocs.io/en/latest/getting_started/contributing.html) for
-complete details.
+OpenOA implements peer-reviewed methodologies for wind plant operational assessment:
-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):
+### Long-term Energy Assessment
+- **MonteCarloAEP**: Estimates long-term AEP (10-20 years) from short-term data (1-3 years) with uncertainty quantification
+- **TurbineLongTermGrossEnergy**: Calculates theoretical energy production excluding operational losses
-```bash
-cd OpenOA
-pip install -e ".[develop, docs, examples]"
-pre-commit install
-```
+### Loss Analysis
+- **WakeLosses**: Quantifies internal wake effects using operational data
+- **ElectricalLosses**: Measures energy losses between turbines and grid connection
+- **EYAGapAnalysis**: Compares pre-construction estimates with operational performance
-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:
+### Turbine Performance
+- **StaticYawMisalignment**: Detects and quantifies yaw misalignment issues
-```bash
-pre-commit autoupdate
-git add .pre-commit-config.yaml
-```
+> **π Methodology References**
+> Each analysis method is based on peer-reviewed research. See the [full documentation](https://openoa.readthedocs.io) for detailed methodology descriptions and citations.
-#### 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:
+## Documentation
-```bash
-pytest
-```
+- π **[Complete Documentation](https://openoa.readthedocs.io)** - API reference, tutorials, and methodology details
+- π **[Example Notebooks](https://openoa.readthedocs.io/en/latest/examples)** - Interactive tutorials and use cases
+- π **[Try Online](https://mybinder.org/v2/gh/NREL/OpenOA/main?filepath=examples)** - Run examples without installation
+- π¬ **[Community Chat](https://gitter.im/NREL_OpenOA/community)** - Get help and discuss with other users
-To run unit tests only:
+### Example Notebooks
-```bash
-pytest --unit
-```
+- **Getting Started**: Basic PlantData usage and analysis setup
+- **AEP Analysis**: Comprehensive annual energy production assessment
+- **Wake Loss Analysis**: Internal wake loss quantification
+- **Data Quality**: SCADA data validation and cleaning
+- **Custom Analysis**: Building your own analysis workflows
-To run all tests and generate a code coverage report
+---
-```bash
-pytest --cov=openoa
-```
+## Contributing
-#### Documentation
+We welcome contributions from the wind energy community! OpenOA is developed collaboratively to advance operational assessment methodologies.
-Documentation is automatically built by, and visible through
-[Read The Docs](http://openoa.readthedocs.io/).
+### Quick Contribution Guide
-You can build the documentation with [sphinx](http://www.sphinx-doc.org/en/stable/), but will need
-to ensure [Pandoc is installed](https://pandoc.org/installing.html) on your computer first.
+1. **Fork** the repository on GitHub
+2. **Clone** your fork locally
+3. **Install** development dependencies: `pip install -e ".[develop,docs]"`
+4. **Create** a feature branch: `git checkout -b feature/your-feature`
+5. **Make** your changes and add tests
+6. **Run** tests: `pytest --unit`
+7. **Submit** a pull request
+
+### Development Setup
```bash
+# Clone your fork
+git clone https://github.com/your-username/OpenOA.git
cd OpenOA
-pip install -e ".[docs]"
-cd sphinx
-make html
+
+# Install in development mode
+pip install -e ".[develop,docs,examples]"
+
+# Set up pre-commit hooks
+pre-commit install
+
+# Run tests
+pytest --unit # Fast unit tests
+pytest # All tests (may take 20+ minutes)
```
-## Contributors β¨
+### Ways to Contribute
+
+- π **Bug Reports**: Submit detailed issue reports
+- π‘ **Feature Requests**: Propose new analysis methods or improvements
+- π **Documentation**: Improve guides, examples, and API documentation
+- π¬ **Research**: Contribute new validated methodologies
+- π§ͺ **Testing**: Add test cases and improve coverage
-Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+See our [Contributing Guide](contributing.md) for detailed guidelines.
-
-
-
- Rob Hammond π» π π β π§ π€ π |
-  Jordan Perr-Sauer π π» π β π§ π€ π |
-  ejsimley π π» π£ π π β π€ π |
-  Jason Fields π π πΌ π¨ π |
-  Nicola Bodini π» π β π€ |
-  moptis π» π£ π π β π€ |
-  Joseph Lee π» |
-
 Charlie π» π£ π β π€ |
-  zheitkamp1 π» |
-  Abiodun Timothy Olaoye π» |
-  Kristen Thyng π» |
-  Rafael M Mudafort π» |
-  sebastianpfaffel π» |
-  nateagarwal π» π |
-
 Var-Char π» |
- ||||||
- 
- Add your contributions
-
- |
- ||||||