herbie.accessors.HerbieAccessor

class herbie.accessors.HerbieAccessor(xarray_obj)

Accessor for xarray Datasets opened with Herbie.

__init__(xarray_obj)

Methods

__init__(xarray_obj)
nearest_points(points[, names, verbose])	Get the nearest latitude/longitude points from a xarray Dataset.
pick_points(points[, method, k, ...])	Pick nearest neighbor grid values at selected points.
plot([ax, common_features_kw, vars])	Plot data on a map.

Attributes

center	Return the geographic center point of this dataset.
crs	Cartopy coordinate reference system (crs) from a cfgrib Dataset.
polygon	Get a polygon of the domain boundary.

Methods:

__init__(xarray_obj)
nearest_points(points[, names, verbose])	Get the nearest latitude/longitude points from a xarray Dataset.
pick_points(points[, method, k, ...])	Pick nearest neighbor grid values at selected points.
plot([ax, common_features_kw, vars])	Plot data on a map.

Attributes:

center	Return the geographic center point of this dataset.
crs	Cartopy coordinate reference system (crs) from a cfgrib Dataset.
polygon	Get a polygon of the domain boundary.

__init__(xarray_obj)

property center

Return the geographic center point of this dataset.

property crs

Cartopy coordinate reference system (crs) from a cfgrib Dataset.

Projection information is from the grib2 message for each variable.

Parameters:

ds (xarray.Dataset) – An xarray.Dataset from a GRIB2 file opened by the cfgrib engine.

nearest_points(points, names=None, verbose=True)

Get the nearest latitude/longitude points from a xarray Dataset.

• Stack Overflow: https://stackoverflow.com/questions/58758480/xarray-select-nearest-lat-lon-with-multi-dimension-coordinates

• MetPy Details: https://unidata.github.io/MetPy/latest/tutorials/xarray_tutorial.html?highlight=assign_y_x

Parameters:

• ds (xr.Dataset) – A Herbie-friendly xarray Dataset

• points (tuple, list of tuples, pd.DataFrame) –

  Points to be plucked from the gridded Dataset. There are multiple objects accepted.

  1. Tuple of longitude and latitude (lon, lat) coordinate pair. 1. List of multiple (lon, lat) coordinate pair tuples. 1. Pandas DataFrame with longitude and latitude columns. Index will be used as point names, unless names is specified. 1. Shapeley Point or Points

• names (list) – A list of names for each point location (i.e., station name). None will not append any names. names should be the same length as points.

Notes

This is much faster than my old “pluck_points” method. For matching 1,948 points: - nearest_points completed in 7.5 seconds. - pluck_points completed in 2 minutes.

TODO: Explore alternatives - Could Shapely nearest_points be used https://shapely.readthedocs.io/en/latest/manual.html#nearest-points - Or possibly scipy BallTree method.

pick_points(points, method='nearest', *, k=None, max_distance=500, use_cached_tree=True, tree_name=None, verbose=False)

Pick nearest neighbor grid values at selected points.

Parameters:

• points (Pandas DataFrame) – A DataFrame with columns ‘latitude’ and ‘longitude’ representing the points to match to the model grid.

• method ({'nearest', 'weighted'}) –

  Method used to pick points. - nearest : Gets grid value nearest the requested point. - weighted: Gets four grid value nearest the requested

  point and compute the inverse-distance-weighted mean.

• k (None or int) – If None and method is nearest, k=1. If None and method is weighted, k=4. Else, specify the number of neighbors to find.

• max_distance (int or float) – Maximum distance in kilometers allowed for nearest neighbor search. Default is 500 km, which is very generous for any model grid. This can help the case when a requested point is off the grid.

• use_cached_tree ({True, False, "replant"}) –

  Controls if the BallTree object is caches for later use. By “plant”, I mean, “create a new BallTree object.” - True : Plant+save BallTree if it doesn’t exist; load

  saved BallTree if one exists.

  • False: Plant the BallTree, even if one exists.

  • ”replant” : Plant a new BallTree and save a new pickle.

• tree_name (str) – If None, use the ds.model and domain size as the tree’s name. If ds.model does not exists, then the BallTree will not be cached, unless you provide the tree_name.

Examples

>>> H = Herbie("2024-03-28 00:00", model="hrrr")
>>> ds = H.xarray("TMP:[5,6,7,8,9][0,5]0 mb", remove_grib=False)
>>> points = pd.DataFrame(
...     {
...         "longitude": [-100, -105, -98.4],
...         "latitude": [40, 29, 42.3],
...         "stid": ["aa", "bb", "cc"],
...     }
... )

Pick value at the nearest neighbor point >>> dsp = ds.herbie.pick_points(points, method=”nearest”)

Get the weighted mean of the four nearest neighbor points >>> dsp = ds.herbie.pick_points(points, method=”weighted”)

A Dataset is returned of the original grid reduced to the requested points, with the values from the points dataset added as new coordinates.

A user can easily convert the result to a Pandas DataFrame >>> dsp.to_dataframe()

If you want to select points by a station name, swap the dimension. >>> dsp = dsp.swap_dims({“point”: “point_stid”})

plot(ax=None, common_features_kw={}, vars=None, **kwargs)

Plot data on a map.

Parameters:

vars (list) – List of variables to plot. Default None will plot all variables in the DataSet.

property polygon

Get a polygon of the domain boundary.