API Reference

API Reference#

Cutout#

class atlite.Cutout(path, **cutoutparams)#

Cutout base class.

This class builds the starting point for most atlite functionalities.

area(crs=None)#

Get the area per grid cell as a DataArray with coords (x,y).

Parameters:: crs (int, optional) – The coordinate reference system (CRS) to use for the calculation. Defaults to the crs of the cutout.
Returns:: A DataArray containing the area per grid cell with coordinates (x,y).
Return type:: xr.DataArray

availabilitymatrix(shapes, excluder, nprocesses=None, disable_progressbar=True)#

Compute the eligible share within cutout cells in the overlap with shapes.

For parallel calculation (nprocesses not None) the excluder must not be initialized and all raster references must be strings. Otherwise processes are colliding when reading from one common rasterio.DatasetReader.

Parameters:

cutout (atlite.Cutout) – Cutout which the availability matrix is aligned to.
shapes (geopandas.Series/geopandas.DataFrame) – Geometries for which the availabilities are calculated.
excluder (atlite.gis.ExclusionContainer) – Container of all meta data or objects which to exclude, i.e. rasters and geometries.
nprocesses (int, optional) – Number of processes to use for calculating the matrix. The paralle- lization can heavily boost the calculation speed. The default is None.
disable_progressbar (bool, optional) – Disable the progressbar if nprocesses is not None. Then the map function instead of the imap function is used for the multiprocessing pool. This speeds up the calculation.

Returns:

availabilities – DataArray of shape (|shapes|, |y|, |x|) containing all the eligible share of cutout cell (x,y) in the overlap with shape i.

Return type:

xr.DataArray

Notes

The rasterio (or GDAL) average downsampling returns different results dependent on how the target raster (the cutout raster) is spanned. Either it is spanned from the top left going downwards, e.g. Affine(0.25, 0, 0, 0, -0.25, 50), or starting in the lower left corner and going up, e.g. Affine(0.25, 0, 0, 0, 0.25, 50). Here we stick to the top down version which is why we use cutout.transform_r and flipping the y-axis in the end.

property available_features#: List of available weather data features for the cutout.

property bounds#: Total bounds of the area covered by the cutout (x, y, X, Y).

property chunks#: Chunking of the cutout data used by dask.

coefficient_of_performance(source='air', sink_T=55.0, c0=None, c1=None, c2=None, **params)#

Convert ambient or soil temperature to coefficient of performance (COP) of air- or ground-sourced heat pumps. The COP is a function of temperature difference from source to sink. The defaults for either source (c0, c1, c2) are based on a quadratic regression in [1].

Paramterers#

sourcestr: The heat source. Can be ‘air’ or ‘soil’.
sink_Tfloat: The temperature of the heat sink.
c0float: The constant regression coefficient for the temperature difference.
c1float: The linear regression coefficient for the temperature difference.
c2float: The quadratic regression coefficient for the temperature difference.

Reference#

[1] Staffell, Brett, Brandon, Hawkes, A review of domestic heat pumps, Energy & Environmental Science (2012), 5, 9291-9306, https://doi.org/10.1039/C2EE22653G.

convert_and_aggregate(convert_func, matrix=None, index=None, layout=None, shapes=None, shapes_crs=4326, per_unit=False, return_capacity=False, capacity_factor=False, capacity_factor_timeseries=False, show_progress=False, dask_kwargs={}, **convert_kwds)#

Convert and aggregate a weather-based renewable generation time-series.

NOTE: Not meant to be used by the user him or herself. Rather it is a gateway function that is called by all the individual time-series generation functions like pv and wind. Thus, all its parameters are also available from these.

Parameters:

matrix (N x S - xr.DataArray or sp.sparse.csr_matrix or None) – If given, it is used to aggregate the grid cells to buses. N is the number of buses, S the number of spatial coordinates, in the order of cutout.grid.
index (pd.Index) – Index of Buses.
layout (X x Y - xr.DataArray) – The capacity to be build in each of the grid_cells.
shapes (list or pd.Series of shapely.geometry.Polygon) – If given, matrix is constructed as indicatormatrix of the polygons, its index determines the bus index on the time-series.
shapes_crs (pyproj.CRS or compatible) – If different to the map crs of the cutout, the shapes are transformed to match cutout.crs (defaults to EPSG:4326).
per_unit (boolean) – Returns the time-series in per-unit units, instead of in MW (defaults to False).
return_capacity (boolean) – Additionally returns the installed capacity at each bus corresponding to layout (defaults to False).
capacity_factor (boolean) – If True, the static capacity factor of the chosen resource for each grid cell is computed.
capacity_factor_timeseries (boolean) – If True, the capacity factor time series of the chosen resource for each grid cell is computed.
show_progress (boolean, default False) – Whether to show a progress bar.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
convert_func (Function) – Callback like convert_wind, convert_pv

Returns:

resource (xr.DataArray) – Time-series of renewable generation aggregated to buses, if matrix or equivalents are provided else the total sum of generated energy.
units (xr.DataArray (optional)) – The installed units per bus in MW corresponding to layout (only if return_capacity is True).

cooling_demand(threshold=23.0, a=1.0, constant=0.0, hour_shift=0.0, **params)#

Convert outside temperature into daily cooling demand using the degree-day approximation.

Since “daily average temperature” means different things in different time zones and since xarray coordinates do not handle time zones gracefully like pd.DateTimeIndex, you can provide an hour_shift to redefine when the day starts.

E.g. for Moscow in summer, hour_shift = 3, for New York in summer, hour_shift = -4

This time shift applies across the entire spatial scope of ds for all times. More fine-grained control will be built in a some point, i.e. space- and time-dependent time zones.

WARNING: Because the original data is provided every month, at the month boundaries there is untidiness if you use a time shift. The resulting xarray will have duplicates in the index for the parts of the day in each month at the boundary. You will have to re-average these based on the number of hours in each month for the duplicated day.

Parameters:

threshold (float) – Outside temperature in degrees Celsius below which there is no cooling demand. The default 23C is taken as a more liberal estimation following European computational practices (e.g. UK Met Office and European commission take as thresholds 22C and 24C, respectively)
a (float) – Linear factor relating cooling demand to outside temperature.
constant (float) – Constant part of cooling demand that does not depend on outside temperature (e.g. due to ventilation).
hour_shift (float) – Time shift relative to UTC for taking daily average

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

property coords#: Geographic coordinates of the cutout.

property crs#: Coordinate Reference System of the cutout.

csp(installation, technology=None, **params)#

Convert downward shortwave direct radiation into a csp generation time- series.

Parameters:

installation (str or xr.DataArray) – CSP installation details determining the solar field efficiency dependent on the local solar position. Can be either the name of one of the standard installations provided through atlite.cspinstallationsPanel or an xarray.DataArray with ‘azimuth’ (in rad) and ‘altitude’ (in rad) coordinates and an ‘efficiency’ (in p.u.) entry.
technology (str) – Overwrite CSP technology from the installation configuration. The technology affects which direct radiation is considered. Either ‘parabolic trough’ (DHI) or ‘solar tower’ (DNI).

Returns:

csp – Time-series or capacity factors based on additional general conversion arguments.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] Tobias Hirsch (ed.). SolarPACES Guideline for Bankable STE Yield Assessment, IEA Technology Collaboration Programme SolarPACES, 2017. URL: https://www.solarpaces.org/csp-research-tasks/task-annexes-iea/task-i-solar-thermal-electric-systems/solarpaces-guideline-for-bankable-ste-yield-assessment/

