Skip to content

pcr2nc

Jump to bottom
casadoj edited this page Aug 30, 2024 · 1 revision

Usage

This tool converts PCRaster maps to NetCDF4 files. Charactericstics:

  • convert a single map into a NetCDF4 file
  • convert a time series of maps into a NetCDF4 mapstack
  • support for WGS84 and ETRS89 (LAEA) reference systems
  • fine tuning of output files (compression, significant digits, etc.)

Note: This guide assumes you have installed the program with PiP. If you cloned the source code instead, just substitute the executable pcr2nc with python pcr2nc_script.py that is in the root folder of the cloned project.

Requirement: PCRaster must be installed in the Conda environment.

The tool takes three command line input arguments:

  • -i, --input: It can be a path to a single file, a folder or a unix-like widlcard expression like /path/to/files/dis00*
  • -o, --output_file: Path to the output nc file
  • -m, --metadata: Path to a yaml or json file containing configuration for the NetCDF4 output file.

Unless the input is a single file, the resulting NetCDF4 file will be a mapstack according to a time dimension.

Input as a folder containing PCRaster maps. In this case, the folder must contain ONLY PCraster files and the output will be a mapstack.

pcr2nc -i /path/to/input/ -o /path/to/output/out.nc -m ./nc_metadata.yaml

Input as a path to a single map. In this case, the output won't be a mapstack.

pcr2nc -i /path/to/input/pcr.map -o /path/to/output/out.nc -m ./nc_metadata.yaml

Input as a Unix style pathname pattern expansion. The output will be a mapstack. Note that in this case the input argument must be contained in double quotes!

pcr2nc -i "/path/to/input/pcr00*" -o /path/to/output/out.nc -m ./nc_metadata.json

Writing metadata configuration file

Format of resulting NetCDF4 file is configured into a metadata configuration file. This file can be written in YAML or JSON format.

An example of a metadata configuration file is the following

variable:
  shortname: dis
  description: Discharge
  longname: discharge
  units: m3/s
  compression: 9
  least_significant_digit: 2
source: JRC Space, Security, Migration
reference: JRC Space, Security, Migration
geographical:
  datum: WGS84
  variable_x_name: lon
  variable_y_name: lat
time:
  calendar: proleptic_gregorian
  units: days since 1996-01-01

Variable section

In variable section you can configure metadata for the main variable:

  • shortname: A short name for the variable
  • longname: The long name version
  • description: A description for humans
  • units: The units of the variable
  • compression: Optional, integer number between 1 and 9, default 0 (no compression). If present the output nc file will be compressed at this level.
  • least_significant_digit: Optional, integer number, default 2. From NetCDF4 documentation:

If your data only has a certain number of digits of precision (say for example, it is temperature data that was measured with a precision of 0.1 degrees), you can dramatically improve zlib compression by quantizing (or truncating) the data using the least_significant_digit keyword argument to createVariable. The least significant digit is the power of ten of the smallest decimal place in the data that is a reliable value. For example if the data has a precision of 0.1, then setting least_significant_digit=1 will cause data the data to be quantized using numpy.around(scale*data)/scale, where scale = 2**bits, and bits is determined so that a precision of 0.1 is retained (in this case bits=4). Effectively, this makes the compression 'lossy' instead of 'lossless', that is some precision in the data is sacrificed for the sake of disk space.

Source and reference

source and reference add information for the institution that is providing the NetCDF4 file.

Geographical section

In the geographical section you can configure datum and name of the x and y variables. As variable_x_name and variable_y_name you should use 'lon' and 'lat' for geographical coordinates (e.g. WGS84) and 'x' and 'y' for projected coordinates (e.g. ETRS89).

Currently, pcr2nc supports the following list for datum:

  • WGS84
  • ETRS89
  • GISCO

Time section

This section is optional and is only required if the output file is a mapstack (a timeseries of georeferenced 2D arrays) In this section you have to configure units and calendar.

  • units: Can be one of the following strings (replacing placeholders with the actual date):
    • hours since YYYY-MM-DD HH:MM:SS
    • days since YYYY-MM-DD
  • calendar: A recognized calendar identifier, like proleptic_gregorian, gregorian etc.
Clone this wiki locally