Table of Contents

1. FCAT Overview
   1. prepare-fvs
   2. run-fvs
   3. gridfire
   4. carbon-data
   5. fofem
   6. delayed-reforestation
   7. quantification
2. Using the reporting microservice
   1. global
   2. report
   3. script-obj
   4. report-obj
   5. sections
   6. content
   7. Special Placeholders
   8. org-meta
   9. Examples
3. Using python
4. Using powershell
   1. Run a Chain of Microservices
   2. Run a Single Microservice
   3. Make a Report

FCAT Overview

FCAT stands for Forest Carbon Analysis Tool.

It consists in running computations, step by step, to provide data outputs to aid decision making for scientists and companies.

The usual computation order for FCAT is the following:

[:fcat/prepare-fvs
 :fcat/run-fvs
 :fcat/gridfire
 :fcat/carbon-data
 :fcat/fofem
 :fcat/delayed-reforestation
 :fcat/quantification]

prepare-fvs

Step that prepares inputs for run-fvs (FVS stands for Forest Vegetation Simulation) step.

The main inputs validations are done in a clj file: src/fcat/prepare_fvs_inputs/prepare_fvs_inputs.clj

Input Arguments:

Arg	Required?	Type	Default
cell-size	False	int	30
external-treatment-raster	False	str(file)	None
include-dead-trees	False	bool	True
regen-kcp	False	str(file)	regen.kcp
aoi-file	False	str(file)	/mnt/share/rem-inputs/ThreeCreeks_UTM11N.shp
past-wf-suffix	False	str	None
buffer	False	int	15000
global-kcp	False	str(file)	global_generic.kcp
treatment-file	False	str(file)	/srv/share/rem-inputs/CM_baseline_project.shp
past-wf-path	False	str(file)	/srv/share/rem/CONUS/CONUS_wildfire_data.tif
past-dist-path	False	str(file)	/srv/share/rem/CONUS/CONUS_disturbance_data.shp
treemap-path	False	str(file)	/srv/share/rem/CONUS/CONUS_treemap.tif
treemap-csv-path	False	str(file)	/srv/share/rem/CONUS/CONUS_tree_table.csv

Outputs:

Main output table is FVS_StandInit in /mnt/share/rem/<project_code>/fvs/runs/FVS_Data.db

run-fvs

The run-fvs runs an R script file directly (resources/scripts/run-fvs/r/execute_fvs.r), passing the input args to it:

The main input for run-fvs step is the FVS_StandInit table (see prepare-fvs outputs).

Input Arguments:

Arg	Required?	Type	Default	Description
auto-out	False	type=str	None	Comma separated list of additional output fields
cycleat	False	type=int(year)	None	Usually "" is used so this is Usually not used
ext-stand-list	False	type=str(file)	None	Path to external stand list
future-wf-params-file	False	type=str	None	Path to a kcp file defining the parameters for future wildfires
exec-wildfires	False	type=bool	True	Execute wildfires scenario
exec-project	False	type=bool	True	Execute project scenario
exec-baseline	False	type=bool	True	Execute baseline scenario

Outputs:

/mnt/share/rem/<project_code>/fvs/runs/FVSOut.db

gridfire

The main inputs validations are done in a clj file: src/fcat/gridfire/gridfire.clj

The clj script file calls some org files with contains scripts to run gridfire in the following order:

• resources/scripts/gridfire/org/export_fvs_gridfire_inputs.org
• resources/scripts/gridfire/org/prepare_gridfire_inputs.org
• resources/scripts/gridfire/org/execute_gridfire.org
  • The gridfire run is called in this script using via babashka: bb /opt/gridfire/src/gridfire/server/sync/call.clj
• resources/scripts/gridfire/org/process_gridfire_outputs.org
  • This script outputs the following file: /mnt/share/rem/<project_code>/gridfire/outputs/average_fire_sizes.csv

Input Arguments:

args	required	type	default	description
num-simulations	False	int	10	Number of simulations to run
fuel-moistures	False	str(csv string)	None	fuel-moistures is an optional argument. It is a comma separated string with 5 numbers (example: "1 , 2 , 3 , 4 , 5" , which represents 1% , 2% , 3% , 4% and 5% respectively)
temperature	False	int	None	Temperature in Fahrenheit
relative-humidity	False	int	None	Relative Humidity in percent
wind-speed-20-ft	False	int	None	Wind Speed(20ft) in miles per hour
wind-from-direction	False	int	None	wind-from-direction in degrees clockwise from north
foliar-moisture	False	int	None	Foliar Moisture in percent

