internal modules

_corine

Module for querying CORINE land cover classes and calculating mean roughness.

This module provides functions to query CORINE land cover classes based on geographic coordinates and calculate the mean roughness of a specified area.

austaltools._corine.corine_file_help()
austaltools._corine.corine_file_load()
austaltools._corine.mean_roughness(source: str, xg: float, yg: float, h: float, fac=10.0) → float

returns the mean roughness of an area based on CORINE land cover classes from either source - web for eea web API or - austal for CORINE inventory from local austal installation

Parameters:

  • source (str) – source of CORINE land cover classes.

  • xg (float) – X-coordinate of the center point.

  • yg (float) – Y-coordinate of the center point.

  • h (float) – Radius of the area to calculate mean roughness.

  • fac (float, optional) – Factor to determine the density of sample points (default is 10).

Returns:

Mean roughness of the specified area.

Return type:

float

austaltools._corine.query_corine_class(lat: float, lon: float) → int

Queries the CORINE land cover class for a given latitude and longitude from the EEA web API.

Parameters:

  • lat (float) – Latitude of the location to query.

  • lon (float) – Longitude of the location to query.

Returns:

CORINE land cover class code for the specified location.

Return type:

int

austaltools._corine.roughness_austal(xg: float, yg: float, h: float, fac: int = None) → int

Looks up the CORINE land cover class for a given latitude and longitude in the corine data file distributed along with AUSTAL.

Parameters:

  • xg (float) – X-coordinate of the center point.

  • yg (float) – Y-coordinate of the center point.

  • h (float) – Radius of the area to sample points.

  • fac (float, optional) – Factor to determine the density of sample points (default is 10).

Returns:

CORINE land cover class code for the specified location.

Return type:

int

austaltools._corine.roughness_web(xg: float, yg: float, h: float, fac=10.0) → float

Calculates the mean roughness of an area based on CORINE land cover classes.

Parameters:

  • xg (float) – X-coordinate of the center point.

  • yg (float) – Y-coordinate of the center point.

  • h (float) – Radius of the area to calculate mean roughness.

  • fac (float, optional) – Factor to determine the density of sample points (default is 10).

Returns:

Mean roughness of the specified area.

Return type:

float

austaltools._corine.sample_points(xg: float, yg: float, h: float, fac: int = None) → list

Generates a list of sample points within a specified radius.

Parameters:

  • xg (float) – X-coordinate of the center point.

  • yg (float) – Y-coordinate of the center point.

  • h (float) – Radius of the area to sample points.

  • fac (float, optional) – Factor to determine the density of sample points (default is 10).

Returns:

List of tuples representing the sample points (x, y).

Return type:

list

austaltools._corine.LANDCOVER_CLASSES_Z0_CORINE

Dictionary mapping CORINE class codes [JCR07] to roughness lengths [TAL2002] (in meters).

austaltools._corine.LANDCOVER_CLASSES_Z0_LBM_DE

Dictionary mapping LBM-DE (Digitales Landbedeckungsmodell für Deutschland) class codes to roughness lengths [TAL2021] (in meters).

austaltools._corine.REST_API_URL

URL for the REST API endpoint to query CORINE land cover classes.

_datasets

_dispersion

This module provides funtions to determine the stability classes as used by atmospheric dispersion model by varius methods.

class austaltools._dispersion.StabiltyClass(bounds: list | tuple | None = None, centers: list | tuple | None = None, tabbed_is_inverse: bool = False, reverse_index: bool = True, names: list[str] | tuple[str] | None = None, austal: list[int] | tuple[int] | None = None)

Class that holds information about a set of stabilty classes.

Parameters:

  • bounds (list[tuple[list]]) – for each stability class, a 2-element list or tuple must be given. The first list must contain the z0 vlaues for the roughness lenght classes in ascending order, the second list must be of the same length and contain the boundary values of the Obukhov lenght separating the 1st and 2nd class, the 2nd and the 3rd, … . Mutually exclusive with centers.

  • centers (list[tuple[list]]) – for each stability class, a 2-element list or tuple must be given. The first list must contain the z0 vlaues for the roughness lenght classes in ascending order, the second list must be of the same length and contain the center values of the Obukhov lenght for 1st, 2nd, 3rd, … class Mutually exclusive with bounds.

  • tabbed_is_inverse (bool) – False if the bounds or center values should be taken as they are. True if values shoud be inverted i.e. \(1/x\). Defaults to False.

  • reverse_index – False if the numeric class index is acsending. True if it is decending. Defaults to False.

  • names (list[str]) – Names of the stability classes. Must be same lenght as centers or one more element as bounds

class_bound(cls: int | str, z0: float, inverse: bool = False) → float

get the upper boundary value of Obukhov lentgh \(L\) for the class with number num for roughness length z0.

Note: there is no such value for the class with the highest number.

Parameters:

  • cls – class name or number (1-based)

  • z0 (float) – roughness length in m

  • inverse (bool (optional)) – True if \(1/L\) should be returned instead of \(L\)

Returns:

Obukhov length \(L\) in m

Return type:

float

class_center(cls: int | str, z0: float, inverse: bool = False) → float

get the center value of Obukhov lentgh \(L\) for the class with number num for roughness length z0.

Parameters:

  • cls – class name or number (1-based)

  • z0 (float) – roughness length in m

  • inverse (bool (optional)) – True if \(1/L\) should be returned instead of \(L\)

Returns:

Obukhov length \(L\) in m

Return type:

float

lookup_austal(z0: float | Series, lob: float | Series, inverse: bool = False) → int

get the class name for roughness length z0 and Obukhov lentgh \(L\).

Parameters:

  • z0 (float | pd.Series) – roughness length in m

  • lob (float | pd.Series) – Obukhov lentgh

  • inverse (bool (optional)) – True if lob is \(1/L\) instead of \(L\)

Returns:

Numeric class index

Return type:

int

lookup_name(z0: float | Series, lob: float | Series, inverse: bool = False) → str

get the class name for roughness length z0 and Obukhov lentgh \(L\).

Parameters:

  • z0 (float | pd.Series) – roughness length in m

  • lob (float | pd.Series) – Obukhov lentgh

  • inverse (bool (optional)) – True if lob is \(1/L\) instead of \(L\)

Returns:

Numeric class index

Return type:

int

lookup_num(z0: float | Series, lob: float | Series, inverse: bool = False) → int

get the numeric class for roughness length z0 and Obukhov lentgh \(L\).

Parameters:

  • z0 (float | ps.Series) – roughness length in m

  • lob (float | pd.Series) – Obukhov lentgh

  • inverse (bool (optional)) – True if lob is \(1/L\) instead of \(L\)

Returns:

Numeric class index

Return type:

int

name2austal(name: str) → int

get the AUSTAL numeric class index for class name

Parameters:

name (str | list | pd.Series) – class name

Returns:

numeric class index

Return type:

int | pd.Series

name2num(name: str | list | Series) → int | Series

Get the numeric class for a class name.

Parameters:

name (str | list | pd.Series) – class name(s)

Returns:

numeric class index (1-based); scalar input returns a scalar

Return type:

int | pd.Series

num2austal(num: int) → int | Series

get the AUSTAL numeric class for numeric class

Parameters:

num (int | list | pd.Series[int]) – numeric class index

Returns:

class name

Return type:

int | pd.Series

num2name(num: int) → str

get the class name for numeric class

Parameters:

num (int | list | pd.Series[int]) – numeric class index

Returns:

class name

Return type:

str | pd.Series

austal = None
count = 0
names = None
austaltools._dispersion.h_eff(has: float | Series, z0s: float | Series) → list[float]
Calculate effective anemometer heights for all nine

z0 class values used by AUSTAL [AST31] from the actual height of the wind measurement

Parameters:

  • has (pandas.Series of float) – actual height of the wind measurement

  • z0s (pandas.Series of float) – roughness lenght at the position of the wind measurement

Returns:

height for nine roughness lenght at the model position ordered from the smallest to the lagrest roughness length

Return type:

list[float]

Note:

The effective roughness height is the height where the same wind speed would be measured considering the roughness at the model site as it is measured by a nearby the anemometer that is mounted at height has on a site where the roughness is z0s

