geotopbricks (version 1.5.9.1)

get.geotop.inpts.keyword.value: Importing a GEOtop Keyword and its Value into R

Description

It returns the values of a keyword of "geotop.inpts" file or data frame with the suitable format.

Usage

get.geotop.inpts.keyword.value(
  keyword,
  inpts.frame = NULL,
  vector_sep = NULL,
  col_sep = ",",
  numeric = FALSE,
  format = "%d/%m/%Y %H:%M",
  date = FALSE,
  tz = "Etc/GMT-1",
  raster = FALSE,
  file_extension = ".asc",
  add_wpath = FALSE,
  wpath = NULL,
  use.read.raster.from.url = FALSE,
  data.frame = FALSE,
  formatter = "%04d",
  level = 1,
  date_field = "Date",
  isNA = -9999,
  matlab.syntax = TRUE,
  projfile = "geotop.proj",
  start_date = NULL,
  end_date = NULL,
  ContinuousRecovery = 0,
  ContinuousRecoveryFormatter = "_crec%04d",
  zlayer.formatter = NULL,
  z_unit = c("centimeters", "millimeters"),
  geotop_z_unit = "millimeters",
  add_suffix_dir = NULL,
  MAXNROW = 4,
  header.only = FALSE,
  ...
)

Value

the keyword value

Arguments

keyword

keyword name

inpts.frame

data frame returned by declared.geotop.inpts.keywords or NULL. Default is NULL.

vector_sep

character value for the separator character if Keyword Value must be returned as a vector, otherwise it is NULL. Default is NULL, but if numeric or date are FALSE, vector_sep is set "," by default.

col_sep

character value for the separator character of columuns. It is used if Keyword Value is returned as a data frema or zoo object or list of these objects. Default is NULL, but is set ",".

numeric

logical value. If TRUE the Value has numeric type, otherwise it is a string or string vector. Default is FALSE.

format

string format representing the date, see as.POSIXlt, used if date is TRUE. Default is "%d/%m/%Y %H:%M" (which is the format used in geotop.inpts keyword InitDateDDMMYYYYhhmm)

date

logical value. If TRUE the Value is retured as POSIXlt date, otherwise it is a string or string vector. Default is FALSE.

tz

format string representing the time zone, see as.POSIXlt, used if date is TRUE. Default is "Etc/GMT-1" (until the previous version it was "A") which meens UTC +1.

raster

logical value. Default is FALSE. If TRUE function returns direclty the raster map as Raster-class object built with raster method.

file_extension

Extension to be added to the keyword if keyword is a file name. Default is ".asc"

add_wpath

logical value. Default is FALSE. If TRUE, the wpath string is attached to the keyword string value. It is automatically set TRUE if raster is TRUE.

wpath

working directory containing GEOtop files (included the inpts file). It is mandatory if raster is TRUE. See declared.geotop.inpts.keywords.

use.read.raster.from.url

logical value. Default is TRUE. If TRUE the RasterLayer are read with read.raster.from.url, istead of raster (otherwise). It is recomended in case the files whose paths are contained in x are remote and are 'http' addresses. In this cases the stand-alone method raster(x) does not always work and use.read.raster.from.url is necessary.

data.frame

logical value. It is an option for tabular data. If TRUE function returns direclty a data frame or a list of data frames as data.frame or zoo objects imported from the keyword-related files using read.table function. In this case the argument wpath (see declared.geotop.inpts.keywords) is mandatory. Default is FALSE.

formatter

string value. It is the decimal formatter contained in the file name and used in case the tabular data are referred at several points. Default is "%04d" . It is used in case data.frame is TRUE.

level

integer values. Numbers incating all the identandification numbers of the files containing the requested data frames. Default is 1, correspondig to the decimal formatter "0001". See examples.

date_field

string value. Default is "Date", otherwise defined by the value of HeaderDateDDMMYYYYhhmmMeteo geotop keyword. It is used only if the argument data.frame is TRUE. If it is NULL or NA the function return a list of generic data.frame object(s), otherwise link{zoo} object(s). See the arguments tz and format for Date formatting.

isNA

numeric value indicating NA in geotop ascii files. Default is -9999.00

matlab.syntax

logical value. Default is FALSE. If TRUE a vector is written in a string according to *.m file syntax. Warning: this synstax is not read by GEOtop.

projfile

fileneme of the GEOtop projection file. Default is geotop.proj.

start_date, end_date

null objects or dates in POSIXlt format between which the variables are returned. It is enabled in case that date_field is not NULL or NA and data.frame is TRUE. Default is NULL.

ContinuousRecovery

integer value. Default is 0. It is used for tabular output data and is the number of times GEOtop simulation broke during its running and was re-launched with 'Contiuous Recovery' option.

ContinuousRecoveryFormatter

character string. Default is '_crec%04d'. It is used only for tabular output data and if ContinuousRecovery is equal or greater than 1.

zlayer.formatter

decimal formatter. It is used if data.frame==TRUE and the columns refers to different soil depths. Default is NULL.

z_unit

z coordinate measurement unit. GEOtop values expressed in millimeters which are converted to centimeters by default. Default is c("centimeters","millimeters"). Otherwise can be the ratio between the unit and one meter. It is used if zlayer.formatter=="z%04d" or similar.

