Python API #
AFEIM.FLAM.Model runs the whole FLAM chain from Python: ignition probability, burned area, calibration and evaluation. Unlike the GUI, it aligns inputs to the base map automatically, uses all CPU cores, and reports performance scores.
Quick start #
import datetime
import AFEIM
m = AFEIM.FLAM.Model()
m.project_name = 'Example' # no '.', '/', '\' or ':'
m.outfolder = './output'
m.start_date = datetime.datetime(2001, 1, 1)
m.end_date = datetime.datetime(2014, 12, 31)
m.basemap = './basemap.tif' # reference grid
m.input.population = './population.tif' # a file = constant
m.input.fuel = './fuel' # a folder = time series (fuel_YYYY.tif)
m.input.moisture = './moisture' # daily, fraction
m.input.windspeed = './windspeed' # daily, km/h
m.input.lightning = './lightning' # optional, monthly
m.input.A_burn_obs = './ba_monthly' # observed burned area, km²
m.input.calib_years = range(2001, 2011) # remaining years are used for validation
m.dynamic.fuel = 'Yearly'
m.dynamic.lightning = 'Monthly'
m.initialize() # checks inputs, aligns them to the basemap
m.preprocess(force=True) # P_h, F_supp, P_l, P_b, P_m, a, i
m.process() # daily P and A_burn
m.calibration(force=True) # fits q, then reruns process()
m.summary(export=m.outfolder + '/Summary')
m.save('./output/model.pkl') # reload later with AFEIM.FLAM.Model('./output/model.pkl')
initialize() requires population, moisture and windspeed. Also provide fuel; without it, the model expects input from the G4M coupling, which the public build doesn’t include. initialize() copies inputs that don’t match the base map into a subfolder named after project_name, next to the original data.
If an output folder already exists, the methods ask
overwrite? (y/n)in the console. Passforce=True(orforce_P/force_Btoprocess()) to skip the questions in scripts.
Settings #
m.input takes file or folder paths. A file means constant data; a folder means a time series named as described in Input data.
| Attribute | Content |
|---|---|
population, fuel, moisture, windspeed, lightning | As in the GUI |
fuel_litter, fuel_CWD | Use instead of fuel to give litter and coarse woody debris separately. They are summed. |
A_burn_obs | Observed burned area, for calibration and evaluation |
calib_years | Years used for calibration. The other years are used for validation. |
veg_fraction | Vegetated share of each pixel (0–1). It scales ignition probability. |
m.dynamic sets the time step of each input:
| Attribute | Allowed values | Default |
|---|---|---|
population | Constant, Daily, Monthly, Yearly, Decadal | Constant |
fuel | Constant, Daily, Monthly, Yearly | Constant |
A_burn_obs | Constant, Daily, Monthly, Yearly | Monthly |
lightning | Constant, Daily, Monthly, Month-wise (12 climatology files), Yearly | Monthly |
moisture, windspeed | Daily | Daily |
stochastic | False, or an integer random seed. With a seed, ignitions are drawn at random each day. | False |
stochastic_naming | True appends the seed to the output folder name (A_burn_<seed>) | False |
spotting | True adds wind-driven ember spotting to ignition | False |
m.params holds the FLAM parameters:
| Attribute | GUI name | Default |
|---|---|---|
P_UP, P_E | p_up, p_e | 300, 0.43 |
SUPP_MAX, C_SUPP | Supp_max, C_supp | 0.9, 0.025 |
L_F_LOW, L_F_UP | L_f,low, L_f,up | 0.02, 0.85 |
B_LOW, B_UP | B_l, B_u | 200, 1000 |
M_E, P_m_alpha, P_m_beta | m_e, 1.75, m_e_pw | 0.35, 1.75, 2.0 |
U_MAX | u_max | 10.8 |
ignition_factor | — | 1.0; multiplies ignition probability |
H_CONT, L_FUEL | — | 18000, 5000; used only for fire-line intensity (i) |
factor_spot_length, factor_spot_wind | — | 0.006, 1.5; spotting distance |
Other settings:
| Setting | Description |
|---|---|
m.unit.A_burn | Burned-area unit: 'sqkm' (default), 'ha' or 'sqm' |
m.mask | Boolean array of pixels to model. Defaults to the valid pixels of the base map. |
m.region_map | Integer array of region IDs. summary(region=k) then evaluates region k only. |
m.setup.CORE | Number of CPU cores used (default: all but one) |
m.setup.MONTH_STEP | Calibration period length in months: 1 (default), 2, 3, 4, 6 or 12 |
AFEIM.setup['calendar'] | 'gregorian' (default) or '360_day', for climate-model data |
Outputs #
These folders are created in outfolder:
| Folder | Content |
|---|---|
P_h, F_supp, P_l, P_b, P_m | Probability components, as in the GUI |
a, i | Potential burned area (km²) and fire-line intensity (kW/m) per day |
P | Daily ignition probability, stored × 10 000. These files are not interchangeable with the GUI’s P. |
A_burn | Daily burned area, in m.unit.A_burn units |
q | q_01.tif … q_12.tif and q.npy. preprocess() offers to reuse q.npy. |
Report | FLAM_YYYY.png: predicted vs. observed burned area, updated every year |
summary(export=folder) writes:
| File | Content |
|---|---|
summary_1.png | Maps of predicted and observed burned area, plotted as percentile rank |
summary_2.png | Temporal correlation (monthly and yearly) and spatial correlation at increasing smoothing, for training and validation years |
Temporal.csv | Monthly and yearly totals, observed and predicted |
Prediction_YYYY.tif, Observation_YYYY.tif, *_total.tif | Burned-area maps per year and for the whole period |
Stand-alone functions #
| Function | Purpose |
|---|---|
FLAM.daily_moisture(out_folder, temp, prc, hum, wsp, start, end) | Daily Fuel Moisture |
FLAM.daily_moisture_dmc(...), FLAM.daily_moisture_dc(...) | Duff moisture (DMC) and drought code (DC) moisture series |
FLAM.prob_P_h, prob_F_supp, prob_P_l, prob_P_b, prob_P_m | Single probability rasters |
FLAM.calc_potential_BA(wsp, m, output_a) | Potential burned area a |
FLAM.calc_BA(P, a, q, output) | Burned area from P, a and q |
FLAM.BA_from_shape(shp, base_tif, out_folder, timecolumn) | Create Labeling Data |
FLAM.q_2_day(q), FLAM.day_2_q(days) | Convert q to and from expected days of burning |
Tools.tif_2_array(path), Tools.array_to_raster(arr, path, base) | Read and write rasters |
Tools.snap(data, base_map) | Align a raster or folder to a base map |
Tools.netCDF4_to_raster(...) | Rasterize netCDF4 |
Tools.topography(dem, output_slope=...) | Slope and aspect from a DEM |
Tools.pixel_area(raster, 'km2') | Pixel areas, also for geographic CRSs |
Most functions have docstrings, for example help(AFEIM.FLAM.calc_BA).