austaltools._dispersion.klug_manier_scheme(*args, **kwargs) → str | Series

shorthand for the currently valid version of the Klug/Manier scheme austaltools._dispersion.klug_manier_scheme_2017()

austaltools._dispersion.klug_manier_scheme_1992(time: Timestamp | DatetimeIndex | datetime64 | str | list[str], ff: float | list[float] | Series, tcc: float | list[float] | Series, lat: float, lon: float, cty: str | list[float] | Series | None = None) → str | Series

Calulate stability class after Klug/Manier accroding to according to VDI 3782 Part 1 (issued 1992)

Category

Atmospheric stability

numeric

I

very stable

1

II

stable

2

III1

neutral/stable

3

III2

neutral/unstable

4

IV

unstable

5

V

very unstable

6
Parameters:

  • time – (required, time-like) An arbitrary time during the day of year for which surise and sunset should be calculated. May be supplied as any form accepted by pandas.to_datetime(), e.g. timestamp (“2000-12-14 18:00:00”) or datetime64. If timezone is not supplied, UTC is assumed. If timezone is supplied, time is converted to CET.

  • ff – (required, float) wind speed in 10m height.

  • tcc – (required, float) total cloud cover as fraction of 1 (equals value in octa divided by 8).

  • lat – (required, float) latitude in degrees. Southern latitudes must be nagtive.

  • lon – (required, float) longitude in degrees. Eastern longitudes are positive, western longitudes are negative.

  • cty – (optional, str) cloud type of lowest cloud layer. When it is “CI”, “CS”, or “CC”, the condition “cloud coverage exclusively consits of high clouds (Cirrus)” is met. If absent, “CU” is assumed.

Returns:

class value (numeric index)

Return type:

int if time is a scalar, pandas.Series(int64) if time is array-like.

austaltools._dispersion.klug_manier_scheme_2017(time: DatetimeIndex | Timestamp | datetime64 | str | list[str], ff: float | list[float] | Series, tcc: float | list[float] | Series, lat: float, lon: float, ele: float, cty: float | list[float] | Series | None = None, cbh: float | list[float] | Series | None = None, _cloudout=False) → str | Series

Calulate stability class after Klug/Manier according to according to VDI 3782 Part 6 (issued Apr 2017)

Category

Atmospheric stability

numeric

I

very stable

1

II

stable

2

III1

neutral/stable

3

III2

neutral/unstable

4

IV

unstable

5

V

very unstable

6

The norm states:

Strictly speaking, the above correction conditions apply only to locations in Central Europe with a pronounced season- al climate and sunrise and sunset times definable over the whole year, which in particular during the winter months always exhibit a time difference exceeding six hours. These conditions are met in Germany. For other countries, CET should be replaced where relevant by the corresponding zone- time. In climatic zones with diurnal climate or other calendar classifications of astronomical seasons, the correction condi- tions are not directly applicable in the above form. Adaptation of subsections a to d for other global climatic zones does not form a part of this standard.

Parameters:

  • time – (required, time-like) An arbitrary time during the day of year for which surise and sunset shout be calculated. May be supplied as any form accepted by pandas.to_datetime(), e.g. timestamp (“2000-12-14 18:00:00”) or datetime64. If timezone is not supplied, UTC is assumed. If timezone is supplied, time is converted to CET.

  • ff –

    (required, float) wind speed in 10m height. VDI 3782 Part 6 states:

    The standard conditions for the wind speed (υa) are the standard measurement height of 10 m above ground (VDI 3786 Part 2; VDI 3783 Part 8) in combination with a roughness length of z0 = 0,1 m. Other measurement heights are suitable if they equal at least twelve times the roughness length and are at least 4 m above ground level. If the wind speed is available for other than the above standard conditions, i.e. for another suitable measurement height or a different roughness length, a conversion needs to be carried out.

  • tcc – (required, float) total cloud cover as fraction of 1 (equals value in octa divided by 8).

  • lat – (required, float) latitude in degrees. Southern latitudes must be nagtive.

  • lon – (required, float) longitude in degrees. Eastern longitudes are positive, western longitudes are negative.

  • ele – (required, float) surface elvation above sea level in m.

  • cbh – (optional, float) cloud base height in m.

  • cty – (optional, str) cloud type of lowest cloud layer. When it is “CI”, “CS”, or “CC”, the condition “cloud coverage exclusively consits of high clouds (Cirrus)” is met. If absent, “CU” is assumed.

  • _cloudout – (optional, boolean) for verification only.

Returns:

class value (numeric index)

Return type:

int if time is a scalar, pandas.Series(int64) if time is array-like.

austaltools._dispersion.obukhov_length(ust: float | Series, rho: float | Series, Tv: float | Series, H: float | Series, E: float | Series, Kelvin: bool | None = None) → float | ndarray

Returns the Obuhkov lenght [GOL1972] from surface values of air density, virtual temperature, latent and sensible heat-flux density.

Parameters:

  • ust (pandas.Series or float) – friction velocity in m/s.

  • rho (pandas.Series or float) – density of air kg/m^3.

  • Tv (pandas.Series or float) – virtual temperature in K or C, depending on Kelvin.

  • H (pandas.Series or float) – surface sensible heat flux density in W/m^2.

  • E (pandas.Series or float) – surface latent heat flux density in W/m^2.

  • Kelvin – (optional) If False, all temperatures are assumed to be Kelvin. If False, all temperatures are assumed to be Celsius. If missing of None, unit temperatures are autodetected. Defaults to None.

austaltools._dispersion.pasquill_taylor_scheme(time: DatetimeIndex | Timestamp | datetime64 | str | list[str], ff: float | list[float] | Series, tcc: float | list[float] | Series, lat: float, lon: float, ceil: float | list[float] | Series) → str | Series

Calulate stability class after Pasquill and Turner [EPA2000]

Category

Atmospheric stability

numeric

A

very unstable

1

B

unstable

2

C

neutral/unstable

3

D

neutral/stable

4

E

stable

5

F

very stable

6

G

very very stable

7
The norm states:

Strictly speaking, the above correction conditions apply only to locations in Central Europe with a pronounced seasonal climate and sunrise and sunset times definable over the whole year, which in particular during the winter months always exhibit a time difference exceeding six hours. These conditions are met in Germany. For other countries, CET should be replaced where relevant by the corresponding zone- time. In climatic zones with diurnal climate or other calendar classifications of astronomical seasons, the correction conditions are not directly applicable in the above form. Adaptation of subsections a to d for other global climatic zones does not form a part of this standard.

Parameters:

  • time – (required, time-like) An arbitrary time during the day of year for which surise and sunset should be calculated. May be supplied as any form accepted by pandas.to_datetime(), e.g. timestamp (“2000-12-14 18:00:00”) or datetime64. If timezone is not supplied, UTC is assumed. If timezone is supplied, time is converted to CET.

  • ff – (required, float) wind speed in 10m height.

  • tcc – (required, float) total cloud cover as fraction of 1 (equals value in octa divided by 8).

  • lat – (required, float) latitude in degrees. Southern latitudes must be nagtive.

  • lon – (required, float) longitude in degrees. Eastern longitudes are positive, western longitudes are negative.

  • ceil – (required, float) cloud base height in m.

Returns:

class value (numeric index)

Return type:

int if time is a scalar, pandas.Series(int64) if time is array-like.

austaltools._dispersion.taylor_insolation_class(solar_altitude: float) → int
austaltools._dispersion.turners_key(ff: float, NRI: int) → int

Returns the P-G stability class matching a wind speed class and net radiation index [EPA2000]

Parameters:

  • ff (float) – wind speed in m/s

  • NRI (int) – net radiation index

Returns:

P-G stability class as number (1=A, 2=B,…)

Return type:

int

austaltools._dispersion.vdi_3872_6_standard_wind(va: float | ndarray, hap: float, z0p: float) → float | ndarray

Returns the Calculation value of wind speed according to VDI 3782 Part 6, Annex A

