Minor documentation improvements for v2 (#187)

* More details on FLASC packages, point users to examples.

* Remove trailing whitespace.

docs/getting_started.md

@@ -0,0 +1,29 @@
+# Getting started
+
+The easiest way to get started is to install FLASC and
+then follow the examples. The correct order is:
+
+## Install FLASC
+Install the repository following the instructions `here <installation.html>`_.
+
+## FLASC 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.
+
+Roughly speaking, the examples in both ``examples_smarteole/`` and
+``examples_artificial_data`` demonstrate the FLASC modules in the order:
+- `flasc.data_processing`
+- `flasc.analysis`
+- `flasc.model_fitting`
+
+and use `flasc.utilities` throughout.

docs/overview.md

@@ -2,97 +2,66 @@
 
 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) wake modeling utility.
-FLASC also largely relies on the energy ratio to, among others, quantify wake
-losses in synthetic and historical data, to perform turbine northing
+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.
 
-# Literature
-
-See a particular wind rose, e.g., for annual operation. See
-{cite:p}`Doekemeijer2022a` and {cite:p}`Bay2022a`for a practical
-example of how the flasc repository is used or 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 (2024). Available at https://github.com/NREL/flasc.
-
-For LaTeX users:
-
-
-    @misc{flasc2024,
-      author = {NREL},
-      title = {FLASC. Version 2.0},
-      year = {2022},
-      publisher = {GitHub},
-      journal = {GitHub repository},
-      url = {https://github.com/NREL/flasc},
-    }
+# FLASC package
 
+FLASC consists of multiple modules, including:
 
-# 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]>`_.
+## flasc.data_processing
 
-<!--
-# Module overview
+This module contains functions that supports importing and processing raw
+SCADA data files. Data is saved in feather
+format for optimal balance of storage size and load/write speed.
 
-FLASC consists of multiple modules, including:
+Functions include filtering data by wind direction, wind speed an/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.
 
-## flasc.dataframe_operations
+Finally, functions are provided to detect northing bias (caused by
+miscalibrated yaw encoders) in turbine data.
 
-This module includes functionality to easily manipulate Pandas DataFrames.
-Functions include filtering data by wind direction, wind speed an/or TI,
-deriving the ambient conditions from the upstream turbines, all the while
-dealing with angle wrapping for angular variables.
+## flasc.model_fitting
 
+This is a module related to the estimation of parameters in the FLORIS wind
+farm wake model, as well as fitting behavior of turbines in yaw misalignment.
 
-## flasc.energy_ratio
+## flasc.analysis
 
-this module contains classes to calculate and visualize the energy ratio as
+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.
-
+details. Also included are methods for calculating the total power uplift in a
+comparative field experiment.
 
-## flasc.floris_tools
+## flasc.utilities
 
-This module contains functions that leverage the floris model directly. This
-includes functions to calculate a large set of floris simulations (with MPI,
-optionally) for different atmospheric conditions, yaw misalignments and/or
-model parameters. It also includes two functions to precalculate and
+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.
 
-
-## flasc.model_estimation
-
-This is a module related to the estimation of parameters in the floris wind
-farm model. One class herein, called floris_sensitivity_analysis, performs
-Sobol parameter sensitivity studies to determine which parameters are most
-sensitive in various situations (atmospheric conditions, turbine settings,
-wind farm layouts).
-
-
-## flasc.optimization
-
-The optimization module includes functions to estimate the timeshift between
+Also included are functions to estimate the timeshift between
 two sources of data, for example, to sychronize 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.
@@ -101,32 +70,42 @@ 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.`
 
-## flasc.raw_data_handling
+# Literature
 
-This module contains functions that supports importing and processing raw
-SCADA data files. Specifically, it provides a class called
-"sql_database_manager" which can be used to up- and download data between
-your local system and a remote SQL database. This class also contains a GUI
-to visualize data existent in the remote repository. This repository also
-includes data handling for very large datasets. Data is saved in feather
-format for optimal balance of storage size and load/write speed.
-Additionally, can split one large dataframe into multiple dataframes and
-feather files.
+See {cite:p}`Doekemeijer2022a` and {cite:p}`Bay2022a`for practical
+examples of how the flasc repository is used or processing and analyses of
+historical SCADA data of three offshore wind farms.
 
+  ```{bibliography}
+  ```
 
-## flasc.time_operations
+# Citation
 
-This module allows the user to easily 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 to maximize performance.
 
+If FLASC played a role in your research, please cite it. This software can be
+cited as:
+
+   FLASC. Version 2.0 (2024). Available at https://github.com/NREL/flasc.
+
+For LaTeX users:
 
-## flasc.turbine_analysis
 
-this module allows the user to analyze SCADA data on a turbine level. Outliers
-can be detected and removed. Filtering methods include sensor-stuck type of
-fault detection and analysis of the turbine wind speed-power curve. -->
+    @misc{flasc2024,
+      author = {NREL},
+      title = {FLASC. Version 2.0},
+      year = {2022},
+      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]>`_.