[2] Tobias Hirsch (ed.). CSPBankability Project Report, DLR, 2017. URL: https://www.dlr.de/sf/en/desktopdefault.aspx/tabid-11126/19467_read-48251/

property dt#: Time resolution of the cutout.

property dx#: Spatial resolution on the x coordinates.

property dy#: Spatial resolution on the y coordinates.

equals(other)#: It overrides xarray.Dataset.equals and ignores the path attribute in the comparison

property extent#: Total extent of the area covered by the cutout (x, X, y, Y).

grid#

Cutout grid with coordinates and geometries.

The coordinates represent the centers of the grid cells.

Returns:: Frame with coordinate columns ‘x’ and ‘y’, and geometries of the corresponding grid cells.
Return type:: geopandas.GeoDataFrame

heat_demand(threshold=15.0, a=1.0, constant=0.0, hour_shift=0.0, **params)#

Convert outside temperature into daily heat demand using the degree-day approximation.

E.g. for Moscow in winter, hour_shift = 4, for New York in winter, hour_shift = -5

This time shift applies across the entire spatial scope of ds for all times. More fine-grained control will be built in a some point, i.e. space- and time-dependent time zones.

Parameters:

threshold (float) – Outside temperature in degrees Celsius above which there is no heat demand.
a (float) – Linear factor relating heat demand to outside temperature.
constant (float) – Constant part of heat demand that does not depend on outside temperature (e.g. due to water heating).
hour_shift (float) – Time shift relative to UTC for taking daily average

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

hydro(plants, hydrobasins, flowspeed=1, weight_with_height=False, show_progress=False, **kwargs)#

Compute inflow time-series for plants by aggregating over catchment basins from hydrobasins

Parameters:

plants (pd.DataFrame) – Run-of-river plants or dams with lon, lat columns.
hydrobasins (str|gpd.GeoDataFrame) – Filename or GeoDataFrame of one level of the HydroBASINS dataset.
flowspeed (float) – Average speed of water flows to estimate the water travel time from basin to plant (default: 1 m/s).
weight_with_height (bool) – Whether surface runoff should be weighted by potential height (probably better for coarser resolution).
show_progress (bool) – Whether to display progressbars.

References

[1] Liu, Hailiang, et al. “A validated high-resolution hydro power time-series model for energy systems analysis.” arXiv preprint arXiv:1901.08476 (2019).

[2] Lehner, B., Grill G. (2013): Global river hydrography and network routing: baseline data and new approaches to study the world’s large river systems. Hydrological Processes, 27(15): 2171–2186. Data is available at www.hydrosheds.org.

indicatormatrix(shapes, shapes_crs=4326)#

Compute the indicatormatrix.

The indicatormatrix I[i,j] is a sparse representation of the ratio of the area in orig[j] lying in dest[i], where orig and dest are collections of polygons, i.e.

A value of I[i,j] = 1 indicates that the shape orig[j] is fully contained in shape dest[j].

Note that the polygons must be in the same crs.

Parameters:: shapes (Collection of shapely polygons)
Returns:: I – Indicatormatrix
Return type:: sp.sparse.lil_matrix

intersectionmatrix(shapes, shapes_crs=4326)#

Compute the intersectionmatrix.

The intersectionmatrix is a sparse matrix with entries (i,j) being one if shapes orig[j] and dest[i] are intersecting, and zero otherwise.

Note that the polygons must be in the same crs.

Parameters:

orig (Collection of shapely polygons)
dest (Collection of shapely polygons)

Returns:

I – Intersectionmatrix

Return type:

sp.sparse.lil_matrix

irradiation(orientation, irradiation='total', tracking=None, clearsky_model=None, **params)#

Calculate the total, direct, diffuse, or ground irradiation on a tilted surface.

Parameters:

orientation (str, dict or callback) – Panel orientation can be chosen from either ‘latitude_optimal’, a constant orientation {‘slope’: 0.0, ‘azimuth’: 0.0} or a callback function with the same signature as the callbacks generated by the ‘atlite.pv.orientation.make_*’ functions.
irradiation (str) – The irradiation quantity to be returned. Defaults to “total” for total combined irradiation. Other options include “direct” for direct irradiation, “diffuse” for diffuse irradation, and “ground” for irradiation reflected by the ground via albedo. NOTE: “ground” irradiation is not calculated by all trigon_model options in the convert_irradiation method, so use with caution!
tracking (None or str:) – None for no tracking, default ‘horizontal’ for 1-axis horizontal tracking ‘tilted_horizontal’ for 1-axis horizontal tracking with tilted axis ‘vertical’ for 1-axis vertical tracking ‘dual’ for 2-axis tracking
clearsky_model (str or None) – Either the ‘simple’ or the ‘enhanced’ Reindl clearsky model. The default choice of None will choose dependending on data availability, since the ‘enhanced’ model also incorporates ambient air temperature and relative humidity.

Returns:

irradiation – The desired irradiation quantity on the tilted surface. Defaults to “total”.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] D.T. Reindl, W.A. Beckman, and J.A. Duffie. Diffuse fraction correla- tions. Solar Energy, 45(1):1 – 7, 1990.

layout_from_capacity_list(data, col='Capacity')#

Get a capacity layout aligned to the cutout based on a capacity list.

Parameters:

data (pandas.DataFrame) – Capacity list with columns ‘x’, ‘y’ and col. Each capacity entry is added to the grid cell intersecting with the coordinate (x,y).
col (str, optional) – Name of the column with capacity values. The default is ‘Capacity’.

Returns:

Capacity layout with dimensions ‘x’ and ‘y’ indicating the total capacity placed within one grid cell.

Return type:

xr.DataArray

Example

>>> import atlite
>>> import powerplantmatching as pm

>>> data = pm.data.OPSD_VRE_country('DE')
>>> data = (data.query('Fueltype == "Solar"')
            .rename(columns={'lon':'x', 'lat':'y'}))

>>> cutout = atlite.Cutout('Germany', x = slice(-5, 15), y = slice(40, 55),
               time='2013-06-01', module='era5')
>>> cutout.prepare(features=['influx', 'temperature'])
>>> layout = cutout.layout_from_capacity_list(data)
>>> pv = cutout.pv('CdTe', 'latitude_optimal', layout=layout)
>>> pv.plot()

line_rating(shapes, line_resistance, show_progress=False, dask_kwargs={}, **params)#

Create a dynamic line rating time series based on the IEEE-738 standard.

[1].

The steady-state capacity is derived from the balance between heat losses due to radiation and convection, and heat gains due to solar influx and conductur resistance. For more information on assumptions and modifications see convert_line_rating.

[1]“IEEE Std 738™-2012 (Revision of IEEE Std 738-2006/Incorporates IEEE Std: 738-2012/Cor 1-2013), IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors,” p. 72.

Parameters:

cutout (atlite.Cutout)
shapes (geopandas.GeoSeries) – Line shapes of the lines.
line_resistance (float/series) – Resistance of the lines in Ohm/meter. Alternatively in p.u. system in Ohm/1000km (see example below).
show_progress (boolean, default False) – Whether to show a progress bar.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
params (keyword arguments as float/series) –
Arguments to tweak/modify the line rating calculations based on [1]. Defaults are:
- D : 0.028 (conductor diameter)
- Ts : 373 (maximally allowed surface temperature)
- epsilon : 0.6 (conductor emissivity)
- alpha : 0.6 (conductor absorptivity)

