ShapeToMask developments

This issue is to keep track of the developments of the function ShapeToMask. This function was created by @aho that described the first version here: #2 (closed).

Functionality
This function takes as input a shapefile and a reference grid (NetCDF or list of lat and lon vectors) and creates a mask array with the shaded regions from the intersection of the grid points and the region.

Examples

• Example of NUTS and LAU: https://earth.bsc.es/gitlab/aho/aho-testtest/-/blob/master/shapefile/example.R
• Example of GADM: https://earth.bsc.es/gitlab/erifarov/eva-r-project/-/blob/main/shapefile/example-shapetomask.R

Current functionality

• Take one .shp file (shp.file) and one .nc file or a list of lon/lat (ref.grid) as grid reference, specify the desired shape regions, find the corresponding grid points for each region and generate a mask array. If region is FALSE: with the value 0 (no shp), 1 (1st region), 2 (2nd region), etc. If region is TRUE: a 3 dimensional mask array with dimensions: lat, lon and region; the values will be 1 for each region.
• If you want to subset specific regions:
  • (a) Using shp.system: the function currently consider shapefile systems "NUTS", "ADM" and "GADM".
    • There are two ways to specify the shape regions: (1) Use reg.ids, which is the unique ID of each region (2) Use reg.names, which is a list that contains the country names as the list name and the region vector under each country. This method is less secure because the region name may not be unique;
    • The parameter level is for NUTS system since it has 3 levels. If you use reg.names as input, this param can make the shape search more secure. Can only choose one level (1, 2, or 3)
    • reg.ids is prior to reg.names if both are provided.
    • One problem of using reg.names is that some names have alphabets that cannot be recognized by the function, so copy&paste the names may not work well.
  • (b) Using shp_col_name_idsspecifying the column name of the shapefile. For this case, the shp.system is not used. To subset the regions, reg.ids is used.
• For the reference grid, lat_dim and lon_dim can be provided; but if not, the function will try to look for the correct longitude/latitude dimension names and get the values.

Next developments:

• Parallel computation with multiple cores
• Add initial checks
• Add unit test (can be improved)
• Add saving option