API Reference

Wind Conditions

The WindKit API provides a set of functions to work with wind conditions, the “raw” wind speed and direction data, and wind climates in specific formats: time-series, histogram, weibull, and the WAsPs generalized wind climate and geostrophic wind climate formats.

Wind functions

`wind_speed`(u, v)	Calculate wind speed from wind vectors.
`wind_direction`(u, v)	Calculate wind directions from wind vectors.
`wind_speed_and_direction`(u, v)	Calculate wind speed and wind direction from wind vectors.
`wind_vectors`(ws, wd)	Calculate wind vectors u,v from the speed and direction.
`wind_direction_difference`(wd_obs, wd_mod)	Calculate the circular (minimum) distance between two directions (observed and modelled).
`wd_to_sector`(wd[, sectors, output_type, ...])	Convert wind directions to 0-based sector indices.
`vinterp_wind_direction`(wind_direction, ...)	Interpolate wind direction to a given height.
`vinterp_wind_speed`(wind_speed, height[, ...])	Vertically interpolate wind speed to a given height from other height levels.
`rotor_equivalent_wind_speed`(wind_speed, ...)	Calculate the rotor equivalent wind speed (REWS) from given wind speed and directions on height levels.

Wind climate functions

`create_met_fields`(output_locs[, n_sectors, ...])	Create empty dataset filled with met_fields
`mean_ws_moment`(wc_obj[, moment, bysector])	Calculate the mean wind speed moment from a wind climate.
`ws_cdf`(wc_obj, *[, bysector])	Calculate the wind speed cumulative distribution function from a wind climate.
`ws_freq_gt_mean`(wc_obj, *[, bysector])	Calculate the wind speed frequency greater than the mean from a wind climate.
`mean_wind_speed`(wc_obj, *[, bysector])	Calculate the mean wind speed from a wind climate.
`mean_power_density`(wc_obj, *[, bysector, ...])	Calculate the power density of wind climate object
`get_cross_predictions`(wcs[, wcs_src, ...])	Get cross predictions from a dataset

Time Series Wind Climate (TSWC)

`validate_tswc`(obj[, run_extra_checks])	Validation function.
`is_tswc`(obj[, run_extra_checks])	Check that an object is valid.
`create_tswc`(output_locs[, date_range, ...])	Create empty time series wind climate dataset.
`read_tswc`(filename[, file_format])	Reads a time series wind climate file into a xarray.Dataset.
`tswc_from_dataframe`(pd_df, west_east, ...[, ...])	transforms a pandas.DataFrame into a time series wind climate xarray.Dataset.
`tswc_resample`(ds, freq[, var_ws, var_wd, ...])	Resample wind speed and direction to a given frequency.

Long-term correction

The long-term correction (LTC) module provides functionality for performing long-term corrections on wind time series data. It includes methods for linear regression and variance ratio methods.

`ltc.LinRegMCP`([ws_cutoff])	Sectorwise MCP using Scipy's linear regression.
`ltc.VarRatMCP`([fit_intercept, ws_cutoff])	Sectorwise MCP using variance ratio linear regression.

Binned Wind Climate (BWC)

`validate_bwc`(obj[, run_extra_checks])	Validation function.
`is_bwc`(obj[, run_extra_checks])	Check that an object is valid.
`create_bwc`(output_locs[, n_sectors, ...])	Create empty binned wind climate dataset.
`read_bwc`(filename, *[, crs, file_format])	Creates binned wind climate xarray.Dataset from file.
`bwc_from_tswc`(ts[, wsbin_width, n_wsbins, ...])	Creates object from a timeseries.
`bwc_to_file`(bwc, filename, *[, file_format])	Write binned wind climate to file.
`combine_bwcs`(bwc_list)	Combines a list of bwc's into one binned wind climate.
`weibull_fit`(bwc[, include_met_fields, atol])	Returns sectorwise Weibull parameters using WAsP's fitting algorithm.

Weibull Wind Climate (WWC)

`validate_wwc`(obj[, run_extra_checks])	Validation function.
`is_wwc`(obj[, run_extra_checks])	Check that an object is valid.
`create_wwc`(output_locs[, n_sectors, ...])	Create empty weibull wind climate dataset.
`read_wwc`(filename, *[, file_format])	Read a weibull wind climate dataset from a file.
`read_mfwwc`(files[, file_format])	Read multiple weibull wind climate datasets from files.
`wwc_to_file`(wwc, filename, *[, file_format])	Write a weibull wind climate dataset to a file.
`wwc_to_bwc`(wwc, ws_bins)	Creates object from directional A's and k's.
`weibull_combined`(wwc[, atol])	Return the all sector A & k.

