.. _installation:

Installation
############

.. note::
 Only Python >= 3.7 is supported!

`wind_validation` is distributed as both `pypi <https://pypi.org>`__ and `conda <https://docs.conda.io/en/latest/>`__ packages. However, due to dependencies on several GIS utilities (`GeoPandas <https://geopandas.org>`__, `Rasterio <https://rasterio.readthedocs.io>`__), which depend on large C based libraries (`GEOS <https://geos.osgeo.org/>`__, `GDAL <https://www.gdal.org/>`__, `PROJ <https://proj.org/>`__), we recommend installing using the conda packages whenever possible.

Conda installation
------------------

About Conda
^^^^^^^^^^^

Conda is a package manager that is able to use many different sources of packages. `wind_validation`'s dependencies require the use of the `conda-forge <https://conda-forge.org/>`__ channel, which is a community effort to provide conda packages for a wide range of software. `wind_validation` itself is currently only distributed through specific DTU Wind Energy channels

Instructions
^^^^^^^^^^^^

1. To install `wind_validation` you need to first install the *conda* package manager. This is done by installing a conda based distribution. We have been using the `Mambaforge <https://github.com/conda-forge/miniforge#mambaforge>`__ distribution with great success, and recommend it, but other Conda based distributions will work as well.

2. After you have installed a conda distribution, you will need to add the DTU Wind Energy Open Conda Channel, and if not using a forge based distribution, you will also need to add the conda-forge channel.

  The easiest way to do so is via the command prompt.

  On Linux and macOS, open a terminal that has conda configured. On Windows, you will find an entry called the Anaconda Prompt, which will setup the necessary environment for configuring conda.

  Run the commands below to add the channels globally so you can use them for all conda environments::

    conda config --add channels https://conda.windenergy.dtu.dk/channel/open/
    conda config --add channels conda-forge

3. Now you can setup a new conda environment that has `wind_validation` installed. We recommend that you always create a new environment. This helps to prevent the mixing of different channels packages, and allows for easy testing of different versions::

    conda create -n <env_name> wind_validation <other_libraries>


  This command will find the latest version of all of wind_validation's dependencies and install them along with `wind_validation` in an environment named *env_name*. You can add other dependencies as a space-separated list.

4. After creating the new environment, you can change to it using the *conda activate* command::

    conda activate <env_name>

Pip installation
----------------

Wind-validation can also be installed with pip::

  pip install wind_validation

As noted above, you may run into issues with using the pip installer, please see the installation instructions for `GeoPandas <https://geopandas.org/en/stable/getting_started/install.html>`__ and `Rasterio <https://rasterio.readthedocs.io/en/latest/installation.html>`__ to find the best installation method for your platform. Note that for the optional dependency `pyemd <https://github.com/wmayner/pyemd>`__  you will need a c++ compiler, which on windows can be heavy dependency.

Dependencies
------------

Required dependencies:

  - `windkit <https://docs.wasp.dk/windkit>`__

Optional dependencies:
  - `pyemd <https://github.com/wmayner/pyemd>`__ (Needed when you want to calculate the Earth Movers distance for histograms)

Create development environment
##############################

The following packages are required for doing development work on this repository (e.g. running test or updating building the documentation).

.. code-block::

    conda create -n windval_dev pytest pytest-cov setuptools-scm pre-commit ipython jupyter pip nbval pandoc windkit
    pip install sphinx sphinx_rtd_theme sphinx-argparse sphinxcontrib-bibtex recommonmark nbsphinx nbsphinx_link

    # Install and reformat all of your files to match requirements
    pre-commit install

Build documentation
###################

``sphinx`` package is used to document the code, the source files are located in ``docs`` folder. Building docs is as simple as running single command:

.. code-block::

    sphinx-build -b html docs/source public

API reference is generated automatically with ``autosummary`` feature of ``sphinx``. It reads all the doc-strings and produces descriptions for every function in the module.

.. warning::
  Please be aware of leftovers generated by autogen when building docs multiple times and changing the source code. To overwrite previously build docs use the command with additional options:

  .. code-block::

    sphinx-build -E -a -b html docs/source public

Testing
#######

To test the package and get coverage information run from the root of the repository:

.. code-block::

     pytest --cov=wind_validation --cov-report html:tmp/cov_html