The norm is based on wind speed values that are taken at the standard measurement height of 10 m above ground (VDI 3786 Part 2; VDI 3783 Part 8; [5; 6]) in combination with a roughness length of \(z0 = 0.1\) m. If the wind speed \(v_a\) is available for other than the standard conditions, a conversion needs to be carried out from the conditions (measurement height \(h_a'\), roughness lenght \(z_0'\)) at the measurement site to the standard conditions.

Parameters:

  • va – (required,float or array-like) measured wind speed (\(v_a\)) in m/s.

  • hap – (required,float) height of the wind measurement above ground (\(h_a\)) in m.

  • z0p – (required,float) roughness lenght at the measurement site (\(z_0\)) in m.

austaltools._dispersion.vdi_3872_6_sun_rise_set(time: Timestamp | DatetimeIndex | datetime64 | str | list[str], lat: float, lon: float) → tuple[float, float] | tuple[Series, Series]

Sunrise and sunset calculation according to VDI 3782 Part 6, Annex A

Based on equation (B10) for the solar elevation angle \({\gamma}\) quoted in VDI 3789:

\(\sin\gamma = \sin\phi + \cos\phi \cos\delta \cos\omega_0\)

Parameters:

  • time – (required, time-like) An arbitrary time during the day of year for which surise and sunset should be calculated. May be supplied as any form accepted by pandas.to_datetime(), e.g. timestamp (“2000-12-14 18:00:00”) or datetime64. If timezone is not supplied, CET (without daylight saving) is assumed. If timezone is supplied, time is converted to CET.

  • lat – (required, float) latitude in degrees. Southern latitudes must be nagtive.

  • lon – (required, float) longitude in degrees. Eastern longitudes are positive, western longitudes are negative. Only positions iside CET timezone (-9.5 < lon < 32.0) are allowed, by definition.

Returns:

sunrise, sunset as decimal hours in the timezone supplied in parameter time.

Return type:

tuple(float) if time is a scalar, tuple(pandas.Series) if time is array-like.

austaltools._dispersion.z0_verkaik(z: float, speed: float | list | Series, gust: float | list | Series, dirct: float | list | Series, rose: bool = False) → float | tuple[DataFrame, DataFrame]

Calculates an estimate for the roughness lentgh of a site from the gustiness of the wind, according to the Method by Verkaik (as used by Koßmann and Namyslo [KoNa2019].

Parameters:

  • z (float, list or pandas.Series) – height of the wind measurement in meters

  • speed

  • gust (float, list or pandas.Series)

  • dirct (float, list or pandas.Series)

  • rose (bool) – If True individual values of roughness length in m and number of intervals when the wind cam from this sector. are returned for 12 wind-direction sectors (clockwise from north). If False one mean roughness lenght value in m for the site is returned. Default is False.

Returns:

roughness lenght either as mean or as sector-wise value(s)

Return type:

float or tuple[list,list], depending on rose

austaltools._dispersion.KM2002

Klug/Manier stabilty classes. Class center values taken from TA Luft 2002 [TAL2002].

Tabelle 17: Bestimmung der Monin–Obukhov–Länge L_M

austaltools._dispersion.KM2021

Klug/Manier stabilty classes. Class center values taken from TA Luft 2021 [TAL2021].

Tabelle 17: Klassierung der Obukhov-Länge L in m

austaltools._dispersion.PG1972

Pasquill-Gifford stability classes. Class Boundaries scraped from [GOL1972] Fig 4

According to EPA [EPA2000] class G is neglected for regulatory modeling

austaltools._dispersion.PT1972

Pasquill-Turner stability classes. Class Boundaries scraped from [GOL1972] Fig 5

According to EPA [EPA2000] class G is neglected for regulatory modeling

_fetch_dwd

Created on Thu Feb 3 19:20:42 2022

@author: clemens

class austaltools._fetch_dwd.DWDStationinfo(stationfile=None)

Class that holds information about weather stations from a dataset.

This function retrieves metadata about a specific weather station from a dataset that is either provided or located in a default location. The dataset is expected to be a JSON file containing information about multiple weather stations, including their geographical coordinates, elevation, and names.

param stationfile:

The path to the JSON file containing station information. If None, a default path is used. Defaults to None.

type stationfile:

str | None

This class can be used as a context manager.

Example:

with DWDStationinfo() as si:
    lat, lon, ele = si.position(1234)
classmethod from_dict(d: dict) → DWDStationinfo
classmethod read(stationfile) → DWDStationinfo
data_period(station: int) → tuple[Timestamp, Timestamp]

Retrieves the time period covered by data from a specific weather station identified by the station number

Returns start and end date :param station: :type station: :return: start, end :rtype: (pd.Timestamp, pd.Timestamp)

name(station: int) → str

Retrieves the name of a specific weather station identified by the station number :param station: :type station: :return: name :rtype: str

nearest(lat: float, lon: float, radius: float | None = None) → int | None

Returns the number of the nearest station in the stationinfo file.

If limit is given, a station is only returned, if one if found within the given radius around the position.

Parameters:

  • lat (float) – latitude in degrees

  • lon (float) – longitude in degrees

  • radius (float) – Max distance toe station returned in km

Returns:

station number or None if no station inside the search radius

Return type:

int | None

position(station: int) → tuple[float, float, float]

Retrieves the position of a specific weather station identified by the station number

Returns latitude, longitude, elevation, and name :param station: :type station: :return: lat, lon, ele :rtype: (float, float, float)

roughness(station: int) → str

Retrieves the surface roughness $z_0$ at a specific weather station identified by the station number :param station: :type station: :return: roughness length in m :rtype: float

set_roughness(station: int, z0: float) → str

Sets the surface roughness $z_0$ at a specific weather station identified by the station number :param station: :type station: :param z0: new rougness length value in m :type z0: float

write(path_or_buf: str | IO | None = None, fmt: str | None = None)
data: DataFrame
property numbers
austaltools._fetch_dwd.assemble_stationlist(path: str = None, fmt: str = None, h: float | None = None)

Downloads, extracts, and merges DWD station lists.

Parameters:

  • path (str) – The path where the final merged file will be stored.

  • fmt (str) – file format or generate (csv or json)

  • h (float) – (optional) height of wind measurements in m, mut be gerater than 1. Defaults to standard heigth (10)

  • This function assumes that a global _tools.TEMP variable is defined and points to a valid temporary directory for intermediate files.

austaltools._fetch_dwd.build_table(dat_df_in: DataFrame, meta_df_in: DataFrame, years: list) → DataFrame | None
austaltools._fetch_dwd.data_from_download(product_files: list[str], path_to_files: str, oldest: Timestamp | datetime | str | None = None) → DataFrame

Build one single table of weather data from the individual downloadad files

Parameters:

  • product_files – list of extracted “produkt” files

  • path_to_files – path where the product files are stored

Returns:

weather timeseries as dataframe. The columns are named as they appear in the “produkt” files, except “MESS_DATUM” and “STATIONS_ID”. Instead, the index contains the time of the measurement as datetime64.

Return type:

pandas.DataFrame

austaltools._fetch_dwd.fetch_dirlist(url: str, pattern: str = '.*') → list[str]

get directory listing from (opendata) server

Parameters:

  • url (str) – directory URL

  • pattern (str) – filter directory entries by this regex pattern

Returns:

fle names

Return type:

list

austaltools._fetch_dwd.fetch_file(group: str, station: int | str, era: str | None = None, local_path: str = '.') → str

download observation file from (opendata) server

Parameters:

  • group (str) – name of parameter group, for example ff

  • station ((int, str)) – DWD station number

  • era (str) – current or historical

  • local_path (str) – where to store the downloaded file

Returns:

name of the downloaded file

Return type:

str

austaltools._fetch_dwd.fetch_station_data(station: int, store: bool = True, time_start: Timestamp | str | None = None, time_end: Timestamp | str | None = None, force: bool = False) → tuple[DataFrame, DataFrame] | tuple[str, str]

Ensure that the DWD weather station data for station number station is available at storage_path. If not, data is downloaded and stored in the storage_path.

Parameters:

  • station (int) – DWD station number

  • store – If True data are be saved to files, if False data are returned as data frames

  • time_start (pd.Timestamp | str) – start of desired time window or None for getting earliest available data

  • time_end (pd.Timestamp | str) – end of desired time window or None for getting latest available data

  • force (bool) – overwrite existing temp data

Returns:

data file name or DataFrame and metadata file name or DataFrame

Return type:

tuple[pd.DataFrame, pd.DataFrame] | tuple[str, str]

austaltools._fetch_dwd.fetch_stationinfo(years: list[int] | int | None = None, fullyear=True) → DWDStationinfo

compile the station list from (opendata) server

Parameters:

  • years (list) – list of years for wich the station should habe reported data must be continuous and ascending order

  • fullyear – If True, stations are olny listed, if they have reported data for the full period. If False, stations that have strated operation in the first or ceised operation in the last year are also listed.

Returns:

list of stations

Return type:

dict[dict]

austaltools._fetch_dwd.get_meta_value(metadata: str | DataFrame, time_begin: DatetimeIndex | Timestamp | datetime64 | str, time_end: DatetimeIndex | Timestamp | datetime64 | str, par_name: str) → Any

get station metadata value for parameter par_name valid for the time period info from time_begin to time_end

Parameters:

  • metadata – filename or pandas dataframe

  • time_begin – start time as string of datetime-like

  • time_end – end time as string of datetime-like

  • par_name – string containig the parameter name

Returns:

values for parameter par_name

Return type:

pandas.Series

austaltools._fetch_dwd.meta_from_download(metadata_files: list[str], station: int, path_to_files: str) → DataFrame

Build one single table of the metadata provided by the individual metadata files contained in the downloadad zip archives

Parameters:

  • metadata_files – list of extracted “Metadaten” files

  • path_to_files – path where these files are stored

Returns:

metadata table as dataframe. The columns are named as they appear in the “produkt” files, except “MESS_DATUM” and “STATIONS_ID”. Instead, the index contains the time of the measurement as datetime64.

Return type:

pandas.DataFrame

austaltools._fetch_dwd.METAFILE_DWD = 'metadata_%05i.csv'

filename pattern for cached DWD metadata

austaltools._fetch_dwd.OBSFILE_DWD = 'observations_hourly_%05i.csv'

filename pattern for cached DWD observations

austaltools._fetch_dwd.OLDEST = Timestamp('1970-01-01 00:00:00+0000', tz='UTC')

remove observations before … to avoid problems with odd observation timing in the very manual era)

