composite_about_extrema#

rojak.atmosphere.compositing.composite_about_extrema(target_data, extrema_data, *, time_dim_name='time', num_extrema_dim='n_extrema', lat_dim_name='latitude', lon_dim_name='longitude', vert_dim_name=None, max_km_extent=2000, grid_km_spacing=25, int_for_center=2, is_only_extrema_region=False)[source]#

Composite a geophysical field onto a common km-scale grid centred on each extremum.

For every extremum recorded in extrema_data, the corresponding timestep of target_data is extracted and re-projected onto a regular Cartesian grid (in km) centred on that extremum using a WGS-84 orthographic projection. The result is a stack of re-projected fields - one per extremum - that can subsequently be averaged to produce a mean composite structure.

Optionally supports a vertical dimension, in which case the re-projection is applied independently at each level via xarray.apply_ufunc() with vectorize=True.

Parameters:

  • target_data (xr.DataArray) – Geophysical field to composite. Must contain at minimum the dimensions lat_dim_name, lon_dim_name, and time_dim_name. If vert_dim_name is provided, that dimension must also be present.

  • extrema_data (xr.DataArray) – Per-extremum mask array, as returned by identify_and_stack_circular_extrema(). Must contain: 1) Dimensions num_extrema_dim, lat_dim_name, lon_dim_name, and 2) a time coordinate indexed by num_extrema_dim that maps each extremum to its source timestamp in target_data.

  • time_dim_name (str) – Name of the time dimension in target_data and the time coordinate in extrema_data. Defaults to "time".

  • num_extrema_dim (str) – Name of the dimension in extrema_data that indexes individual extrema. Defaults to "n_extrema".

  • lat_dim_name (str) – Name of the latitude dimension. Defaults to "latitude".

  • lon_dim_name (str) – Name of the longitude dimension. Defaults to "longitude".

  • vert_dim_name (str, optional) – Name of the vertical dimension in target_data (e.g. "level"). If None, the input is treated as purely 2D in space. Defaults to None.

  • max_km_extent (float) – Half-width of the output Cartesian grid in kilometres. The grid spans [-max_km_extent, +max_km_extent] in both x and y. Defaults to 2000.

  • grid_km_spacing (float) – Spacing between output grid points in kilometres. Defaults to 25.

  • int_for_center (int) – Pixel value in extrema_data that marks an extremum centre. Forwarded to _project_data_about_extrema(). Defaults to 2.

  • is_only_extrema_region (bool) – If True, pixels in target_data that fall outside the labelled extremum region (i.e. where extrema_data == 0) are masked to NaN before compositing. Defaults to False.

Returns:

Composited field with dimensions (n_extrema, [vert_dim_name,] y_km, x_km) and coordinates:

  • n_extrema - integer index for each extremum.

  • time - source timestamp of each extremum, attached to n_extrema.

  • y_km, x_km - symmetric kilometre-coordinate arrays spanning [-max_km_extent, +max_km_extent] with spacing grid_km_spacing.

  • vert_dim_name - vertical coordinate values, if applicable.

Return type:

xr.DataArray

Raises:

  • ValueError – If target_data or extrema_data do not contain the required latitude and longitude dimensions.

  • ValueError – If vert_dim_name is specified but absent from target_data.

  • ValueError – If num_extrema_dim is absent from extrema_data.

  • ValueError – If num_extrema_dim of extrema_data has size 0, i.e. there are no extrema.

  • ValueError – If time_dim_name is absent from target_data or from the coordinates of extrema_data.

  • ValueError – If num_extrema_dim is not a dimension of extrema_data[time_dim_name].