% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ShapeToMask.R
\name{ShapeToMask}
\alias{ShapeToMask}
\title{Convert Shapefile to Mask Array}
\usage{
ShapeToMask(
  shp_file,
  ref_grid = NULL,
  shp_system = "NUTS",
  shp_system_name = NULL,
  reg_ids = NULL,
  reg_names = NULL,
  reg_level = 3,
  lat_dim = NULL,
  lon_dim = NULL,
  savefile = FALSE,
  region = FALSE,
  target_crs = NULL,
  check_valid = FALSE,
  find_min_dist = FALSE,
  max_dist = 50,
  ...
)
}
\arguments{
\item{shp_file}{A character string indicating the shp file path.}

\item{ref_grid}{A character string indicating the path to the reference 
data. Either (1) a netCDF file or (2) a list of lon and lat to provide the 
reference grid points. It is NULL by default.}

\item{shp_system}{A character string containing the Shapefile System Database 
name. The accepted systems are: 'NUTS', 'LAU', and 'GADM'. It is set to 
'NUTS' by default.}

\item{shp_system_name}{A character string indicating the column name of the 
column in where the specified 'reg_ids' will be taken.}

\item{reg_ids}{A character string indicating the unique ID in shapefile. 
It is NULL by default.}

\item{reg_names}{A named list of character string vectors indicating the 
country and the region name. The name of the list stands for the country 
name code and the vector character strings indicate the region name for 
each country. It is NULL by default.}

\item{reg_level}{An integer number from 1 to 3 indicating the 'NUTS' dataset 
level. For other datasets this parameter is not used. One mask can only have 
a unique level. It is set to 3 by default.}

\item{lat_dim}{A character string indicating the latitudinal dimension. If it 
is NULL, the latitudinal name will be searched using an internal function 
with the following possible names: 'lat', 'latitude', 'y', 'j' and 
'nav_lat'. It is NULL by default.}

\item{lon_dim}{A character string indicating the longitudinal dimension. If it 
is NULL, the longitudinal name will be searched using an internal function 
with the following possible names: 'lon', 'longitude', 'x', 'i' and 
'nav_lon'. It is NULL by default.}

\item{savefile}{A logical value indicating wether to save the mask array into 
a NetCDF format file (TRUE) or to return an array (FALSE). It is FALSE by 
default. This functionality is not developed yet.}

\item{region}{A logical value indicating if we want a dimension for the 
regions in the resulting mask array. It is FALSE by default.}

\item{target_crs}{A character string indicating the target 'Coordinate 
Reference System'.}

\item{check_valid}{A logical value that when it is TRUE it uses the function 
'sf::st_make_valid' applied to the shapefile and to the coordinates.}

\item{find_min_dist}{A logical value indicating if we want to look for the 
nearest coordinate between the shapefile region and the reference grid when 
there is no intersection between the shapefile and the reference grid. It is 
FALSE by default.}

\item{max_dist}{A numeric value indicating the maximum distance is accepted 
to the closest gridpoint when there is no intersection between the shapefile 
and the reference grid.}

\item{...}{Arguments passed on to 's2_options' in function 'st_intersection'.
See 's2 package'.}
}
\value{
A multidimensional array containing a mask array with longitude and 
latitude dimensions. If 'region' is TRUE, there will be a dimension for 
the region.
}
\description{
This function reads a shapefile (.shp) containing information about polygonal 
regions. It then transfers the shapefile data into an array and subsets the 
output based on requested region names or IDs. The accepted shapefile 
databases are 'NUTS', 'LAU', and 'GADM', each with its own unique format. 
However, the function can use other shapefiles databases with specifying the 
categories names with the parameter 'shp_system_name'.
}
\details{
To ensure accurate comparison with the shapefile, the function loads a 
reference dataset that provides longitude and latitude information. By 
intersecting each subset of the shapefile with the reference coordinates, the 
function selects only the desired regions. The final step involves creating a 
mask array. Depending on the chosen option, the mask array is either returned 
as the function's output or saved into a NetCDF format in the specified 
directory.

Note: Modules GDAL, PROJ and GEOS are required.
}
\examples{
# Exmple (1): NUTS
shp_file <- paste0('/esarchive/shapefiles/NUTS3/NUTS_RG_60M_2021_4326.shp/', 
                  'NUTS_RG_60M_2021_4326.shp')
# shp_file <- paste0('/esarchive/scratch/cdelgado/focus_outputs/Shapefiles/',
#                    'tza_admbnda_adm1/tza_admbnda_adm1_20181019.shp')
# ref_grid <- paste0('/esarchive/exp/ecmwf/system5c3s/monthly_mean/',
#                    'tas_f6h/tas_20170201.nc')
# ref_grid <- paste0('/esarchive/exp/ecmwf/s2s-monthly_ensfor/weekly_mean/',
#                    'tas_f6h/tas_20191212.nc')
ref_grid <- paste0('/esarchive/recon/ecmwf/era5land/monthly_mean/',
                  'tas_f1h/tas_201006.nc')
# ref_grid <- list(lon = seq(10, 40, 0.5), lat = seq(40, 85, 0.5))

NUTS.id <- paste0("FI1D", c(1:3, 5, 7:9))  
NUTS.name <- list(FI = c('Lappi', 'Kainuu'), SI = c('Pomurska', 'Podravska'))
mask1 <- ShapeToMask(shp_file, ref_grid, reg_ids = NUTS.id)
mask2 <- ShapeToMask(shp_file = shp_file, ref_grid = ref_grid, 
                    reg_names = NUTS.name)

# Exmple (2): GADM
shp_file <- "/esarchive/shapefiles/gadm_country_mask/gadm_country_ISO3166.shp"
ref_grid <- paste0('/esarchive/exp/ecmwf/s2s-monthly_ensfor/weekly_mean/',
                  'tas_f6h/tas_20191212.nc')
GADM.id <- c("ESP", "ITA")
GADM.name <- c("Spain", "Italy")
mask1 <- ShapeToMask(shp_file = shp_file, ref_grid = ref_grid, 
                    reg_ids = GADM.id, shp_system = "GADM")
mask2 <- ShapeToMask(shp_file = shp_file, ref_grid = ref_grid, 
                    reg_names = GADM.name, shp_system = "GADM")
}
