create_header: 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
)

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".

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.

Examples

Run this code

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
)