Geographic transformation of gridded data — geo

Gridded data can be transformed from one grid definition to another, to geographic points, to cross sections, to sub-domains of the original grid, or zoomed into the original a grid. The geo_<transformation> functions are used to achieve this, while the generalized function geo_transform is designed to be used in functions that will take the transformation as an argument.

Usage

geo_points(
  x,
  points,
  method = c("bilinear", "nearest", "bicubic"),
  mask = NULL,
  force = FALSE,
  weights = NULL,
  keep_weights = FALSE
)

geo_regrid(
  x,
  new_grid,
  method = c("bilinear", "nearest", "bicubic"),
  mask = NULL,
  new_mask = NULL,
  weights = NULL,
  keep_weights = FALSE
)

geo_subgrid(x, i1, i2, j1, j2)

geo_zoom(x, centre_lon, centre_lat, length_x, length_y)

geo_xsection(
  x,
  p1,
  p2,
  n = 100,
  method = c("bilinear", "nearest", "bicubic"),
  weights = NULL,
  keep_weights = FALSE
)

geo_upscale(
  x,
  factor,
  method = "mean",
  downsample_location = "bottom_left",
  ...
)

geo_transform(
  x,
  trans = c("points", "regrid", "subgrid", "zoom", "xsection"),
  opts
)

Arguments

x: A geofield, geolist, or a data frame with class harp_grid_df. For transformations that do not involve the interpolation of gridded data (e.g. zoom, subgrid) x can also be a geodomain.
points: A data frame of geographic points to which to interpolate the gridded data. The data frame must include the columns "SID" for a unique id for the point, "lon" for the longitude of the point in decimal degrees and "lat" for the latitude of the point in decimal degrees. The data frame can contain other columns, which will be retained in the output.
method: The interpolation method. Can be "nearest" for nearest neighbour, "bilinear", or "bicubic." The default is "bilinear". For geo_upscale, can be any function that summarises a vector to a single value and can found with match.fun, the default being "mean". A further option is "downsample", dwhich is described in the argument for downsample_location.
mask: A mask to prevent grid points being used in the interpolation. Should be on the same grid as x and grid points with values of 0 or FALSE will be masked from the interpolation.
force: For interpolations that include a mask, it is possible that a point will be surrounded by 4 masked points. In this case the mask will be ignored and all 4 points used in the interpolation (the default). Set force = TRUE to force the mask to be applied and set the interpolated to NA.
weights: Pre-computed weights for the interpolation. Should be the output from the appropriate geo_weights function.
keep_weights: Whether to keep weights in the output. If set to TRUE, the return object will have a "weights" attribute.
new_grid: A geofield or geodomain on the grid that x should be regridded to. define_domain can be used to define a new geodomain.
new_mask: A geofield on the same grid as new_grid with grid points that should not be interpolated to set to 0 or FALSE.
i1: The x index of the western side of the sub domain.
i2: The x index of the eastern side of the sub domain.
j1: The y index of the southern side of the sub domain.
j2: The y index of the northern side of the sub domain.
centre_lon: The longitude in decimal degrees of the centre of the zoomed grid.
centre_lat: The latitude in decimal degrees of the centre of the zoomed grid.
length_x: The number of grid squares from west to east of the zoomed grid. If an even number is used, it will be extended by 1 since the zoomed grid should be centred on the grid square containing (centre_lat, centre_lon).
length_y: The number of grid squares from south to north of the zoomed grid. If an even number is used, it will be extended by 1 since the zoomed grid should be centred on the grid square containing (centre_lat, centre_lon).
p1: The geographic location in decimal degrees of the start of the section. Should be a vector of length 2 with the first value being the longitude and the second value the latitude.
p2: The geographic location in decimal degrees of the end of the section. Should be a vector of length 2 with the first value being the longitude and the second value the latitude.
n: The number of equally spaced points along the section. The default is 100.
factor: An integer by which to upscale the data. Can be of length 2 to achieve different upscaling in the x and directions.
downsample_location: When "downsample" is the chosen method, each pixel in the upscaled field is sampled from a pixel from the original field that is inside the upscaled pixel. The location of that pixel can be one of "bottom_left", "bottom_centre", "bottom_right", "left_centre", "centre", "right_centre", "top_right", "top_centre", "top_left" or "random".
...: Extra options for method.
trans: The transformation to apply. Can be "points", "regrid", "xsection", "subgrid", or "zoom".
opts: A list of options for the chosen transformation. The appropriate geo_opts function should be used to generate this list.

Value

In the case of transformations to points and cross sections, a data frame. In all other cases an object of the same class as x with the transformation applied.

Details

geo_points is used to interpolate from a regular grid to geographic points within the domain of the grid
geo_regrid is used to interpolate from one regular grid to another regular grid. This can include reprojection from one grid projection to another.
geo_xsection extracts an equally spaced straight line of points between to geographic locations and cen be used to construct a vertical cross section of a 3-dimensional field. For grids that are equally space in longitude - latitude coordinates (e.g. latlong projections) the section can be along a great circle and thus the shortest distance between the two points.
geo_subgrid extracts a sub domain of the data without changing the coordinate reference system.
geo_zoom is a special case of geo_subgrid whereby a sub domain of the data is extracted centred around a geographic point.
geo_upscale upscales data from a higher resolution grid to a coarser resolution grid using an integer upscaling factor. The default method is to take the mean of all high resolution pixels inside each coarse resolution pixels, though sampling using the "downsample" method is faster and likely sufficient for upscaling for raster raster plotting.
geo_transform is a generalized function that can be used in functions that take the type of geographic transformation as an argument.

For transformations that require the interpolation of data (points, regrid and xsection), the method of interpolation can be chosen. The available interpolation methods are nearest neighbour, bilinear and bicubic. In addition, masks can be used to prevent grid points being used in the interpolation - for example if you have a land-sea mask, grid points with a value of 0 or FALSE will not be used in the interpolation.