API Reference

Utilities

iconspy.convert_tgrid_data(ds_tgrid, pyic_kwargs=None)

Formats the model grid in the format required by iconspy

Parameters:

ds_tgrid (xarray.Dataset) – Dataset represention of the raw model grid (e.g. downloaded from “http://icon-downloads.mpimet.mpg.de”)
pyic_kwargs (dict, optional) – Dictionary containig arguments to be passed to the pyicon.convert_tgrid_data function, by default None

Returns:

ds_IsD – Dataset represention of the model grid in the format required by iconspy

Return type:

xarray.Dataset

Notes

An iconspy dataset (ds_IsD) is similar to but distinct from a pyicon dataset (ds_IcD). I suggest loading the dataset having loaded it

Example

>>> from pathlib import Path
>>> import xarray as xr
>>> import iconspy as ispy
>>> tgrid_path = Path("/pool/data/ICON/grids/public/mpim/0036/icon_grid_0036_R02B04_O.nc")
>>> ds_tgrid = xr.open_dataset(tgrid_path)
>>> ds_IsD = convert_tgrid_data(ds_tgrid)
>>> ds_IsD = ds_IsD.load()

Target station

class iconspy.TargetStation(name, lon, lat, boundary=True)

Represents a target station

Parameters:

name (str) – Name of the target station
lon (float) – Longitude of the target station
lat (float) – Latitude of the target station
boundary (bool, optional) – Whether the station should be sited on a boundary point or not, by default True

name

Name of the target station

Type:: str

target_lon

Longitude of the target station

Type:: float

target_lat

Latitude of the target station

Type:: float

boundary

Whether the station should be sited on a boundary point or not

Type:: bool

Example

>>> import iconspy as ispy
>>> target_station = ispy.TargetStation("My Station", 10.0, 20.0)
>>> target_station.plot()

plot(ax=None, proj=None, extent=None, coastlines=True, gridlines=True)

plot the target station on a map

Parameters:

ax (matplotlib.axes, optional) – axis to plot on, by default None
proj (ccrs.Projection, optional) – projection of map to be plotted, by default None
extent (arraylike, optional) – extent of plot, by default None
coastlines (bool, optional) – whether to overlay coastlines, by default True
gridlines (bool, optional) – whether to overlay lines of latitude and longitude, by default True

to_boundary_model_station(ds_IsD)

Converts the target station to a dry model station regardless of boundary

Parameters:: ds_IsD (xarray.Dataset) – A dataset contining the model grid information, having been operated on by iconspy.convert_tgrid_data()
Returns:: A model station object representing the closest dry model grid point to the target station
Return type:: iconspy.BoundaryModelStation

to_model_station(ds_IsD)

Converts the target station to a model station

Parameters:: ds_IsD (xarray.Dataset) – A dataset contining the model grid information, having been operated on by iconspy.convert_tgrid_data()
Returns:: A model station object representing the closest model grid point to the target station
Return type:: iconspy.ModelStation

to_wet_model_station(ds_IsD)

Converts the target station to a wet model station regardless of boundary

Parameters:: ds_IsD (xarray.Dataset) – A dataset contining the model grid information, having been operated on by iconspy.convert_tgrid_data()
Returns:: A model station object representing the closest wet model grid point to the target station
Return type:: iconspy.WetModelStation

Model stations

class iconspy.ModelStation(target_station)

Represents a station on the model grid

Normally created using iconspy.TargetStation.to_model_station()

Parameters:: target_station (iconspy.TargetStation) – The target station object that this model station is based on

name

Name of the target station

Type:: str

vertex

The vertex number of the model grid point

Type:: int

model_lon

Longitude of the model grid point

Type:: float

model_lat

Latitude of the model grid point

Type:: float

plot(ax=None, proj=None, extent=None, coastlines=True, gridlines=True)

class iconspy.WetModelStation(target_station, ds_IsD): Bases: ModelStation

class iconspy.BoundaryModelStation(target_station, ds_IsD): Bases: ModelStation

Sections

class iconspy.Section(name, model_station_a, model_station_b, ds_IsD, section_type=None, contour_target=None, contour_data=None)

compute_vertex_graph(ds_IsD, contour_target=None, contour_data=None)

contour_weights(ds_IsD, contour_target, contour_data)

great_circle_weights(ds_IsD, angular_distance=True)

lat_lon_as_cartesian_weights(ds_IsD)

plot(ax=None, proj=None, extent=None, coastlines=True, gridlines=True)

reverse_section()

set_pyic_orientation_along_path(ds_IsD)

Calculate the orientation of the edges along the path

Add the edge orientation object to the section object using code from pyicon.

Parameters:

self (iconspy.Section) – The section you wish to calculate the edge orientation for
ds_IsD (xarray.Dataset) – A dataset containing the model grid information, having been operated on by iconspy.convert_tgrid_data()

Notes

Original code from pyicon under the MIT license. Modified by Fraser Goldsworth on 18.06.2025. See LICENSE file for more information.

to_ispy_section(fpath, dryrun=False)

class iconspy.LandSection(name, model_station_a, model_station_b, ds_IsD, section_type=None, contour_target=None, contour_data=None)

Bases: Section

compute_vertex_graph(ds_IsD, contour_target=None, contour_data=None)

class iconspy.CombinedSection(name, section_list, ds_IsD): Bases: Section

Region

class iconspy.Region(name, section_list, ds_IsD, test=False, manual_order=False)

calculate_contained_cells(ds_IsD)

calculate_section_order(section_list)

Given a list of sections, calculates the order the sections should be in.

Notes

This function is nigh on unreadable. Sorry.

calculate_vertex_circuit(ds_IsD)

extract_sections_from_region(ds_IsD)

order_sections(section_order, section_list)

plot(ax=None, proj=None, extent=None, coastlines=True, gridlines=True)

to_ispy_section(fpath, dryrun=False)

to_pyicon_section(fpath)