stilt.sampling.sample_field#

stilt.sampling.sample_field(field, x, y, z=None, times=None, fill_value=nan, step_starts=False)[source]#

Return the field’s value in the cell nearest each point.

A point outside the field horizontally, or in a missing cell, gives fill_value. Longitudes are wrapped to the field’s convention (-180 to 180 or 0 to 360).

Parameters:

  • field (DataArray) – Field with horizontal dimensions (lat and lon, or y and x), and optionally a vertical dimension and time.

  • x (ArrayLike) – Point coordinates: longitude and latitude for a lat/lon field.

  • y (ArrayLike) – Point coordinates: longitude and latitude for a lat/lon field.

  • z (ArrayLike | None) – Vertical coordinate of each point, in the units of the field’s vertical dimension. Required when the field has one. Matched to the nearest level, so a point above the top level takes the top level.

  • times (ArrayLike | None) – Time of each point. Required when the field has a time dimension. By default matched to the nearest time, so times outside the field’s span take the first or last step. See step_starts.

  • fill_value (float) – Value for points outside the field and for missing cells. Use 0 for a surface flux, where no data means no emission. NaN suits a mole fraction, which is unknown there.

  • step_starts (bool) – Whether the field’s time labels are the starts of steps, as a flux inventory’s are. A point then takes the last step that starts at or before its time, the rule of foot.stilt.aggregate and project.jacobian. A point before the first label takes fill_value and a point after the last takes the last step, since the labels do not say where it ends. The labels must strictly increase: a repeated label is an error.

Returns:

One value per point.

Return type:

ndarray