Outputs:

Other outputs can be found in /mnt/share/rem/<project_code>/gridfire/outputs folder.

carbon-data

The carbon-data step uses an org file directly: resources/scripts/process-carbon-data/org/process_carbon_data.org

Input arguments:

args	required	type	default
area-factor	False	float	0.2224

Outputs:

/mnt/share/rem/<project_code>/carbon/carbon_summary_data.csv

fofem

The main inputs validations are done in a clj file: src/fcat/fofem/fofem.clj

FOFEM is run using wine via shell in the directory /home/sig-app/.wine/drive_c/Program Files/FOFEM6.7

The fofem-inputs.csv file is created based off fvs outputs from /mnt/share/rem/<project_code>/fvs/runs/FVSOut.db.

After the input generation, FOFEM is run via command line with the following:

wine FOF_GUI C fofem-input.csv fofem-output.csv fofem-log.csv fofem-error.csv H

Input arguments:

args	required	type	default	description
ten-hr-fm	False	float(positive)	4
thousand-hr-fm	False	float(positive)	10
thousand-hr-per-rotten	False	float(positive)	30
duff-moist	False	float(positive)	15
duff-depth	False	float	1.25	duff depth: any value in inches up to 12
fofem-region	False	str(set)	InteriorWest	Region: InteriorWest; PacificWest; NorthEast or SouthEast
cover-group	False	str(set)	PN	any string
season	False	str(set)	Fall	"Spring"; "Summer"; "Winter" or "Fall"
fuel-cat	False	str(set)	Natural	Fuel category: "Natural" or "Slash"

Outputs:

/mnt/share/rem/<project_code>/fofem/FOFEM_results.csv is generated after processing fofem-output.csv.

delayed-reforestation

The delayed-reforestation step uses an org file directly: resources/scripts/delayed-reforestation/org/delayed_reforestation.org

Input arguments: <none>

Outputs:

/mnt/share/rem/<project_code>/delayed_reforestation/delayed_reforestation.csv

quantification

The quantification step uses an org file directly: resources/scripts/quantification/org/quantification.org

Input arguments:

args	required	type	default	description
region	False	str	Cold Deserts	from ECO_REGIONS.csv file. Current are: "Western Cordillera" "Marine West Coast Forest" "Cold Deserts" "Warm Deserts" "Mediterranean California"
afp	False	float	0.0000968	annual fire probability
carbon-stocks-in-wood-products-tco2e	False	float	0
net-merch-rem-ts	False	float	0

Outputs:

/mnt/share/rem/<project_code>/quantification/report.txt

/mnt/share/rem/<project_code>/quantification/spreadsheet.csv

Using the reporting microservice

The reporting API optionally accepts scripts to be run before the report generation and requires report data to be passed as argument.

The sig_relay_arguments to call submit-job for the reporting microservice are:

Key	Required?	Type	Description
global	yes	json	common arguments between all microservices
report	yes	json	report microservice specific arguments

global

Key	Required?	Type	Description
project-code	yes	string	the name of the project under the project-root (/srv/share/rem/) folder

report

Key	Required?	Type	Description
scripts	no	json (array)	a collection of script-obj
analyst	no	string	a person, team or company name that are involved in the report
report	yes	json	report data representation: report-obj
report-name	yes	string	the report name, which will be part of the file name as well

script-obj

Example: {"script": "./test/scripts/echo.sh", "args": "hello"}

Key	Required?	Type	Description
script	yes	string	the script to run
args	no	string	the script's arguments to run
dir	no	json	the root directory from which the script will run. If absent, /opt/forest-carbon-analysis-tool/ will be used

report-obj

It's a json that represents the report. There are 2 ways to represent a report.

1. Storing the sections it in a configuration file then fetching it. The config-file is a json with keys representing a report and values representing sections.

Key	Required?	Type	Description
config-file	no	string	a file that stores sessions as json (array). If not provided, defaults to resources/config-file.json
report-key	yes	string	an entry key in the config-file

1. Representing the report directly

Key	Required?	Type	Description
sections	no*	json (array)	a collection of section

* not required if using the "config-file/report-key" way

sections

Each section represents a section in the report.

A section has a title and a collection of contents.

Key	Required?	Type	Description
title	yes	string	the section's title
contents	yes	json (array)	a collection of content

content

Each content represents text, a picture or html, that can be inside the report.

Each content can be either:

1. a string
   • If the string ends with .png, .html or .txt for example, their content will be parsed accordingly for the report.
   • If the string ends with .json, the reporting microservice will read the given json file, which must represent a section. This file must reside in the :project-root/:project-code directory
2. or a json object:

Key	Required?	Type	Description
content	yes	string	the content itself
org-meta	no	json	special information to manipulate the content

Special Placeholders

Each content can make use of some special placeholders that will be replaced with their data later.

For example a content can have the following data:

In this report, the :project-dir is the folder which contains all the project data and :conus-dir is the one with some global files...

Then when rendering the report, these contents will be replaced by their respective values. Considering the user passed project-code=Kodama for example:

In this report, the /srv/share/rem/Kodama is the folder which contains all the project data and /srv/share/rem/CONUS is the one with some global files...

Currently the placeholders can be used are:

Key	Value
:project-root	project-root
:project-code	project-code
:project-dir	:project-root/:project-code
:conus-dir	:project-root/CONUS
:report-temp-dir	:project-dir/report/temp
:analyst	analyst

org-meta

We use org-mode to represent a report, thus sometimes there is need to make custom changes in the default way of how the reporting microservice generates the contents.

The org-meta is a json object with the possible following format:

Key	Required?	Type	Description
text	no	boolean	forces the content to be rendered as text (do not try to read file if they have png or html extensions for example)
before	no	string	text to be inserted before the given content
after	no	string	text to be inserted after the given contentt

Examples

• Full example of a sig_relay_arguments json object:

  {
    "global": {
      "project-code": "PLACEHOLDER"
    },
    "report": {
      "analyst": "John Doe",
      "report": {
        "sections": [
          {
            "contents": [
              ":report-temp-dir is very temporary...",
              "some-file.png",
              {
                "content": ":report-temp-dir/gridfire_template.html",
                "org-meta": {
                  "after": "</pre>",
                  "before": "<pre>"
                }
              }
            ],
            "title": "Some title"
          }
        ]
      },
      "report-name": "MyReport",
      "scripts": [
        {
          "args": "treatment-year 2022 project-code "FA002_CM_ft_only" start-year 2021 end-year 2067",
          "script": "resources/run_org_script.el resources/scripts/generate-report/org/prepare_report.org"
        }
      ]
    }
  }
  

Using Python

See the following scripts in resources/doc/ directory in the forest-carbon-analysis-tool repository:

• call-results.py
• call-fcat.py
• call-report-only.py

Using Powershell

Using the FCAT API to Run a Chain of Microservices

In order to submit a job to the FCAT microservice system, you can follow the three simple steps outlined below.

---

Step 1: Create an INI file for your job

Each FCAT job is parameterized by a single INI file, based on the following template:

{global}
project-code=Kodama_fcat_relay_test
project-root=/srv/share/rem
start-year=2024
end-year=2039

{prepare-fvs}
aoi-file=/mnt/share/rem-inputs/FA019_Kodama_aoi.shp
buffer=15000
cell-size=30
external-treatment-raster=
global-kcp=global_generic.kcp
include-dead-trees=true
regen-kcp=Regen_FA019.kcp
treatment-file=/mnt/share/rem-inputs/ThreeCreeks_UTM11N.shp

{run-fvs}
auto-out=
cycleat=
exec-baseline=true
exec-project=true
exec-wildfires=true
ext-stand-list=

{gridfire}
num-simulations=10000

{carbon-data}
area-factor=0.2224

{fofem}

{delayed-reforestation}

{quantification}
region=Cold Deserts
afp=0.0000968
carbon-stocks-in-wood-products-tco2e=0
net-merch-rem-ts=0

You can download this template file from here.

Note: The INI file's name should be something like my-scenario.ini, where my-scenario should be a descriptive identifier for your run.

---

Step 2: Submit your job request to the FCAT API server

To submit your job request, simply download the submit-job.ps1 script to your machine and run it as follows:

1. Connect to the SIG VPN. (Note: If you are running submit-job.ps1 from a SIG virtual machine, it will already be connected to the VPN.)
2. Open a Powershell, navigate to the directory containing my-scenario.ini, and run this command:

   .\submit-job.ps1 my-scenario.ini my-auth-token
   

Note: You should replace my-auth-token with the auth token that you were given by your project manager. This may be changed occasionally for security reasons.

Before the command exits, it will print out a string of numbers and letters. This is your job-id. Save this value somewhere for use in Step 3 below.

---

