Salem: Geoscientific data I/O and map projections

Salem is a library designed for geoscientific data processing and plotting. It acts as an extension to xarray, adding specialized geolocalised operations to xarray.DataArray and xarray.Dataset structures. Key capabilities include:

• Geolocalised subsetting: Selecting data based on geographic coordinates.
• Masking: Applying geographic masks to datasets.
• Plotting: Specialized plotting operations tailored for geoscientific data.

Salem is a Python library designed for geoscientific data processing and plotting. It functions as an extension to xarray, adding specialized geolocalised operations to xarray.DataArray and xarray.Dataset structures.

Key capabilities include:

• Geolocalised subsetting
• Masking operations
• Geoscientific plotting operations

Salem introduces a third coordinate reference system (CRS) called a GRID. While standard systems use DATUM (angular coordinates like lon/lat) or PROJ (cartesian coordinates like x/y), a GRID defines coordinates $(i, j)$ based on a structured grid with constant $(dx, dy)$ steps. This is particularly useful when transforming data between two structured datasets or from unstructured data to a structured one.

A salem.Grid is defined by:

• A projection (proj)
• A reference point in that projection (x0y0)
• Grid spacing (dxdy)
• Number of grid points (nxny)

import numpy as np
import salem
from salem import wgs84

grid = salem.Grid(nxny=(3, 2), dxdy=(1, 1), x0y0=(0.5, 0.5), proj=wgs84)
x, y = grid.xy_coordinates

Salem extends xarray.DataArray and xarray.Dataset objects by adding a .salem attribute. To enable this, you must simply import salem in your code. Once imported, the .salem accessor provides georeferencing and transformation tools directly on your Xarray objects.

import xarray as xr
import salem

# After importing salem, the accessor is available
da = xr.DataArray(...) 
da.salem  # returns the accessor object

Upon the first import, Salem creates a hidden directory named .salem_cache in your home folder.

Purpose of .salem_cache:

• Downloading Salem's demo files and standard shapefiles.
• Storing results of slow operations via joblib (e.g., reading/transforming shapefiles or downloading Google Maps).

Maintenance: If the cache becomes too large, you can safely delete the .salem_cache directory to free up space.

Salem adds a layer on top of xarray that computes variables on demand. This includes:

1. Unstaggering: Accessing staggered variables (like U or V components) automatically 'unstaggers' them.
2. Diagnostic Variables: Salem provides convenient computed variables such as:
   • T2C: Temperature in Celsius (converted from Kelvin).
   • SLP: Sea-level pressure.
   • PRCP: Step-wise total precipitation (computed from accumulated fields).

These computations are performed lazily and are relatively inexpensive.

# Accessing an unstaggered velocity component
print(ds.U)

# Accessing a diagnostic variable like precipitation
ds.PRCP.isel(time=-1).salem.quick_map(cmap='Purples', vmax=5)

Salem provides high-level graphics classes for spatial visualization:

DataLevels

Used to manage colorbars and data scaling. Methods include:

• set_levels, set_nlevels, set_vmin, set_vmax: Control the color scale and data range.
• set_cmap: Set the colormap.
• visualize and plot: Render the data.

Map

Used to render spatial layers. Methods include:

• set_data, set_contour, set_contourf: Add data layers.
• set_geometry, set_shapefile: Add vector layers.
• set_topography: Add terrain layers.
• set_scale_bar: Add a scale bar to the map.

Upon the first import, Salem creates a hidden directory named .salem_cache in your home folder.

This directory serves several purposes:

• Downloading Salem's demo files and standard shapefiles.
• Storing results of slow operations (via joblib), such as reading/transforming shapefiles.
• Caching downloaded Google Maps.

If the cache becomes excessively large, it can be safely deleted.

The Grid class is a core component of Salem used to represent spatial grids. It includes attributes for projection (proj), dimensions (nx, ny), resolution (dx, dy), and spatial extent/origin.

Key capabilities include:

• Spatial transformations: Convert between grid indices and coordinates using ij_to_crs or transform.
• Data mapping: Use map_gridded_data to apply data to the grid.
• Serialization: Export/import grids via to_dict, from_dict, to_json, or from_json.
• Integration: Convert grids to xarray datasets via to_dataset or geometries via to_geometry.

When you need to aggregate higher-resolution data onto a coarser grid, use DatasetAccessor.lookup_transform(). This method creates a lookup table that maps each coarse grid point to the high-resolution points located beneath it.

Aggregation methods:

• The default method is to average the points.
• You can provide any aggregation function, such as np.std or len (to count the number of high-resolution pixels found below a coarse point).

import salem
import numpy as np

dse = salem.open_xr_dataset(salem.get_demo_file('era_interim_tibet.nc'))
ds = salem.open_xr_dataset(salem.get_demo_file('some_coarse_grid.nc'))

# Default: Average aggregation
dsl = dse.salem.lookup_transform(ds)

# Custom: Standard deviation aggregation
dsl_std = dse.salem.lookup_transform(ds, method=np.std)

# Custom: Count pixels
dsl_len = dse.salem.lookup_transform(ds, method=len)

Standard xarray.open_dataset calls on WRF files often result in messy structures because WRF files are not strictly CF-compliant, use exotic coordinate names, and contain staggered variables.

Use salem.open_wrf_dataset to parse these files. This function simplifies the structure by renaming dimensions/coordinates, defining new variables, and removing staggered dimensions to make the dataset easier to work with.

import salem
from salem.utils import get_demo_file

ds = salem.open_wrf_dataset(get_demo_file('wrfout_d01.nc'))