Return type:

Current thermal limit timeseries with dimensions time x lines in Ampere.

Example

>>> import pypsa
>>> import xarray as xr
>>> import atlite
>>> import numpy as np
>>> import geopandas as gpd
>>> from shapely.geometry import Point, LineString as Line

>>> n = pypsa.examples.scigrid_de()
>>> n.calculate_dependent_values()
>>> x = n.buses.x
>>> y = n.buses.y
>>> buses = n.lines[["bus0", "bus1"]].values
>>> shapes = [Line([Point(x[b0], y[b0]), Point(x[b1], y[b1])]) for (b0, b1) in buses]
>>> shapes = gpd.GeoSeries(shapes, index=n.lines.index)

>>> cutout = atlite.Cutout('test', x=slice(x.min(), x.max()), y=slice(y.min(), y.max()),
                        time='2020-01-01', module='era5', dx=1, dy=1)
>>> cutout.prepare()

>>> i = cutout.line_rating(shapes, n.lines.r/n.lines.length)
>>> v = xr.DataArray(n.lines.v_nom, dims='name')
>>> s = np.sqrt(3) * i * v / 1e3 # in MW

merge(other, path=None, **kwargs)#

Merge two cutouts into a single cutout.

Parameters:

other (atlite.Cutout) – Other cutout to merge.
path (str | path-like) – File where to store the merged cutout. Defaults to a temporary file.
**kwargs – Keyword arguments passed to xarray.merge().

Returns:

merged – Merged cutout.

Return type:

Cutout

property module#: Data module of the cutout.

property name#: Name of the cutout.

prepare(features=None, tmpdir=None, data_format='grib', overwrite=False, compression={'complevel': 9, 'shuffle': True, 'zlib': True}, show_progress=False, dask_kwargs=None, monthly_requests=False, concurrent_requests=False)#

Prepare all or a selection of features in a cutout.

This function loads the feature data of a cutout, e.g. influx or runoff. When not specifying the feature argument, all available features will be loaded. The function compares the variables which are already included in the cutout with the available variables of the modules specified by the cutout. It detects missing variables and stores them into the netcdf file of the cutout.

Parameters:

cutout (atlite.Cutout)
features (str/list, optional) – Feature(s) to be prepared. The default slice(None) results in all available features.
tmpdir (str/Path, optional) – Directory in which temporary files (for example retrieved ERA5 netcdf files) are stored. If set, the directory will not be deleted and the intermediate files can be examined.
data_format (str, optional) – The data format used to retrieve the data. Only relevant for ERA5 data. The default is ‘grib’.
overwrite (bool, optional) – Whether to overwrite variables which are already included in the cutout. The default is False.
compression (None/dict, optional) – Compression level to use for all features which are being prepared. The compression is handled via xarray.Dataset.to_netcdf(…), for details see: https://docs.xarray.dev/en/stable/generated/xarray.Dataset.to_netcdf.html . To efficiently reduce cutout sizes, specify the number of ‘least_significant_digits’: n here. To disable compression, set “complevel” to None. Default is {‘zlib’: True, ‘complevel’: 9, ‘shuffle’: True}.
show_progress (bool, optional) – If True, a progress bar is shown. The default is False.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
monthly_requests (bool, optional) – If True, the data is requested on a monthly basis in ERA5. This is useful for large cutouts, where the data is requested in smaller chunks. The default is False
concurrent_requests (bool, optional) – If True, the monthly data requests are posted concurrently. Only has an effect if monthly_requests is True. The default is False.

Returns:

cutout – Cutout with prepared data. The variables are stored in cutout.data.

Return type:

atlite.Cutout

property prepared#: Boolean indicating whether all available features are prepared.

property prepared_features#: Get the list of prepared features in the cutout.

pv(panel, orientation, tracking=None, clearsky_model=None, **params)#

Convert downward-shortwave, upward-shortwave radiation flux and ambient temperature into a pv generation time-series.

Parameters:

panel (str or dict) – Panel config dictionary with the parameters for the electrical model in [3]. Alternatively, name of yaml file stored in atlite.config.solarpanel_dir.
orientation (str, dict or callback) – Panel orientation can be chosen from either ‘latitude_optimal’, a constant orientation {‘slope’: 0.0, ‘azimuth’: 0.0} or a callback function with the same signature as the callbacks generated by the ‘atlite.pv.orientation.make_*’ functions.
tracking (None or str:) – None for no tracking, default ‘horizontal’ for 1-axis horizontal tracking ‘tilted_horizontal’ for 1-axis horizontal tracking with tilted axis ‘vertical’ for 1-axis vertical tracking ‘dual’ for 2-axis tracking
clearsky_model (str or None) – Either the ‘simple’ or the ‘enhanced’ Reindl clearsky model. The default choice of None will choose dependending on data availability, since the ‘enhanced’ model also incorporates ambient air temperature and relative humidity.

Returns:

pv – Time-series or capacity factors based on additional general conversion arguments.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] Soteris A. Kalogirou. Solar Energy Engineering: Processes and Systems, pages 49–117,469–516. Academic Press, 2009. ISBN 0123745012.

[2] D.T. Reindl, W.A. Beckman, and J.A. Duffie. Diffuse fraction correla- tions. Solar Energy, 45(1):1 – 7, 1990.

[3] Hans Georg Beyer, Gerd Heilscher and Stefan Bofinger. A Robust Model for the MPP Performance of Different Types of PV-Modules Applied for the Performance Check of Grid Connected Systems, Freiburg, June 2004. Eurosun (ISES Europe Solar Congress).

sel(path=None, bounds=None, buffer=0, **kwargs)#

Select parts of the cutout.

Parameters:

path (str | path-like) – File where to store the sub-cutout. Defaults to a temporary file.
bounds (GeoSeries.bounds | DataFrame, optional) – The outer bounds of the cutout or as a DataFrame containing (min.long, min.lat, max.long, max.lat).
buffer (float, optional) – Buffer around the bounds. The default is 0.
**kwargs – Passed to xr.Dataset.sel for data selection.

Returns:

selected – Selected cutout.

Return type:

Cutout

property shape#: Size of spatial dimensions (y, x) of the cutout data.

solar_thermal(orientation={'azimuth': 180.0, 'slope': 45.0}, trigon_model='simple', clearsky_model='simple', c0=0.8, c1=3.0, t_store=80.0, **params)#

Convert downward short-wave radiation flux and outside temperature into time series for solar thermal collectors.

Mathematical model and defaults for c0, c1 based on model in [1].

Parameters:

cutout (cutout)
orientation (dict or str or function) – Panel orientation with slope and azimuth (units of degrees), or ‘latitude_optimal’.
trigon_model (str) – Type of trigonometry model
clearsky_model (str or None) – Type of clearsky model for diffuse irradiation. Either ‘simple’ or ‘enhanced’.
c0 (float) – Parameters for model in [1] (defaults to 0.8 and 3., respectively)
c1 (float) – Parameters for model in [1] (defaults to 0.8 and 3., respectively)
t_store (float) – Store temperature in degree Celsius

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] Henning and Palzer, Renewable and Sustainable Energy Reviews 30 (2014) 1003-1018

