HGSFile: Read HGS output file and create HSGFile object

In FluvialLandscapeLab/HGSReader: Reads output from the HydroGeoSphere model into R

Read HGS output file and create HSGFile object

Description

Returns information about an file created by HGS in the form of an HGSFile object. The HGSFile object can then be passed to other functions to return HGS output in R friendly formats.

Usage

HGSFile(x = file.choose())

Arguments

x	A file name to read.

Value

Returns an S3 object with a class of "HGSFile". The object will also have a subclass, which is the text "HGSFile_" contatinated with the type of HGS output file. So, for instance, the S3 class resulting from reading an HGS "pm" file will be c("HGSFile_pm", "HGSFile"). (To see the currently supported types, use HGSSupported

An HGSFile object is a list which has, at minimum, three elements:

• fileInfo will contain the results from file.info for the HGS file that was read, at the time the HGSFile object was created.

• description will contain the model run description provided by the HGS user when the model was run.

• taggedLines is a data.frame with one record for each "tagged" line of the HGS file. Tagged lines demarcate the beginning of an item of interest in the HGS data file. For instance, "pm" files contain tags for titles, variable names, zones, data, and node IDs. To see the tags for each supported for each file type, use HGSTags.

An HGSFile object may have additional elements, determined by the subclass.

HGSFile_pm objects will contain the following additional elements:

• variables is a vector of variable names included in output.

• elementNodeLookup A named numeric vector telling the number of lines to skip and the number of lines to read in the original data file to determine the node IDs associated with each element of the model. Useful with scan. (HGS elements are, e.g., the cubes demarcated by eight nodes in the simulation space.)

• modelDim A named numeric vector telling the number of nodes in the simulation space in X, Y, and Z dimensions.

• blocks A list containing sublists describing information about each "block" in the original data file. The information available for each block can be investigated with HGSQueryBlocks. The information stored in a block's sublist is variable, depending on the contents of the HGS data file. For instance, in a 'HGSFile_pm' object, there is a block for each simulation time at which the user requested output from HGS. Therefore, in a 'HGSFile_pm' object, each block has a "SOLUTIONTIME" element. Critically, each block has a DATAMAP element, containing a data.frame with one row for each variable that can be extracted from the HGS data file. Model variable names are the row names of the DATAMAP data.frame. The columns tell how many lines to skip and how many lines to read in the datafile in order to retrieve the data for each variable from the block. That said, rather than try to read the DATAMAPs directly, use the HGSGetData function, which uses the DATAMAPs correctly to retrieve data for specific variables and simulation times from an HGS output file.

See Also

HGSQueryBlocks

Examples

  # requires name of a legetimate pm file
  HGSF <- HGSFile("a_File_Name.pm.dat")

FluvialLandscapeLab/HGSReader documentation built on April 10, 2024, 8:18 a.m.