NatLabRockies · paulf81 · Sep 26, 2025 · Sep 4, 2024 · Sep 11, 2024 · Sep 12, 2024
diff --git a/.gitignore b/.gitignore
@@ -32,4 +32,4 @@ SMARTEOLE_WakeSteering_ReadMe.xlsx
 SMARTEOLE_WakeSteering_Map.pdf
 SMARTEOLE-WFC-open-dataset.zip
 examples_artificial_data/03_energy_ratio/heterogeneity_layouts.pdf
-docs/examples
+*.pkl
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,7 +2,7 @@
 repos:
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.4.0
+  rev: v5.0.0
   hooks:
   - id: trailing-whitespace
   - id: end-of-file-fixer

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -6,23 +6,17 @@ root: index
 parts:
   - caption: Getting Started
     chapters:
-    - file: overview
+    - file: introduction
     - file: installation
-    - file: getting_started
 
   - caption: User Reference
     chapters:
-    # - file: data_processing
     - file: flasc_data_format
     - file: energy_ratio
     - file: energy_change
+    - file: model_fit
     - file: licensing
 
-  # - caption: Developer Reference
-  #   chapters:
-  #   - file: contributing
-  #   - file: development
-  #   - file: testing
   - caption: Examples Data Processing
     chapters:
     - file: examples/01_raw_data_processing/03_northing_calibration_hoger

diff --git a/docs/getting_started.md b/docs/getting_started.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,22 +1,48 @@
 
-# FLASC documentation
-
+# FLASC
 
 Welcome to the documentation of the NREL FLASC repository!
 
 ```{note}
 FLASC v2.3 now requires `numpy` version 2, following the update in FLORIS v4.3. See the [numpy documentation for details](https://numpy.org/doc/stable/numpy_2_0_migration_guide.html).
 ```
 
