composite_about_points#

rojak.atmosphere.compositing.composite_about_points(target_data, centres, *, time_dim_name='time', lat_dim_name='latitude', lon_dim_name='longitude', vert_dim_name=None, group_dim_name=None, time_column='time', lat_column='latitude', lon_column='longitude', vert_column=None, carry_columns=(), time_tolerance=None, max_km_extent=2000, grid_km_spacing=25, interpolation=CompositeInterpolation.BILINEAR, max_centres_per_task=500, centre_dim_name='n_centre', lat_lon_buffer=0.5)[source]#

Composite a geophysical field onto a common km-scale grid centred on each row of a dataframe.

This is the counterpart of composite_about_extrema() for when the centres are arbitrary points (e.g. observations) stored in a dask.dataframe.DataFrame rather than extrema on the grid of target_data. For each centre, the nearest time step (and, if vert_dim_name is given, nearest vertical level) of target_data is re-projected onto a regular Cartesian grid (in km) centred on that point using a WGS-84 orthographic projection.

Rather than expanding target_data to have one slice per centre, the centres are grouped by the chunks of target_data along group_dim_name (time by default, or the vertical dimension). The centres are shuffled so that partition i of the dataframe contains exactly the centres whose nearest time step (or vertical level) lies in chunk i of target_data. Each output block is computed by a single task that depends only on its block of centres and the one matching chunk, which keeps the graph small: every task refers to existing chunks by key and no data is duplicated or embedded in the graph.

Note

The only computation triggered is the number of centres per chunk, an integer per chunk, which is needed for the shape of the output. Persist centres beforehand if it is expensive to compute.

The centres in the output are sorted by their index along group_dim_name, not in the order of centres. Use carry_columns to keep an identifier.

Parameters:

  • target_data (xr.DataArray) – Geophysical field to composite with dimensions time_dim_name, lat_dim_name, lon_dim_name and optionally vert_dim_name. It should be chunked along group_dim_name only; other dimensions are rechunked to a single chunk.

  • centres (dask.dataframe.DataFrame) – Centres to composite about. Must contain time_column, lat_column, lon_column (and vert_column if vert_dim_name is given) as columns.

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

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

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

  • vert_dim_name (str, optional) – Name of the vertical dimension in target_data. The level nearest to the centre’s vert_column value is used. Defaults to None.

  • group_dim_name (str, optional) – Dimension of target_data whose chunks the centres are grouped by. Must be either time_dim_name or vert_dim_name, as each centre selects a single slice along these. Each task loads one chunk along this dimension and all of the other dimensions, so it should be the dimension target_data is chunked along. If None, time_dim_name is used. Defaults to None.

  • time_column (str) – Column with the time of each centre. Naive times are assumed to be UTC. Defaults to "time".

  • lat_column (str) – Column with the latitude of each centre in degrees. Defaults to "latitude".

  • lon_column (str) – Column with the longitude of each centre in degrees. Defaults to "longitude".

  • vert_column (str, optional) – Column with the vertical position of each centre in the same units as target_data[vert_dim_name]. Required if vert_dim_name is given. Defaults to None.

  • carry_columns (Sequence[str]) – Additional columns of centres to attach as coordinates along centre_dim_name, e.g. a cluster label. Defaults to ().

  • time_tolerance (numpy.timedelta64, optional) – Centres further than this from the nearest time step are dropped, e.g. np.timedelta64(30, "m"). If None, all centres are kept. Defaults to None.

  • max_km_extent (float) – Half-width of the output Cartesian grid in kilometres. Defaults to 2000.

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

  • interpolation (CompositeInterpolation) – Interpolation scheme. Use CompositeInterpolation.GRIDDATA for the same results as composite_about_extrema(). Defaults to CompositeInterpolation.BILINEAR.

  • max_centres_per_task (int) – Maximum number of centres in a single output block. Bounds the memory of each task to roughly max_centres_per_task * n_km**2 * 8 bytes. Defaults to 500.

  • centre_dim_name (str) – Name of the output dimension indexing the centres. Defaults to "n_centre".

  • lat_lon_buffer (float) – Only used by CompositeInterpolation.GRIDDATA. See _project_data_about_extrema(). Defaults to 0.5.

Returns:

Dask-backed composited field with dimensions (centre_dim_name, y_km, x_km) and coordinates:

  • y_km, x_km - symmetric kilometre-coordinate arrays.

  • time_dim_name - time step of target_data used for each centre.

  • vert_dim_name - vertical level of target_data used for each centre, if applicable.

  • centre_latitude, centre_longitude - location of each centre.

  • Each of carry_columns.

Return type:

xr.DataArray

Raises:

  • ValueError – If group_dim_name is not a dimension of target_data, is a horizontal dimension, or is neither time_dim_name nor vert_dim_name.

  • ValueError – If target_data does not have exactly the specified dimensions.

  • ValueError – If only one of vert_dim_name and vert_column is specified.

  • ValueError – If a required column is missing from centres.

  • ValueError – If there are no centres to composite about.