Step 3: Check on the status of your running job

To check on the status of your running job, simply download the check-job.ps1 script to your machine and run it as follows:

1. Connect to the SIG VPN. (Note: If you are running check-job.ps1 from a SIG virtual machine, it will already be connected to the VPN.)
2. Open a Powershell and run this command:

   .\check-job.ps1 my-job-id my-auth-token
   

Note: You should replace my-job-id with the string of numbers and letters returned by the submit-job.ps1 command in Step 2 above.

Note: You should replace my-auth-token with the auth token that you were given by your project manager. This may be changed occasionally for security reasons.

If your job has not yet completed, you will receive a message explaining that it is still pending.

If your job has completed, you will receive the output value of the final microservice that was run.

---

Using the FCAT API to Run a Single Microservice

In order to submit a job to a specific microservice, you can follow the steps outlined below.

---

Step 1: Download the ps1 script, the sample ini file, make changes to the ini file, and run the ps1 script.

Prepare FVS

call-prepare-fvs-only ps1 file

prepare-fvs ini file

.\call-prepare-fvs-only.ps1 prepare-fvs.ini my-auth-token

---

Run FVS

call-run-fvs-only ps1 file

run-fvs ini file

.\call-run-fvs-only.ps1 run-fvs.ini my-auth-token

---

Gridfire

call-gridfire-only ps1 file

gridfire ini file

.\call-gridfire-only.ps1 gridfire.ini my-auth-token

---

Carbon Data

call-carbon-data-only ps1 file

carbon-data ini file

.\call-carbon-data-only.ps1 carbon-data.ini my-auth-token

---

FOFEM

call-fofem-only ps1 file

fofem ini file

.\call-fofem-only.ps1 fofem.ini my-auth-token

---

Delayed Reforestation

call-delayed-reforestation-only ps1 file

delayed-reforestation ini file

.\call-delayed-reforestation-only.ps1 delayed-reforestation.ini my-auth-token

---

Quantification

call-quantification-only ps1 file

quantification ini file

.\call-quantification-only.ps1 quantification.ini my-auth-token

---

Old Quantification

call-old-quantification-only ps1 file

old-quantification ini file

.\call-old-quantification-only.ps1 old-quantification.ini my-auth-token

---

Argmax

call-argmax-only ps1 file

argmax ini file

.\call-argmax-only.ps1 argmax.ini my-auth-token

---

Spatialize

call-spatialize-only ps1 file

spatialize ini file

.\call-spatialize-only.ps1 spatialize.ini my-auth-token

---

---

Step 2: Execute check-job to get the job results.

---

Using the FCAT API to Make a Report

Step 1: Create an INI file for your report creation job

Each report job is parameterized by a single INI file, based on the following template:

{global}
project-code=FA002_CM_ft_only
project-root=/srv/share/rem

{report}
analyst=Spatial Informatics Group
report-name=Report for FA002_CM_ft_only project
treatment-year=2022
start-year=2021
end-year=2067

You can download this template file from here.

Note: The INI file's name should be something like my-report.ini, where my-report should be a descriptive identifier for your run.

---

Step 2: Submit your report creation request to the FCAT API server

To create a report, download the following files to your machine and run make-report.ps1 as follows:

• make-report.ps1
• regular-report.json
• regular-report-scripts.json
• Connect to the SIG VPN. (Note: If you are running make-report.ps1 from a SIG virtual machine, it will already be connected to the VPN.)
• Open a Powershell, navigate to the directory containing my-report.ini, and run this command:

  .\make-report.ps1 my-report.ini my-auth-token
  

Note: You should replace my-auth-token with the auth token that you were given by your project manager. This may be changed occasionally for security reasons.

Before the command exits, it will print out a string of numbers and letters. This is your job-id. Save this value somewhere for use in Step 3.

---

Step 3: Download the report

To download the report, simply download the download-report.ps1 script to your machine and run it as follows:

1. Connect to the SIG VPN. (Note: If you are running download-report.ps1 from a SIG virtual machine, it will already be connected to the VPN.)
2. Open a Powershell and run this command:

   .\download-report.ps1 my-job-id my-auth-token
   

Note: You should replace my-job-id with the string of numbers and letters returned by the make-report.ps1 command in Step 2 above.

Note: You should replace my-auth-token with the auth token that you were given by your project manager. This may be changed occasionally for security reasons.

If your job has not yet completed, you will receive a message explaining that it is still pending.

If your job has completed, the pdf file will be downloaded to your machine.