utils.obs.ObsGridMapping

Import path: earth2studio.utils.obs.ObsGridMapping

View source on GitHub

Documentation

Maps point observations to and from a 2-D model grid.

Supports regular (1-D lat/lon axes) and irregular (2-D lat/lon) grids. CuPy is used automatically when available and the target device is a GPU.

Parameters:

• grid_variables (ndarray) –

  Ordered array of variable names that define the channel dimension.

• grid_lat (ndarray or Tensor) –

  Latitude coordinates. Shape (H,) for a regular grid or (H, W) for an irregular grid.

• grid_lon (ndarray or Tensor) –

  Longitude coordinates. Shape (W,) for a regular grid or (H, W) for an irregular grid. Values are expected in [0, 360).

• device (torch.device, str, or None, default: None ) –

  Target device. Inferred from grid_lat when it is a torch.Tensor; defaults to CPU otherwise.

Raises:

• ValueError –

  If grid_lat is neither 1-D nor 2-D.

obs_coords

obs_coords(
    obs_var: ndarray,
    obs_lat: ndarray,
    obs_lon: ndarray,
    remove_out_of_bounds: bool = True,
) -> tuple[Tensor, Tensor, Tensor, Tensor]

Convert observation locations to fractional grid indices.

Parameters:

• obs_var (ndarray) –

  Variable name for each observation.

• obs_lat (ndarray) –

  Latitude of each observation in degrees.

• obs_lon (ndarray) –

  Longitude of each observation in degrees, in [0, 360).

• remove_out_of_bounds (bool, default: True ) –

  When True (default), observations outside the grid or with an unknown variable are removed from the returned arrays. The full boolean mask is always returned as the fourth element.

Returns:

• obs_c ( Tensor ) –

  Channel index for each (retained) observation.

• obs_i ( Tensor ) –

  Fractional row index in the grid for each observation.

• obs_j ( Tensor ) –

  Fractional column index in the grid for each observation.

• obs_in_bounds ( Tensor ) –

  Boolean mask of length N indicating which of the original observations are in-bounds and have a known variable.

obs_to_grid

obs_to_grid(
    obs: DataFrame | None,
    variables: list[str] | None = None,
    request_time: datetime64 | None = None,
    time_tolerance: (
        timedelta64 | tuple[timedelta64, timedelta64] | None
    ) = None,
    return_empty_grid: bool = False,
) -> tuple[Tensor, Tensor] | tuple[None, None]

Bin point observations onto the model grid.

Observations are filtered to variables and to those within time_tolerance of request_time. Multiple observations that fall in the same grid cell are averaged.

Parameters:

• obs (DataFrame or None) –

  Observation table with columns variable, lat, lon, observation. If request_time is used, obs must also have a time column.

• variables (list[str], default: None ) –

  Variable names to retain; others are discarded. None (default) uses all variables.

• request_time (datetime64, default: None ) –

  Target valid time for the observations. None (default) skips time filtering.

• time_tolerance ((timedelta64, tuple[timedelta64, timedelta64]), default: None ) –

  Time window used to filter observations around request_time. A single np.timedelta64 creates a symmetric window [-time_tolerance, +time_tolerance]. A 2-tuple (lower, upper) is passed directly to filter_time_range as an asymmetric window. None (default) skips time filtering.

• return_empty_grid (bool, default: False ) –

  When True, return zero-filled tensors instead of (None, None) when no observations are gridded. Defaults to False.

Returns:

• y_obs ( Tensor or None ) –

  Gridded observations, shape (1, C, H, W), or None when no observations remain and return_empty_grid is False.

• mask ( Tensor or None ) –

  Observation count per cell (float), same shape as y_obs, or None under the same condition as above.

grid_to_obs

grid_to_obs(
    x: Tensor,
    obs_c: Tensor,
    obs_i: Tensor,
    obs_j: Tensor,
    method: Literal["nearest", "linear"] = "linear",
) -> Tensor

Sample grid values at observation locations (differentiable).

Parameters:

• x (Tensor) –

  Grid tensor of shape (C, H, W).

• obs_c (Tensor) –

  Channel index for each observation.

• obs_i (Tensor) –

  Fractional row index for each observation.

• obs_j (Tensor) –

  Fractional column index for each observation.

• method ((nearest, linear), default: "nearest" ) –

  Interpolation method. "linear" (default) performs bilinear interpolation and supports gradient backpropagation.

Returns:

• Tensor –

  Sampled values, shape (N,).

Raises:

• ValueError –

  If method is not "nearest" or "linear".