arlmet.sample_points#

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

Sample meteorological variables at arbitrary (lon, lat, z, time) points.

Accepts a single ARL file or a sequence of files spanning different time periods. Each may be an open File or a path to an ARL file; paths are opened (read mode) and closed automatically, while already-open Files are left open for the caller to manage. Each point is sampled from the file that contains its valid time.

Parameters:

  • files (File, path-like, or sequence of File or path-like) – A single open File or path, or a sequence of Files and/or paths. Each valid time must appear in at most one file.

  • points (pandas.DataFrame or mapping) – 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 or iterable of 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.

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

  • z_kind ({"pressure", "native", "agl", "msl"}, default "pressure") – Vertical coordinate system of the z values. See arlmet.File.sample_points() for the method each vertical coordinate system uses and the fields it requires.

  • method ({"linear", "nearest"}, default "linear") – Horizontal interpolation: bilinear or nearest grid point.

  • earth_relative (bool, default False) – Rotate sampled wind pairs (UWND/VWND, U10M/V10M) from the grid axes to east/north, using the meridian convergence of each file’s grid. Both components of a pair must be requested. No effect on lat/lon grids.

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:

pandas.DataFrame

Raises:

ValueError – If a required column is missing, time is given alongside a time column, no time is given and the inputs hold more than one time, a point time is in none of the files, a time is in more than one file, a variable name collides with a column of points, z_kind or method is invalid, or a field that z_kind requires is missing.

Examples

>>> import pandas as pd
>>> import arlmet
>>> points = pd.DataFrame(
...     {"lon": [-111.9], "lat": [40.7], "z": [850.0], "time": ["2024-07-18 00:00"]}
... )
>>> arlmet.sample_points("met.arl", points, ["UWND", "VWND"])

Sample across files spanning different times by passing their paths:

>>> arlmet.sample_points(["met_00.arl", "met_06.arl"], points, ["UWND", "VWND"])