.. _data_structures:

===============
Data Structures
===============

The data structures in PyWAsP consists of :py:class:`xarray.Dataset` and :py:class:`xarray.DataArray` objects for array-like objects,
:py:class:`geopandas.GeoDataFrame` and :py:class:`geopandas.GeoSeries` for vector objects, and custom classes for higher-level abstractions.

Xarray objects are made to be domain-agnostic, so labels and names can be anything, but in WindKit and PyWAsP we make them be
domain-specific by defining specific variable, dimension, and coordinate names to represent specific kinds of data. So, while many xarray
objects in PyWAsP are "simple" array variables, like an array of wind speed or annual energy production values, other objects
are collections of arrays following a particular format and naming convention pattern (schema).
This is described in some detail in :doc:`WindKit's introduction <windkit:windkit>`, but below we also provide an overview.

Spatial structures in xarray objects
====================================

WindKit/PyWAsP recognizes three kinds of spatial structures in xarray objects (see also the :doc:`Description of GeoSpatial Structures in WindKit <windkit:windkit>`).

**point**

    Xarray objects associated with points in 3D space are expected to contain the following:

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (point, ...)
        Coordinates:
            west_east(point, ...)
            south_north(point, ...)
            height(point, ...)



**stacked_point**

    Xarray objects associated with points in x, y space with information at multiple vertical levels,
    are expected to contain the following:


    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (stacked_point, height, ...)
        Coordinates:
            west_east(stacked_point, ...)
            south_north(stacked_point, ...)
            height(height, ...)

**raster**

    Xarray raster objects are expected to contain the following:

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (west_east, south_north, ...)
        Coordinates:
            west_east(west_east, ...)
            south_north(south_north, ...)

**cuboid**

    Xarray objects with a regular gridded structure in x, y, and z, are expected to contain the following:

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (west_east, south_north, height, ...)
        Coordinates:
            west_east(west_east, ...)
            south_north(south_north, ...)
            height(height, ...)

All four spatial xarray.Dataset structures also expects a variables ``crs`` that contain the geopstial coordinate reference system information.

xarray.Dataset objects
======================

.. _data_structures_datasets:

**Binned Wind Climate**

    A binned wind climate in PyWAsP is expected to have two variables,
    respectively containing the wind speed and wind direction distributions:

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (wsbin, sector, ...)
        Data variables(dims):
            wsfreq(wsbin, sector, ...)
            wdfreq(sector, ...)

**Weibull Wind Climate**

    Weibull wind climates have weibull parameters and wind direction frequencies varying by sector:

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (sector, ...)
        Data variables(dims):
            A(sector, ...)
            k(sector, ...)
            wdfreq(sector, ...)

**Generalized Wind Climate**

    Generalized wind climates are (for now) weibull wind climates with two extra
    dimensions: generalized height and generalized roughness.

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (gen_height, gen_roughness, sector, ...)
        Data variables(dims):
            A(gen_height, gen_roughness, sector, ...)
            k(gen_height, gen_roughness, sector, ...)
            wdfreq(gen_height, gen_roughness, sector, ...)


**Wind Turbine Generator**

    Wind Turbine Generators are expected to look as below. It is assumed that Wind Turbine
    generator's dont have "extra" dimensions.

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Dimensions: (mode, wind_speed)
        Data variables(dims):
            power_output                   (mode, wind_speed)
            thrust_coefficient             (mode, wind_speed)
            air_density                    (mode)
            stationary_thrust_coefficient  (mode)
            wind_speed_cutin               (mode)
            wind_speed_cutout              (mode)
            rated_power                    (mode)
            name
            rotor_diameter
            hub_height


xarray.DataArray variables
==========================


**Raster maps**

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Data variables:
            elevation
            roughness
            landcover

**Terrain Effect**

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Data variables:
            z0meso
            slfmeso
            displ
            user_def_speedups
            orographic_speedups
            obstacle_speedups
            roughness_speedups
            user_def_turnings
            orographic_turnings
            obstacle_turnings
            roughness_turnings
            site_elev
            rix
            dirrix



**Wind Climate**

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Data variables:
            mean_dgdz
            mean_dgdz_dir
            mean_temp_scale_land
            mean_temp_scale_sea
            rms_temp_scale_land
            rms_temp_scale_sea
            mean_pblh_land
            mean_pblh_sea

**Wind Farm**

    .. code-block:: bash

        <xarray.Dataset>
        ...
        Data variables:
            gross_AEP
            potential_AEP
            AEP_deficit
            turbulence_intensity_eff
            wspd_eff
            wspd
            wspd_deficit



geopandas.GeoDataFrame
======================

**Elevation vector map**

    .. code-block:: bash

        <geopandas.GeoDataFrame>
        columns:
            elev
            geometry: LINESTRING


**Land cover vector map**

    .. code-block:: bash

        <geopandas.GeoDataFrame>
        columns:
            id_left
            id_right
            geometry: LINESTRING

Other objects
======================

**windkit.WindTurbines**: :py:class:`windkit.WindTurbines`


**WAsP Model Config**:  :py:class:`pywasp.wasp.Config`


**TopographyMap**: :py:class:`pywasp.wasp.TopographyMap`


**Land Cover Table**: :py:class:`pywasp.io.LandCoverTable`