A Toolkit for Computing the Historical Rate at which Fire Scars were Formed on Sampled Trees
by Joseph Fall
DOWNLOAD
Scar Rate Probability Tools (0.1MB)
The tools in this package allow you to compute the rate at which fire scars were formed on trees in your study area!
The tutorial included with the package describes how to run the PERL script against your FHX2 fire history data set, and then load the output from this script into the Excel analysis template. This tutorial contains a set of detailed, step-by-step instructions for working through an analysis, including error messages, reports, and files generated. In addition, the tutorial will lead you through a worked example using the sample data set included with the toolkit package. However, a description of the analytical methods applied in these analyses are not covered in this tutorial.
The toolkit also includes an Excel workbook containing a proof-of-concept model that should to help you convince yourself that the methods produce useful results. This workbook uses a random process to simulate fire scar formation on five trees sampled from the same plot. It allows you to set the input fire scar recording rate, simulates the random formation of fire scars based on this rate to create a synthetic fire scar data set, and then explicitly computes the probability of scaring from this synthetic data set. You can use this workbook to work through the analytical methods, which are explicitly coded on the spreadsheet, and to judge the accuracy of the estimate of the fire scar recording rate produced by these methods.
System requirements
- FHX2 tree-ring-based fire history analysis package (or at least the FHX2 file format)
- A PERL language interpreter
- Try agia.fsf.org to order a CD ROM with PERL and other GNU utilities (very cheap for a lot of great tools) for either UNIX, Windows or MS DOS.
- Microsoft Excel 97 or later
Step-by-Step instructions for running an analysis
(Note: These instructions are from the Tutorial included with the toolkit package.)
- Design a suitable sampling scheme, and collect fire-scarred samples. Several fire-scarred trees must be sampled within each relatively small sampling plot. Each sample plot should be as small as possible and at least three fire-scarred trees should be sampled in each plot. See the article above for details.
- Enter data into the fire history analysis package FHX2, using the following conventions to name each tree and identify which plot it came from. Each tree ID must uniquely identify both the fire-scarred sample tree and the plot from which it was sampled (so that all trees from the same plot can be grouped for analysis).
E.g., Plot ID's might have 6 characters and trees within plots are a single digit, yielding: PLOTAA1, PLOTAA2, PLOTAA3, PLOTBB1, PLOTBB2, PLOTBB3, etc. - Ensure the FHX2 file has the correct format, and set the constants in the scarprob.pl PERL script to describe your data set (you can edit the script with any text editor all constants are near the top, with instructions)
The first set of constants, $pIDsize and $tIDsize, give the number of characters in the plot ID and tree ID respectively:
The second set of constants, $ScarSymb, $StartSymb and $EndSymb, give the FHX2 symbols (characters) used to identify a fire year, years in which tree was recording, and the end of the fire record for a tree respectively:
# The header portion of the FHX file gives the plot and tree ID's as:
# First [P] characters give plot ID
# Next [T] characters give tree ID within plot
# The values of [P] and [T] must be set with the constants:
$pIDsize = 6;
$tIDsize = 1;
# NOTE: pIDsize + tIDsize MUST EQUAL # hdr rows!!!
# Example file format:
# FHX2 FORMAT - first record identifies FHX2 file format.
# 1527 5 7 - first year in record, # trees (cols), # hdr rows
# DDDDD |
# CCCCC \
# RRRRR \_ [six] character plot ID
# 00000 /
# 11111 /
# 55566 |
# 12312 - [one] character tree ID within plot# The list of symbols recognised as indicating a fire scar are: $ScarSymb = 'ADEMLUd';
# The list of symbols that indicates a tree is a recording tree are: $StartSymb = $ScarSymb.'|';
# The list of symbols that indicates a tree is finished recording are: $EndSymb = '}]'; - Run the scarprob.pl script (you must have a PERL language interpreter!!!) to compute the probability of scarring "vital statistics". Run the script from a DOS window (or UNIX command shell) with your FHX2 file(s) as arguments, and redirect the output to a temporary file (E.g., "perl scarprob.pl sample1.fhx sample2.fhx sample3.fhx > Output.txt").
Note: before running the script adjust the 'properties' of the DOS window (right-click on the top bar to get menu) so the 'Screen Buffer Size' on the 'Layout' tab has a height of at least 100. This will allow you to scroll back and see all the messages produced by the script.
This script reads in the FHX2 tree-ring data file(s) and runs a number of analyses on each plot. All the trees on a plot are grouped together for analysis. For each such group, all possible tuples (pairs, triples, etc.) of trees are formed, and the common recording period for each tuple is identified. The mark-and-recapture statistic for a tuple is computed by using the first tree as the initial "capture", with all fire years recorded on this tree are "marked". Fire years recorded on subsequent trees in the tuple either identify new fire years, which are "marked", or have already been identified on previous trees, in which case they count as "recaptures". The empirical quantity Gt is also computed for each tuple. See the article above for a complete description of how these quantities are used in the analysis. - The script produces an output file (written to stdout, which you should redirect to a file, as in the example above), and a log of it's activities and any anomalous data records in the FHX2 file (written to the screen, stderr, which will not be redirected to your output file). To find errors in the FHX2 file, do not redirect the output to a file and then the error messages will be interleaved with the output on screen, allowing you to identify the problem areas.
The following fatal errors are reported: File format is not FHX2!! Cause: The first line in the input file MUST read: "FHX2 FORMAT"
Header rows does not equal internal header size!! Cause: The number of header rows identified in the FHX2 input file (third number on the second line) MUST equal the size of the ID string given by the sum of $pIDsize + $tIDsize (see step 3 above)
Tree is defined more than once!! Cause: Two trees (columns) in the FHX2 file have identical ID's (headers). Each tree MUST be identified by a unique ID composed of a plot ID and tree ID (see step 3 above).
BUG—This should never happen!! Cause: This message is printed if the script ever enters an invalid state (fails an invariant test) and it indicates a bug in the script. We have tested the script as best we can, so this should never happen. If it does, please send a copy of your FHX2 file to forestry@sfu.ca with a description of the problem so we can fix the script.
The following anomalies, which may or may not represent errors in the data set or analyses are reported: Plot has < 2 trees, and thus is not included in output!Cause: Only plots with two or more trees can be used for computing the probability of scarring. This may just be a plot that's ignored in this analysis, or may indicate an error in the FHX2 file--check to make sure the plot ID was not misspelled for a single tree, causing it to appear as if it were in a separate plot by itself.
Tuple had no duplicates—not included in mark-recapture! Cause: If a tuple (pair, triple, etc.) of trees did not share at least one fire year in common, then the mark-recapture computation will not work because nothing was ever "recaptured". This case should result in an infinitely small probability of scarring for the tuple, but if this were included it would likely unduly bias the final results. Thus, these cases are simply reported separately, and left out of the final analysis. If you have several of these cases in your data set, it indicates that the mark-recapture estimate likely overestimates the true probability of scarring. The model-fit method does not suffer from this shortcoming.
Finally, a report is generated to summarise the analyses performed:Report for file 'fhx2 file name and 2nd header row'
Typical ID: Plot.Tree = 'sample ID from fhx2 file'
Markers used to indicate fire scars: 'value of $ScarSymb constant'
Markers found in file: 'a list of all markers found in the file'
Error: No start of record for tree 'tree ID' Cause: no start symbol was ever detected for the tree.
Error: No end of record for tree 'tree ID' Cause: no end symbol was ever detected for the tree.
Warning: No fire years found for tree 'tree ID' Cause: no fire scar symbols were detected for the tree.
Be sure to check the output log very carefully each time you run an analysis! Make sure you understand why each message is printed in the log, and what the implications are for the analyses.
The following quantities are computed for further analysis:
N^ = S(Ci * Mt-1)/S(Rt) | Mark-Recapture estimate of N = number of fires in common period.
p^ = Ci /N^ | Mark-Recapture estimate of the fire scar recording rate for a single tree.
Gt = Mt/S(Ci) | Empirical estimate of the function G(t) for model-fit analysis. - The remainder of the analysis is performed by an Excel spreadsheet (you'll need Excel 97 or later). The spreadsheet "ScarProb.xls" included with this package will automate all of the computations and graph the results in a few simple steps.
Start Excel and open the file "ScarProb.xls". You should be on a sheet called "Database" with the instructions for "Step 1" showing. The complete instructions are given below, but are also available right on the spreadsheets:- Click the "Load Data File" button to load the output data file you produced in step 4 above. You will be prompted to select the file, and it will load onto this sheet automatically. Press the "Next" button to go to Step 2. There is another button lower on this page that will completely automate the whole procedure in a single step. However, we strongly recommend that you go through each step until you are completely familiar with the process.
- Click the "Mark-Recapture" button to perform the Mark-and-Recapture analysis. This will copy data from the database sheet, and graph the histogram of recording rates over all trees. The average recording rate is given as the average proportion of fires that actually formed a fire scar on a particular tree. Press the "Next" button to go to Step 3.
- Click the "Fit Model" button to perform the model-fit analysis. This will copy data from the database sheet, and use Excel's Solver to do a 'least-squares' fit of the model, G(t), to the empirical data, Gt. The graph of the model that was fit to the empirical data is shown along with the overall estimate of the probability of scarring.
- Click the "Save Workbook" button to save the workbook you just created to a new file name. Equivalently, you can do a 'File.. Save as' from the Excel menu if you prefer. Note: if you do a straight 'Save' you will overwrite the original template, which may confuse other analyses!
Note: The Excel template makes use of Visual Basic macros to "run the show". You can open the workbook with macros disabled to verify for yourself that they are harmless. However, please read the following disclaimer:
This package is intended for general use and no warranty is implied for suitability to any given task. As far as I know, it contains no harmful macros or viruses. However, I hold no responsibility for your set-up or any damage done while using/installing/modifying this package or the running the scripts or macros it contains.
If you downloaded the file ScarProb.zip from our web site at rem.sfu.ca then I assure you the scripts and macros contained in the package are harmless, and are used only to automate the procedure and compute functions. However, if you received this package from another person, I cannot guarantee that they did not tamper with the code. Please download a registered copy of your own from our web site.
Thanks ;) Have fun.