austaltools._fetch_dwd.TO_COLLECT = [['air_temperature', 'TU', 'tu'], ['cloud_type', 'CS', 'cs'], ['precipitation', 'RR', 'rr'], ['pressure', 'P0', 'p0'], ['soil_temperature', 'EB', 'eb'], ['visibility', 'VV', 'vv'], ['wind', 'FF', 'ff'], ['wind_synop', 'F', 'f']]

parameter groups to collect from opendata file tree

_geo

Thisn module provides geo-position related functionality.

austaltools._geo.evaluate_location_opts(args: dict)

get position from the command-line location options and if applicable the WMO station number of this position

Parameters:

args (dict) – parsed arguments

Returns:

position as lat, lon (WGS84) and rechts, hoch in Gauss-Krüger Band 3 and WMO station number of this position (0 if not applicable)

Return type:

float, float, float, float, int

austaltools._geo.gk2ll(rechts: float, hoch: float) -> (<class 'float'>, <class 'float'>)

Converts Gauss-Krüger rechts/hoch (east/north) coordinates (DHDN / 3-degree Gauss-Kruger zone 3 (E-N), https://epsg.io/5677) into Latitude/longitude (WGS84, https://epsg.io/4326) position.

Parameters:

  • rechts – “Rechtswert” (eastward coordinate) in m

  • hoch – “Hochwert” (northward coordinate) in m

Type:

float

Type:

float

Returns:

latitude in degrees, longitude in degrees, altitude in meters

Return type:

float, float, float

austaltools._geo.gk2ut(rechts: float, hoch: float) -> (<class 'float'>, <class 'float'>)

Converts Gauss-Krüger rechts/hoch (east/north) coordinates (DHDN / 3-degree Gauss-Kruger zone 3 (E-N), https://epsg.io/5677) into UTM east/north coordinates (ETRS89 / UTM zone 32N, https://epsg.io/25832).

Parameters:

  • rechts – “Rechtswert” (eastward coordinate) in m

  • hoch – “Hochwert” (northward coordinate) in m

Type:

float

Type:

float

Returns:

“easting” (eastward coordinate) in m, “northing” (northward coordinate) in m

Return type:

float, float

austaltools._geo.ll2gk(lat: float, lon: float) -> (<class 'float'>, <class 'float'>)

Converts Latitude/longitude (WGS84, https://epsg.io/4326) position into Gauss-Krüger rechts/hoch (east/north) coordinates (DHDN / 3-degree Gauss-Kruger zone 3 (E-N), https://epsg.io/5677).

Parameters:

  • lat – latitude in degrees

  • lon – longitude in degrees

Type:

float

Type:

float

Returns:

“Rechtswert” (eastward coordinate) in m, “Hochwert” (northward coordinate) in m

Return type:

float, float

austaltools._geo.ll2ut(lat: float, lon: float) -> (<class 'float'>, <class 'float'>)

Converts Latitude/longitude (WGS84, https://epsg.io/4326) position into UTM east/north coordinates (ETRS89 / UTM zone 32N, https://epsg.io/25832)

Parameters:

  • lat – latitude in degrees

  • lon – longitude in degrees

Type:

float

Type:

float

Returns:

“easting” (eastward coordinate) in m, “northing” (northward coordinate) in m

Return type:

float, float

austaltools._geo.spheric_distance(lat1, lon1, lat2, lon2)

Calculate the great circle distance between two points (specified in decimal degrees) on a spheric earth. Reference: https://stackoverflow.com/a/29546836/7657658

Parameters:

  • lat1 – Position 1 latitude in degrees

  • lon1 – Position 1 longitude in degrees

  • lat2 – Position 2 latitude in degrees

  • lon2 – Position 2 longitude in degrees

Type:

float

Type:

float

Type:

float

Type:

float

Returns:

Great circle distance in km

Return type:

float

austaltools._geo.ut2gk(east: float, north: float) -> (<class 'float'>, <class 'float'>)

Converts UTM east/north coordinates (ETRS89 / UTM zone 32N, https://epsg.io/25832) into Gauss-Krüger rechts/hoch (east/north) coordinates (DHDN / 3-degree Gauss-Kruger zone 3 (E-N), https://epsg.io/5677).

Parameters:

  • east – eastward UTM coordinate in m

  • north – northward UTM coordinate in m

Type:

float

Type:

float

Returns:

“Rechtswert” (eastward coordinate) in m, “Hochwert” (northward coordinate) in m, Altitude in m

Return type:

float, float, float

austaltools._geo.ut2ll(east: float, north: float) -> (<class 'float'>, <class 'float'>)

Converts UTM east/north coordinates (ETRS89 / UTM zone 32N, https://epsg.io/25832) into Latitude/longitude (WGS84, https://epsg.io/4326) position.

Parameters:

  • east – eastward UTM coordinate in m

  • north – northward UTM coordinate in m

Type:

float

Type:

float

Returns:

latitude in degrees, longitude in degrees, altitude in meters

Return type:

float, float, float

_plotting

austaltools._plotting.common_plot(args: dict, dat: dict, unit: str = '', topo: dict = None, dots: dict = None, buildings: list = None, mark: dict = None, scale: list = None)

Standard plot function for the package.

Parameters:

  • args (dict) – dict containing the plot configuration

  • args["colormap"] (str) – name of colormap to use Defaults to austaltools._tools.DEFAULT_COLORMAP:.

  • args['kind'] – How to display the data. Permitted values are “contour” for colour filled contour levels and “grid” for color-coded rectangular grid.

  • args['fewcols'] (bool) – if True, a colormap of at most 9 (or the numer of levels if explicitly passed by scale) discrete colors ist generated for easy print reproduction.

  • args["plot"] – Destination for the plot. If empty or None no plot is produced. If the value is a string, the plot will be saved to file with that name. If the name does have the extension .png, this extension is appendend. If the string does not contain a path, the file will besaved in the current working directory. If the string contains a path, the file will be saved in the respective location.

  • args['working_dir'] – Working directory, where the data files reside.

  • dat (dict) – dictionary of x, y, and z values to plot. ‘x’ and ‘y’ must be lists of float or 1-D ndarray. ‘z’ must be ndarray of a shape matching the lenght of x and y

  • unit (tuple or None) – physical units of the values z in dat

  • scale – range of the color scale. None means auto scaling.

  • topo (dict or string or None) – topography data as dict (same form as dat) or filename of a topography file in dmna-format or None for no topography

  • dots – data to ovelay dotted areas (e.g. to mark significance). dots must either be a dict (same form as dat) or a ndarray matching the z data in dat in shape. dat values z < 0 are not overlaid, values 0 <= z < 1 are sparesely dotted, values 1 <= z < 2 are sparesely dotted, spography data as dict (same form as dat) or filename of a topography file in dmna-format or None for no topography

  • buildings (list) – List of Building objects to be displayed. If None or list is epmty, no buildings are plotted.

  • mark (dict or pandas.Dataframe) – positions to mark. either dict containing list-like objects of x, y and optionally ‘symbol’ of the same length or a pandas data frame containing such columns. symbol are matplotlib symbol strings. If missing ‘o’ is used.

austaltools._plotting.consolidate_plotname(argument, default: str | None = None)
austaltools._plotting.finalize_plot(fig, ax, args: dict)

Common finishing touches for a plot: axis labels, layout, and either showing the plot on screen or saving it to file, depending on args["plot"]. Shared between common_plot() and overlap_plot().

Parameters:

  • fig – matplotlib figure.

  • ax – matplotlib axes.

  • args (dict) – dict containing at least args["plot"] (see common_plot()) and args["working_dir"].

austaltools._plotting.overlap_plot(args: dict, reference: dict, comparison: dict, thx: float, unit: str = '', topo: dict = None, buildings: list = None, mark: dict = None, scale: float = None)

Plot two scalar fields (typically the reference and comparison fields produced by austaltools.compare_weather.run_austal()) overlaid in a single map, as similar as reasonably possible to common_plot(), but using a bivariate color scheme instead of a single colormap + colorbar, since two independent fields are shown at once:

The reference field is rendered in shades of OVERLAP_REFERENCE_COLOR (orange), the comparison field in shades of OVERLAP_COMPARISON_COLOR (purple); both ramp from white at/below the threshold thx to the fully-saturated color at the field’s maximum (or scale, if given), logarithmically rather than linearly (see _overlap_blend_rgb()) so that the typical decades-wide spread between threshold and peak of a concentration field is actually visible as color, rather than only a thin band near the isoline. The two rasters are then combined with a multiplicative RGB blend (see _overlap_blend_rgb()): since white is the identity color for multiplication, a cell above threshold in only one field shows that field’s pure hue, while a cell above threshold in both fields darkens towards a brown/maroon tone where the two hues overlap. Highly visible isolines at z == thx are drawn for both fields, in their respective hue (solid for the reference, dashed for the comparison).

A color-key legend replaces the usual colorbar, since a single colorbar cannot represent a bivariate color scheme.

Parameters:

  • args (dict) – dict containing the plot configuration – the same keys as common_plot() accepts, except args['colormap'] is ignored (the two hues are fixed, see above).

  • reference (dict) – dict of x, y, z values of the reference field (same form as dat in common_plot()).

  • comparison (dict) – dict of x, y, z values of the comparison field, on the same x/y grid as reference.

  • thx (float) – threshold value (both fields are white at/below it) – typically the same value used to compute the overlap ratio, see austaltools.compare_weather.compute_overlap().

  • unit (str) – physical unit of the values in reference/ comparison, shown in the legend.

  • topo (dict or str or None) – topography, see common_plot().

  • dots – not supported by overlap_plot (no dots parameter – two fields are already shown at once).

  • buildings (list) – see common_plot().

  • mark (dict or pandas.DataFrame) – see common_plot().

  • scale (float, optional) – value that maps to the fully-saturated color of each field. None (default) means auto-scaling to the larger of the two fields’ maxima.

See also

common_plot(), austaltools.compare_weather.compute_overlap()

austaltools._plotting.plot_add_mark(ax, mark)
austaltools._plotting.plot_add_overlays(ax, topo: dict = None, buildings: list = None, mark: dict = None, working_dir: str = '.')

Overlay topography isolines, buildings and position marks on an existing plot axes. Shared between common_plot() and overlap_plot().

Parameters:

  • ax – matplotlib axes to draw on.

  • topo (dict or str or None) – topography data as dict (same form as dat in common_plot()) or filename of a topography file in dmna/grid-format, or None for no topography.

  • buildings (list) – List of Building objects to be displayed. If None or list is empty, no buildings are plotted.

  • mark (dict or pandas.DataFrame) – positions to mark, see common_plot().

  • working_dir (str) – working directory, used to resolve a relative topo filename.

austaltools._plotting.plot_add_topo(ax, topo, working_dir='.')
austaltools._plotting.read_topography(topo_path)
austaltools._plotting.OVERLAP_COMPARISON_COLOR = 'darkviolet'

str: matplotlib color name used for the comparison field in overlap_plot().

austaltools._plotting.OVERLAP_REFERENCE_COLOR = 'darkorange'

str: matplotlib color name used for the reference field in overlap_plot().

_metadata

austaltools._metadata.get_metadata()

Get package metadata from pyproject.toml

_netcdf

_storage

Module that provides funtions to manage the storage locations for configuration and datasets that serve as input for austaltools

austaltools._storage.find_writeable_storage(locs: str = None, stor: str = None) → str

Finds a viable data storage directory and returns its path. If storage_path is provided, only this path is checked for existance.

Parameters:

  • locs (str) – Candidate locations

  • stor (str) – Storage directory expected at location

Returns:

path to a writable data storage directory

Return type:

str

austaltools._storage.location_has_storage(location, storage)

Check if location has storage :param location: path to storage location :type location: str :param storage: name of storage :type storage: str :return: True if location has storage :rtype: bool

austaltools._storage.locations_available(locs: list[str]) → list[str]

Check whether locations exist :param locs: paths of storage location directories :type locs: list[str] :return: locations that exist :rtype: list[str]

austaltools._storage.locations_writable(locs: list[str]) → list[str]

Check whether locations are writable :param locs: paths of storage location directories :type locs: list[str] :return: locations that are writable :rtype: list[str]

austaltools._storage.read_config(locs: str = None) → dict
austaltools._storage.write_config(config: dict, locs: str = None) → bool
austaltools._storage.COMPRESS_NETCDF = 'zlib'

Standard compression method of netCDF files

austaltools._storage.CONFIG_FILE = 'austaltools.yaml'

Name of the optional austaltools config file

austaltools._storage.DIST_AUX_FILES = PosixPath('/builds/druee/austaltools/austaltools/data')

path to the auxiliary data files distributes alongside the code

austaltools._storage.SIMPLE_DEFAULT_EXTENT = 10.0

default terrain extent in austaltools simple

austaltools._storage.SIMPLE_DEFAULT_TERRAIN = 'DGM25-DE'

default terrain source in austaltools simple

austaltools._storage.SIMPLE_DEFAULT_WEATHER = 'CERRA'

default weather source in austaltools simple

austaltools._storage.SIMPLE_DEFAULT_YEAR = 2003

default weather year in austaltools simple

austaltools._storage.STORAGES = ['terrain', 'weather']

storage directories that hold data inside the storage locations

austaltools._storage.STORAGE_LOCATIONS = ['/opt/austaltools', '/root/.local/share/austaltools', '/root/.austaltools', '.']

Default locations where downloaded or cashed data are expected

austaltools._storage.STORAGE_TERRAIN = 'terrain'

storage directory that holds terrain data inside the storage locations

austaltools._storage.STORAGE_WAETHER = 'weather'

storage directory that holds weather data inside the storage locations

austaltools._storage.TEMP = '/tmp'

default path for temp files/dierctories

_tools

class austaltools._tools.Building(*args, **kwargs)

A class representing the Geometry of building

class austaltools._tools.Geometry(x: float = 0, y: float = 0, a: float = 0, b: float = 0, c: float = 0, w: float = 0)

A class that defines a geometric shape of the form that austal uses for sources and buildings. It is a cuboid of given widht, depth, and height, that may be rotated around its southwest corner.

Parameters:

  • x (float (optional), default 0.) – x position of the south-west corner

  • y (float (optional), default 0.) – y position of the south-west corner

  • a (float (optional), default 0.) – width (along x-axis) of the cuboid

  • b (float (optional), default 0.) – depth (along y-axis) of cuboid

  • c (float (optional), default 0.) – height (along z-axis) of cuboid

  • w (float (optional), default 0.) – rotation angle anticlockwise around the south-west corner

a = 0.0
b = 0.0
c = 0.0
w = 0.0
x = 0.0
y = 0.0
class austaltools._tools.GridASCII(file=None)

Class that represents a grid in ASCII format.

Example:
>>> grid = GridASCII("my_grid.asc")
>>> print(grid.header["ncols"])  # Access header values
>>> grid.write("output_grid.asc")  # Write grid data to a new file
read(file)

Reads the data from a GridASCII file in to the object.

Parameters:

file (str) – file name (optionally including path)

Raises:

ValueError if file is not a GridASCII file

write(file=None)

Writes the data the object into a GridASCII file.

Parameters:

file (str, optional) – file name (optionally including path). If missing, the name contained in the attribute name is used.

Raises:

ValueError if file is not a GridASCII file

data = None

grided data

file = None

Path to the ASCII file.

header = {'NODATA_value': None, 'cellsize': None, 'ncols': None, 'nrows': None, 'xllcorner': None, 'yllcorner': None}

Dictionary containing header information.

class austaltools._tools.SmartFormatter(prog, indent_increment=2, max_help_position=24, width=None, color=True)

Custom Help Formatter that maintains ‘\n’ in argument help.

class austaltools._tools.Source(*args, **kwargs)

A class representing the Geometry of pollutant source

class austaltools._tools.Spinner(text: str = None, step: int = None)
end()
spin()
spinner = '|/-\\\\'
step = 1
text = 'Working ...'
austaltools._tools.add_arguents_common_plot(parser: ArgumentParser) → ArgumentParser

Add agruments to a parser

Parameters:

parser (argparse.ArgumentParser) – parser to add arguments to

Returns:

parser with added arguments

Return type:

argparse.ArgumentParser

austaltools._tools.add_location_opts(parser, stations=False, required=True)

This routine adds the input arguments defining a position:

Parameters:

  • parser (argpargse.ArgumentParser) – the arguemnt parser to add the options to

  • stations (bool) – WMO or DWD station numbers are accepted as positions

  • required – if a location specification is required type required: bool

Note:

  • dwd (str or None): DWD option, mutually exclusive with ‘wmo’ and required with ‘ele’.

  • wmo (str or None): WMO option, mutually exclusive with ‘dwd’ and required with ‘ele’.

  • ele (str or None): Element option, required with either ‘dwd’ or ‘wmo’.

  • year (int or None): Year option, required with ‘-L’, ‘-G’, ‘-U’, ‘-D’, or ‘-W’.

  • output (str or None): Output name, required with ‘-L’, ‘-G’, ‘-U’, ‘-D’, or ‘-W’.

  • station (str or None): Station option, only valid with ‘dwd’ or ‘wmo’.

austaltools._tools.analyze_name(name)

determine wind direction, stability class and grid index from the filename of a file in the wind library

Parameters:

name (str) – filename

Returns:

grid ID, wind direction, snd stability class

Return type:

tuple[int, int, int]

austaltools._tools.download(url, file, usr=None, pwd=None)

Downloads a file from a specified URL and saves it to a given local file path.

Parameters:

  • url (str) – The URL of the file to download.

  • file (str) – The local path, including the filename, where the downloaded file will be saved.

Returns:

The name of the file saved locally.

Return type:

str

Raises:

Exception – An exception is raised if the download fails (HTTP status code is not 200).

This function sends a GET request to the specified URL. If the request is successful (HTTP status code 200), it writes the content of the response to a file specified by the ‘file’ parameter. If the request fails, it raises an exception with information about the failure.

Example:
>>> try:
>>>     file_name = download('http://example.com/file.jpg', '/path/to/local/file.jpg')
>>>     print(f"Downloaded file saved as {file_name}")
>>> except Exception as e:
>>>     print(str(e))
austaltools._tools.download_earthdata(url, file, usr, pwd)

Downloads a file from a specified URL that needs authorization from earthdata.nasa.gov and saves it to a given local file path.

Parameters:

  • url (str) – The URL of the file to download.

  • file (str) – The local path, including the filename, where the downloaded file will be saved.

  • usr (str) – The username of the user to authenticate with.

  • pwd (str) – The password of the user to authenticate with.

Returns:

The name of the file saved locally.

Return type:

str

Raises:

Exception – An exception is raised if the download fails (HTTP status code is not 200).

This function sends a GET request to the specified URL. If the request is successful (HTTP status code 200), it writes the content of the response to a file specified by the ‘file’ parameter. If the request fails, it raises an exception with information about the failure.

Example:
>>> try:
>>>     file_name = download('https://n5eil01u.ecs.nsidc.org/'
>>>                          'MOST/MOD10A1.006/2016.12.31/'
>>>                          'MOD10A1.A2016366.h14v03.006.'
>>>                          '2017002110336.hdf.xml',
>>>                          '/path/to/local/hdf.xml',
>>>                          'sampleuser', 'verysecret')
>>>     print(f"Downloaded file saved as {file_name}")
>>> except Exception as e:
>>>     print(str(e))
austaltools._tools.estimate_elevation(lat, lon)

Quick estimation of elevation at a postion (for simple cli use)

Parameters:

  • lat (float|str) – position latitude

  • lon (float|str) – position longitude

Returns:

elevation in m

Return type:

float

austaltools._tools.expand_sequence(string)

Parse a string representing a sequence of values

Parameters:

string (str) – The string to parse. The string can take the form of a comma-seperated list <value>, <value>, …, <value> or the form <start>-<stop>/<step> (in which step is optional).

Returns:

The sequence of values as describe by the string

Return type:

list[int]

Example:

>>> expand_sequence("1,2,3,4,5")
[1, 2, 3, 4, 5]
>>> expand_sequence("1-9/2")
[1, 3, 5, 7, 9]
Note:

If the string is a comma-seperated list of integers, the values must in increasing order.

List form and start-stop form are mutually exclusive

Raises:

ValueError if the string contains any characters other than digits, “,”, “-”, or “/”

Raises:

ValueError if the string contains “,” and “-” or “/”

Raises:

ValueError if the string is comma-seperated list of integers, but is not ordered.

austaltools._tools.find_austxt(wdir='.', fail=True)

Find AUSTAL configuration file in a given directory

Parameters:

  • wdir (str, optional) – working directory, defaults to current working directory

  • fail (bool, optional) – whether to raise an exception when no file is found (default = True, i.e. raise Exception)

Returns:

AUSTAL configuration file name

Return type:

str

austaltools._tools.find_z0_class(z0)

return index of roughness-length class that matches z0 best

Parameters:

z0 – actual roughness length

Returns:

index of matching roughness-length class

austaltools._tools.get_austxt(path=None)

Get AUSTAL configuration fron the file ‘austal.txt’ as dictionary

Parameters:

path – Configuration file. Defaults to

Type:

str, optional

Returns:

configuration

Return type:

dict

austaltools._tools.get_buildings(conf)

read the buildings defined in austal.txt and rerurn a list of Building objects.

Parameters:

conf (dict) – austal configuration as dict

Returns:

list of Building objects

Return type:

list[:Building]

Raises:

ValueError if the lists in each of the building-related configuration values are not all the same length.

austaltools._tools.jsonpath(json_obj, path)

Extracts values from specified keys or indices within a JSON object based on a given path.

Parameters:

  • json_obj – The JSON object (dict or list). This can be the result of json.loads() if using a JSON string.

  • path – A string representing the hierarchical path to the desired keys or indices. This path may include dictionary keys, list indices, and an optional filtering condition for dictionaries with specific key-value pairs.

Path Syntax

  • ‘key’: Selects the value associated with ‘key’ in a dictionary.

  • ‘[index]’: Selects the n-th element in a list (0-based index).

  • ‘key=value’: Selects dictionaries from a list of dictionaries where ‘key’ matches ‘value’.

  • Any combination of the above, separated by ‘/’ to navigate through nested structures.

  • an asterisk (*) may be specified instead of ‘key’ to match any key.

Returns:

A list containing the extracted values from the JSON object based on the input path.

Example:

>>> json_obj = {
>>>   "items": [
>>>       {"id": 1, "name": "Item 1"},
>>>       {"id": 2, "name": "Item 2", "extra": "yes"}
>>>   ]
>>>  }
...
>>> path_to_name = 'items/name'
>>> names = jsonpath(json_obj, path_to_name)
['Item 1', 'Item 2']
...
>>> path_to_extra = 'items/extra'
>>> extras = jsonpath(json_obj, path_to_extra)
['yes']
Note:

  • This function simplifies direct navigation and filtering in JSON objects but does not offer the full querying capabilities of more complex JSON querying libraries such as jsonpath-rw.

austaltools._tools.overlap(first: tuple[int | float, int | float], second: tuple[int | float, int | float]) → bool
austaltools._tools.progress(itr: Iterable | None = None, desc: str = '', *args, **kwargs)

A progress bar that shows if tqdm.tqdm is available and the log level is below logging.DEBUG

Parameters:

  • itr (list or iterable) – iterator

  • desc (str (optional)) – string displayed in the progress bar

  • args – arguments to tqdm.tqdm

  • kwargs – keyword arguments to tqdm.tqdm

Returns:

decorated iterator or itr, depending on the conditions

Return type:

iterator

austaltools._tools.prompt_timeout(prompt, timeout, default: str = None)

Ask the user a question, wait timeout seconds for an answer, then continue

Parameters:

  • prompt (str) – Text to show as prompt

  • timeout (int) – Time to weit for an answer in seconds

  • default (str|None) – Default answer

Returns:

The answer. If the user typed in someting, it is returned, else the default.

Return type:

str|None

austaltools._tools.put_austxt(path='austal.txt', data=None)

Write AUSTAL configuration file ‘austal.txt’.

If the file exists, it will be rewritten. Configuration values in the file are kept unless data contains new values.

A Backup file is created wit a tilde appended to the filename.

Parameters:

  • path – File name. Defaults to ‘austal.txt’

  • data – Dictionary of configuration data. The keys are the AUSTAL configuration codes, the values are the configuration values as strings or space-separated lists

Type:

str, optional

Returns:

configuration

Return type:

dict

austaltools._tools.read_extracted_weather(csv_name: str) -> (<class 'float'>, <class 'float'>, <class 'float'>, <class 'float'>, <class 'float'>, <class 'str'>, <class 'str'>, <class 'pandas.DataFrame'>)

Read weather data that were previously extracted from a dataset and stored in a CSV file with a specially crafted comment header line.

Two header formats are supported:

  1. (legacy, without anemometer height):

    # lat lon ele z0 source station_name

  2. (current, with anemometer height):

    # lat lon ele ha z0 source station_name

Format 2 is detected when field index 4 parses as a float (i.e. is the numeric z0 value rather than the source string).

Parameters:

csv_name (str) – path of the CSV file to read

Returns:

latitude, longitude, elevation, anemometer height $h_a$, roughness length $z_0$, source dataset code, station name, and the weather observations as a time-indexed DataFrame.

Return type:

tuple[float, float, float, float, float, str, str, pandas.DataFrame]

Raises:

  • IOError – if csv_name does not exist.

  • RuntimeError – if the header format cannot be determined.

austaltools._tools.read_wind(file_info: dict, path: str = '.', grid: int = 0, centers: bool = False)

read wind library files

Parameters:

  • file_info (dict) – dict of lists containing names, stability classes, general wind directions, and grid indexes of all files.

  • path (str) – Wind library files are expected to be in this path

  • grid (int) – index of the grid for which to read the wind data

Returns:

u_grid, v_grid, axes

Return type:

tuple of (np.ndarray, np,dnarray, dict of lists of float)

austaltools._tools.slugify(value, allow_unicode=False)

Taken from https://github.com/django/django/blob/master/django/utils/text.py Convert to ASCII if ‘allow_unicode’ is False. Convert spaces or repeated dashes to single dashes. Remove characters that aren’t alphanumerics, underscores, or hyphens. Convert to lowercase. Also strip leading and trailing whitespace, dashes, and underscores.

austaltools._tools.str2bool(inp)

Convert a string to a boolean value.

accept the usual strings indicating the user’s consent or refusal

austaltools._tools.wind_files(path)

find wind library files

Parameters:

path (str) – path where to search. Wind library files are expected to be in this path or in the subdirectory ‘lib’ of this path.

Returns:

dict of lists containing names, stability classes, general wind directions, and grid indexes of all files.

Return type:

dict[str, list]

austaltools._tools.wind_library(path)

Find the directory that contains the wind library

Parameters:

path (str) – user supplied path

Returns:

path to wind library

Return type:

str

austaltools._tools.xmlpath(xml, path)

Extracts text or attribute values from specified elements within an XML string based on a given path. The function implements only a small subset of the XPath syntax.

Parameters:

  • xml – The XML document as a str.

  • path – A string representing the hierarchical path to the desired elements. This path may include element names, indexes in square brackets for direct child selection, and an optional attribute filter or attribute name preceded by :: for final value extraction.

Path Syntax

  • 'element': Selects all children named element from the current node.

  • 'element[index]': Selects the n-th element among its siblings (0-based index).

  • 'element[@attribute="value"]': Selects all element nodes where the attribute matches the specified value.

  • 'element::attribute': Retrieves the value of an attribute named attribute from the selected elements.

  • Any combination of the above, separated by ‘/’ to navigate through child elements.

Returns:

A list containing the extracted data from the XML, either the text content of selected elements or the values of specified attributes, depending on the input path.

Example:
>>> xmlstring = '''<data>
...                     <item id="1">Item 1</item>
...                     <item id="2" extra="yes">Item 2</item>
...                </data>'''
...
>>> pathtotext = 'item'
>>> textresult = xmlpath(xmlstring, pathtotext)
['Item 1', 'Item 2']
...
>>> pathtoattribute = 'item::id'
>>> attributeresult = xmlpath(xmlstring, pathtoattribute)
['1', '2']
Note:

  • This function is designed to operate on well-formed XML strings. Malformed XML might lead to unexpected results.

  • The function uses Python’s built-in XML handling capabilities and regular expressions for parsing and navigating the XML.

  • Namespace handling: If the XML contains namespaces, they are automatically recognized and handled for tag matching.

Raises:

The function itself does not explicitly raise exceptions, but misuse (e.g., incorrect XML or path syntax) can lead to exceptions thrown by the underlying XML or regex processing libraries.

austaltools._tools.AUSTAL_POLLUTANTS_DUST
Pollutant dust substances that are defined by austal:

“pm”, “as”, “cd”, “hg”, “ni”, “pb”, “tl”, “ba”, “dx”, “xx”

austaltools._tools.AUSTAL_POLLUTANTS_DUST_CLASSES

Pollutant dusts that are defined by austal, each composed of a substance and grain-size class 1-4 or x

austaltools._tools.AUSTAL_POLLUTANTS_GAS
Pollutant gases that are defined by austal:

“so2”, “nox”, “no”, “no2”, “nh3”, “hg0”, “hg”, “bzl”, “f”, “xx”, “odor”, “odor_050”, “odor_065”, “odor_075”, “odor_100”, “odor_150”

austaltools._tools.DEFAULT_COLORMAP = 'YlOrRd'

Default colors used for the commpon plot type

austaltools._tools.DEFAULT_WORKING_DIR = '.'

Default location for input and output

austaltools._tools.ELEVATION_API = 'https://api.open-elevation.com/api/v1/lookup'

api used for estimation of elevation

austaltools._tools.MAX_RETRY = 3

number of tries made to download a ceratin file

austaltools._tools.Z0_CLASSES = [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0, 1.5, 2.0]

Surface roughness values corresponding to the roughness classes defined by austal

_windutil

Wind measurement utility functions for AUSTAL dispersion modelling.

Provides routines to retrieve, correct, and standardise wind observations for use with the AUSTAL / AUSTAL2000 atmospheric dispersion model:

  • Roughness length z0: read from configuration, log files, or CORINE data

  • Effective anemometer height: derived from z0 class and AKTERM file

  • Weather time series: load from DMNA or AKTERM files

  • Roughness correction: convert anemometer readings to standardised open-terrain wind speed at 10 m using WMO, Eurocode 1, or DIN EN 1991-1-4 methods

austaltools._windutil.get_roughness_length(working_dir=None, conf=None)

Get roughness length z0 for the AUSTAL simulation area.

Attempts to determine z0 in the following priority order: 1. Read from austal.txt configuration file 2. Extract from AUSTAL log files (austal.log, austal2000.log, taldia.log) 3. Calculate from CORINE land use data based on simulation position

Parameters:

  • working_dir (str, optional) – The working directory of austal(2000), where austal.txt resides. If None, uses DEFAULT_WORKING_DIR

  • conf (dict, optional) – AUSTAL configuration file contents as dict. If None, the configuration will be read from working_dir

Returns:

Roughness length z0 in meters

Return type:

float

Raises:

ValueError – If z0 cannot be determined from any source and position is not defined in configuration

The function attempts to determine z0 from multiple sources:

  • If z0 is explicitly defined in austal.txt, that value is used

  • If not defined, searches log files for z0 values that AUSTAL rounded

  • If still not found, calculates mean z0 from CORINE land use data:

    • Requires position (xg/yg or xu/yu) in configuration

    • Optionally uses source height (hq) from configuration, defaults to 10m

    • First tries local CORINE inventory

    • Falls back to EEA Web API if local data unavailable

If conf is provided, this configuration is evaluated; otherwise the configuration file is read from working_dir. This option is intended for situations where conf has already been read into memory for other purposes.

austaltools._windutil.load_weather(working_dir: str, conf: dict = None, file: str = None) → DataFrame

Get the weather time series height working_dir. Files are evaluated in the same order as by AUSTAL: zeitreihe.dmna or timeseries.dmna are tried to read first, then the AKTERM file spezified in the config file under parameter ‘az’

Parameters:

  • working_dir (str) – the working directory of austal(2000), where austal.txt resides. If path is a file, this file is read, ignoring the AUSTAL configuration.

  • conf (dict) – (optional) AUSTAL configuration file contents as dict

Returns:

effective anemometer height

Return type:

float

If conf is provided, this configuration is evaluated, else the configuration file from working_dir is read. This option is indended for situation in which conf has already been read into memory for other purposes.

austaltools._windutil.read_heff(working_dir, conf=None, z0=None)

get effective anemometer height from z0 defined in austal.txt and the heights given in the akterm file (weather timeseries) given as parameter ‘az’

Parameters:

  • working_dir (str) – the working directory of austal(2000), where austal.txt resides

  • conf (dict) – (optional) configuration file contents as dict

  • z0 (float) – (optional) override z0 defined in austal.txt

Returns:

effective anemometer height

Return type:

float

If conf is provided, this configuration is evaluated, else the configuration file from working_dir is read. This option is indended for situation in which conf has already been read into memory for other purposes.

austaltools._windutil.read_z0(working_dir, conf=None)

get roughness length z0 defined in austal.txt

Parameters:

  • working_dir (str) – the working directoty of austal(2000), where austal.txt resides

  • conf (dict) – (optional) configuration file contents as dict

Returns:

effective anemometer height

Return type:

float

If conf is provided, this configuration is evaluated, else the configuration file from working_dir is read. This option is indended for situation in which conf has already been read into memory for other purposes.

austaltools._windutil.roughness_correction(ua, ha, z0a, method=None)

Correct wind speed readings for local surface roughness exposure.

Converts anemometer measurements taken over terrain with roughness length z0a to the equivalent wind speed over open, level terrain with standardised roughness at 10 m height, following one of three established methods.

Scalar inputs are accepted and return a scalar; array-like or Series inputs return a pandas.Series. Mixed scalar / array inputs are supported: scalars are broadcast to the length of the array argument.

Parameters:

  • ua (int | float | list | pandas.Series) – Wind speed measured by the anemometer [m/s].

  • ha (int | float | list | pandas.Series) – Height of the anemometer above ground [m].

  • z0a (int | float | list | pandas.Series) – Roughness length of the terrain at (or upstream from) the anemometer location [m].

  • method (str, optional) –

    Correction method to apply:

    • 'wmo' (default): WMO-No. 8 logarithmic profile with extrapolation to 60 m and back [WMO8], equation (5.3). Standard roughness z0 = 0.03 m (cut grass), standard height z_std = 10 m, extrapolation height z_ext = 60 m. Flow-distortion factor cf = 1 and topographic factor ct = 1 are assumed (free-standing mast, flat terrain).

    • 'en': Eurocode 1 EN 1991-1-4:2005 [EN1991], equations (4.4) and (4.5). Reference roughness z0 = 0.05 m (terrain category II). Topographic correction co = 1.

    • 'din': DIN EN 1991-1-4/NA:2010 [DIN1991], equation (NA.1). Assigns each z0a value to the nearest terrain category (I–IV) by minimising |log(z0_cat / z0a)|, then applies the corresponding power-law exponent alpha.

Returns:

Corrected wind speed at 10 m over standard open terrain [m/s]. Returns a scalar float when all inputs are scalar, otherwise a pandas.Series aligned to the index of ua.

Return type:

float | pandas.Series

Raises:

  • ValueError – If method is not one of the accepted values.

  • ValueError – If array-like arguments have incompatible lengths.

austaltools._windutil.search_logs_for_z0(working_dir) → float | None

Search for z0 value in AUSTAL log files.

Searches for files ‘austal.log’, ‘austal2000.log’, or ‘taldia.log’ in working_dir and scans for lines containing z0 rounding information in German or English.

Parameters:

working_dir – Directory to search for log files

Returns:

z0 value as float, or None if not found

Return type:

float | None

Raises:

UserWarning: If multiple different z0 values are found

_wmo_metadata

This contains functions that provide metadata about weather stations extracted from the WMO OSCAR/surface database https://oscar.wmo.int/surface

austaltools._wmo_metadata.by_wigos_id(id: str) → dict

Return station data entry of station identified by ist WIGOS ID.

Fills STATIONLIST stub if not yet filled.

Parameters:

id (str) – WIGOS ID

Returns:

station dataset

Return type:

dict

austaltools._wmo_metadata.by_wmo_id(id: (<class 'str'>, <class 'int'>)) → dict

Return station data entry of station identified by its WMO number.

Fills STATIONLIST stub if not yet filled.

Parameters:

id (int|str) – WMO station number

Returns:

station dataset

Return type:

dict

austaltools._wmo_metadata.position(station: dict) → tuple[float, float, float]

Return position of a station

Parameters:

station (dict) – station dataset

Returns:

Latitude, longitude and elevation

Return type:

(float, float, float)

austaltools._wmo_metadata.wigos_ids(station: dict) → list[str]

Get the WIGOS IDs of a station

Parameters:

station (dict) – station dataset

Returns:

List of the WIGOS IDs

Return type:

list[str]

austaltools._wmo_metadata.wmo_stationinfo(wmoid: (<class 'str'>, <class 'int'>)) -> (<class 'float'>, <class 'float'>, <class 'float'>, <class 'str'>)

Return information about a station identified by its WMO number.

Parameters:

station (dict) – station dataset

Returns:

Latitude, longitude, elevation and name

Return type:

(float, float, float, str)

austaltools._wmo_metadata.OSCARFILE = '/builds/druee/austaltools/austaltools/data/wmo_stationlist.json'

File holding the WMO station data retrieved from WMO OSCAR database

austaltools._wmo_metadata.STATIONLIST = {}

dictionary holding the WMO station data. Empty stub to be filled later when needed