In JBrenn/TopoSUB: TopoSUB tool

knitr::opts_chunk$set(echo = TRUE)

Install R-library TopoSUB

The R-library TopoSUB is a GitHub repository which can be installed via devtools in R. The following R snippet will install/load devtools and TopoSUB if neccessary.

if(!require(TopoSUB))
{
  if(!require("devtools"))
  {
    install.packages(devtools)
    require("devtools")
  }
  install_github("TopoSUB", "JBrenn")
  require("TopoSUB")
}

TopoSUB root folder

A TopoSUB root folder exists of

two TopoSUB configuration files, locations.txt and setup.txt,
the master folder, containing GEOtop input data (input maps, meteo, horizon, soil files), the GEOtop configuration file (geotop.inpts) and eventually a folder called obs with observed data,
the src folder contains additional TopoSUB functions, which are not included in the library. This folder is part of the TopoSUB repository on GitHub and can either be downloaded or cloned:

git clone https://github.com/JBrenn/TopoSUB

For clarification on the folder structure a TopoSUB example simulation can be found here.

The directory of these files/folders is the root directory, defined in the location configuration file. The folder names of all necessary input files have to be specified in the location configuration file. The parameters 1d folder and experiment number will define the simulation output path. The 1d folder can be seen as an project folder, where different simulations of a project are stored.

As the first intension of this extended version of TopoSUB were simulation runs for climate impact assessments with continuous input data up to 140 years, parallelisation is implemented either for your local machine (see example simulation) or a HPC cluster (e.g. Vienna Scientific Cluster - VSC). In the example simulation 256 point simulations are splited into 8 branches (Number of simulations in parallel mode in setup configuration file), where each branch exists of 32 point simulations, computes 32 cluster centroids. For the VSC a number of job files (specified by Ncores) can be created and run directly from R. For further info on the VSC see its wiki page.

Run TopoSUB

A TopoSUB simulation is started with the function TopoSUB_preprocessor. After preparing GEOtop input files (raster maps, meteorological input stations, horizon files, ...), the GEOtop configuration file (geotop.inpts) and the TopoSUB configuration files (locations.txt, setup.txt), use this function to carry out landscape clustering and GEOtop point simulations, for computational intensive simulations preferable parallelized on a HPC server. See the function documentation for a short description.

?TopoSUB_preprocessor

For the example simulation we can run the R-script main_pre.R as following in a Linux terminal

Rscript main_pre.R & > log/sim1.log

Let's take a look at the commands it is processing

# install/source TopoSUB library
# see R block above

#  source code of TopoSUB (download from TopoSUB GitHub repo)
  source("src/toposub_src.r")
  source("src/toposub_src_BrJ.r")

# setup file
  setupfile = "setup.txt"

# location file
  locationfile = "locations.txt"

# topoSUB preprocessor
  TopoSUB_preprocessor(location.file = locationfile, setup.file = setupfile,
                       PredNamesList=list(topo=c("dem", "slp", "asp", "svf"),
                                          clas=c("landcover", "soil")),
                       uniform_class = c(landcover=NA, soil=NA))

First the additional TopoSUB functions are sourced, then we launch the preprocessor, with defined names for the location and setup configuration file. In PredNamesList we define the predictors we want to use for clustering, these are splitted in continuous (e.g. elevation - dem) and discrete (e.g. land cover types - landcover) data. If we want to simulate only a single land cover or soil type over the whole study area we can change the argument uniform_class accordingly. The number of the listed argument refers to the number defining specific classes in the soil/land cover input maps.

TopoSUB Project folder | 1d folder

As explained above TopoSUB is orgnised in project directories, which can be found in the sim folder. These are mainly meant to experiment with the configuration of TopoSUB itself, means that for each project the same master folder is used. If GEOtop specific parameterisations or input data is changed a new project should be started. The master folder is copyed once in the project folder, the simulations which were run within the project are written in a specific folder, called according to the experiment number, e.g. 00001.

TopoSUB simulation folder | experiment number

The main structure of a TopoSUB simulation folder is provided by the GEOtop configuration file geotop.inpts. If the simulation is run in parallel an extra folder parallel is containing the simulation output files. The TopoSUB preprocessor is creating two files of particular importance

the listpoint.txt file is describing the characteristics for each cluster centroid. It is read as input in GEOtop defining point simulation setups.
the landform .asc file is mapping the IDs of the cluster centroids for each grid cell of the simulation domain. This map is later on used for re-maping simulation variables (see Lect 2: How to Postprocess a TopoSUB sim).

Observed Data

Observed data is stored station vise in .csv files within the master folder. The first column of each station file is reserved for the date, called Index, date format is YYYY-MM-DD, so time step is daily. Column names of soil moisture data do have the following specification: SWC_[SensorName]z[DepthInCM]. Colnames of further variables have to be set according to the names of the output data.table of the function _TopoSUB_read.

Variable names to use can be obtained by sourcing colnames from the TopoSUB package:

data("colnames")
View(colnames)

A meta data file - meta.csv - contains station names (same names as the .csv station file names), geographic coordinates and the elevation of the stations. For formating issues see the example simulation.