CM.ini: Get the global data object

In AntoniusGolly/cmgo: Derive principle Channel metrics from bank points

Description

Create the global data object with data and parameters (information on the global data object in section "General information on the global data object). Depending on the arguments passed to CM.ini(), the data are either created from input files, a work space file or from a demo data set. The parameters are either created from defaults, from a parameter file or merged with a passed list of parameters.

Usage

CM.ini(object = "demo", par = NULL)

Arguments

object	either a global data object of type list or a string to specify a demo data set (see Details)
par	either a parameter list, a string to specify a parameter file or NULL to load default parameters (see also CM.par())

Details

CM.ini() returns a global data object based on the arguments passed to it. Initially, the function builds a parameter object. If you leave the par argument empty, the default configuration is loaded. You can also pass everything to par that is accepted by CM.par() as this argument will be directly passed to this function (see the documentation of CM.par() for further information). Once the parameter object is built, the function will create the data object by the following rules (if one rule was successfull, the routine stops and returns the global data object):

1. If $workspace.read is TRUE (default) the function looks for an .RData user workspace named $workspace.filename (defaults to "./user_workspace.RData"). Note: there will be no such workspace file once you start a project, since it needs to be saved by the user with CM.writeData(). If such a workspace file exists the global data object will be created from this source, otherwise the next source is tested.

2. If data input files are available in the directory $input.dir (defaults to "./input") the function interates over all files in this directory and create the data object from this source (see section "Input data" below for further information on the data format). If this rule applies you will start with a clean data set, that contains nothing than the bank geometry and you will need to process the data from scratch. Otherwise the next source is tested.

3. If object is a string, the function will check for a demo data set with the same name. Available demo data sets are "demo", "demo1" and "demo2". See section "Demo data sets" below.

Value

returns the global data object containing data and parameters that will be passed to all main functions of cmgo.

General information on the global data object

All the data and parameters used in cmgo are stored in one variable of type list: the global data object, in the following examples named cmgo.obj. Its structure is:

cmgo.obj = list(
  data = list()  # the data set(s), different surveys of the channel
    set1 = list(), # survey 1
    set2 = list()  # survey 2
    # ...
  ),
  par  = list() # all plotting and model parameters
)

The global data object then has to be passed to and is returned from all main functions of the package as in

cmgo.obj = CM.generatePolygon(cmgo.obj)
cmgo.obj = CM.calculateCenterline(cmgo.obj)
cmgo.obj = CM.processCenterline(cmgo.obj)
CM.writeData(cmgo.obj)
CM.plotPlanView(cmgo.obj)

Input data

The package requires as input data the bank points of a river in 2D- or 3D-coordinates along with the information of the side of the bank points (right or left), as for example:

Name POINT_X POINT_Y
right 401601.0819 3106437.335
right 401586.5327 3106406.896
right 401568.3238 3106383.586
right 401558.4961 3106364.129
...
left 401621.4337 3106431.134
left 401602.9913 3106405.991
left 401574.6073 3106352.232
left 401582.2671 3106323.134
...

The data can be either collected during field surveys with GPS or total stations or through remote sensing techniques with further digitizing for example in a GIS. The input can be given in any ASCII table format. By default, the program expects tab-delimited columns of a table with one header line with the header names Names (for the side) and POINT_X/_Y/Z (the coordinates of the bank points) where the z component is optional. The expected column names and tab delimiters are set in the parameters (see documentation of CM.par() for details). The order of the points can be either all right bank points first or all left bank points first but not mixed.

The input file(s) have to be placed in the input directory specified in the parameters (defaults to "./input") and can have any file extension (.txt, .csv, etc.). The function CM.ini() will iterate over all files in that directory and create a data set for each file in the global data object of cmgo.

Demo data sets

Four demo data sets are available, which contain a few kilometer long section of a channel. The data sets differ in the degree of data processing. The data set demo only contains the channel bank points, thus contains a global data object how it looks directly after reading the input files (check structure with str(cmgo.obj$data[[set]]$channel)). The data set demo1 has passed the first steps of the processing: CM.generatePolygon() and CM.calculateCenterlin(). Thus, it contains successfully created centerlines (check structure with str(cmgo.obj$data[[set]]$cl)). The data set demo2 has gone through the full stack of processing of cmgo, e.g. CM.processCenterline() , and all metrics are calculated (check structure with str(cmgo.obj$data[[set]]$metrics)). Thus you can use this data set for testing the plotting functions CM.plotPlanView() and CM.plotWidth(). Note, that demo data set demo3 uses the standard mode for the calculation of the metrics (default) and not the reference centerline mode. To see the reference centerline mode in action use data set demo3. In addition to the previously mentioned plotting functions, here also CM.plotMetrics() is available.

Author(s)

Antonius Golly

Examples

# example 1: get data set from demo data
cmgo.obj = CM.ini("demo")

# example 2: get data set from input files
par = CM.par()
print(cmgo.obj$par$input.dir)
par$input.dir = "custom_input_folder"
#cmgo.obj = CM.ini(NULL, par) # works if 'custom_input_folder' contains file(s)

# example 3: load existing workspace
# (see CM.writeData() to learn how to write your workspace)
cmgo.obj$par$workspace.filename = "custom_workspace.RData"
#cmgo.obj = CM.ini(NULL, par) # works if 'custom_workspace.RData' exists

AntoniusGolly/cmgo documentation built on Sept. 24, 2021, 1:33 a.m.