arlmet.File.sample_points#

File.sample_points(points, variables, *, time=None, z_kind='pressure', method='linear', earth_relative=False, model_top=25000.0)[source]#

Sample fields from this file at arbitrary lon/lat/z points.

Equivalent to arlmet.sample_points() with this file as the only input.

Parameters:

  • points (DataFrame | Mapping[str, Any]) – Table-like object with lon, lat (degrees), and z columns, and optionally a time column. Any other columns are carried through to the result unchanged.

  • variables (str | Iterable[str]) – One or more ARL field names (e.g. "TEMP", "UWND"), or "pressure" for the virtual pressure variable. A name must not collide with an existing column of points. On a WRF file with mass-coupled winds (MUU0, MUV0) UWND, VWND and WWND are decoupled as HYSPLIT does (UWND * MSFU / MUU0, …), and on a file with THET but no TEMP, TEMP is THET * (PRES / 1000) ** 0.286.

  • time (Timestamp | str | None) – One valid time for every point, used when points has no time column. Passing both raises ValueError. When neither is given, the file must contain exactly one time, which is used.

  • z_kind (Literal['native', 'pressure', 'agl', 'msl']) –

    Vertical coordinate system of the z values:

    • "native": fractional ARL level index.

    • "pressure": hPa. Sigma/hybrid files (flag 1/4) need PRSS, and sigma files use the PRES field when they have it; pressure files (flag 2) use the stored levels; terrain-following files (flag 3) raise ValueError; WRF files (flag 5) use the PRES field.

    • "agl": meters above ground level. Sigma/hybrid/WRF files integrate hypsometrically from the ground (PRSS, T02M) through each level’s pressure (PRES on WRF files) with the virtual temperature (TEMP with SPHU or RELH), as HYSPLIT’s prfsig and prfecm do; pressure files use HGTS - SHGT from the ground up; terrain-following files scale the stored levels as HYSPLIT’s prfter does (with model_top=None, the stored levels as they are).

    • "msl": meters above mean sea level, taken as the height above the ground at the point (less SHGT there), then as "agl". Every file needs SHGT.

    Each vertical coordinate system has exactly one method, as in HYSPLIT; there is no fallback between them. On sigma, hybrid and WRF files, and on pressure-level files at heights, level 0 is the ground: a point between it and the first level is interpolated from the ground values (PRSS for PRES, T02M for TEMP, U10M/V10M for winds), and pressure is interpolated as ln p, as HYSPLIT does. Where the first level is below the ground (its PRES above PRSS) the ground values are passed over, as in HYSPLIT. The Vertical Coordinates guide has the details.

  • method (Literal['linear', 'nearest']) – Horizontal interpolation: bilinear or nearest grid point. At heights ("agl", "msl"), as in HYSPLIT, the column at each of the four grid points around a point is interpolated to the point’s z first, with that grid point’s own ground and level heights, and the four values are then blended; a grid point whose column ends below z does not count, and the others are reweighted. At pressures and native levels each level is blended first, as before. On a WRF file (source AWRF) UWND and VWND are read where WRF’s staggered grid holds them, half a cell east and north of each point, as HYSPLIT reads them; “nearest” gives the winds at the nearest cell’s center. The Sampling guide has the details.

  • earth_relative (bool) – Rotate sampled wind pairs (UWND/VWND, U10M/V10M) from the grid axes to east/north. Winds in ARL files on projected grids are stored grid-relative, as HYSPLIT expects. Both components of a pair must be requested. No effect on lat/lon grids.

  • model_top (float | None) – The HYSPLIT run’s top of model domain [m] (the CONTROL file’s, PYSTILT’s z_top). At heights the values are the ones a HYSPLIT run with that top uses, on its internal levels; the default is PYSTILT’s default top. None reads each grid point’s column at the point’s own height instead, which is not HYSPLIT’s value. See arlmet.sample_points().

Returns:

Copy of points (all columns and the index preserved) with one added column per requested variable. Points outside the grid or the vertical range are NaN.

Return type:

DataFrame

Raises:

ValueError – If a required column is missing, time is given alongside a time column, no time is given for a multi-time file, a point time is not in the file, a variable name collides with a column of points, z_kind or method is invalid, a field that z_kind requires is missing, or model_top is passed with z_kind "pressure" or "native" or is not a positive number.

Examples

>>> import pandas as pd
>>> import arlmet
>>> pts = pd.DataFrame({"lon": [-111.9], "lat": [40.7], "z": [850.0]})
>>> with arlmet.File("met.arl") as met:
...     out = met.sample_points(pts, ["UWND", "VWND"], time="2024-07-18 00:00")
>>> out.round(1)
     lon   lat      z  UWND  VWND
0 -111.9  40.7  850.0   6.2  -3.8