to_file(fn=None)#

Save cutout to a NetCDF file.

Parameters:: fn (str | path-like) – File name where to store the cutout, defaults to cutout.path.

property transform#: Get the affine transform of the cutout.

property transform_r#: Get the affine transform of the cutout with reverse y-order.

uniform_density_layout(capacity_density, crs=None)#

Get a capacity layout from a uniform capacity density.

Parameters:

capacity_density (float) – Capacity density in capacity/projection unit squared.
crs (int, optional) – CRS to calculate the total area of grid cells. Passed to Cutout.area().

Returns:

Capacity layout with dimensions ‘x’ and ‘y’ indicating the total capacity placed within one grid cell.

Return type:

xr.DataArray

uniform_layout()#: Get a uniform capacity layout for all grid cells.

wind(turbine: str | Path | dict, smooth: bool | dict = False, add_cutout_windspeed: bool = False, interpolation_method: Literal['logarithmic', 'power'] = 'logarithmic', **params) → xr.DataArray#

Generate wind generation time-series.

Extrapolates wind speed to hub height (using logarithmic or power law) and evaluates the power curve.

Parameters:

turbine (str or dict) –
A turbineconfig dictionary with the keys ‘hub_height’ for the hub height and ‘V’, ‘POW’ defining the power curve. Alternatively a str refering to a local or remote turbine configuration as accepted by atlite.resource.get_windturbineconfig(). Locally stored turbine configurations can also be modified with this function. E.g. to setup a different hub height from the one used in the yaml file,one would write

”turbine=get_windturbineconfig(“NREL_ReferenceTurbine_5MW_offshore”)|{“hub_height”:120}”
smooth (bool or dict) – If True smooth power curve with a gaussian kernel as determined for the Danish wind fleet to Delta_v = 1.27 and sigma = 2.29. A dict allows to tune these values.
add_cutout_windspeed (bool) – If True and in case the power curve does not end with a zero, will add zero power output at the highest wind speed in the power curve. If False, a warning will be raised if the power curve does not have a cut-out wind speed. The default is False.
interpolation_method ({"logarithmic", "power"}) – Law to interpolate wind speed to turbine hub height. Refer to atlite.wind.extrapolate_wind_speed().

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

Data#

Management of data retrieval and structure.

atlite.data.available_features(module=None)#

Inspect the available features of all or a selection of modules.

Parameters:: module (str/list, optional) – Module name(s) which to inspect. The default None will result in all modules
Returns:: A Series of all variables. The MultiIndex indicated which module provides the variable and with which feature name the variable can be obtained.
Return type:: pd.Series

atlite.data.cutout_prepare(cutout, features=None, tmpdir=None, data_format='grib', overwrite=False, compression={'complevel': 9, 'shuffle': True, 'zlib': True}, show_progress=False, dask_kwargs=None, monthly_requests=False, concurrent_requests=False)#

Prepare all or a selection of features in a cutout.

Parameters:

cutout (atlite.Cutout)
features (str/list, optional) – Feature(s) to be prepared. The default slice(None) results in all available features.
tmpdir (str/Path, optional) – Directory in which temporary files (for example retrieved ERA5 netcdf files) are stored. If set, the directory will not be deleted and the intermediate files can be examined.
data_format (str, optional) – The data format used to retrieve the data. Only relevant for ERA5 data. The default is ‘grib’.
overwrite (bool, optional) – Whether to overwrite variables which are already included in the cutout. The default is False.
compression (None/dict, optional) – Compression level to use for all features which are being prepared. The compression is handled via xarray.Dataset.to_netcdf(…), for details see: https://docs.xarray.dev/en/stable/generated/xarray.Dataset.to_netcdf.html . To efficiently reduce cutout sizes, specify the number of ‘least_significant_digits’: n here. To disable compression, set “complevel” to None. Default is {‘zlib’: True, ‘complevel’: 9, ‘shuffle’: True}.
show_progress (bool, optional) – If True, a progress bar is shown. The default is False.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
monthly_requests (bool, optional) – If True, the data is requested on a monthly basis in ERA5. This is useful for large cutouts, where the data is requested in smaller chunks. The default is False
concurrent_requests (bool, optional) – If True, the monthly data requests are posted concurrently. Only has an effect if monthly_requests is True. The default is False.

Returns:

cutout – Cutout with prepared data. The variables are stored in cutout.data.

Return type:

atlite.Cutout

atlite.data.get_features(cutout, module, features, data_format, tmpdir=None, monthly_requests=False, concurrent_requests=False)#

Load the feature data for a given module.

This get the data for a set of features from a module. All modules in atlite.datasets are allowed.

atlite.data.maybe_remove_tmpdir(func)#: Use this wrapper to make tempfile deletion compatible with windows machines.

atlite.data.non_bool_dict(d)#: Convert bool to int for netCDF4 storing.

Convert#

All functions for converting weather data into energy system model data.

atlite.convert.coefficient_of_performance(cutout, source='air', sink_T=55.0, c0=None, c1=None, c2=None, **params)#

Paramterers#

sourcestr: The heat source. Can be ‘air’ or ‘soil’.
sink_Tfloat: The temperature of the heat sink.
c0float: The constant regression coefficient for the temperature difference.
c1float: The linear regression coefficient for the temperature difference.
c2float: The quadratic regression coefficient for the temperature difference.

Reference#

[1] Staffell, Brett, Brandon, Hawkes, A review of domestic heat pumps, Energy & Environmental Science (2012), 5, 9291-9306, https://doi.org/10.1039/C2EE22653G.

atlite.convert.convert_and_aggregate(cutout, convert_func, matrix=None, index=None, layout=None, shapes=None, shapes_crs=4326, per_unit=False, return_capacity=False, capacity_factor=False, capacity_factor_timeseries=False, show_progress=False, dask_kwargs={}, **convert_kwds)#

Convert and aggregate a weather-based renewable generation time-series.

Parameters:

matrix (N x S - xr.DataArray or sp.sparse.csr_matrix or None) – If given, it is used to aggregate the grid cells to buses. N is the number of buses, S the number of spatial coordinates, in the order of cutout.grid.
index (pd.Index) – Index of Buses.
layout (X x Y - xr.DataArray) – The capacity to be build in each of the grid_cells.
shapes (list or pd.Series of shapely.geometry.Polygon) – If given, matrix is constructed as indicatormatrix of the polygons, its index determines the bus index on the time-series.
shapes_crs (pyproj.CRS or compatible) – If different to the map crs of the cutout, the shapes are transformed to match cutout.crs (defaults to EPSG:4326).
per_unit (boolean) – Returns the time-series in per-unit units, instead of in MW (defaults to False).
return_capacity (boolean) – Additionally returns the installed capacity at each bus corresponding to layout (defaults to False).
capacity_factor (boolean) – If True, the static capacity factor of the chosen resource for each grid cell is computed.
capacity_factor_timeseries (boolean) – If True, the capacity factor time series of the chosen resource for each grid cell is computed.
show_progress (boolean, default False) – Whether to show a progress bar.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
convert_func (Function) – Callback like convert_wind, convert_pv

Returns:

resource (xr.DataArray) – Time-series of renewable generation aggregated to buses, if matrix or equivalents are provided else the total sum of generated energy.
units (xr.DataArray (optional)) – The installed units per bus in MW corresponding to layout (only if return_capacity is True).

