API Reference#

Accessors#

ARTist registers xarray accessors when the package is imported:

import artist

ds.icon provides ICON dataset helpers:

add_grid(gridfile, ltranslon=False): Attach native ICON grid coordinates from a grid file.
get_dz(): Compute model-layer thickness from interface heights.
look_up(key="mixed"): Return dataset variable names containing a search key.
distance(origin, destination, radius=6371.0): Compute great-circle distance between lon/lat coordinates.
nearest_gridpoints(coordinate): Find nearest ICON native cells for lon/lat coordinates.
sellonlat(lonmin, lonmax, latmin, latmax, lon="clon", lat="clat"): Select native ICON cells inside a lon/lat box.
sel_lonlat(lonmin, lonmax, latmin, latmax, lon="clon", lat="clat"): xarray-style alias for sellonlat.
show_slice_line(points, gridpoints, grid_stride=5): Plot a vertical slice path and selected gridpoints.
noncyl_xticks(ax, ticks, fontsize=None): Draw longitude ticks for non-cylindrical Cartopy projections.
noncyl_yticks(ax, ticks, fontsize=None): Draw latitude ticks for non-cylindrical Cartopy projections.
noncyl_gridlines(ax, xticks=None, yticks=None, fontsize=None, **gridline_kwargs): Draw gridlines and edge ticks for non-cylindrical Cartopy maps.

da.icon provides native-grid helpers for individual fields:

regrid(lon, lat, method="linear", ltranslon=True, gridfile=None): Interpolate a native ICON field to a regular lon/lat grid.
tri_data(gridfile=None, cmap=None, vrange=[], ltranslon=True): Build native-cell triangle vertices and colors for plotting.
tri_plot(ax, gridfile=None, cmap=None, vrange=[], ltranslon=False, add_colorbar=True, map_extent=None): Plot a field on ICON triangular cells.

da.viz.tricontourf(ax, cmap="coolwarm", levels=10, backend="tricontourf", ...): Plot a field from cell centers with Matplotlib tricontourf or from ICON cell vertices with the "polycollection" backend.

da.art provides ICON-ART tracer diagnostics:

tracer_load(rho, dz): Compute column tracer load.
select_plume(thresh, fill_value=0): Keep values above a plume threshold.
plume_center(v_cell, z_mc, dim=None, skipna=True): Compute plume center height.
plume_top(z_mc, height_dim="height", fill_value=0): Compute the highest plume-cell height.
plume_bottom(z_mc, height_dim="height", fill_value=0): Compute the lowest plume-cell height.
value_at_plume_top(z_mc, val, height_dim="height", fill_value=0): Sample another field at the plume top.
max_conc_height(z_mc, height_dim="height", fill_value=0): Find the height where plume concentration is maximal.
plot_hov(height, gridpoints, start_t=0, end_t=100, levels=80, point_size=90): Plot a time-height view at one native gridpoint.
plot_slice(height, gridpoints, t, deg_E_start, deg_E_end, deg_N, n=4000, levels=80, point_size=35): Plot a vertical tracer slice.
quick_plot(gridfile=None, cmap="coolwarm", levels=10, projection=None): Quickly plot a field on a Cartopy map.

ds.art provides dataset-level ICON-ART optical diagnostics:

vmr_to_du(tracer, pres=None, temp=None, dz=None): Convert a volume mixing ratio profile to Dobson units.
plume_mass(var, thres_var, thres, cell_area=None, dz=None, molar_frac=1.0): Compute total tracer mass inside a threshold-defined plume.
density(components): Compute particle density from mass-weighted component density.
coating_fraction(): Compute ash core diameter fractions for mixed modes.
effective_radius(kind="all"): Compute effective radius for sulfate, ash, or all aerosol modes.
reff_sulfate(): Compute sulfate effective radius.
reff_ash(): Compute ash effective radius.
reff_all(): Compute effective radius over sulfate and ash modes.
rayleigh_part(wavelength, height_ref=90, scale_height=1.0): Compute Rayleigh extinction and backscatter coefficients.
att_bsct(wavelength): Compute attenuated backscatter for aerosol tracers.
att_bsct_sph(wavelength): Compute attenuated backscatter using spherical aerosol fractions.
aod(wavelength): Compute layer aerosol optical depth.
aod_misr(wavelength, frac="all"): Compute MISR-style layer aerosol optical depth by fraction.
sulfate_aod(wavelength): Compute sulfate-only layer aerosol optical depth.
saod(wavelength): Script-name alias for sulfate_aod.
ssa(wavelength): Compute mass-weighted single-scattering albedo.

ds.oem provides helpers for preparing ICON online emission module inputs:

map_edgar(edgar_directory, year, species, gridfile=None, output_dir="./output", ...): Map EDGAR emissions for selected species to an ICON grid and return the exported OEM emissions dataset.
plot_raw_edgar(edgar_directory=None, year=None, species=None, total_only=True, cmap="magma", **kwargs): Plot raw EDGAR inventory data before ICON remapping. If called after ds.oem.map_edgar(...), EDGAR directory, year, and species are inferred.
plot_mapped_emissions(emissions, variable=None, gridfile=None, selectors=None, ax=None, ...): Plot gridded OEM emissions after mapping to an ICON grid.

artist.oem.map_edgar(edgar_directory, year, species, gridfile, output_dir="./output", ...): High-level EDGAR-to-ICON OEM workflow.
artist.oem.download_edgar(local_dir, year, substances): Download EDGAR inventory files with emiproc.
artist.oem.load_edgar_inventory(local_dir, pattern="*.nc", year=None, substances=None): Load an EDGAR v8 inventory.
artist.oem.remap_to_icon(inventory, icon_grid, weights_file=".remap_weights"): Remap an emiproc inventory to an ICON grid.
artist.oem.export_icon_oem(inventory, icon_grid_file, output_dir, temporal_profiles_type="THREE_CYCLES"): Export ICON OEM input files.

artist.utils.add_grid(gridfile, ltranslon=False): Open an ICON grid file and return converted vertex and cell-center coordinates.
artist.utils.distance(origin, destination, radius=6371.0): Compute great-circle distance in kilometers.