FFT Webtool: User Documentation

 

Batch processing

For larger sets of fuelbeds, use the Spreadsheet to XML tools for bulk editing then run batches of fuelbeds by calling the FCCS & Consume calculators from a command prompt.

Running FCCS & Consume From Command Line


Prerequisites: Java and Python installed with PATH environment variable updated on your computer.

Start by downloading and unzipping the FccsConsumeCommandLine.zip file (unzipping to the C:\ drive in this example).

Contents of extracted FccsConsumeCommandLine.zip file

The command line instructions for each tool (FCCS_Command_line_instructions.docx and Consume5_CommandLine_instructions.docx) included in this package will be the most up-to-date and will supersede those given here where different. These instructions assume that Java and Python are installed with environment variables configured for command line use. Instructions below are for Windows/DOS users. Instructions for Linux/other users are given in the zip file's Word documents.

Running FCCS at the command line

  1. Set up your FCCS environment
    1. Locate the fuelbed.jar file contained in the zip file.
    2. Add fuelbed .xml files to the folder that contains the fuelbed.jar file (in this example, C:\FccsConsumeCommandLine\). Copy your custom fuelbeds into their own folder ("fuelbeds_custom" in this example) and/or download and unzip FCCS fuelbed packages:
      1. FCCS Reference fuelbeds (base package of original 946 FCCS fuelbeds)
        Download | File documentation
      2. FCCS Disturbance fuelbeds (~15K files)
        Created for LANDFIRE, these are the 'disturbed' (i.e., post fire, thinning operation, blowdown, or insect damage) versions of the FCCS reference fuelbeds.
        Download
      3. Natural Fuels Photo Series fuelbeds (434 files)
        Created to represent the sites sampled for the Natural Fuels Photo Series. Browse by volume at the Digitial Photo Series website.
        Download
      4. Region 6 pathway fuelbeds (487 files)
        Fuelbeds developed for the US Forest Service Region 6 (PNW) to simulate changes in fuelbeds along management and successional pathways initiated by stand-replacement events, such as wildfires, various harvesting techniques, or insect damage/disease.
        Download | File documentation
    3. If you plan to specify custom fuel moistures, create a new folder ("ev_files" in this example) and copy the sample fuel moisture file (sample_fccs_moisture.csv) from the input_files folder into it to use as a template. (Skip this step to accept the benchmark D2L2 moisture profile.)

      FCCS fuel moisture inputs file data dictionary
      This optional file contains a header followed by a single row of values that will apply to all fuelbeds in the given run.
      Column name Definition Benchmark values
      oneHourFM Fuel moisture % of 1-hr fuels (e.g., < 0.25” in diameter) 6
      tenHourFM Fuel moisture % of 1-hr fuels (e.g., 0.25-1” in diameter) 7
      hundredHourFM Fuel moisture % of 1-hr fuels (e.g., 1-3” in diameter) 8
      liveNonWoodyFM Fuel moisture % of live forbs and graminoids 60
      liveShrubFM Fuel moisture % of live shrubs 90
      crownFM Fuel moisture % of live canopy 60

      The sample file is populated with the FCCS default/benchmark fuel moisture percents (D2L2). Here is the list of D#L# moisture profiles for reference.
      FM Code FM Desc 1,10,100,herb,shrub,crown
      D1L1 Very low dead, fully cured herb 3,4,5,30,60,60
      D1L2 Very low dead, 2/3 cured herb 3,4,5,60,90,90
      D1L3 Very low dead, 1/3 cured herb 3,4,5,90,120,120
      D1L4 Very low dead, fully green herb 3,4,5,120,150,150
      D2L1 Low dead, fully cured herb 6,7,8,30,60,60
      D2L2 Low dead, 2/3 cured herb 6,7,8,60,90,90
      D2L3 Low dead, 1/3 cured herb 6,7,8,90,120,60
      D2L4 Low dead, fully green herb 6,7,8,120,150,90
      D3L1 Moderate dead, fully cured herb 9,10,11,30,60,90
      D3L2 Moderate dead, 2/3 cured herb 9,10,11,60,90,90
      D3L3 Moderate dead, 1/3 cured herb 9,10,11,90,120,120
      D3L4 Moderate dead, fully green herb 9,10,11,120,150,120
      D4L1 High dead, fully cured herb 12,13,14,30,60,120
      D4L2 High dead, 2/3 cured herb 12,13,14,60,90,150
      D4L3 High dead, 1/3 cured herb 12,13,14,90,120,150
      D4L4 High dead, fully green herb 12,13,14,120,150,150

      Edit copies of this file to create custom fuel moisture scenarios. E.g., you could save the csv file with D1L1 values and name it 'D1L1.csv' to get outputs under drier conditions. That file would look like:
      oneHourFM,tenHourFM,hundredHourFM,liveNonWoodyFM,liveShrubFM,crownFM
      3,4,5,30,60,60
    4. Assuming you downloaded the base (reference) fuelbeds package and created the two folders for custom inputs, your file structure will now look something like:
  2. Open a command prompt. In Windows, you can type "cmd" in the search box of the Start menu to open a DOS window. The following instructions will be for Windows users.
  3. Change directories to the fccs folder that contains the fuelbed.jar file. In our example, at the C prompt type:
    cd C:\FccsConsumeCommandLine\fccs\fccs
  4. To test the waters, type
    java –jar fuelbed.jar
    to get basic usage instructions with the full list of argument options and example code.
  5. Run FCCS. The only required argument to run FCCS is the path to fuelbed(s). To run FCCS for all fuelbeds within a folder (e.g., "fuelbeds_custom") using benchmark (default) fuel moistures, type:
    java –jar fuelbed.jar fuelbeds_custom\*.xml

    • Important: you will need to type the commands in manually as copying and pasting from your browser to the DOS prompt causes errors (the hyphen in HTML renders improperly when pasted into a DOS window.
    • If you get a 'Java not recognized' error double check that you have Java installed and that the executable is added to your computer's PATH environmental variable. This page has a nice walk-through.
    • If you get a ' Error: Could not find or load main class ?jar' error recheck your syntax and paths and make sure you hand-entered in the '-jar' part of the command line. This error is typical when you copy/paste commands or when you're not in the same directory as the fccs.jar file.
       
    In this example we had 3 fuelbeds in the fuelbeds_custom folder. If all goes well, you will get a message similar to: 'Elapsed: 0m 1s Files processed: 3' before the C: prompt returns.

    Two output files will be created in the same folder as the fccs.jar file: fccs_summary.csv (FCCS outputs) and consume_loadings.csv (the input file needed to run Consume for given fuelbeds).
  6. To specify optional environmental parameters use the -p indicator followed by parameter name=parameter value. Here's the syntax to run the fuelbeds in the fuelbeds_custom folder using the dry D1L1 scenario we saved in the ev_files folder, with 10mph windspeed (instead of the default of 4mph) and 15% slope (instead of 0%):
    java –jar fuelbed.jar fuelbeds_custom\*.xml –p moisture_file=ev_files\D1L1.csv -p windspeed=10 -p slope=15
  7. To convert the output file (fccs_summary.csv) to metric values, type:
    python fccs_post_process.py fccs_summary.csv metric_all.csv metric_output.csv true
  8. For other arguments, such as specifying an output filename and location, please refer to the help Word document included in the zip file.

Running Consume (building from above instructions)

The Consume 5 calculator module contains the consumption equations published in:
Prichard et al. 2017. Predicting forest floor and woody fuel consumption from prescribed burns in southern and western pine ecosystems of the United States. Forest Ecology and Management 405:328-338. The Consume source code was written in Python and can be cloned from GitHub repository https://github.com/pnwairfire/fera-apps-consume.

  1. Unzip the consume.zip file contained in the zip file.
  2. Organize your input files.
    1. Create 2 folders in the Consume working directory (the folder that contains the consume_batch.py file, in this case C:\FccsConsumeCommandLine\consume):
      'loadings' for the fuelbed loadings file generated by FCCS (consume_loadings.csv) and
      'ev_files' to store your Consume environmental variables files.
    2. Copy the consume_loadings.csv file created by running FCCS above from C:\FccsConsumeCommandLine\fccs\fccs to the loadings folder.
    3. Copy the various sample environmental variables input files from the C:\FccsConsumeCommandLine\input_files folder into the Consume ev_files folder to use as templates (recommend using sample_activity_input_9_52.csv and sample_natural_input_9_52.csv, which contain scenarios for a hypothetical run with fuelbed numbers 9 and 52). Unlike with FCCS, where the ev file contains a single row of moisture values that apply to all fuelbeds in a given run, Consume's ev file contains one row for every fuelbed in the run, corresponding to the fuelbeds given in the consume_loadings.csv file. The columns needed depend on whether you specify natural or activity fuels at command line.
    4. Edit the appropriate sample environmental variables file to match the fuelbeds in your run. In the example FCCS run above we ran 3 fuelbeds, so we would need to copy/paste a 3rd row, update the fuelbed numbers to the ones in this run, and change any of the burn time conditions as needed. Refer to the Consume EV file data dictionary for more information. In this example we'll save the file as 'natural_ev.csv'.
    The file structure of the Consume working directory will now look like:
  3. Open a command prompt and change into the Consume working directory (the folder that contains the consume_batch.py file). In our example:
    cd C:\FccsConsumeCommandLine\consume
  4. Consume requires python 3.10+. Check your python installation by typing:
    python –-version

    If you get a ‘Python was not found’ message, you may either need to install (or reinstall) python, or add the executable to your computer’s PATH variable.
  5. Set up a virtual environment in which to run Consume. The following commands require you have the Python virtual environment creator venv and the package installer pip installed on your system. You will have to run all 3 of these commands the first time you run Consume on your system. Thereafter you only enter the first 2 commands (as the required packages will have already been installed).

    python -m venv my310env    [Note: might take several seconds before the cursor reappears]
    my310env\Scripts\activate.bat (my310env)    [This starts the virtual environment, denoted by (my310env) appearing before the C: prompt]
    pip install -r requirements.txt    [*1st time only*]

    Here's what you should see if all goes well (truncated):

    After a long scroll, the screen should revert to the command prompt within the virtual environment.
  1. Run Consume.
    Consume required command line arguments:
    1. Burn type (activity or natural)
      Activity refers to a burn in recent logging slash and Natural refers to a burn in natural fuels that have not been influenced by recent logging or other disturbances (e.g., wind throw) .
    2. Environmental inputs file (e.g., natural_ev.csv).
      See data dictionaries for natural/activity input files below.
      Note: each fuelbed has to have a corresponding input file record.
    3. Consume loadings file designated with the -f option.

    Example command line entries using the directory structure above: 
    python consume_batch.py natural ev_files\natural_ev.csv –f loadings\consume_loadings.csv
    python consume_batch.py activity ev_files\activity_ev –f loadings\consume_loadings.csv

    Here's an example for a natural fire and what you should see if all went well:

    If you get the error "Invalid fuelbed specified", that probably means there's a mismatch between your loadings and ev file. Check that the environmental variables file has the same fuelbeds as the loadings file.

    The Consume output file (consume_results.csv) has 195 columns (view data dictionary).

    Review of Consume command line arguments:
    Variable Sample arguments Definitions
    Burn type activity
    natural    		 Activity refers to a burn in recent logging slash and Natural refers to a burn in natural fuels that have not been influenced by recent logging or other disturbances (e.g., wind throw)
    Environmental inputs file input_western.csv, sample_activity_inputs.csv,
    sample_natural_inputs.csv    		 The environmental input file specifies environmental variables listed in the table below for each fuelbed listed in the fccs_loadings.csv file.
    Consume loadings file -f fccs_loadings.csv Consume loadings by fuelbed stratum.  This file is a standard output of FCCS calculations (either batch or within the FFT).
    Additional optional arguments are detailed in Consume5_CommandLine_instructions.docx (included in the zip file). 

    Consume environmental inputs file data dictionary
    This optional file should have the same number of records as the fccs_loadings.csv.
    Field Definition (units) Sample data
    fuelbeds Fuelbed number in fccs_loadings.csv (one per row) 220u1
    area Area (acres) 1
    fm_duff Fuel moisture content of duff (%) 40
    fm_1000hr Fuel moisture content of 1000-hr fuels (%) 15
    can_con_pct Percent of canopy stratum blackened by fire (%) 0
    shrub_black_pct Percent of shrub stratum blackened by fire (%) 50
    pile_black_pct Percent consumption of piles (%) 90
    units Tons or Mg/ha tons
    ecoregion Region applicable to natural burn types (boreal, southern, or western) western
    fm_litter Fuel moisture content of litter (%) 10
    season Winter, spring, summer, or fall fall
    duff_pct_available % duff available for consumption, 0-100% 55
    sound_cwd_pct_available % sound coarse woody debris available for consumption, 0-100% 55
    rotten_cwd_pct_available % rotten coarse woody debris available for consumption, 0-100% 70
    Activity fuels only:
    slope Slope gradient (%) 0
    windspeed Windspeed (mph) 4
    days_since_rain Number of days since significant rainfall (> ¼ inch) 7
    length_of_ignition Time to ignite burn unit (min.) 30
    fm_type Type of fuel moisture (MEAS-Th or NFDRS-Th) MEAS-Th
    fm_10hr Fuel moisture of 10-hr wood 10

Spreadsheet Utilities

For advanced users to edit larger sets of fuelbeds offline in a single spreadsheet. Populate a spreadsheet with given fuelbed XML files, edit as needed, then save edited fuelbeds to XML files for running in batch mode or uploading to the FFT Webtool.

FFTSpreadsheetTools.zip: ZIP file includes 2 Python scripts: 1) fuelbedsToSpreadsheet.py populates a spreadsheet (CSV) with given XML files, and conversely 2) spreadsheetToFuelbeds.py generates fuelbed XML files from a spreadsheet (either the CSV file generated above or the included Excel template (_fuelbedInputTemplate.xslx)). Limited validation support is provided re fuelbed structure and values.

