windkit 0.8.0__tar.gz → 2.0.0__tar.gz

{windkit-0.8.0 → windkit-2.0.0}/CHANGELOG.md

@@ -2,9 +2,321 @@
 
 All major changes are listed here.
 
-## Unreleased
+## 2.0.0 (2025-07-21)
 
-## 0.8.0 (2024-06-10)
+### Highlights
+
+### Performance improvements
+* Significantly reduced import time by lazy loading some packages and data. Should be approx 1/3 of previous import time.
+
+### Sheer and veer functionality
+
+* Added new function `wk.shear_extrapolate` to extrapolate wind speeds to different heights using a power law shear profile.
+* Added new function `wk.shear_exponent` to calculate a shear exponent from wind speeds
+* Added guidance about `wk.shear_exponent` into shear extrapolation example. 
+
+* Added new function `wk.veer_extrapolate` to extrapolate wind direction linearly to different heights, accounting for circular discontinuities.
+* Added new function `wk.wind_veer` to calculate wind veer from wind direction
+* Added guidance about `wk.wind_veer` into shear extrapolation example. 
+
+### Support for PyWAsP's Geostrophic wind climate objects
+
+* new function `create_geowc`, which creates a dummy geostrophic wind climate
+* functions `mean_wind_speed`, `mean_power_density`, `ws_freq_gt_mean`, `ws_cdf` and `mean_ws_moment` are now also working when a geostrophic wind climate is passed.
+* bug fix to interpolation, which would create invalid spatial structures when a dimension was in exclude dims but not present in the target structure (e.g. when doing interpolation from `stacked_point` to `point`).
+
+### New features
+* Added new function `wk.extrapolate_to_height` to extrapolate wind climate objects to different heights. Currently, only works for time-series wind climates (TSWC).
+* Fixed bug where a point dataset with several horizontal locations would be converted to a single horizontal location when using the function `to_stacked_point`
+* `wk.roughness_map_to_file` now allows to write to a old fashioned `.map` file for the special case where these is a single polygon and the external roughness length is not specified (None). For this case we assume that the external roughness length is the same as the roughness length inside the polygon.
+* `wk.roughness_map_to_file` now allows users to write to a `.map` as long all displacement heights in the map are zero.
+* Bugfix in `read_bwc`: it now opens `bwc` stored in netcdf correctly.
+but some of this functionality was only available in pywasp, so it has been moved there.
+* For `wv_count` objects (thus also geostrophic wind climates) if all of the bins have nan's, the result of function `mean_wind_speed`, `mean_power_density`, `ws_freq_gt_mean` and `mean_ws_moment` operating on such a function is also nan, whereas before it would be 0.
+
+### Changes
+* Changed default value of `use_bounds` to `True` in `wk.spatial.BBox.reproject` method.
+
+### Breaking changes
+
+* `spatial_interpolate_gwc` has been removed. This functionality is now only available in PyWAsP through its `interpolate_gwc` function.
+
+## [1.0.2 (2025-07-21)](https://docs.wasp.dk/windkit/v1.0.2/)
+
+WindKit 1.0.2 is a patch release to ensure consistent config and app data paths on windows. Both the config and app data paths are now set by default to ``C:\\Users\\<user>\\AppData\\Roaming\\DTU Wind Energy\\windkit``.
+
+## 1.0.1 (2025-07-15)
+
+WindKit 1.0.1 is a patch release that changes the config migration that shipped with 1.0.0. The changed ensures that the legacy `.ini` configuration files are migrated to the new `.toml` format without automatically removing the old file. This ensures that users are not constantly prompted to update their configuration file if they use different versions of WindKit in different environments.
+
+## 1.0.0 (2025-06-26)
+
+This is a major release that introduces a significantly cleaner and more intuitive API. We have removed many functions from the public namespace, renamed others for consistency, and introduced powerful new features. While this version includes many breaking changes, the result is a more streamlined and user-friendly library. We strongly recommend all users to carefully read these release notes and update their code.
+
+### Highlights
+
+#### Simplified and Consistent API
+The `windkit` namespace has been significantly cleaned up to make the API more predictable and easier to learn. Many internal or redundant functions have been removed from the public API, and others have been renamed for better clarity and consistency.
+*   Functions for reading and writing different objects in windkit are now grouped by type, such as `read_tswc`, `read_bwc`, `read_wwc`, and `read_gwc` for reading wind climate datasets, and `bwc_to_file`, `wwc_to_file`, and `gwc_to_file` for writing them.
+*   Functions for creating empty datasets are now prefixed with `create_*` (e.g., `create_bwc` instead of `empty_bwc`).
+*   Functions for creating wind climate objects from other data types now follow a `[climate]_from_[source]` pattern (e.g., `bwc_from_tswc` instead of `bwc_from_timeseries`).
+*   Validation functions are now consistently named `validate_*` (e.g., `validate_bwc` instead of `bwc_validate`).
+
+#### Revamped Map Reading and Writing
+The API for handling spatial maps has been completely overhauled. The generic `read_raster_map`, `read_vector_map`, `raster_map_to_file`, and `vector_map_to_file` functions have been replaced by specific, format-aware functions for each map type:
+*   `read_elevation_map` and `elevation_map_to_file`
+*   `read_roughness_map` and `roughness_map_to_file`
+*   `read_landcover_map` and `landcover_map_to_file`
+
+These new functions automatically infer the file format from the suffix (e.g., `.map`, `.tif`, `.gpkg`) and provide a more robust and intuitive interface for working with elevation, roughness, and landcover data.
+
+#### Polygon Representation for Landcover and Roughness Maps
+A major improvement is the new default support for polygon-based landcover and roughness maps. The functions `read_landcover_map` and `read_roughness_map` now return `geopandas.GeoDataFrame` objects with polygons when reading vector data, which is a more standard and powerful representation for GIS data. This enables more robust handling and validation of maps. For backward compatibility, you can still work with the legacy line-based format by setting `polygons=False`.
+
+#### Unified API for Wind Climate Statistics
+Calculating statistics from wind climate objects is now much simpler. A new set of generic functions can operate on any wind climate type (BWC, WWC, etc.):
+*   `wk.mean_wind_speed`
+*   `wk.mean_power_density`
+*   `wk.ws_cdf` (Cumulative Distribution Function)
+*   `wk.ws_freq_gt_mean`
+*   `wk.mean_ws_moment`
+
+This unified API replaces the climate-specific functions (e.g., `bwc_mean_windspeed`), simplifying your code and making it more versatile.
+
+#### New Loss and Uncertainty Modeling
+WindKit now includes tools to support loss and uncertainty analysis, designed to integrate seamlessly with PyWAsP. You can now create, validate, and summarize standardized loss and uncertainty tables using:
+*   `get_loss_table`, `total_loss`, `loss_summary`
+*   `get_uncertainty_table`, `total_uncertainty`, `uncertainty_summary`
+
+This provides a structured framework for AEP calculations.
+
+### Breaking Changes and Migration Guide
+Due to the extensive API changes, you will need to update your existing code. Here is a guide to the most common changes:
+
+#### General Renaming and Removals
+*   **Namespace Cleanup**: Many functions like `bwc_validate_wrapper`, `update_history`, and various `spatial` utilities have been removed from the public `windkit` namespace. 
+*   **Function Renaming**:
+  *   `windkit.read_timeseries_from_pandas` is now `windkit.tswc_from_dataframe`.
+  *   `windkit.bwc_from_timeseries` is now `windkit.bwc_from_tswc`.
+  *   `windkit.read_timeseries_from_csv` is now `windkit.read_tswc`.
+  *   All `windkit.empty_*` functions are now `windkit.create_*` (e.g., `empty_bwc` -> `create_bwc`).
+  *   `lines2poly` is now `lines_to_poly`, and `poly2lines` is now `poly_to_lines`.
+  *   `add_crs` is now `set_crs`.
+*   **Argument Renaming**: Several function arguments have been renamed for consistency. For example, `nsec` is now `n_sectors` and `nwsbins` is now `n_wsbins`. Check the function signatures if you encounter errors.
+*   **Removed Classes**: The `windkit.WindTurbines` class has been removed. Use the functions in the `windkit.wind_turbines` module to work with `xarray.Dataset` representations of turbines.
+
+
+#### Wind Climate I/O 
+Wind climate reading and writing has been standardized to one reader and one writer for each type:
+  *   Use `read_tswc` to read time series wind climate datasets.
+  *   Use `read_bwc` and `bwc_to_file` for Binned Wind Climate datasets.
+  *   Use `read_wwc` and `wwc_to_file` for Weibull Wind Climate datasets.
+  *   Use `read_gwc` and `gwc_to_file` for Generalized Wind Climate datasets.
+
+  #### Configuration File and Environment Variables
+  The configuration file format has been switched from INI to TOML. Existing `.ini` configuration files will be migrated automatically.
+
+  Additionally, user details can now be configured using case-insensitive environment variables, which is ideal for containerized or CI/CD environments:
+  *   `WINDKIT_NAME`
+  *   `WINDKIT_EMAIL`
+  *   `WINDKIT_INSTITUTION`
+
+  If no configuration is found (either via file or environment variables), you will be prompted for the information upon initialization.
+
+
+
+### Full list of changes
+
+#### Bug Fixes
+*   `clip_with_margin` now returns a `ValueError` when the bbox crosses the dateline.
+*   Fixed an issue where `read_raster_map` was checking for too high roughness values twice.
+*   Duplicate heights passed to `create_dataset` with `struct=stacked_point` are now correctly removed.
+*   `gdf_to_ds` now correctly handles unique points to ensure round-tripping with `ds_to_gdf` works as expected.
+*   Fixed a bug where `get_vector_map` for CORINE data could fail with a missing column error.
+*   `to_stacked_point` now correctly retains the input order of coordinates.
+*   `nearest_points` now raises an error on duplicate points to be compatible with newer xarray versions.
+*   Fixed a bug in `wk.spatial.add_crs` where custom projection information could be overwritten by a detected EPSG code.
+*   Fixed `wk.spatial.interp_unstructured_like` to correctly broadcast single-point sources.
+*   Fixed a bug in `nearest_points` when `keep_duplicates=False` and `return_distance=True`.
+
+
+#### API Breaks
+* `windkit.read_timeseries_from_pandas` renamed as `windkit.tswc_from_dataframe`
+* `windkit.bwc_from_timeseries` renamed as `windkit.bwc_from_tswc`
+* `windkit.read_timeseries_from_csv` renamed as `windkit.read_tswc`
+* all `windkit.empty_*` functions renamed to `windkit.create_*`
+* renamed `lines2poly` to `lines_to_poly` and `poly2lines` to `poly_to_lines`
+* removed `wk.lib_string` from public namespace
+* `windkit.spatial.interp_unstructured_like` and `windkit.spatial.interp_structured_like` will not interpolate over 1D variables by default
+ * Removed `read_raster_map`,`raster_map_to_file`, and `read_vector_map` and `vector_map_to_file` (made private)
+ * Added `read_elevation_map` and `elevation_map_to_file` (works for vector and raster)
+ * Added `read_roughness_map` and `roughness_map_to_file` (works for vector and raster)
+ * Added `read_landcover_map`, and `landcover_map_to_file` (works for vector and raster)
+* Old .gpkg files with change lines in landcover_map_to_file
+and roughness_map_to_file can be written by using polygons=False
+ * File formats for the readers and writers described above are now inferred from the filename's suffix, e.g., `.map` for map files.
+ * The functions `read_landcover_map` and `read_roughness_map` by default return polygons instead of changes lines. You can set the argument `polygons=False` to open the file as old fashioned change lines. You can try this if your file is not being opened correctly, but you are responsible for checking it's correctness, because there is less error checking for these types of files.
+ * Added `roughness_to_landcover` to convert roughness maps to landcover maps (vector or raster)
+ * Added `landcover_to_roughness` to convert landcover maps to roughness maps (vector or raster)
+ * Renamed `add_crs` to `set_crs` and and deprecated `add_crs` (which calls `set_crs`)
+* `get_vector_map` now returns landcover data as polygons by default.
+ * Removed `wk.bwc_ws_moment` from public namespace, use `wk.mean_ws_moment` instead
+ * Removed `wk.bwc_mean_windspeed` from public namespace, use `wk.mean_wind_speed` instead
+ * Removed `wk.bwc_mean_windspeed3` from public namespace, use `wk.mean_wind_speed3` instead
+ * Removed `wk.bwc_power_density` from public namespace, use `wk.mean_power_density` instead
+ * Removed `wk.bwc_ws_cdf` from public namespace, use `wk.ws_cdf` instead
+ * Removed `wk.bwc_ws_freq_gt_mean` from public namespace, use `wk.ws_freq_gt_mean` instead
+ * Removed `wk.bwc_to_tabfile` from public namespace, use `wk.bwc_to_file` instead
+ * Removed `wk.bwc_validate_wrapper` from public namespace
+ * Removed `wk.create_time_attributes` from public namespace
+ * Removed `wk.count_to_ws_freq_by_sector` from public namespace
+ * Removed `wk.read_rsffile`  from public namespace use `wk.read_wwc` instead
+ * Removed `wk.read_wrgfile` from public namespace, use `wk.read_wwc` instead
+ * Removed `wk.read_grdfile` from public namespace, use `wk.read_wwc` instead
+ * Removed `wk.read_pwcfile` from public namespace, use `wk.read_wwc` instead
+ * Removed `wk.to_rsffile` from public namespace, use `wk.wwc_to_file` instead
+ * Removed `wk.to_wrgfile` from public namespace, use `wk.wwc_to_file` instead
+ * Removed `wk.wwc_validate_wrapper` from public namespace
+ * Removed `wk.wwc_validate_structure`
+ * Removed `wk.wwc_validate_structure_wrapper`
+ * Removed `wk.wwc_mean_windspeed` from public namespace, use `wk.mean_wind_speed` instead
+ * Removed `wk.wwc_power_density` from public namespace, use `wk.mean_power_density` instead
+ * Removed `wk.to_libfile` from public namespace, use `wk.gwc_to_file` instead
+ * Removed `wk.gwc_validate_wrapper` from public namespace
+ * Removed `wk.wtg_validate_wrapper` from public namespace
+ * Removed `wk.windturbines_validate_wrapper` from public namespace
+ * Modified `wk.read_tswc` to be a generic tswc reader (not just for CSV)
+ * Renamed `wk.is_windturbines` to `wk.is_wind_turbines`
+ * Renamed `wk.windturbines_validate` to `wk.validate_windturbines`
+ * Renamed `wk.wtg_validate` to `wk.validate_wtg`
+ * Renamed `wk.gwc_validate` to `wk.validate_gwc`
+ * Renamed `wk.wwc_validate` to `validate_wwc`
+ * Renamed `wk.bwc_validate` to `wk.validate_bwc`
+ * Removed `wk.get_map`
+ * Removed `wk.spatial.interpolate_to_grid`
+ * Removed `wk.WindTurbines`
+ * Removed `wk.Workspace.get_vector_map`
+ * Added `wk.Workspace.get_elevation_map`
+ * Added `wk.Workspace.get_roughness_map`
+ * Removed `wk.bwc_from_counts` (from public namespace)
+ * Removed `wk.create_wv_count` (from public namespace)
+ * Removed `wk.update_history` (from public namespace)
+ * Removed `wk.update_coords_attrs` (from public namespace)
+ * Removed `wk.update_var_attrs` (from public namespace)
+ * Removed `wk.ALL_VARS_META` (from public namespace)
+ * Removed `wk.spatial.spatial_stack` (from public namespace)
+ * Removed `wk.spatial.spatial_unstack` (from public namespace)
+ * Removed `wk.spatial.stack_then_unstack` (from public namespace)
+ * Removed `wk.spatial.get_latitude` (from public namespace)
+ * Removed `wk.spatial.is_vertical` (from public namespace)
+ * Removed `wk.import_optional_dependency` (from public namespace)
+ * Removed `wk.reproject_gwc` (from public namespace)
+ * Removed `wk.get_ee_map` (from public namespace)
+ * Removed `wk.create_coords` 
+ * Renamed `wk.create_ws_bin_coords` to `wk.create_wsbin_coords` and changed the arguments to `bins`, `width` and `start`. `bins` is an integer number of bins or a list of bin edges. `width` is the width of the bins, and `start` is the starting point of the first bin. `width` and `start` are only used if `bins` is an integer.
+ * Removed `wk.create_ws_bin_coords_from_values` 
+ * Changed `wk.create_sector_coords` arguments to `bins` and `start`. `bins` is an integer number of bins or a list of bin edges. `start` is the starting point of the first bin. By default, `start` is -360/n_bins/2.
+ * Removed `wk.create_sector_coords_from_edges` 
+ * Removed `wk.create_direction_coords` (from public namespace)
+ * `wk.create_vector_map` now has bbox as a first positional argument and argument `dist` is removed
+ * Renamed `wk.get_land_cover_table` to `wk.get_landcover_table`
+
+#### New features
+* `wk.read_wtg` can read wind turbine generators files in netCDF format.
+* `wk.mean_ws_moment` to calculate the mean of a wind speed moment of any wind climate
+* `wk.ws_cdf` to calculate the cumulative distribution function of a wind speed of any wind climate
+* `wk.ws_freq_gt_mean` to calculate the fraction of probability mass above the mean of a wind speed of any wind climate
+* `wk.mean_wind_speed` to calculate the mean wind speed of any wind climate
+* `wk.mean_wind_speed3` to calculate the mean wind speed cubed of any wind climate
+* `wk.mean_power_density` to calculate the mean power density of any wind climate
+* All of the above calculates the the variable of all wind climates (not all functions are supports all climates yet).
+* Added `read_wwc` to read a weibull wind climate dataset from a file
+* Added `read_mfwwc` to read a multi-filey weibull wind climate dataset
+*  Added `wwc_to_file` to write a weibull wind climate dataset to a file
+* Added `read_gwc` to read a generalized wind climate dataset from a file
+* Added `gwc_to_file` to write a generalized wind climate dataset to a file
+* Added `bwc_to_file` to write a binned wind climate dataset to a file
+* New function `add_projected_wrf_coordinates` that is useful to process `WRF` output data to be used with `windkit`.
+* Existing function `windkit.read_wtg` can optionally read the wind turbine manufacturer name from a `.wtg` file if exists.
+* New function `windkit.metadata.update_coords_attrs` to update attributes of a dataset coordinates.
+* New function `create_baro` to create a baro file with dummy values
+* New function `create_stab` to create a stab file with dummy values
+* New function `windkit.snap_to_layer` that transform a vector map with polyons with gaps, open areas and inconsistent vertices into a valid vector map to run `pywasp`.
+* New example notebook tutorial for `windkit.get_era5` to get ERA5 data from Microsoft Planetary Computer
+* `windkit.raster_map_to_file` allows extra arguments that are forwarded to `rasterio.open`. Useful to create e.g. compressed geoTIFF files with the "compress" option.
+* New class `windkit.WengWorkspace` to read WAsP Engineering proyect files in XML format and converting its content to `xarray.Dataset` and `xarray.DataArray` instances such as extreme wind climate datasets, location datasets and raster map data arrays.
+* Enable roughness maps to be written to `.map` files
+* Added kw-argument `return_lctable` to functions reading landcover maps, set to false by default, which means only the landcover map is returned
+* Added kw-argument `convert_to_landcover` to functions reading roughness maps to optionally convert the map to landcover, returning both the map and the table (two outputs)
+* It is now allowed to use `wk.landcover_map_to_file` to write a landcover map to a `.map` file as long as the displacements are all zero.
+* `lines_to_polygons` is a more robust version of `lines_to_poly` and now tries to make the polygons valid if they are not. It is also much faster.
+* `polygons_to_lines` is a more robust version of `poly_to_lines` and is much faster.
+* Added function `windkit.plot.landcover_map`, which can plot a landcover map with some nicer color schemes.
+* Added function `windkit.plot.elevation_map`, which can plot an elevation map with some nicer color schemes.
+* Added function `windkit.add_landcover_table` to add roughness and other information from a wk.LandCoverTable to a geopandas dataframe with only an `id` column
+* in `get_raster_map`, an option to download from GWA4 landcover `GWA4_landcover` and `GWA4_elevation` has been added
+* Added function `windkit.get_tutorial_data` to download tutorial data from the windkit zenodo repository. The data is downloaded to a local cache directory, which is created if it does not exist.
+* Configuration can now be defined using case-insensitive environment variables `windkit_name`, `windkit_email` and `windkit_institution`. If these are not set, and the configuration file is not found, you will be prompted on initialization.
+
+#### Added functionality to work with losses
+- Defined the data structure of loss tables: a pandas DataFrame with required columns: "loss_name" and "loss_percentage". It can also have optional columns "loss_category", "loss_upper_bound", "loss_lower_bound", "loss_default", and "description"
+- Added function `get_loss_table` to obtain a loss tables (DataFrame) from known name. Currently, only "dtu_default" exists.
+- Added function `validate_loss_table` to validate a loss table is formatted correctly
+- Added function `total_loss` to calculate the total loss in percentage from a loss table
+- Added function `loss_summary` to print a formatted summary of the loss table
+- Added function `total_loss_factor` to calculate the loss factor (the factor that can be directly multiplied to subtract the loss from an AEP number)
+
+#### Added functionality to work with uncertainties
+- Defined the data structure of uncertainty tables: a pandas DataFrame with required columns: "uncertainty_kind", "uncertainty_name" and "uncertainty_percentage". It can also have optional columns "uncertainty_category", "uncertainty_upper_bound", "uncertainty_lower_bound", "uncertainty_default", and "description"
+- Added function `get_uncertainty_table` to obtain an uncertainty table (DataFrame) from known name. Currently, only "dtu_default" exists.
+- Added function `validate_uncertainty_table` to validate an uncertainty table is formatted correctly
+- Added function `total_uncertainty` to calculate the total uncertainty in percentage from an uncertainty table. Following the GUM guideline on adding uncertainties.
+- Added function `uncertainty_summary` to print a formatted summary of the uncertainty table
+- Added function `total_uncertainty_factor` to calculate the uncertainty factor (the factor that can be directly multiplied to add the uncertainty to an AEP estiamtion)
+
+#### Bug fixes
+* `clip_with_margin` now returns a `ValueError` when the bbox crosses the dateline
+* `read_raster_map` was checking for too high roughness twice, one is enough
+* If duplicate heights are passed to `create_dataset` with `struct=stacked_point` it will remove the duplicates
+as required in the `stacked_point` structure.
+* in `gdf_to_ds` we must create the target dataset using unique (`west_east`,`south_north`) points for `stacked_point` and unique `west_east` and `south_north` for cuboids to be able to round trip `ds_to_gdf` and `gdf_to_ds`.
+* get_vector_map(bb, "CORINE", source="dtu") could sometimes fail with "Exception: Missing required column: id", this has been fixed
+* read_vector_map also reads .gpkg files where a geometry column is missing on the landcovertable layer
+* to_stacked_point now retains input order of west_east/south_north coordinates
+* Nearest_points will now raise an error if there are duplicate points resulting from the nearest neighbour lookup if the data is in stacked_point or cuboid format. This is required because xarray >2024.02 does not allow duplicates in MultiIndexes anymore. A new keyword argument keep_duplicates controls the behaviour, the default being True, i.e. when possible behaviour is the same as before.
+* In the function `wk.spatial.add_crs` assigning a projection with more detailed info given in a proj4 string or custom CRS was overwritten when an EPSG was found for the projection. This is now fixed and the full custom CRS is added.
+* Fixed `wk.spatial.interp_unstructured_like` to broadcast single-point sources correctly to target.
+* Fix bug in `nearest_points` when `keep_duplicates=False` and `return_distance=True`: it threw an error that the arrays were not the same size. 
+
+#### Breaking changes
+* `empty_wasp_site_factors` renamed to `empty_wasp_site_effects`
+* in `empty_z0meso` argument `site_factors` was renamed renamed to `site_effects`
+* in `empty_pwc` argument `site_factors` was renamed renamed to `site_effects`
+- Argument `nwsbins`, `nws`, `n_bins` has been renamed to `n_wsbins` or `wsbins` (in case of array-like argument) in the following functions:
+    - `bwc_from_tswc`
+    - `create_ws_bin_coords`
+    - `create_ws_bin_coords_from_values`
+- Argument `nsec`, `nsecs`, `nwd`, `nbins` has been renamed to `n_sectors` in the following functions:
+    - `create_sector_coords`
+    - `create_direction_coords`
+    - `create_sector_coords_from_edges`
+    - `wd_to_sector`
+    - `bwc_from_tswc`
+- Argument `num_args` has been renamed to `n_args` in the following functions:
+    - `ltc_validate`
+- Argument `ws_bin_width`has been renamed to `wsbin_width` in the following functions:
+    - `create_ws_bin_coords`
+    - `bwc_from_tswc`
+* Metadata variable name `aep_deficit` has been renamed to `potential_aep_deficit`
+
+* Functions `read_raster_map` and `raster_map_to_file` were removed in favour of the new functions `read_elevation_raster`, `write_elevation_raster`, `read_landcover_raster`, and `write_landcover_raster`.
+* Functions `read_vector_map` and `vector_map_to_file` were removed in favour of the new functions `read_elevation_vector`, `write_elevation_vector`, `read_landcover_vector`, and `write_landcover_vector`.
+* Changed most instances where "header" is used to "description"
+* `get_vector_map` returns polygons instead of lines.
+* Switched configuration file from ini to toml, old file will be automatically migrated
+
+
+## [0.8.0 (2024-06-10)](https://docs.wasp.dk/windkit/v0.8.0/)
 
 ### New features
 