-FLASC provides a rich suite of analysis tools for SCADA data filtering &
-analysis, wind farm model validation, field experiment design, and field
-experiment monitoring. The repository is centrally built around NRELs
-in-house [FLORIS](https://github.com/NREL/floris/discussions/)
- wake modeling utility.
+FLASC provides a comprehensive toolkit for wind farm analysis, combining SCADA data processing with advanced wake modeling capabilities. The repository is intended as a community-driven toolbox, available on its [GitHub Repository](https://github.com/NREL/flasc).
+
+## What is FLASC?
+
+FLASC offers analysis tools for SCADA data filtering & analysis, wind farm model validation, field experiment design, and field experiment monitoring. Built around NREL's [FLORIS](https://github.com/NREL/floris/discussions/) wake modeling utility, FLASC enables researchers and practitioners to:
+
+- **Process and filter SCADA data** with robust outlier detection and quality control
+- **Analyze energy production patterns** using energy ratio methodology for wake quantification  
+- **Calibrate wake models** automatically to match observed turbine performance
+- **Evaluate field experiments** with comprehensive uplift analysis tools
+
+## Documentation Structure
+
+This documentation is organized to guide you from basic concepts to advanced applications:
+
+### Getting Started
+- **[Introduction](introduction)**: Overview of FLASC capabilities and package structure
+- **[Installation](installation)**: Setup instructions and requirements
+
+### Core Concepts
+- **[FLASC Data Format](flasc_data_format)**: Understanding FLASC's data structures and conventions
+- **[Energy Ratio Analysis](energy_ratio)**: Quantifying wake effects and turbine performance
+- **[Energy Change Analysis](energy_change)**: Methods for calculating production changes
+- **[Model Fitting](model_fit)**: Automated FLORIS model calibration to SCADA data
+
+### Practical Applications
+The documentation includes extensive examples demonstrating real-world applications using both synthetic data (`examples_artificial_data/`) and field experiment data (`examples_smarteole/`). These examples follow a typical FLASC workflow: data processing → analysis → model calibration.
+
+## Key Features
+
+FLASC's modular design supports the complete wind farm analysis workflow:
 
-FLASC also largely relies on the energy ratio to, among other things, quantify wake
-losses in synthetic and historical data, to perform turbine northing
-calibrations, and for model parameter estimation.
+- **Data Processing**: Import, filter, and quality-control SCADA data with specialized tools for wind measurements
+- **Wake Analysis**: Quantify wake effects using energy ratios and validate against physics-based models  
+- **Model Calibration**: Automatically tune FLORIS parameters to match observed performance
+- **Experiment Analysis**: Evaluate control strategies and technology impacts with statistical rigor
 
 The FLASC repository is intended as a community driven toolbox, available on
 its [GitHub Repository](https://github.com/NREL/flasc).

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,44 +1,3 @@
-<!-- # Installation
-
-FLASC is currently not available as a package on any repository manager.
-Instead, it must be installed by the user by cloning the GitHub repository.
-
-To download the source code, use `git clone`. Then, add it to
-your Python path with the "local editable install" through `pip`.
-
-```bash
-# Download the source code.
-git clone https://github.com/NREL/flasc.git
-
-# Install into your Python environment
-pip install -e flasc
-
-```
-
-If installing FLASC with the intention to develop, some additional configuration is helpful:
-
-
-Install FLASC in editable mode with the appropriate developer tools
-
-   - ``".[develop]"`` is for the linting and code checking tools
-   - ``".[docs]"`` is for the documentation building tools. Ideally, developers should also be
-     contributing to the documentation, and therefore checking that
-     the documentation builds locally.
-
-```bash
-pip install -e ".[develop, docs]"
-```
-Turn on the linting and code checking tools
-
-```bash
-pre-commit install
-```
-
-If everything is configured correctly, any changes made to the source
-code will be available directly through your local Python. Remember
-to re-import the FLASC module when changes are made if you are working
-in an interactive environment like Jupyter. -->
-
 # Installation
 
 FLASC is available as a package on PyPI. We strongly recommend installing FLASC

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -0,0 +1,77 @@
+# Introduction to FLASC
+
+FLASC provides a rich suite of analysis tools for SCADA data filtering & analysis, wind farm model validation, field experiment design, and field experiment monitoring. The repository is centrally built around NREL's in-house [FLORIS](https://github.com/nrel/floris) wake modeling utility. FLASC also largely relies on the "energy ratio" to quantify wake losses in synthetic and historical data, perform turbine northing calibrations, and for model parameter estimation.
+
+## Getting Started
+
+The easiest way to get started is to install FLASC and then follow the examples. The recommended approach is:
+
+### 1. Install FLASC
+Install the repository following the instructions in [installation](installation).
+
+### 2. Explore Examples
+You can generate a demo dataset by following the examples in `examples_smarteole/`. The notebook `02_download_and_format_dataset.ipynb` downloads data from a wake steering experiment conducted in 2019. We encourage users to step through the notebooks in `examples_smarteole/` in order to develop an understanding of FLASC's capabilities using a dataset from a real field experiment.
+
+Additional useful examples can be found in `examples_artificial_data/`, where we intentionally introduce "challenges" for the FLASC tools to solve using artificially-generated data. This provides a good way for users to get to know the FLASC tools in more depth. Again, we recommend stepping through the examples in the subdirectories in their numerical order.
+
+### 3. Workflow Overview
+Roughly speaking, the examples in both `examples_smarteole/` and `examples_artificial_data` demonstrate the FLASC modules in the order:
+- `flasc.data_processing` - Import and filter SCADA data
+- `flasc.analysis` - Energy ratio analysis and uplift calculations  
+- `flasc.model_fitting` - Calibrate FLORIS models to SCADA data
+
+and use `flasc.utilities` throughout for supporting functions.
+
+## FLASC Package Structure
+
+FLASC consists of multiple modules, each serving specific analysis needs:
+
+### flasc.data_processing
+This module contains functions that support importing and processing raw SCADA data files. Data is saved in feather format for optimal balance of storage size and load and write speed.
+
+Functions include filtering data by wind direction, wind speed and/or TI, deriving the ambient conditions from the upstream turbines, all the while dealing with angle wrapping for angular variables. Outliers can be detected and removed at the turbine level. Filtering methods include sensor-stuck type of fault detection and analysis of the turbine wind speed-power curve.
+
+Also included are functions to downsample, upsample and calculate moving averages of a data frame with SCADA and/or FLORIS data. These functions allow the user to specify which columns contain angular variables, and consequently 360 deg wrapping is taken care of. It also allows the user to calculate the min, max, std and median for downsampled data frames. It leverages efficient functions inherent in pandas and polars to maximize performance.
+
+Finally, functions are provided to detect northing bias (caused by miscalibrated yaw encoders) in turbine data.
+
+### flasc.analysis
+This module contains classes to calculate and visualize the energy ratio as defined by Fleming et al. (2019). The energy ratio is a very useful quantity in SCADA data analysis and related model validation. It represents the amount of energy produced by a turbine relative to what that turbine would have produced if no wakes were present. See [energy ratio](energy_ratio) for more details. Also included are methods for calculating the total power uplift in a comparative field experiment.
+
+### flasc.model_fitting
+This module provides automated calibration of FLORIS wake models to SCADA data through the ModelFit framework. It includes modular cost functions, optimization algorithms, and tools for parameter sensitivity analysis. See [model fitting](model_fit) for comprehensive documentation.
+
+### flasc.utilities
+This module contains utilities that support the other modules within FLASC. These utilities help to interface with FLORIS and calculate a large set of floris simulations for different atmospheric conditions, yaw misalignments and/or model parameters. It also includes two functions to precalculate and respectively interpolate from a large set of model solutions to speed up further postprocessing.
+
+Also included are functions to estimate the timeshift between two sources of data, for example, to synchronize measurements from a met mast with measurements from SCADA data. The module also includes a function to estimate the offset between two timeseries of wind direction measurements. This is useful to determine the northing bias of a turbine if you know the correct calibration of at least one other wind turbine. Finally, this module also contains a function to estimate the atmospheric turbulence intensity based on the power measurements of the turbines inside a wind farm.
+
+Additionally, visualization tools can be found in `flasc.visualization` and `flasc.yaw_optimizer_visualization`.
+
+## Literature
+
+See {cite:p}`Doekemeijer2022a` and {cite:p}`Bay2022a` for practical examples of how the flasc repository is used for processing and analyses of historical SCADA data of three offshore wind farms.
+
+```{bibliography}
+```
+
+## Citation
+
+If FLASC played a role in your research, please cite it. This software can be cited as:
+
+   FLASC. Version 2.0.1 (2024). Available at https://github.com/NREL/flasc.
+
+For LaTeX users:
+
+    @misc{flasc2024,
+      author = {NREL},
+      title = {FLASC. Version 2.0.1},
+      year = {2024},
+      publisher = {GitHub},
+      journal = {GitHub repository},
+      url = {https://github.com/NREL/flasc},
+    }
+
+## Questions
+
+For technical questions regarding FLASC usage, please post your questions to [GitHub Discussions](https://github.com/NREL/flasc/discussions) on the FLASC repository. Alternatively, email the NREL FLASC team at `[email protected] <mailto:[email protected]>`_ or `[email protected] <mailto:[email protected]>`_.