fuelbedsToSpreadsheet: populate a spreadsheet with a directory of fuelbeds
With 138 columns to populate (149 with optional loadings fields included), it's helpful to seed your spreadsheet with preexisting fuelbeds to then edit as needed. The fuelbedsToSpreadsheet tool will populate a CSV spreadsheet with fuelbeds in a given directory to get you started. You can work in the CSV file or if you prefer to work in the colorful Excel template, you can copy the rows from the CSV to a copy of the included _fuelbedInputTemplate.xlsx (just be careful to line the columns up). Either are accepted as input for the spreadsheetToFuelbeds tool.

  1. Open a command window and change directory to the folder containing both the python file (fuelbedsToSpreadsheet.py) and the subfolder containing your fuelbed XML files (e.g., myFuelbeds).
    >cd C:\MyDocuments\FFT\FFTSpreadsheetTools
     
  2. Call the program by typing "python fuelbedsToSpreadsheet.py" followed by 3 arguments (separated by spaces): a units toggle (1 = imperial, 2 = metric), the name of the directory with XML fuelbeds, and the desired name of the CSV output file. Note: data are always stored in imperial units in the XML files, so specifying metric will have the app populate the spreadsheet with converted numbers with several digits after the decimal point.
    >python fuelbedsToSpreadsheet.py 2 myFuelbeds myFuelbeds.csv