Generalized Wind Climate (GWC)

`validate_gwc`(obj[, run_extra_checks])	Validation function.
`is_gwc`(obj[, run_extra_checks])	Check that an object is valid.
`create_gwc`(output_locs[, n_sectors, ...])	Create empty generalized wind climate dataset.
`read_gwc`(filename, *[, crs, west_east, ...])	Create gwc xarray.Dataset from file.
`gwc_to_file`(gwc, filename, *[, file_format])	Write generalized wind climate to file.

Geostrophic Wind Climate (GeoWC)

`validate_geowc`(obj[, run_extra_checks])	Validation function.
`is_geowc`(obj[, run_extra_checks])	Check that an object is valid.

Topography

Topography provides the roughness and elevation data that is used to model the wind resource. The tools in WindKit allow you to work with both raster and vector based maps, and use the powerful GDAL library behind the scenes to enable a wide variety of file formats to be used.

Landcover

`LandCoverTable`(*args[, levels, colors])	Subclass of dictionary that provides a lookup table for landcover and roughness.
`get_landcover_table`(dataset[, table])	Get landcover table from dataset and table name.
`add_landcover_table`(gdf, lctable)	Add a landcover table to a GeoDataFrame.
`roughness_to_landcover`(rgh)	Converts a roughness map to landcover map.
`landcover_to_roughness`(lc, lctable)	Converts a landcover map to roughness map.
`read_roughness_map`(filename[, crs, ...])	Read roughness map from file.
`read_landcover_map`(filename[, crs, ...])	Read landcover map from file.
`landcover_map_to_file`(landcover_map, ...)	Write landcover map to file.
`roughness_map_to_file`(roughness_map, ...)	Write roughness map to file.

Elevation

`read_elevation_map`(filename[, crs])	Read elevation map from file.
`elevation_map_to_file`(elevation_map, ...)	Write elevation map to file.

Raster maps

`create_raster_map`(output_locs, resolution[, ...])	Create empty raster map data array The values in the raster map are a 2d gaussian and the boundaries are defined by output_locs.
`get_raster_map`(bbox[, dataset, band, source])	Download a raster map from DTU, the planetary computer or google earth engine.

Vector maps

`create_vector_map`(bbox[, map_type, ...])	Create a square elevation or roughness map within the specified bounding box.
`get_vector_map`(bbox[, dataset, source])	Download a map from the GWA map API.

Map conversion

`lines_to_polygons`(lines[, check_errors])	Converts a GeoDataFrame of lines into polygons.
`polygons_to_lines`(gdf[, lctable, map_type, ...])	Convert a GeoDataFrame of polygons into line segments.
`snap_to_layer`(gdf[, tolerance])	Snaps the geometries in a GeoDataFrame to each other within a specified tolerance.
`check_dead_ends`(lines_out[, errors, add_errors])	Detects dead ends in a given set of lines.
`check_lines_cross`(lines_out[, errors, ...])	Detects and handles crossing line geometries in a GeoDataFrame.

Wind Farm

Wind Turbines

`validate_windturbines`(obj[, run_extra_checks])	Validation function.
`is_windturbines`(obj[, run_extra_checks])	Check that an object is valid.
`check_wtg_keys`(wind_turbines, wtg_dict)	Checks that all keys in a wind turbines object are there.
`create_wind_turbines_from_dataframe`(location_df)	Creates a point dataset with required metadata from a dataframe.
`create_wind_turbines_from_arrays`(west_east, ...)	Creates a point dataset with required metadata from explicit arrays.
`wind_turbines_to_geodataframe`(ds)	Converts a wind turbine dataset to a geopandas dataframe.

Wind Turbine Generators (WTG)

Windkit’s wind turbine API has routines to load both wind turbine generator power curves, and to create layouts of wind farms.