@@ -107,8 +419,8 @@ Additionally a few high level routines were added for interpolation specific fie
 #### Improvements to the map_conversion routines
 
 * Added `windkit.map_conversion.find_duplicate_lines` to identify duplicated lines in a GeoDataFrame, even if the line is reversed.
-* `windkit.poly2lines` now correctly sets the CRS to match the input data. Before it was `None`.
-* `windkit.poly2lines` and `windkit.lines2poly` now have an absolute tolerance argument, `atol`, which can be used to identify nearby points, which should be joined.
+* `windkit.poly_to_lines` now correctly sets the CRS to match the input data. Before it was `None`.
+* `windkit.poly_to_lines` and `windkit.lines2poly` now have an absolute tolerance argument, `atol`, which can be used to identify nearby points, which should be joined.
 
 #### Access to data from Microsoft's Planetary Computer platform
 
@@ -168,7 +480,7 @@ Additionally a few high level routines were added for interpolation specific fie
 * `windkit.spatial.interpolate_to_grid` deprecated in favor of `windkit.spatial.interp_structured_like` and `windkit.spatial.interp_unstructured_like`
 
 ### Breaking changes
-* `windkit.poly2lines` no longer has a `closed_map` argument. Instead, when `background_lc_id` is set, all empty space is filled with the provided id. This allows for maps that are no longer rectangular, e.g. due to reprojection, to be properly converted to line maps.
+* `windkit.poly_to_lines` no longer has a `closed_map` argument. Instead, when `background_lc_id` is set, all empty space is filled with the provided id. This allows for maps that are no longer rectangular, e.g. due to reprojection, to be properly converted to line maps.
 * Removed accessors, which were previously registered for several wind climate data structures. You will need to use the functions instead.
 
 ## 0.6.3 (2023-07-18)