atlite.convert.convert_dewpoint_temperature(ds)#: Return dewpoint temperature.

atlite.convert.convert_line_rating(ds, psi, R, D=0.028, Ts=373, epsilon=0.6, alpha=0.6, per_unit=False)#

Convert the cutout data to dynamic line rating time series.

The formulation is based on:

[1]“IEEE Std 738™-2012 (Revision of IEEE Std 738-2006/Incorporates IEEE Std

738-2012/Cor 1-2013), IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors,” p. 72.

The following simplifications/assumptions were made:

Wind speed are taken at height 100 meters above ground. However, ironmen and transmission lines are typically at 50-60 meters.
Solar heat influx is set proportionally to solar short wave influx.
The incidence angle of the solar heat influx is assumed to be 90 degree.

Parameters:

ds (xr.Dataset) – Subset of the cutout data including all weather cells overlapping with the line.
psi (int/float) – Azimuth angle of the line in degree, that is the incidence angle of the line with a pointer directing north (90 is east, 180 is south, 270 is west).
R (float) – Resistance of the conductor in [Ω/m] at maximally allowed temperature Ts.
D (float,) – Conductor diameter.
Ts (float) – Maximally allowed surface temperature (typically 100°C).
epsilon (float) – Conductor emissivity.
alpha (float) – Conductor absorptivity.

Returns:

xr.DataArray giving the maximal current capacity per timestep in Ampere.

Return type:

Imax

atlite.convert.convert_soil_temperature(ds)#: Return soil temperature (useful for e.g. heat pump T-dependent coefficient of performance).

atlite.convert.convert_temperature(ds)#: Return outside temperature (useful for e.g. heat pump T-dependent coefficient of performance).

atlite.convert.convert_wind(ds: xr.Dataset, turbine: TurbineConfig, interpolation_method: Literal['logarithmic', 'power']) → xr.DataArray#: Convert wind speeds for turbine to wind energy generation.

atlite.convert.cooling_demand(cutout, threshold=23.0, a=1.0, constant=0.0, hour_shift=0.0, **params)#

Convert outside temperature into daily cooling demand using the degree-day approximation.

E.g. for Moscow in summer, hour_shift = 3, for New York in summer, hour_shift = -4

This time shift applies across the entire spatial scope of ds for all times. More fine-grained control will be built in a some point, i.e. space- and time-dependent time zones.

Parameters:

threshold (float) – Outside temperature in degrees Celsius below which there is no cooling demand. The default 23C is taken as a more liberal estimation following European computational practices (e.g. UK Met Office and European commission take as thresholds 22C and 24C, respectively)
a (float) – Linear factor relating cooling demand to outside temperature.
constant (float) – Constant part of cooling demand that does not depend on outside temperature (e.g. due to ventilation).
hour_shift (float) – Time shift relative to UTC for taking daily average

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

atlite.convert.csp(cutout, installation, technology=None, **params)#

Convert downward shortwave direct radiation into a csp generation time- series.

Parameters:

installation (str or xr.DataArray) – CSP installation details determining the solar field efficiency dependent on the local solar position. Can be either the name of one of the standard installations provided through atlite.cspinstallationsPanel or an xarray.DataArray with ‘azimuth’ (in rad) and ‘altitude’ (in rad) coordinates and an ‘efficiency’ (in p.u.) entry.
technology (str) – Overwrite CSP technology from the installation configuration. The technology affects which direct radiation is considered. Either ‘parabolic trough’ (DHI) or ‘solar tower’ (DNI).

Returns:

csp – Time-series or capacity factors based on additional general conversion arguments.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[2] Tobias Hirsch (ed.). CSPBankability Project Report, DLR, 2017. URL: https://www.dlr.de/sf/en/desktopdefault.aspx/tabid-11126/19467_read-48251/

atlite.convert.heat_demand(cutout, threshold=15.0, a=1.0, constant=0.0, hour_shift=0.0, **params)#

Convert outside temperature into daily heat demand using the degree-day approximation.

E.g. for Moscow in winter, hour_shift = 4, for New York in winter, hour_shift = -5

This time shift applies across the entire spatial scope of ds for all times. More fine-grained control will be built in a some point, i.e. space- and time-dependent time zones.

Parameters:

threshold (float) – Outside temperature in degrees Celsius above which there is no heat demand.
a (float) – Linear factor relating heat demand to outside temperature.
constant (float) – Constant part of heat demand that does not depend on outside temperature (e.g. due to water heating).
hour_shift (float) – Time shift relative to UTC for taking daily average

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

atlite.convert.hydro(cutout, plants, hydrobasins, flowspeed=1, weight_with_height=False, show_progress=False, **kwargs)#

Compute inflow time-series for plants by aggregating over catchment basins from hydrobasins

Parameters:

plants (pd.DataFrame) – Run-of-river plants or dams with lon, lat columns.
hydrobasins (str|gpd.GeoDataFrame) – Filename or GeoDataFrame of one level of the HydroBASINS dataset.
flowspeed (float) – Average speed of water flows to estimate the water travel time from basin to plant (default: 1 m/s).
weight_with_height (bool) – Whether surface runoff should be weighted by potential height (probably better for coarser resolution).
show_progress (bool) – Whether to display progressbars.

References

[1] Liu, Hailiang, et al. “A validated high-resolution hydro power time-series model for energy systems analysis.” arXiv preprint arXiv:1901.08476 (2019).

atlite.convert.irradiation(cutout, orientation, irradiation='total', tracking=None, clearsky_model=None, **params)#

Calculate the total, direct, diffuse, or ground irradiation on a tilted surface.

Parameters:

orientation (str, dict or callback) – Panel orientation can be chosen from either ‘latitude_optimal’, a constant orientation {‘slope’: 0.0, ‘azimuth’: 0.0} or a callback function with the same signature as the callbacks generated by the ‘atlite.pv.orientation.make_*’ functions.
irradiation (str) – The irradiation quantity to be returned. Defaults to “total” for total combined irradiation. Other options include “direct” for direct irradiation, “diffuse” for diffuse irradation, and “ground” for irradiation reflected by the ground via albedo. NOTE: “ground” irradiation is not calculated by all trigon_model options in the convert_irradiation method, so use with caution!
tracking (None or str:) – None for no tracking, default ‘horizontal’ for 1-axis horizontal tracking ‘tilted_horizontal’ for 1-axis horizontal tracking with tilted axis ‘vertical’ for 1-axis vertical tracking ‘dual’ for 2-axis tracking
clearsky_model (str or None) – Either the ‘simple’ or the ‘enhanced’ Reindl clearsky model. The default choice of None will choose dependending on data availability, since the ‘enhanced’ model also incorporates ambient air temperature and relative humidity.

Returns:

irradiation – The desired irradiation quantity on the tilted surface. Defaults to “total”.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] D.T. Reindl, W.A. Beckman, and J.A. Duffie. Diffuse fraction correla- tions. Solar Energy, 45(1):1 – 7, 1990.

atlite.convert.line_rating(cutout, shapes, line_resistance, show_progress=False, dask_kwargs={}, **params)#

Create a dynamic line rating time series based on the IEEE-738 standard.

[1].

[1]“IEEE Std 738™-2012 (Revision of IEEE Std 738-2006/Incorporates IEEE Std: 738-2012/Cor 1-2013), IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors,” p. 72.