spreadsheetToFuelbeds: generate FCCS XML fuelbeds from spreadsheet
The spreadsheet template has 149 columns representing all the data contained in a fuelbed. Refer to the 'Data Dictionary' tab of the Excel template for column definitions, data types, measurement units, and expected formats. Some important things to note:

  1. spreadsheetToFuelbeds.py accepts either the included formatted Excel template file (with shading to demark the fuelbed strata in the first 5 rows, column names in row 6) or a simplified CSV file with column names on row 1. With the exception of species composition fields, the tool expects the data in the spreadsheet to conform with how the data are stored in a fuelbed XML file. Do not delete any columns. The spreadsheet you use as input for the tool should have 147 columns, running from columns A to EQ.
  2. ID fields. Many fields (generally shown as drop-down menus in the Webtool) require ID numbers corresponding to values (e.g., litter arrangement type). Tooltips are provided in the column headers with the options to choose from. See also FFT Help - Appendix Tables - FCCS Fuelbed ID Fields for definitions.
  3. Species/relative cover percents. Throughout a fuelbed, species/relative cover percents are required for the various fuelbed substrata groups (e.g., Overstory trees, rotten wood). To handle these variablely-sized lists in a single cell, the tool expects a list of SPECIES:PERCENT pairs (using a colon to separate species from percent) separated by pipes (|). Species should be given as their ITIS taxonomic serial number (TSN) or USDA PLANTS Database symbol (unique acronym). See FFT Help - Appendix Tables - FCCS Species for the full list of species supported by FCCS, along with their TSN and PLANTS Symbols. If your species is not supported by FCCS at this time, we suggest selected a surrogate species that's closely related.
    Example entries for overstory tree species composition: PSME:75|PIPO:25 or 183424:75|183365:25
  4. Measurement units. See the data dictionary for imperial vs. metric units expected. All data are stored in imperial units in the fuelbed XML files, so specify metric (2) in the argument line if your spreadsheet data are in metric so the tool can do the necessary conversions. You may notice decimal 'creep' after multiple round trips between spreadsheet and fuelbed due to rounding errors when working in metric.
  5. The 'all-or-nothing' rule. If a fuelbed doesn't contain a certain substratum (e.g., a grassland that has no trees) leave all cells for nonpresent substrata BLANK (or, if you prefer, you can enter 'NA' which the app will replace with null). The tool will skip over these groups which is how non-presence of fuelbed substrata is indicated. A single value entered in a given field group toggles that group to 'present', which will spark errors if not every field (including species/percents if applicable) for that subgroup is populated (the one exception being optional loadings for shrubs, litter, duff, etc. which can be left blank). The 'all-or-nothing' groups are: overstory, midstory, understory, snag 1, snag 1 other, snag 2, snag 3, ladder fuels, shrub 1, shrub 2, herb 1, herb 2, sound wood, rotten wood, sound stumps, rotten stumps, lightered/pitchy stumps, moss, ground lichen, litter, upper duff, lower duff, squirrel middens, basal accumulations. Each of these groups are more or less stand alone and can be either present or absent from a given fuelbed.
  6. Piles. FCCS includes piled fuels as a fuelbed component of the Wood Stratum. While the online app supports defining pile groups in detail with inputs needed to calculate loading, these utilities only support the storage of the loadings themselves (by cleanliness class). Going back and forth between spreadsheet-generated fuelbeds and FFT Online could lead to piles data being dropped.

After your spreadsheet is complete, open a command prompt and (assuming python is set up on computer):

  1. Change directory to the folder containing both the python file (spreadsheetToFuelbeds.py) and the spreadsheet template (e.g., fuelbedInputTemplate.xlsx).
    >cd C:\MyDocuments\FFT\spreadsheetToFuelbeds
     
  2. Call the program by typing "python spreadsheetToFuelbeds.py" followed by 3 arguments (separated by spaces): a units toggle (1 = imperial, 2 = metric), the name of the spreadsheet template (or full path if file in a different folder), and the name of the folder to write the XML files to (this last is optional, if omitted the app will write the files to a folder titled 'fuelbeds'). Assuming a spreadsheet with fuelbed inputs entered in metric, the command line text will look like:
    >python spreadsheetToFuelbeds.py 2 myFuelbedInputTemplate.xlsx

    The tool also accepts the CSV version of the spreadsheet template which matches the output of the fuelbedsToSpreadsheet tool.
    >python spreadsheetToFuelbeds.py 1 myFuelbeds.csv

The converter will screen for fuelbed validation errors (e.g., missing required fields or unsupported species) that wouldn't be caught outside of the FFT Webtool interface. Refer to the _validationErrors.csv file after each run for details.