@@ -291,7 +603,7 @@ Several new features in this release including support for Wind Turbines, the ab
   the following:
   - `LineMap` and `PolyMap` classes: These classes enable conversion and nice plotting
     of their types.
-  - `lines2poly` and `poly2lines` helper functions that perform the conversion from
+  - `lines2poly` and `poly_to_lines` helper functions that perform the conversion from
     lines to polygons and from polygons to line respectively, using the library
     `geopandas.GeoDataFrame`.
 * New module `windkit.plot.landcover_map` to plot the `geopandas.GeoDataFrame` polygons
@@ -303,7 +615,7 @@ Several new features in this release including support for Wind Turbines, the ab
 #### New spatial functionality
 
 * New function `windkit.spatial.interpolate_to_grid` to resample data to a target grid.
-* New function `windkit.spatial.get_latitude` that returns data-array of latitude values in wgs84.
+* New function `windkit.spatial._get_latitude` that returns data-array of latitude values in wgs84.
 * New function `windkit.spatial.count_spatial_points` counts how many points are in a windkit dataset or dataarray.
 
 #### Enhancements to `windkit.get_map.get_ee_map`

windkit-2.0.0/PERFORMANCE_CI_PLAN.md

@@ -0,0 +1,294 @@
+# Performance Regression CI Job - Implementation Plan
+
+## Overview
+
+This plan outlines the implementation of a CI job to catch performance regressions in windkit. The job will test import timing, function execution benchmarks, and memory usage.
+
+## Goals
+
+1. **Catch regressions** in import time (target: < 1 second)
+2. **Benchmark critical functions** and track performance over time
+3. **Fail CI** when performance degrades beyond acceptable thresholds
+4. **Provide actionable reports** showing what regressed and by how much
+
+---
+
+## Implementation Components
+
+### 1. Performance Test Module
+
+**File: `test/test_performance.py`**
+
+```python
+"""Performance regression tests for windkit."""
+
+import sys
+import time
+import pytest
+
+# Thresholds (in seconds)
+IMPORT_TIME_THRESHOLD = 1.0  # Maximum acceptable import time
+IMPORT_TIME_WARNING = 0.8    # Warning threshold
+
+
+class TestImportPerformance:
+    """Tests for import time performance."""
+
+    def test_import_time_under_threshold(self):
+        """Verify windkit imports in under 1 second."""
+        # Ensure windkit is not already imported
+        modules_to_remove = [k for k in sys.modules if k.startswith('windkit')]
+        for mod in modules_to_remove:
+            del sys.modules[mod]
+
+        start = time.perf_counter()
+        import windkit  # noqa: F401
+        elapsed = time.perf_counter() - start
+
+        assert elapsed < IMPORT_TIME_THRESHOLD, (
+            f"Import time {elapsed:.3f}s exceeds threshold {IMPORT_TIME_THRESHOLD}s"
+        )
+
+    def test_lazy_imports_not_loaded(self):
+        """Verify heavy optional dependencies are not loaded on import."""
+        modules_to_remove = [k for k in sys.modules if k.startswith('windkit')]
+        for mod in modules_to_remove:
+            del sys.modules[mod]
+
+        import windkit  # noqa: F401
+
+        # These should NOT be loaded on import
+        lazy_modules = [
+            'matplotlib',
+            'numba',
+            'scipy.stats',
+            'pystac_client',
+            'pydantic_settings',
+        ]
+
+        for mod in lazy_modules:
+            assert mod not in sys.modules, (
+                f"Module '{mod}' should not be loaded on 'import windkit'"
+            )
+
+
+@pytest.mark.slow
+class TestFunctionBenchmarks:
+    """Benchmark tests for critical functions."""
+
+    def test_create_bwc_performance(self, benchmark_output_locs):
+        """Benchmark create_bwc function."""
+        import windkit as wk
+
+        start = time.perf_counter()
+        wk.create_bwc(benchmark_output_locs, n_sectors=12, n_wsbins=30)
+        elapsed = time.perf_counter() - start
+
+        # Log timing for tracking
+        print(f"create_bwc: {elapsed:.4f}s")
+
+        # Threshold TBD based on baseline measurements
+        assert elapsed < 5.0, f"create_bwc took {elapsed:.3f}s, exceeds threshold"
+
+    def test_spatial_operations_performance(self, benchmark_dataset):
+        """Benchmark spatial operations."""
+        import windkit as wk
+
+        start = time.perf_counter()
+        wk.spatial.to_point(benchmark_dataset)
+        elapsed = time.perf_counter() - start
+
+        print(f"to_point: {elapsed:.4f}s")
+        assert elapsed < 1.0, f"to_point took {elapsed:.3f}s, exceeds threshold"
+```
+
+### 2. Benchmark Fixtures
+
+**File: `test/fixtures/fixture_benchmarks.py`**
+
+```python
+"""Fixtures for performance benchmarks."""
+
+import pytest
+import numpy as np
+
+
+@pytest.fixture(scope="module")
+def benchmark_output_locs():
+    """Create a standard dataset for benchmarking."""
+    import windkit as wk
+
+    return wk.spatial.create_point(
+        x=[0, 1, 2],
+        y=[0, 1, 2],
+        z=[10, 20, 30],
+        crs=4326
+    )
+
+
+@pytest.fixture(scope="module")
+def benchmark_dataset():
+    """Create a larger dataset for spatial benchmarks."""
+    import windkit as wk
+
+    # Create a 100x100 grid for meaningful benchmarks
+    x = np.linspace(0, 100, 50)
+    y = np.linspace(0, 100, 50)
+
+    return wk.spatial.create_raster(
+        x=x,
+        y=y,
+        crs=32632
+    )
+```
+
+### 3. pytest-benchmark Integration (Optional Enhancement)
+
+**Add to `pixi.toml` feature.dev.dependencies:**
+
+```toml
+[feature.dev.dependencies]
+pytest-benchmark = "*"
+```
+
+**Enhanced benchmark test using pytest-benchmark:**
+
+```python
+def test_import_time_benchmark(benchmark):
+    """Benchmark import time with pytest-benchmark."""
+    def import_windkit():
+        modules = [k for k in sys.modules if k.startswith('windkit')]
+        for mod in modules:
+            del sys.modules[mod]
+        import windkit
+        return windkit
+
+    result = benchmark(import_windkit)
+    assert result is not None
+```
+
+### 4. CI Job Configuration
+
+**Add to `.gitlab-ci.yml`:**
+
+```yaml
+# Performance regression tests
+performance_tests:
+  extends:
+    - .pixi_pytest
+  stage: test
+  before_script:
+    - mkdir -p ~/.config/windkit/
+    - cp .conda_env/windkit.ini ~/.config/windkit/windkit.ini
+  variables:
+    PIXI_ENV: "default"
+  script:
+    - pixi run -e $PIXI_ENV test-performance
+  artifacts:
+    when: always
+    paths:
+      - performance_results/
+    reports:
+      junit: performance_junit.xml
+    expire_in: 1 month
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  allow_failure: false  # Fail the pipeline on performance regression
+```
+
+### 5. Pixi Task Configuration
+
+**Add to `pixi.toml`:**
+
+```toml
+[feature.dev.tasks]
+# ... existing tasks ...
+
+# Performance tests
+test-performance = {cmd="cd test; pytest test_performance.py -v --tb=short --junitxml=../performance_junit.xml", depends-on = ["install_tests"]}
+
+# Performance tests with benchmarks (if pytest-benchmark is added)
+test-benchmark = {cmd="cd test; pytest test_performance.py -v --benchmark-only --benchmark-json=../performance_results/benchmark.json", depends-on = ["install_tests"]}
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Basic Import Time Testing (Minimal)
+- [ ] Create `test/test_performance.py` with import time tests
+- [ ] Add `performance` marker to `pyproject.toml`
+- [ ] Add `test-performance` task to `pixi.toml`
+- [ ] Verify tests pass locally
+
+### Phase 2: CI Integration
+- [ ] Add `performance_tests` job to `.gitlab-ci.yml`
+- [ ] Configure artifacts for performance results
+- [ ] Test in MR pipeline
+
+### Phase 3: Function Benchmarks (Optional)
+- [ ] Add `pytest-benchmark` dependency
+- [ ] Create benchmark fixtures
+- [ ] Add benchmark tests for critical functions
+- [ ] Store benchmark history for trend analysis
+
+### Phase 4: Advanced Monitoring (Future)
+- [ ] Memory profiling with `pytest-memray` or `memory_profiler`
+- [ ] Benchmark comparison against main branch
+- [ ] Performance dashboard/visualization
+- [ ] Slack/email alerts on regression
+
+---
+
+## Thresholds and Metrics
+
+| Metric | Threshold | Warning | Action on Failure |
+|--------|-----------|---------|-------------------|
+| Import time | < 1.0s | < 0.8s | Block merge |
+| Lazy modules loaded | 0 | - | Block merge |
+| create_bwc | < 5.0s | < 3.0s | Warning |
+| Spatial operations | < 1.0s | < 0.5s | Warning |
+
+---
+
+## File Changes Summary
+
+| File | Change |
+|------|--------|
+| `test/test_performance.py` | New file - performance tests |
+| `test/fixtures/fixture_benchmarks.py` | New file - benchmark fixtures |
+| `test/conftest.py` | Import benchmark fixtures |
+| `pixi.toml` | Add test-performance task |
+| `.gitlab-ci.yml` | Add performance_tests job |
+| `pyproject.toml` | Add performance marker |
+
+---
+
+## Questions to Consider
+
+1. **Should performance tests run on every MR or only on main?**
+   - Recommendation: Run on every MR to catch regressions before merge
+
+2. **Should we use pytest-benchmark for detailed tracking?**
+   - Recommendation: Start simple, add later if needed
+
+3. **What functions should be benchmarked?**
+   - Import time (critical)
+   - create_bwc, create_tswc (commonly used)
+   - Spatial transformations (performance-sensitive)
+   - File I/O operations (user-facing)
+
+4. **How to handle flaky timing tests?**
+   - Use generous thresholds (2x expected time)
+   - Run multiple iterations and take median
+   - Mark as `allow_failure` initially, tighten later
+
+---
+
+## Next Steps
+
+1. Review and approve this plan
+2. Implement Phase 1 (basic import time testing)
+3. Test locally and in CI
+4. Iterate based on results