`validate_wtg`(obj[, run_extra_checks])	Validation function.
`is_wtg`(obj[, run_extra_checks])	Check that an object is valid.
`RegulationType`(*values)
`estimate_regulation_type`(wtg)	Estimate the regulation type of a WTG
`read_wtg`(wtg_file[, file_format, ...])	Read in Wind Turbine Generator (WTG) data from a file.
`wtg_power`(wtg[, ws, interp_method, ...])	Get power output when the inflow wind speed is ws.
`wtg_cp`(wtg[, ws, air_density, ...])	Get power coefficient when the inflow wind speed is ws.
`wtg_ct`(wtg[, ws, interp_method, ct_stat])	Get the thrust coefficient of a Wind Turbine Generator for given wind speed(s).

Losses and Uncertainty

Windkit has support for basic loss and uncertainty calculations to obtain, for example, a p90 of AEP estimates.

`validate_uncertainty_table`(uncertainty_table)	Perform several checks to ensure that an uncertainty table DataFrame is valid.
`get_uncertainty_table`([table_name])	Get the wind and energy uncertainty DataFrame from the supported uncertainty tables.
`total_uncertainty`(uncertainty_table[, ...])	Calculate the total uncertainty in the DataFrame.
`uncertainty_table_summary`(uncertainty_table)	Print a summary of the uncertainties in the DataFrame.
`total_uncertainty_factor`(uncertainty_table)	Calculate the total uncertainty factor for a given exceedance probability or a list of probabilities.

Spatial

The WindKit Geospatial Tools allow you to perform common GIS functions such as convert between the different Geospatial xarray structures in windkit, reproject or warp the data into common projections, and clip or mask the data based on additional data sources.

In addition to the provided tools, since WindKit stores its objects in the formats of powerful python libraries, you can also make use of additional geopandas functions for vector data, and additional xarray functions for raster data.

Throughout this documentation, the following abbreviations are used to reference different data types.

geodf - either a geopandas.GeoDataFrame or geopandas.GeoSeries
xr_data - either an xarray.DataArray or xarray.Dataset
CRS - pyproj.crs.CRS

Coordinate Reference System

`spatial.get_crs`(obj)	Returns a pyproj.crs.CRS object from object metadata.
`spatial.add_crs`(obj, crs)
`spatial.set_crs`(obj, crs)	Adds a Coordinate Reference System to a WindKit object.
`spatial.crs_are_equal`(obj_a, obj_b)	Check if CRS's of two WindKit objects are equal

Bounding Box

spatial.BBox(ring, crs)

WindKit Bounding Box

Create spatial objects

`spatial.create_dataset`(west_east, ...[, ...])	Create a WindKit dataset given a set of locations.
`spatial.create_raster`(west_east, ...)	Create a WindKit raster dataset given a set of locations.
`spatial.create_point`(west_east, south_north, ...)	Create a WindKit point dataset given a set of locations.
`spatial.create_stacked_point`(west_east, ...)	Create a WindKit stacked point dataset given a set of locations.
`spatial.create_cuboid`(west_east, ...)	Create a WindKit cuboid dataset given a set of locations.

Validate spatial objects

`spatial.is_point`(obj)	Check if WindKit xarray object has 'point' spatial dimension.
`spatial.is_stacked_point`(obj)	Check if WindKit xarray object has 'stacked_point' dimension.
`spatial.is_cuboid`(obj)	Check if WindKit xarray object has cuboid dimensions.
`spatial.is_raster`(obj)	Check if WindKit xarray object has raster-like dimensions.

Convert between spatial objects

`spatial.to_point`(obj)	Converts a WindKit xarray.Dataset or xarray.DataArray to 'point' structure
`spatial.to_cuboid`(obj[, ignore_raster_check])	Converts a point based object to a cuboid based object
`spatial.to_stacked_point`(obj)	Converts a WindKit dataset or dataarray to a 'stacked_point' structure
`spatial.to_raster`(obj[, ignore_raster_check])	Converts a point based object to a raster based object
`spatial.gdf_to_ds`(gdf[, height, struct])	Convert geopandas dataframe to windkit spatial structure.
`spatial.ds_to_gdf`(ds[, include_height])	Convert windkit spatial structure to geopandas dataframe.

Interpolation

`spatial.interp_structured_like`(source, target)	Interpolate spatially from cuboid dataset/dataarray to another spatial dataset/dataarray
`spatial.interp_unstructured`(obj[, ...])	Interpolate spatially from unstructured dataset/dataarray to new coordinates.
`spatial.interp_unstructured_like`(source, target)	Interpolate spatially from unstructured dataset/dataarray to another spatial dataset/dataarray

Comparison