Parameters:

cutout (atlite.Cutout)
shapes (geopandas.GeoSeries) – Line shapes of the lines.
line_resistance (float/series) – Resistance of the lines in Ohm/meter. Alternatively in p.u. system in Ohm/1000km (see example below).
show_progress (boolean, default False) – Whether to show a progress bar.
dask_kwargs (dict, default {}) – Dict with keyword arguments passed to dask.compute.
params (keyword arguments as float/series) –
Arguments to tweak/modify the line rating calculations based on [1]. Defaults are:
- D : 0.028 (conductor diameter)
- Ts : 373 (maximally allowed surface temperature)
- epsilon : 0.6 (conductor emissivity)
- alpha : 0.6 (conductor absorptivity)

Return type:

Current thermal limit timeseries with dimensions time x lines in Ampere.

Example

>>> import pypsa
>>> import xarray as xr
>>> import atlite
>>> import numpy as np
>>> import geopandas as gpd
>>> from shapely.geometry import Point, LineString as Line

>>> n = pypsa.examples.scigrid_de()
>>> n.calculate_dependent_values()
>>> x = n.buses.x
>>> y = n.buses.y
>>> buses = n.lines[["bus0", "bus1"]].values
>>> shapes = [Line([Point(x[b0], y[b0]), Point(x[b1], y[b1])]) for (b0, b1) in buses]
>>> shapes = gpd.GeoSeries(shapes, index=n.lines.index)

>>> cutout = atlite.Cutout('test', x=slice(x.min(), x.max()), y=slice(y.min(), y.max()),
                        time='2020-01-01', module='era5', dx=1, dy=1)
>>> cutout.prepare()

>>> i = cutout.line_rating(shapes, n.lines.r/n.lines.length)
>>> v = xr.DataArray(n.lines.v_nom, dims='name')
>>> s = np.sqrt(3) * i * v / 1e3 # in MW

atlite.convert.maybe_progressbar(ds, show_progress, **kwargs)#: Load a xr.dataset with dask arrays either with or without progressbar.

atlite.convert.pv(cutout, panel, orientation, tracking=None, clearsky_model=None, **params)#

Convert downward-shortwave, upward-shortwave radiation flux and ambient temperature into a pv generation time-series.

Parameters:

panel (str or dict) – Panel config dictionary with the parameters for the electrical model in [3]. Alternatively, name of yaml file stored in atlite.config.solarpanel_dir.
orientation (str, dict or callback) – Panel orientation can be chosen from either ‘latitude_optimal’, a constant orientation {‘slope’: 0.0, ‘azimuth’: 0.0} or a callback function with the same signature as the callbacks generated by the ‘atlite.pv.orientation.make_*’ functions.
tracking (None or str:) – None for no tracking, default ‘horizontal’ for 1-axis horizontal tracking ‘tilted_horizontal’ for 1-axis horizontal tracking with tilted axis ‘vertical’ for 1-axis vertical tracking ‘dual’ for 2-axis tracking
clearsky_model (str or None) – Either the ‘simple’ or the ‘enhanced’ Reindl clearsky model. The default choice of None will choose dependending on data availability, since the ‘enhanced’ model also incorporates ambient air temperature and relative humidity.

Returns:

pv – Time-series or capacity factors based on additional general conversion arguments.

Return type:

xr.DataArray

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] Soteris A. Kalogirou. Solar Energy Engineering: Processes and Systems, pages 49–117,469–516. Academic Press, 2009. ISBN 0123745012.

[2] D.T. Reindl, W.A. Beckman, and J.A. Duffie. Diffuse fraction correla- tions. Solar Energy, 45(1):1 – 7, 1990.

atlite.convert.solar_thermal(cutout, orientation={'azimuth': 180.0, 'slope': 45.0}, trigon_model='simple', clearsky_model='simple', c0=0.8, c1=3.0, t_store=80.0, **params)#

Convert downward short-wave radiation flux and outside temperature into time series for solar thermal collectors.

Mathematical model and defaults for c0, c1 based on model in [1].

Parameters:

cutout (cutout)
orientation (dict or str or function) – Panel orientation with slope and azimuth (units of degrees), or ‘latitude_optimal’.
trigon_model (str) – Type of trigonometry model
clearsky_model (str or None) – Type of clearsky model for diffuse irradiation. Either ‘simple’ or ‘enhanced’.
c0 (float) – Parameters for model in [1] (defaults to 0.8 and 3., respectively)
c1 (float) – Parameters for model in [1] (defaults to 0.8 and 3., respectively)
t_store (float) – Store temperature in degree Celsius

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

[1] Henning and Palzer, Renewable and Sustainable Energy Reviews 30 (2014) 1003-1018

atlite.convert.wind(cutout, turbine: str | Path | dict, smooth: bool | dict = False, add_cutout_windspeed: bool = False, interpolation_method: Literal['logarithmic', 'power'] = 'logarithmic', **params) → xr.DataArray#

Generate wind generation time-series.

Extrapolates wind speed to hub height (using logarithmic or power law) and evaluates the power curve.

Parameters:

turbine (str or dict) –
A turbineconfig dictionary with the keys ‘hub_height’ for the hub height and ‘V’, ‘POW’ defining the power curve. Alternatively a str refering to a local or remote turbine configuration as accepted by atlite.resource.get_windturbineconfig(). Locally stored turbine configurations can also be modified with this function. E.g. to setup a different hub height from the one used in the yaml file,one would write

”turbine=get_windturbineconfig(“NREL_ReferenceTurbine_5MW_offshore”)|{“hub_height”:120}”
smooth (bool or dict) – If True smooth power curve with a gaussian kernel as determined for the Danish wind fleet to Delta_v = 1.27 and sigma = 2.29. A dict allows to tune these values.
add_cutout_windspeed (bool) – If True and in case the power curve does not end with a zero, will add zero power output at the highest wind speed in the power curve. If False, a warning will be raised if the power curve does not have a cut-out wind speed. The default is False.
interpolation_method ({"logarithmic", "power"}) – Law to interpolate wind speed to turbine hub height. Refer to atlite.wind.extrapolate_wind_speed().

Note

You can also specify all of the general conversion arguments documented in the convert_and_aggregate function.

References

Resource#

Module for providing access to external ressources, like windturbine or pv panel configurations.

atlite.resource.get_cspinstallationconfig(installation)#

Load the ‘installation’.yaml file from local disk to provide the system efficiencies.

Parameters:

installation (str or pathlib.Path) –

if str is provided the name of a preshipped CSP installation: from alite.resources.cspinstallation is expected.
if pathlib.Path is provided the configuration: is read from this local path instead

Returns:

config – Config with details on the CSP installation.

Return type:

dict

atlite.resource.get_oedb_windturbineconfig(search: int | str | None = None, **search_params) → TurbineConfig#

Download a windturbine configuration from the OEDB database.

Download the configuration of a windturbine model from the OEDB database into the local ‘windturbine_dir’. The OEDB database can be viewed here: https://openenergy-platform.org/dataedit/view/supply/wind_turbine_library (2019-07-22) Only one turbine configuration is downloaded at a time, if the search parameters yield an ambigious result, no data is downloaded.

Parameters:

search (int|str) – Smart search parameter, if int use as model id, if str look in name or turbine_type
**search_params (dict) – Recognized arguments are ‘id’, ‘name’, ‘turbine_type’ and ‘manufacturer’

Returns:

turbineconfig – The turbine configuration in the format from ‘atlite.ressource.get_turbineconf(name)’.

Return type:

dict

Example

>>> get_oedb_windturbineconfig(10)
{'V': ..., 'POW': ..., ...}

>>> get_oedb_windturbineconfig(name="E-53/800", manufacturer="Enercon")
{'V': ..., 'POW': ..., ...}

atlite.resource.get_solarpanelconfig(panel)#

Load the ‘panel’.yaml file from local disk and provide a solar panel dict.

Parameters:

panel (str or pathlib.Path) –

if str is provided the name of a preshipped panel: from alite.resources.solarpanel is expected.
if pathlib.Path is provided the configuration: is read from this local path instead

Returns:

config – Config with details on the solarpanel

Return type:

dict

atlite.resource.get_windturbineconfig(turbine: str | Path | dict, add_cutout_windspeed: bool = False) → TurbineConfig#

Load the wind ‘turbine’ configuration.

Parameters:

turbine (str or pathlib.Path or dict) –

if str:
The name of a preshipped turbine from alite.resources.windturbine . Alternatively, if a str starting with ‘oedb:<name>’ is passed the Open Energy Database is searched for a turbine with the matching ‘<name>’ and if found that turbine configuration is used. See atlite.resource.get_oedb_windturbineconfig(…)

if pathlib.Path is provided the configuration is read from this local
path instead

if dict:
a user provided config dict. Needs to have the keys “POW”, “V”, “P”, and “hub_height”. Values for “POW” and “V” need to be list or np.ndarray with equal length.
add_cutout_windspeed (bool) – If True and in case the power curve does not end with a zero, will add zero power output at the highest wind speed in the power curve. If False, a warning will be raised if the power curve does not have a cut-out wind speed.

Returns:

config – Config with details on the turbine

Return type:

dict

atlite.resource.windturbine_smooth(turbine, params=None)#

Smooth the powercurve in turbine with a gaussian kernel.

Parameters:

turbine (dict) – Turbine config with at least V and POW
params (dict) – Allows adjusting fleet availability eta, mean Delta_v and stdev sigma. Defaults to values from Andresen’s paper: 0.95, 1.27 and 2.29, respectively.

Returns:

turbine – Turbine config with a smoothed power curve

Return type:

dict

References

G. B. Andresen, A. A. Søndergaard, M. Greiner, Validation of Danish wind time series from a new global renewable energy atlas for energy system analysis, Energy 93, Part 1 (2015) 1074–1088.

Wind#

Functions for use in conjunction with wind data generation.

atlite.wind.extrapolate_wind_speed(ds: xr.Dataset, to_height: int | float, from_height: int | None = None, method: Literal['logarithmic', 'power'] = 'logarithmic') → xr.DataArray#

Extrapolate the wind speed from a given height above ground to another.

If ds already contains a key refering to wind speeds at the desired to_height, no conversion is done and the wind speeds are directly returned.

Extrapolation of the wind speed can either use the “logarithmic” law as described in [1]_ or the “power” law as described in [2]. See also discussion in GH issue: PyPSA/atlite#231 .

Parameters:

ds (xarray.Dataset) – Dataset containing the wind speed time-series at ‘from_height’ with key ‘wnd{height:d}m’ and the surface orography with key ‘roughness’ at the geographic locations of the wind speeds.
to_height (int|float) – Height (m) to which the wind speeds are extrapolated to.
from_height (int, optional) – Height (m) from which the wind speeds are interpolated to ‘to_height’. If not provided, the closest height to ‘to_height’ is selected.
method ({"logarithmic", "power"}) – Method to use for extra/interpolating wind speeds

Returns:

da – DataArray containing the extrapolated wind speeds. Name of the DataArray is ‘wnd{to_height:d}’.

Return type:

xarray.DataArray

Raises:

RuntimeError – If the cutout is missing the data for the chosen method

References

GIS#

Functions for Geographic Information System.

class atlite.gis.ExclusionContainer(crs=3035, res=100)#

Container for exclusion objects and meta data.

add_geometry(geometry, buffer=0, invert=False)#

Parameters:

geometry (str/path/geopandas.GeoDataFrame) – Path to geometries or geometries which to exclude.
buffer (float, optional) – Buffer around the excluded areas in units of ExclusionContainer.crs. The default is 0.
invert (bool, optional) – Whether to exclude (False) or include (True) the specified areas of the geometries. The default is False.

add_raster(raster, codes=None, buffer=0, invert=False, nodata=255, allow_no_overlap=False, crs=None)#

Parameters:

raster (str/rasterio.DatasetReader) – Raster or path to raster which to exclude.
codes (int/list/function, optional) – Codes in the raster which to exclude. Can be a callable function which takes the mask (np.array) as argument and performs a elementwise condition (must not change the shape). The function may not be an anonymous (lambda) function. The default is 1.
buffer (int, optional) – Buffer around the excluded areas in units of ExclusionContainer.crs. Use this to create a buffer around the excluded/included area. The default is 0.
invert (bool, optional) – Whether to exclude (False) or include (True) the specified areas of the raster. The default is False.
allow_no_overlap – Allow that a raster and a shape (for which the raster will be used as a mask) do not overlap. In this case an array with only nodata is returned.
crs (rasterio.CRS/EPSG) – CRS of the raster. Specify this if the raster has invalid crs.

property all_closed#: Check whether all files in the raster container are closed.

property all_open#: Check whether all files in the raster container are open.

compute_shape_availability(geometry, dst_transform=None, dst_crs=None, dst_shape=None)#

Compute the eligible area in one or more geometries and optionally reproject.

Parameters:

geometry (geopandas.Series) – Geometry of which the eligible area is computed. If the series contains more than one geometry, the eligble area of the combined geometries is computed.
dst_transform (rasterio.Affine) – Transform of the target raster. Define if the availability should be reprojected. Defaults to None.
dst_crs (rasterio.CRS/proj.CRS) – CRS of the target raster. Define if the availability should be reprojected. Defaults to None.
dst_shape (tuple) – Shape of the target raster. Define if the availability should be reprojected. Defaults to None.

Returns:

masked (np.array) – Mask whith eligible raster cells indicated by 1 and excluded cells by 0.
transform (rasterion.Affine) – Affine transform of the mask.

open_files()#: Open rasters and load geometries.

plot_shape_availability(geometry, ax=None, set_title=True, dst_transform=None, dst_crs=None, dst_shape=None, show_kwargs={}, plot_kwargs={})#

Plot the eligible area for one or more geometries and optionally reproject.

This function uses its own default values for rasterio.plot.show and geopandas.GeoSeries.plot. Therefore eligible land is drawn in green Note that this funtion will likely fail if another CRS than the one of the ExclusionContainer is used in the axis (e.g. cartopy projections).

Parameters:

geometry (geopandas.Series) – Geometry of which the eligible area is computed. If the series contains more than one geometry, the eligble area of the combined geometries is computed.
ax (matplotlib Axis, optional)
set_title (boolean, optional) – Whether to set the title with additional information on the share of eligible land.
dst_transform (rasterio.Affine) – Transform of the target raster. Define if the availability should be reprojected. Defaults to None.
dst_crs (rasterio.CRS/proj.CRS) – CRS of the target raster. Define if the availability should be reprojected. Defaults to None.
dst_shape (tuple) – Shape of the target raster. Define if the availability should be reprojected. Defaults to None.
show_kwargs (dict, optional) – Keyword arguments passed to rasterio.plot.show, by default {}
plot_kwargs (dict, optional) – Keyword arguments passed to geopandas.GeoSeries.plot, by default {}

