map2col

map2col

Converts from PCRaster map format to column file format

map2col [options] PCRmap1 PCRmap2....PCRmapN columnfile

PCRmap

boolean, nominal, ordinal, scalar, directional, ldd spatial The maps must have the same projection, the other location attributes and the data types may be different between the maps.

columnfile

asciifile

Options

--unittrue or --unitcell

--unittrue

coordinates in columnfile are interpreted as real distance (default)

--unitcell

coordinates in columnfile are interpreted as distance in number of cell lengths

coordinate positions:

--coorcentre

cell values on columnfile are assigned the coordinates of the centres of the cells on PCRmap1 (default).

--coorul

cell values on columnfile are assigned the coordinates of the upper left corner of the cells on PCRmap1.

--coorlr

cell values on columnfile are assigned the coordinates of the lower right corner of the cells on PCRmap1.

columnnumbers

-x columnnumberx

columnnumberx is the column number of the x coordinate in columnfile; in append mode: the column number of the x coordinate in the inputcolumnfile (default 1).

-y columnnumbery

columnnumbery is the column number of the y coordinate in columnfile; in append mode: the column number of the y coordinate in the inputcolumnfile (default 2).

-m nodatavalue

nodatavalue is the value in columnfile which is converted to a missing value on PCRresult. It can be one ascii character (letters, figures, symbols) or a string of ascii characters. For instance: -m -99.98 or -m ! or -m j5w. Default, if this option is not set, 1e31 is recognized as a missing value.

-M

Default, if PCRmap1 has a missing value in a cell, the cell is not saved in columnfile. If the option -M is set these cells are saved in columnfile. They are assigned the nodatavalue.

-s separator

By default, whitespace (one or more tabs, spaces) is recognized as separator between the values of a row in the columnfile. If the values are separated by a different separator, you can specify it with the option. The separator can be one of the ascii characters (always one). In that case, col2map recognizes the specified separator with or without whitespace as separator. For instance, if the values in columnfile are separated by a ; character followed by 5 spaces, specify -s ; in the command line (you do not need to specify the whitespace characters).

specifying format of columnfile

-p

columnfile is in plain format without header (default)

-g

columnfile is in simplified Geo-EAS format.

row wise or column wise output

-r

row wise output (default). The cell values in the first row onnPCRmap1, PCRmap2,…PCRmapn will be at the top of the columnfile, underneath the cells in the second row, etc.

-c

column wise output. The cell values in the first column onnPCRmap1, PCRmap2,…PCRmapn will be at the top of the columnfile, underneath the cells in the second column, etc.

-a inputcolumnfile

append mode. The inputcolumnfile is the name of the column file to which the data are appended. The file with the appended data is saved as columnfile. See operation in append mode below.

-f C-typeformat

This option is used to specify the sort of format which is assigned to the cell values in columnfile. The format determines the maximal and minimal cell value which can be converted, the precision the data can be saved in columnfile and the number of positions used for each cell value. The default format that is used depends on the data type of PCRmap. For boolean, nominal and ordinal maps, containing only whole values, the smallest possible number of positions is used for each cell value field in columnfile, taking into account all cell values and the number of positions needed for the missing value. For instance, a nominal map with nominal values between 12 and 19 and a no data value -999 (given by the option -m nodatavalue) is written to columnfile using four positions for each cell value (resulting from the number of positions needed for the nodatavalue). For instance, the value 12 is printed as a cell value field made up of 2 spaces followed by 12.

Maps of scalar and directional data type are always printed in the C-type format 11.6g, also used in the C programming language: the precision the data are saved on columnfile corresponds with the precision they are available on PCRmap, with the restriction that the maximal number of significant figures which can be saved on columnfile is six per cell value. The maximum and minimum value which can be saved is 10⁹⁹ and -10⁹⁹ respectively; a notation with base₁₀ exponents is used if the value is larger than 10⁶ or smaller than -10⁶.

Examples:

PCRmap         columnfile
-894.41000     -894.41
-5674935         -5.67494e+06
453628190.6       4.53628e+08
0.000000000031    3.1e-11
-0.02000012      -0.0200001
-1.0200001       -1.02

If you want to prevent the usage of base 10 exponents for scalar or directional data use the C-type format f and specify -f a.df, where a and d must be whole numbers equal to or larger than 0. The value d is the number of decimal figures which will be used for each cell value, the value a is the minimal total number of positions used for each value; if more positions are needed (large values), more positions are used.

Examples:

C-typeformat    PCRmap        columnfile
5.6f            1234.1981     1234.198100
5.3f            1234.1981     1234.198
5.0f            1234.1981     1234
3.1f            1234.1981     1234.2
15.6f           1234.1981     1234.1981
2.1f            1289128932.75 1289128932.7

You can also specify other C-type formats, see for description of these formats a C programming language standard work.

Operation

Default operation (no append mode)

Operation if PCRmap1, PCRmap2,…PCRmapn have corresponding location attributes:

In most cases only one PCRmap1 is given in the command line or several maps PCRmap1, PCRmap2,…PCRmapn are given which have the same location attributes. In these cases, the operation is performed as follows. The PCRaster expression(s) PCRmap1, PCRmap2,…PCRmapn are converted to columnfile, which is an ascii file in column format. Each line in this columnfile represents one cell on PCRmap1, PCRmanp2,…PCRmapn. The x and y coordinates of the cells will be in the column numbers specified by the options -x columnumberx and -y columnnumbery. The cell values of PCRmap1 will be in the first ‘empty’ column, the values of PCRmap2 in the next column etc. For instance if you set -x 2 -y 3, values of PCRmap1 are written in the first column, values of PCRmap2 in the fourth, values of PCRmap3 in the fifth etc.

Operation if PCRmap1, PCRmap2,…PCRmapn have different location attributes:

If more than one PCRmap is given in the command line and the given maps have different location attributes (with the exception of the projection which must be the same) the operation is performed in a somewhat different way. Only the x, y coordinates of the first map PCRmap1 are printed in columnfile. Real world coordinates or cell coordinates are printed, as specified by the option --unittrue, --unitcell; the coordinate position that is printed is specified by the option --coorul, --coorlr, --coorcentre. The cell values are printed as follows: first, each x, y coordinate pair is supplemented with its cell value of PCRmap1. Than, each line in columnfile is supplemented with the cell values of the remaining maps PCRmap2,…PCRmapn. No new lines are appended for these maps. For each of these maps and each line, the cell value is printed of the cell which has a real world location that corresponds with the real world location of the PCRmap1 cell that is already printed on that line. The real world location corresponds if the real world x,y coordinate of the PCRmap1 cell comes into the cell of the PCRmap2,…PCRmapn under consideration (the x,y coordinate of upper left corner, lower right corner or centre of each PCRmap1 cell is used, as specified by the --coorcentre, --coorlr, --coorcentre option). A line on the columnfile that represents a PCRmap1 cell with a real world x,y coordinate that does not come into a cell on the PCRmap2,…PCRmapn under consideration is assigned a missing value in the appended field.

operation in append mode

Data can also be appended to an existing column file inputcolumnfile. This columnfile may be a plain column file without a header or a column file in simplified Geo-EAS format. These formats don’t need to be specified, the map2col operator will detect the format of inputcolumnfile itself. For the append mode, the option -a inputcolumnfile is used. The inputcolumnfile is the name of the column file to which the data are appended. The file with the appended data is saved as columnfile. The data are appended as follows: each line (record) of the inputcolumnfile is supplemented with the PCRmap1, PCRmap2,…PCRmapn values of the cell in which the x,y coordinates of the line (record) are. On each line, the values of PCRmap1, PCRmap2,…PCRmapn will be typed in the order they are specified in the command line (i.e. PCRmap1 values are printed in the first column after the columns in the inputfile, PCRmap2 in the second column, etc.).

The append mode results in the appending of columns only, no lines will be appended: a cell on PCRmap1, PCRmap2,…PCRmapn without a x,y coordinate in the inputcolumnfile that comes into the cell will not be saved in a new line (record). A line (record) on inputcolumnfile with a x,y coordinate that does not come into a cell on PCRmap1, PCRmap2,…PCRmapn is assigned a missing value in the appended column(s).

In append mode the options -M, -r, -c, -p and -g must not be used. The other options can be used as normal, but the default values will be appropriate in almost any case; the flags -m, -f and -s will only affect the columns which are appended. The options --coorcentre, --coorul and --coorlr have the following meaning when used in append mode:

--coorcentre (default) and --coorul

lines (records) with coordinates in inputcolumnfile that are exactly at the upper or left edge of a cell are supplemented with the cell value of that cell, records with coordinates at the lower or right edge are supplemented with the value of a neighbouring cell.

--coorlr

lines (records) with coordinates in inputcolumnfile that are exactly at the lower or right edge of a cell are supplemented with the cell value of that cell, records with coordinates at the upper or left edge are supplemented with the value of a neighbouring cell.

Notes

Group

This operation belongs to the group of Creation of PCRaster maps

See Also

map2asc