`spatial.are_spatially_equal`(obj_a, obj_b)	Checks that the spatial points are equivalent for both datasets
`spatial.equal_spatial_shape`(obj_a, obj_b)	Check if two spatial objects have the same shape.
`spatial.covers`(obj_a, obj_b)	Checks if obj_a covers obj_b

Spatial operations

`spatial.clip`(obj, mask[, all_touched, ...])	Clip object to mask.
`spatial.clip_with_margin`(obj_to_clip, ...[, ...])	Clip a 'raster' or 'cuboid' dataset to the bounding box of another 'raster', 'cuboid', 'stacked_point', or 'point' dataset including a margin around that dataset to ensure several points are avaiable around the clipper dataset from the clipped one.
`spatial.mask`(obj, mask[, all_touched, ...])	Mask WindKit object with geometric mask.
`spatial.nearest_points`(ds_ref, ds_target[, ...])	Get nearest points from dataset in windkit spatial structure
`spatial.reproject`(obj, to_crs[, copy])	Reprojects WindKit object a new CRS without changing the data.
`spatial.warp`(obj, to_crs[, resolution, ...])	Warp cuboid WindKit object to another in a new CRS using data interpolation.
`spatial.add_projected_wrf_coordinates`(ds)	Add the west_east, south_north coordinates to a WRF xarray.Dataset output.
`spatial.count_spatial_points`(obj)	Get the number of spatial points for a dataset or DataArray

Plotting

WindKit Plotting allows you to execute a number of different plotting functions in order to visualize and analyze your data. Plots are largely broken into two categories; statistical and maps. Statistical plots are generally plotted using Plotly and Dash Python libraries at a single location, e.g. mast or turbine location, while maps use geopandas and xarray functions directly to show an overview of the area.

`plot.histogram`(ds[, style, color, weibull, ...])	Plot the histogram represented in a binned wind climate.
`plot.histogram_lines`(ds[, colors, gap])	Create a "distribution" plot and matching frequency wind rose for binned wind climate.
`plot.operational_curves`	Wind turbine generator operational curves.
`plot.raster_plot`(da[, contour, ...])	Creates a raster map plot.
`plot.roughness_rose`(ds[, style, gap])	Create roughness rose plot.
`plot.time_series`	Wind speed time-series plotting including wind speed and wind direction
`plot.vertical_profile`([da_meas, da_pred, ...])	Plots the vertical profile of the dataArray or dataArrays introduced.
`plot.wind_rose`(ds[, wind_speed_bins, style, ...])	Create wind rose plot.
`plot.color`	Helper functions for colors and colormaps.
`plot.landcover_map`(gdf[, column, ax])	Plot the polygons in a map colored by a certain field, picking some reasonable defaults for the colors and legend

Other

Tutorial data

get_tutorial_data(name[, force_download])

Downloads and extracts tutorial data from Zenodo if not already cached.

Weibull distribution

`weibull.fit_weibull_wasp_m1_m3_fgtm`(m1, m3, ...)	Fit weibull parameters from the first and third moments and the fraction of probability mass above the mean
`weibull.fit_weibull_wasp_m1_m3`(m1, m3[, atol])	Fit weibull parameters from the first and third moments
`weibull.fit_weibull_k_sumlogm`(sumlogm[, ...])	Fit weibull shape parameter from the sum of log of moments
`weibull.weibull_moment`(A, k[, n])	Calculate moment for a weibull distribution.
`weibull.weibull_pdf`(A, k, x)	Calculate the probability density function for a weibull distribution.
`weibull.weibull_cdf`(A, k, x)	Calculate the cumulative distribution function for a weibull distribution.
`weibull.weibull_freq_gt_mean`(A, k)	Calculate the fraction of probability mass that lie above the mean wind speed for a weibull distribution
`weibull.get_weibull_probability`(A, k, ...[, ...])	Calculate Weibull probability.

WAsP

`Workspace`(tree, path)	Workspace class for interacting with WAsP workspace XML files
`WengWorkspace`(wep_file_path)
`read_cfdres`(path, crs)	Read .cfdres file into xarray

Coordinates

`create_sector_coords`([bins, start])	Create wind sector coordinate as a data array.
`create_wsbin_coords`([bins, width, start])	Create wind speed bins coordinates.

Get reanalysis data

get_era5(datetime[, bbox, source, ...])

Download ERA5 data from the planetary computer.