How to use the command line version of Fragstats 5 from Python
For those you you who did not notice the command line version of Fragstats 5, present in the installation but mostly overlooked, this article will try to fill the gap.
Using the command line is very easy and at the same time powerful as it can be invoked from not just the command prompt directly but also from all sorts of scripts. The focus of today's blog post is the simple integration of the command line Fragstats 5 into Python.
Let's start with the basics. To use frg_cmd.exe, we need three things:
- A model to specify which metrics you want to compute. You can create this with the Fragstats 5 GUI application.
- A batch file that specifies all the grids you want to process. You can create one with a text editor or generate it right within your Python script.
- A path to store the result tables if you are doing a standard analysis. The folder must exist before invoking the command.
The command line would look like this:
frg_cmd /m "C:\fragstats_work\model\my_model.fca" /b "C:\fragstats_work\model\my_batch.fbt" /o "C:\fragstats_work\out\results"
Please note that when specifying the output base path (ex. C:\landscapes\fragstats\out\results), "results" is the common prefix of the output tables and the folder that will hold these tables is "C:\landscapes\fragstats\out\". The folder must exist prior to running frg_cmd otherwise it will not be created.
The output tables will be named: results.patch, results.class, results.land, and results.adj. If a certain analysis level is not selected in the model, the corresponding table will not be created. The same will happen with the adjacency table.
The command line version of Fragstats 5, has become a first class object with its own entry in the start menu from version 5.1. If you have not used it before, you should give it a try. It only needs to be given a model and a user defined batch file and it will do it's job quietly in the command line. Once the analysis is complete you can load the results and further process them. This can happen automatically within a script or it can be done manually.
And here is the code:
# Copyright (c) 2026 eco-logica software solutions inc.
# coding=utf-8
# This is a sample Python script for Fragstats users that need to automate their data processing.
# It shows how you can use frg_cmd.exe, the command line implementation of Fragstats 5 from Python
# It should also work from applications that embed a Python interpreter, like ArcGIS
import os
import csv
import subprocess
# Create a copy of the current environment to pass to our subprocess
env_copy = os.environ.copy()
# the Fragstats path specified below is the standard one,
# if you installed Fragstats in a different location you must use that location
frg_home = r"C:\Program Files\Fragstats 5.1"
# Modify the copy, not os.environ
PATH = env_copy['PATH']
env_copy["PATH"] = frg_home + ';' + PATH
if __name__ == '__main__':
# = = = This is the batch file line format, one line per grid = = = = = = = = = = = = = = = = = = = =
# file_name, cell_size, back_value, row_count, col_count, band_id, no_data, file_type
# sample Fragstats batch file line: C:\tiffs\land5m.tif, x, 999, x, x, 1, x, IDF_GeoTIFF
# the format below works for GeoTIFFs because they report their own number of rows, columns and cell_size
# other formats may need extra information to be provided
# other considerations
# - frg_cmd can do standard analysis on multi-grid batch files, but it can only do single line batch files for
# modes that generate output grids, those modes will not output tables
batch = r'C:\fragstats_work\data\test_cover1.tif, x, 999, x, x, 1, x, IDF_GeoTIFF' + "\n"\
r'C:\fragstats_work\data\test_cover2.tif, x, 999, x, x, 1, x, IDF_GeoTIFF' + "\n"\
r'C:\fragstats_work\data\test_cover3.tif, x, 999, x, x, 1, x, IDF_GeoTIFF' + "\n"\
r'C:\fragstats_work\data\test_cover4.tif, x, 999, x, x, 1, x, IDF_GeoTIFF' + "\n"
# print(batch)
# replace with your actual paths
model_path = r'C:\fragstats_work\model\my_model.fca'
batch_path = r'C:\fragstats_work\model\my_batch.fbt'
# this must be the base name for the output files, and it will generate the following:
# - results.patch
# - results.class
# - results.land
# in the path below: C:\fragstats_work\out\ is the output folder
# "results" is the base name for the tables, you will get: results.patch, results.class, results.land, results.adj if there
# are metrics selected to generate them
output_path_base = r'C:\fragstats_work\out\results'
# save the batch file on disk in order to pass it to frg_cmd
with open(batch_path, "w") as file:
file.write(batch)
# prepare the system call parameters
program_name = "frg_cmd"
arguments = ['/m', model_path,
'/b', batch_path,
'/o', output_path_base]
command = [program_name]
command.extend(arguments)
# run command line Fragstats as a child process
try:
# subprocess.call() will wait for the process to complete
return_code = subprocess.call(command, env=env_copy, shell=True, cwd=frg_home)
print("Program finished with return code: {}".format(return_code))
except Exception as e:
print("An error occurred while launching the program: {}".format(e))
exit(1)
# no exception thrown, let's load the results
patch_results = []
class_results = []
land_results = []
output_patch_file = output_path_base + '.patch'
if os.path.exists(output_patch_file):
with open(output_patch_file, mode='r') as file:
patch_file = csv.reader(file)
for line in patch_file:
#print(line)
patch_results.append(line)
output_class_file = output_path_base + '.class'
if os.path.exists(output_class_file):
with open(output_class_file, mode='r') as file:
class_file = csv.reader(file)
for line in class_file:
#print(line)
class_results.append(line)
output_land_file = output_path_base + '.land'
if os.path.exists(output_land_file):
with open(output_land_file, mode='r') as file:
land_file= csv.reader(file)
for line in land_file:
#print(line)
land_results.append(line)
# verification of the result tables (uncomment to have them printed on screen)
#print(patch_results)
#print(class_results)
#print(land_results)
# insert here the code you need to process the results
The code above is just a starting point, you can use it as is or modify it to suit your needs. For example you can turn it into a module or function that you can invoke from your own Python scripts or other software that include python scripting.
You can also extract the result loading section into a separate script and use it to load results saved from any interactive Fragstats session into a Python script for further processing.
A Fragstats 5 module for Python is currently under development and it will be included in one of the future releases.
Download the Python code here.
If you have questions or issues related to this code, let us know in the forum.
Eduard Ene