ebv_create_taxonomy: Create an EBV netCDF with taxonomy

In ebvcube: Working with netCDF for Essential Biodiversity Variables

Create an EBV netCDF with taxonomy

Description

Create the core structure of the EBV netCDF based on the json from the EBV Data Portal. Additionally, you can add the hierarchy of the taxonomy. This is not provided in the ebv_create() function. Use the ebv_create() function if your dataset holds no taxonomic information. Data will be added afterwards using ebv_add_data().

Usage

ebv_create_taxonomy(
  jsonpath,
  outputpath,
  taxonomy,
  taxonomy_key = FALSE,
  epsg = 4326,
  extent = c(-180, 180, -90, 90),
  resolution = c(1, 1),
  timesteps = NULL,
  fillvalue,
  prec = "double",
  sep = ",",
  force_4D = TRUE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

jsonpath	Character. Path to the json file downloaded from the EBV Data Portal. Login to the page and click on 'Uploads' and 'New Upload' to start the process.
outputpath	Character. Set path where the netCDF file should be created.
taxonomy	Character. Path to the csv table holding the taxonomy. Default: comma-separated delimiter, else change the sep argument accordingly. The csv needs to have the following structure: The header displays the names of the different taxonomy levels ordered from the highest level to the lowest, e.g. "order", "family", "genus", "scientificName". We strongly encourage the usage of the Darwin Core terminology for the taxonomy levels. The last column (if taxonomy_key=FALSE) is equivalent to the entity argument in the ebv_create() function. Each row of the csv corresponds to a unique entity. In case the taxonomy_key argument (see below) is set to TRUE, this table gets an additional last column which holds the taxonomy key per entity - in this case the second last column contains the entity names, e.g. the following column order: "order", "family", "genus", "scientificName", "taxonomy_key". The last column (here named "taxonomy_key") should have the exact name of the taxonomy key from the authority of the taxonomic backbone. It will be added as an additional attribute to the netCDF. For example, if your taxonomy is based on the GBIF Backbone Taxonomy the column name could be "usageKey". For an example CSV including the taxonomy_key download the 'Entities as CSV' from the Occurrence Metrics for the Birds Directive Annex I Species in EU27 dataset of the portal. For an example without taxonomy_key, download Species habitat suitability of European terrestrial vertebrates for contemporary climate and land use. To create your netCDF follow the same structure. The column names may be different depending on the taxonomy used.
taxonomy_key	Logical. Default: FALSE. Set to TRUE if the last column in your taxonomy csv file defines the taxonomy_key for each entity.
epsg	Integer. Default: 4326 (WGS84). Defines the coordinate reference system via the corresponding epsg code.
extent	Numeric. Default: c(-180,180,-90,90). Defines the extent of the data: c(xmin, xmax, ymin, ymax).
resolution	Numerical. Vector of two numerical values defining the longitudinal and latitudinal resolution of the pixel: c(lon,lat).
timesteps	Character. Vector of the timesteps in the dataset. Default: NULL - in this case the time will be calculated from the start-, endpoint and temporal resolution given in the metadata file (json). Else, the dates must be given in in ISO format 'YYYY-MM-DD' or shortened 'YYYY' in case of yearly timesteps.
fillvalue	Numeric. Value of the missing data (NoData value) in the array. Has to be a single numeric value or NA.
prec	Character. Default: 'double'. Precision of the data set. Valid options: 'short' 'integer' 'float' 'double' 'char' 'byte'.
sep	Character. Default: ','. If the delimiter of the csv specifying the entity-names differs from the default, indicate here.
force_4D	Logical. Default is TRUE. If the argument is TRUE, there will be 4D cubes (lon, lat, time, entity) per metric. If this argument is changed to FALSE, there will be 3D cubes (lon, lat, time) per entity (per metric). So the latter yields a higher amount of cubes and does not bundle all information per metric. In the future the standard will be restricted to the 4D version. Recommendation: go with the 4D cubes!
overwrite	Logical. Default: FALSE. Set to TRUE to overwrite the output file defined by 'outputpath'
verbose	Logical. Default: TRUE. Turn off additional prints by setting it to FALSE.

Value

Creates the netCDF file at the 'outputpath' location including the taxonomy information.

Note

To check out the results take a look at your netCDF file with Panoply provided by the NASA.

You can check the taxonomy info with ebv_properties() in the slot 'general' under the name 'taxonomy' and 'taxonomy_key'.

Examples

#set path to JSON file
json <- system.file(file.path("extdata/testdata","5.json"), package="ebvcube")
#set output path of the new EBV netCDF
out <-  tempfile(fileext='.nc')
#set path to the csv holding the taxonomy names
taxonomy <- file.path(system.file(package='ebvcube'),"extdata/testdata","id5_entities.csv")

#create new EBV netCDF with taxonomy
## Not run: 
ebv_create_taxonomy(jsonpath = json, outputpath = out, taxonomy = taxonomy,
           fillvalue = -127, resolution = c(0.25, 0.25), verbose = FALSE)
#remove file
file.remove(out)

## End(Not run)

ebvcube documentation built on Aug. 8, 2025, 7:24 p.m.