create_header: Create a new LPJmL input/output file header

In lpjmlkit: Toolkit for Basic LPJmL Handling

Create a new LPJmL input/output file header

Description

Create a header from scratch in the format required by write_header().

Usage

create_header(
  name = "LPJGRID",
  version = 3,
  order = 1,
  firstyear = 1901,
  nyear = 1,
  firstcell = 0,
  ncell,
  nbands = 2,
  cellsize_lon = 0.5,
  scalar = 1,
  cellsize_lat = cellsize_lon,
  datatype = 3,
  nstep = 1,
  timestep = 1,
  endian = .Platform$endian,
  verbose = TRUE
)

Arguments

name	Header name attribute (default: '"LPJGRID").
version	CLM version to use (default: 3).
order	Order of data items. See details below or LPJmL code for supported values. The order may be provided either as an integer value or as a character string (default: 1).
firstyear	Start year of data in file (default: 1901).
nyear	Number of years of data included in file (default: 1).
firstcell	Index of first data item (default: 0).
ncell	Number of data items per band.
nbands	Number of bands per year of data (default: 2).
cellsize_lon	Longitude cellsize in degrees (default: 0.5).
scalar	Conversion factor applied to data when it is read by LPJmL or by read_io() (default: 1.0).
cellsize_lat	Latitude cellsize in degrees (default: same as cellsize_lon).
datatype	LPJmL data type in file. See details below or LPJmL code for valid data type codes (default: 3).
nstep	Number of time steps per year. Added in header version 4 to separate time bands from content bands (default: 1).
timestep	If larger than 1, outputs are averaged over timestep years and only written once every timestep years (default: 1).
endian	Endianness to use for file (either "big" or "little", by default uses platform-specific endianness .Platform$endian).
verbose	If TRUE (the default), function provides some feedback on datatype and when using default values for missing parameters. If FALSE, only errors are reported.

Details

File headers in input files are used by LPJmL to determine the structure of the file and how to read it. They can also be used to describe the structure of output files.

Header names usually start with "LPJ" followed by a word or abbreviation describing the type of input/output data. See LPJmL code for valid header names.

The version number determines the amount of header information included in the file. All versions save the header name and header attributes 'version', 'order', 'firstyear', 'nyear', 'firstcell', 'ncell', and 'nbands'. Header versions 2, 3 and 4 add header attributes 'cellsize_lon' and 'scalar'. Header versions 3 and 4 add header attributes 'cellsize_lat' and 'datatype'. Header version 4 adds attributes 'nstep' and 'timestep'.

Valid values for order are 1 / "cellyear", 2 / "yearcell", 3 / "cellindex", and 4 / "cellseq". The default for LPJmL input files is 1. The default for LPJmL output files is 4, except for grid output files which also use 1.

By default, input files contain data for all cells, indicated by setting the firstcell index to 0. If firstcell > 0, LPJmL assumes the first firstcell cells to be missing in the data.

Valid codes for the datatype attribute and the corresponding LPJmL data types are: 0 / "byte" (LPJ_BYTE), 1 / "short" (LPJ_SHORT), 2 / "int" (LPJ_INT), 3 / "float" (LPJ_FLOAT), 4 / "double" (LPJ_DOUBLE).

The default parameters of the function are valid for grid input files using LPJ_FLOAT data type.

Value

The function returns a list with 3 components:

• name: The header name, e.g. "LPJGRID".

• header: Vector of header values ('version', 'order', 'firstyear', 'nyear', 'firstcell', 'ncell', 'nbands', 'cellsize_lon', 'scalar', 'cellsize_lat', 'datatype', 'nstep', 'timestep').

• endian: Endian used to write binary data, either "little" or "big".

See Also

• read_header() for reading headers from LPJmL input/output files.

• write_header() for writing headers to files.

Examples

header <- create_header(
  name = "LPJGRID",
  version = 3,
  order = 1,
  firstyear = 1901,
  nyear = 1,
  firstcell = 0,
  ncell = 67420,
  nbands = 2,
  cellsize_lon = 0.5,
  scalar = 1.0,
  cellsize_lat = 0.5,
  datatype = 3,
  nstep = 1,
  timestep = 1,
  endian = .Platform$endian,
  verbose = TRUE
)

lpjmlkit documentation built on March 31, 2023, 9:35 p.m.