geotop_z_unit

z coordinate measurement unit used by GEOtop. Default is millimeters. It is used if zlayer.formatter=="z%04d" or similar.

add_suffix_dir

character string. Add a suffix at the directory reported in the keyword value

MAXNROW

maximum number accepted for data.frema output. Default is 4. It is used in case of data.frame==TRUE. In case the number of records in the function output is less than MAXNROW , function returns neither data.frame nor zoo objects but only the keyword value.

header.only

logical value. Default is FALSE. If it is TRUE and data.frame==TRUE, only file hedaer with variable names is returned by the function.

...

further arguments of declared.geotop.inpts.keywords

Examples

library(geotopbricks)

#Simulation working path
 


wpath <- 
'https://raw.githubusercontent.com/ecor/geotopbricks_doc/master/simulations/panola13_run2xC_test3'
## URL path (RAW VERSION) of
## https://github.com/ecor/geotopbricks_doc/tree/master/simulations/panola13_run2xC_test3

## This step allows to put all keywords with their value in memory:
## it not mandataory but it can save running time in the session
inpts.frame <- declared.geotop.inpts.keywords(wpath=wpath) 

cond.time <- system.time({

prefix <- get.geotop.inpts.keyword.value("SoilLiqWaterPressTensorFile",wpath=wpath,
inpts.frame=inpts.frame)


layers <- get.geotop.inpts.keyword.value("SoilLayerThicknesses",numeric=TRUE,wpath=wpath,
inpts.frame=inpts.frame)
names(layers) <- paste("L",1:length(layers),sep="",
inpts.frame=inpts.frame)

##### set van genuchten parameters to estimate water volume 
theta_sat <- get.geotop.inpts.keyword.value("ThetaSat",numeric=TRUE,wpath=wpath,
inpts.frame=inpts.frame)
theta_res <- get.geotop.inpts.keyword.value("ThetaRes",numeric=TRUE,wpath=wpath,
inpts.frame=inpts.frame)
alphaVG <-  get.geotop.inpts.keyword.value("AlphaVanGenuchten",
numeric=TRUE,wpath=wpath,inpts.frame=inpts.frame) # expressed in mm^-1

nVG <-  get.geotop.inpts.keyword.value("NVanGenuchten",numeric=TRUE,wpath=wpath,
inpts.frame=inpts.frame) 


##### end set van genuchten parameters to estimate water volume

})

cond2.time <- system.time({
if (cond.time[["elapsed"]]<0.01) {

# \donttest{
##### spatial gridded covarege data (raster)
slope <- get.geotop.inpts.keyword.value("SlopeMapFile",raster=TRUE,wpath=wpath,
 inpts.frame=inpts.frame) 
bedrock_depth <- get.geotop.inpts.keyword.value("BedrockDepthMapFile",raster=TRUE,
wpath=wpath,
 inpts.frame=inpts.frame) 
# }
}
})
cond3.time <- system.time({
if (cond2.time[["elapsed"]]<1) {

# \donttest{
##### meteo data
tz <- "Etc/GMT-1"  ## See help(timezones) In particular:
## Most platforms support time zones of the form Etc/GMT+n 
## and Etc/GMT-n (possibly also without prefix Etc/), 
## which assume a fixed offset from UTC (hence no DST). 
## Contrary to some expectations 
## (but consistent with names such as PST8PDT), negative offsets are times ahead of (east of) UTC, 
## positive offsets are times behind (west of) UTC.
start <-  get.geotop.inpts.keyword.value("InitDateDDMMYYYYhhmm",
date=TRUE,wpath=wpath,tz=tz,inpts.frame=inpts.frame) 
end <- get.geotop.inpts.keyword.value("EndDateDDMMYYYYhhmm",
date=TRUE,wpath=wpath,tz=tz,inpts.frame=inpts.frame) 

nmeteo <- get.geotop.inpts.keyword.value("NumberOfMeteoStations",
numeric=TRUE,wpath=wpath,inpts.frame=inpts.frame)
level <- 1:nmeteo

## set meteo data

 meteo <- get.geotop.inpts.keyword.value("MeteoFile",wpath=wpath,data.frame=TRUE,
       level=level,start_date=start,end_date=end,tz=tz,inpts.frame=inpts.frame)
# }

##### end set meteo data

## IMPORTING AN OUTPUT SOIL MOISTURE PROFILE: 


wpath <-  paste0(
'https://raw.githubusercontent.com/ecor/geotopbricks_doc/',
'master/simulations/Muntatschini_pnt_1_225_B2_004')
## URL Path (RAW VERSION) of 
## https://github.com/ecor/geotopbricks_doc/tree/master/simulations/Muntatschini_pnt_1_225_B2_004
# \donttest{
	SMC  <- get.geotop.inpts.keyword.value("SoilLiqContentProfileFile",
          wpath=wpath,data.frame=TRUE,date_field="Date12.DDMMYYYYhhmm.",
          formatter="%04d")

    SMCz  <- get.geotop.inpts.keyword.value("SoilLiqContentProfileFile",
         wpath=wpath,data.frame=TRUE,date_field="Date12.DDMMYYYYhhmm.",
          formatter="%04d",zlayer.formatter="z%04d")
# }
}
})