SplineVolume: Translate an STX dendrometry file and calculate some volumes
In Dendrometry: Decipher Barr & Stroud FP-15 from STX Files

Description Usage Arguments Details Value Author(s) References

This routine can be used to read a file in STX dendrometry format and process the Barr and Stroud FP-12 or FP-15 measurements into corresponding segment diameters and lengths. More details are given below and in the Fortran and R source code.

SplineVolume(fileName = "odr_wp_1977.stx",
             filePath = getwd(),
             dataPath = "data",
             reportPath = "reports",
             splineMethods = c("natural","monoH"),
             ... )

`fileName`	An input file name with extension corresponding to an STX file on disk.
`filePath`	The full file path to the current R workspace, the default is `getwd()`.
`dataPath`	The relative path from `filePath` to where the STX dendrometry data file resides; i.e, if the current R workspace is in /Rwork, and the STX file is in /Rwork/data, then the default will work fine. The file should have the 10 control records (cards) before the first tree record as in a normal STX file.
`reportPath`	The relative subdirectory where the report files should be written.
`splineMethods`	One or more of the methods available in the `spline` and `splinefun` routines in the `utils` package. The defaults are the ‘natural’ and ‘monoH.FC’ spline methods.
`...`	Just gobbled for now.

This routine has its roots in some old Fortran code used to calculate cubic, Hermite and Akima spline volumes (hence the name) in addition to conic volumes for segments for dendrometry data. In the old Fortran code, input data were in a form that Lew Grosenbaugh's STX program would use. This is still the case, but the Fortran code has been adapted to be used with the R SplineVolume interface to read and process the dendrometry data such that it is returned in data frames for further use in R. In addition, three files are written as output from a run of SplineVolume (Fortran code) to the reportPath subdirectory: (1) a tree file with one record per tree, (2) a segment file with one record per measurement (dendrometer reading) for each tree, and (3) a report file with a formatted tabular report.

The Akima and Hermite splines are not calculated in the current Fortran version because the original code used licensed IMSL routines at the time. They can be fitted and volumes derived from the results using the appropriate R functions based on the results returned from this routine. A Hermite version (see splineMethods argument) is fitted in SplineVolume and Akima can be fitted using the akima package. Similarly, I have removed the ‘natural cubic spline’ fits from the Fortran because of the source license (Numerical Recipes) restrictions. A similar natural cubic spline (see splineMethods argument) is fitted in the R code.

This function is a wrapper for the Fortran code, which was origianlly designed to be a stand-alone program. At present, parsing the STX file to determine the total number of segments is somewhat of a pain. This is done tree-by-tree as the dendrometer measurements are processed in the code. Because each tree can have variable numbers of measurements, and because arrays are allocated and deallocated on a tree-by-tree basis in the Fortran, when combined with R's character variable limitations with Fortran, it was too problematic to pass back the actual arrays to R. Rather the results are written out to the files mentioned above in the Fortran, and then read.table is used to recover these results in the R code. This does result in some loss of precision, but we are only talking about diameters and lengths here, nothing that really requires full precision so it should be enough until someone asks for more. More information on the process is detailed in the R and Fortran source files in the package.

Note that the dendrometry measurements in the STX input file are assumed to be in the form of direct measurements in the first two segments as illustrated on page 31 in Space (1974); e.g., the first two readings are...

Reading 1: FGRAD = Stump diameter, and SINELV = height from stump to dbh, signalled with a negative (-999) TGRAD.
Reading 2: FGRAD = DBH, and SINELV = measured height from DBH to the first Barr & Stroud measurement, often something convenient like 4 feet above DBH (TGRAD = 0.0).

The remainder of the measurements are assumed to have been taken with the Barr & Stroud beyond that. The program should work if all measurements have been taken using a Barr & Stroud (the routine that processes measurements was taken directly from STXMOD and this option is handled in the code, but has not been tested). It would be simple enough to add other alternatives, like all direct measurements, but it has not been done as all of our dendrometry has been taken with the above model.

The code can not be guaranteed, unfortunately. A lot of it was borrowed from STX (actually STXMOD), and that is not easy or simple. There could be errors. Everything that has been tested so far looks fine and the original versions were tesed against STX for conversions of B&S readings.

Finally, please note that this is not a substitute for STX in the sense of 3P sampling as it is only used to process measurements.

A list is returned invisibly as...

z: A list returned from the Fortran program with self evident components as used in the call to the Fortran code.
trees: A data frame with the tree information, one record per tree.

TreeNo: The tree number
Spp: Species
dbhob: Diameter at breast height outside bark.
dbThick: Double bark thinkness.
isForked: TRUE: the tree is forked; FALSE: not forked.
nReadings: Number of dendrometer + direct readings for the tree.
totLen: The total length of the tree including forks lengths.
lenFlag: TRUE: There was a problem with negative lengths in one of the segments measured, this is probably due to an error in the dendrometry reading; FALSE: everything is fine.
conicVol: Tree volumes using the formula for a conic frustum.
natVol, monVol: The tree volumes from the spline fits. The names of these fields depend on what is chosen as the splines to be fitted, the defaults are given above in the splineMethods argument. So be aware that the name of this column may be different for different data sets. The rule is to use the first 3 characters from the names and splineMethods and append “Vol” for the name.

segments: A data frame with the segment information, one record per dendrometer reading (so “readings” would probably have been a more appropriate name) within each tree. The columns in the data frame are the following...

TreeNo: The tree number
Reading: The dendrometer reading number; note that begin at the top reading and decrease to the bottom reading within a tree.
Spp: Species
dob: Diameter outside bark
dib: Diameter inside bark–may be the same as dob if no bark thinkness was recorded.
prod: The produce code for the segment as described below.
tgrad: The ‘tgrad’ readings
fgrad: The ‘fgrad’ readings
sinelv: The ‘sinelv’ readings
instRange: The distance from the instrument to the reading on the tree.
hgtHoriz: The height of the readings above horizontal as determined by the instrument height.
segLen: The segment length between two dendrometer readings.
height: The cumulative height from the previous field; note that this will not equal the real height of the tree in the case of forked trees.
conicVol: Segment volumes using the formula for a conic frustum.
natVol, monVol: The segment volumes from the spline fits. The names of these fields depend on what is chosen as the splines to be fitted, the defaults are given above in the splineMethods argument. So be aware that the name of this column may be different for different data sets. The rule is to use the first 3 characters from the names and

In the segment data frame, please note that the records correspond to dendrometer readings from the bottom to top dendrometer reading as recorded in the field. If the first reading is i=1, then the segment volumes, lengths, etc., are such that i=2 contains the segment information for readings c(1,2); obviously then reading i+1 contains the segment information for readings c(i,i+1).

A final word concerning the spline volumes. The splines can be very (too) flexible and give fits that are not always good depending on the tree shape. One can see this by plotting the results in taperPlot. So please be aware that the volume can be off and that the conic versions are perhaps the best all around.

Jeffrey Gove

: Grosenbaugh, L. R. 1974. STX 3-3-73: Tree Content and Value Estimation Using Various Sample Designs, Dendrometry Methods, and V-S-L Conversion Coefficients. U.S. Forest Service Research Paper SE-117.

: Rennie, J. C. 1977. STX: A Computer System for Processing Timber Inventory Data. Unpublished manuscript.

: Space, J. C. 1974. 3-P Forest Inventory: Design, Procedures, Data Processing. U.S. Forest Service State and Private Forestry, Southeastern Area, Atlanta, GA.

Dendrometry documentation built on May 2, 2019, 5:47 p.m.