Returns:

_description_

Return type:

_type_

atlite.gis.compute_availabilitymatrix(cutout, shapes, excluder, nprocesses=None, disable_progressbar=True)#

Compute the eligible share within cutout cells in the overlap with shapes.

Parameters:

cutout (atlite.Cutout) – Cutout which the availability matrix is aligned to.
shapes (geopandas.Series/geopandas.DataFrame) – Geometries for which the availabilities are calculated.
excluder (atlite.gis.ExclusionContainer) – Container of all meta data or objects which to exclude, i.e. rasters and geometries.
nprocesses (int, optional) – Number of processes to use for calculating the matrix. The paralle- lization can heavily boost the calculation speed. The default is None.
disable_progressbar (bool, optional) – Disable the progressbar if nprocesses is not None. Then the map function instead of the imap function is used for the multiprocessing pool. This speeds up the calculation.

Returns:

availabilities – DataArray of shape (|shapes|, |y|, |x|) containing all the eligible share of cutout cell (x,y) in the overlap with shape i.

Return type:

xr.DataArray

Notes

atlite.gis.compute_indicatormatrix(orig, dest, orig_crs=4326, dest_crs=4326)#

Compute the indicatormatrix.

The indicatormatrix I[i,j] is a sparse representation of the ratio of the area in orig[j] lying in dest[i], where orig and dest are collections of polygons, i.e.

A value of I[i,j] = 1 indicates that the shape orig[j] is fully contained in shape dest[j].

Note that the polygons must be in the same crs.

Parameters:

orig (Collection of shapely polygons)
dest (Collection of shapely polygons)

Returns:

I – Indicatormatrix

Return type:

sp.sparse.lil_matrix

atlite.gis.compute_intersectionmatrix(orig, dest, orig_crs=4326, dest_crs=4326)#

Compute the intersectionmatrix.

The intersectionmatrix is a sparse matrix with entries (i,j) being one if shapes orig[j] and dest[i] are intersecting, and zero otherwise.

Note that the polygons must be in the same crs.

Parameters:

orig (Collection of shapely polygons)
dest (Collection of shapely polygons)

Returns:

I – Intersectionmatrix

Return type:

sp.sparse.lil_matrix

atlite.gis.get_coords(x, y, time, dx=0.25, dy=0.25, dt='h', **kwargs)#

Create an cutout coordinate system on the basis of slices and step sizes.

Parameters:

x (slice) – Numerical slices with lower and upper bound of the x dimension.
y (slice) – Numerical slices with lower and upper bound of the y dimension.
time (slice) – Slice with strings with lower and upper bound of the time dimension.
dx (float, optional) – Step size of the x coordinate. The default is 0.25.
dy (float, optional) – Step size of the y coordinate. The default is 0.25.
dt (str, optional) – Frequency of the time coordinate. The default is ‘h’. Valid are all pandas offset aliases.

Returns:

ds – Dataset with x, y and time variables, representing the whole coordinate system.

Return type:

xarray.Dataset

atlite.gis.maybe_swap_spatial_dims(ds, namex='x', namey='y')#: Swap order of spatial dimensions according to atlite concention.

atlite.gis.pad_extent(src, src_transform, dst_transform, src_crs, dst_crs, **kwargs)#

Pad the extent of src by an equivalent of one cell of the target raster.

This ensures that the array is large enough to not be treated as nodata in all cells of the destination raster. If src.ndim > 2, the function expects the last two dimensions to be y,x. Additional keyword arguments are used in np.pad().

atlite.gis.padded_transform_and_shape(bounds, res)#: Get the (transform, shape) tuple of a raster with resolution res and bounds bounds.

atlite.gis.projected_mask(raster, geom, transform=None, shape=None, crs=None, allow_no_overlap=False, **kwargs)#: Load a mask and optionally project it to target resolution and shape.

atlite.gis.regrid(ds, dimx, dimy, **kwargs)#

Interpolate Dataset or DataArray ds to a new grid, using rasterio’s reproject facility.

Parameters:

ds (xr.Dataset|xr.DataArray) – N-dim data on a spatial grid
dimx (pd.Index) – New x-coordinates in destination crs. dimx.name MUST refer to x-coord of ds.
dimy (pd.Index) – New y-coordinates in destination crs. dimy.name MUST refer to y-coord of ds.
**kwargs – Arguments passed to rio.wrap.reproject; of note: - resampling is one of gis.Resampling.{average,cubic,bilinear,nearest} - src_crs, dst_crs define the different crs (default: EPSG 4326, ie latlong)

atlite.gis.reproject_shapes(shapes, crs1, crs2)#: Project a collection of shapes from one crs to another.

atlite.gis.shape_availability(geometry, excluder)#

Compute the eligible area in one or more geometries.

Parameters:

geometry (geopandas.Series) – Geometry of which the eligible area is computed. If the series contains more than one geometry, the eligble area of the combined geometries is computed.
excluder (atlite.gis.ExclusionContainer) – Container of all meta data or objects which to exclude, i.e. rasters and geometries.

Returns:

masked (np.array) – Mask whith eligible raster cells indicated by 1 and excluded cells by 0.
transform (rasterion.Affine) – Affine transform of the mask.

atlite.gis.shape_availability_reprojected(geometry, excluder, dst_transform, dst_crs, dst_shape)#

Compute and reproject the eligible area of one or more geometries.

The function executes shape_availability and reprojects the calculated mask onto a new raster defined by (dst_transform, dst_crs, dst_shape). Before reprojecting, the function pads the mask such all non-nodata data points are projected in full cells of the target raster. The ensures that all data within the mask are projected correclty (GDAL inherent ‘problem’).

more than one geometry, the eligble area of the combined geometries is computed.

excluderatlite.gis.ExclusionContainer: Container of all meta data or objects which to exclude, i.e. rasters and geometries.
dst_transformrasterio.Affine: Transform of the target raster.
dst_crsrasterio.CRS/proj.CRS: CRS of the target raster.
dst_shapetuple: Shape of the target raster.
maskednp.array: Average share of available area per grid cell. 0 indicates excluded, 1 is fully included.
transformrasterio.Affine: Affine transform of the mask.

atlite.gis.spdiag(v)#: Create a sparse diagonal matrix from a 1-dimensional array.

Utils#

General utility functions for internal use.

class atlite.utils.CachedAttribute(method, name=None, doc=None)#

Computes attribute value and caches it in the instance.

From the Python Cookbook (Denis Otkidach) This decorator allows you to create a property which can be computed once and accessed many times. Sort of like memoization.

class atlite.utils.arrowdict#: A subclass of dict, which allows you to get items in the dict using the attribute syntax!

atlite.utils.migrate_from_cutout_directory(old_cutout_dir, path)#: Convert an old style cutout directory to new style netcdf file.

API Reference

Contents

API Reference#

Cutout#

Paramterers#

Reference#

Data#

Convert#

Paramterers#

Reference#

Resource#

Wind#

GIS#

Utils#