writeValues: Write values to a file

Description

Low level functions for writing blocks (>= 1 row) of values to files. For programmers and advanced users to speed up functions. Others are adviced to use writeRaster which is safer but more limited. writeRaster can only take all values (for smaller data sets) or a single row at a time (for larger data sets). The advantage of the functions described here is that they allow writing values to file using chunks of any size (and some additional optimization for speed). Function blockSize can be used to suggest chunks of a number of rows that can be much larger than 1 (up to all rows). This reduces the number of loops and the number of file i/o requests and hence could speed up writing values to file. These functions do not have many validity tests and will try to do as requested, or perhaps fail, or write invalid files. Hence the adviced to use writeRaster instead (or first, and later optimize with the functions described here).

Usage

blockSize(x, chunksize, n=nlayers(x), minblocks=2)
writeStart(x, filename, ...)
writeValues(x, v, ...)
writeStop(x)

Arguments

Raster* object

chunksize

Integer, normally missing. Can be used to set the block size; unit is number of cells. Block size is then computed in units of number of rows (always >= 1)

Integer. number of layers to consider. The function divides chunksize by n to determine blocksize

minblocks

Integer. Minimum number of blocks

filename

Output filename

vector

...

Additional arguments. See under Methods

Value

the write functions are used for the side-effect of writing values to a file. tileSize returns a list with rows, the suggested row numbers at which to start the blocks for reading and writing, size, the block size (number of rows) and n, the total number of blocks

Methods

Additional arguments for writeStart rll{ format Character. Output file type. See writeFormats datatype Character. Output data type. See dataType overwrite Logical. If TRUE, "filename" will be overwritten if it exists }

Details

First open a file with writeStart, then write values to it in chunks. When writing is done close the file with writeStop. chunkSize can help set the number of rows of each chunk and it returns the row-numbers from where to start reading. Files with a 'native' format must be written in sequence of cell numbers. In contrast, the values of files written via rgdal can be written in any order (but you must write 1 or more entire rows, you cannot write part of a row). For files written via rgdal, an argument start must be provided to writeValues so that it knows where to write the values. This argument is ignored for the native formats (values are assumed to be in sequence).

Examples

Run this code

r <- raster(system.file("external/test.grd", package="raster"))
# write to a new binary file in chunks
s <- raster(r)
# 
tr <- blockSize(r, 25)
tr
s <- writeStart(s, filename='test.grd',  overwrite=TRUE)
for (i in 1:tr$n) {
	v <- getValuesBlock(r, row=tr$row[i], nrows=tr$size)
	writeValues(s, v, tr$row[i])
}
s <- writeStop(s)

if(require(rgdal)){
s2 <- writeStart(s, filename='test2.tif', format='GTiff', overwrite=TRUE)
# writing last row first
for (i in tr$n:1) {
	v <- getValuesBlock(r, row=tr$row[i], nrows=tr$size)
	writeValues(s2, v, tr$row[i])
}
# row number 5 once more
v <- getValuesBlock(r, row=5, nrows=1)
writeValues(s2, v, 5)
s2 <- writeStop(s2)
}

## write values of a RasterStack to a RasterBrick
s <- stack(system.file("external/rlogo.grd", package="raster"))
# create empty brick
b <- brick(s, values=FALSE)  
b <- writeStart(b, filename="test.grd", format="raster",overwrite=TRUE)
tr <- blockSize(b)
for (i in 1:tr$n) {
	v <- getValuesBlock(s, row=tr$row[i], nrows=tr$size)
	writeValues(b, v, tr$row[i])
}
b <- writeStop(b)
# note that the above is equivalent to 
# b <- writeRaster(s, filename="test.grd", format="raster",overwrite=TRUE)

Run the code above in your browser using DataCamp Workspace