Configuration

GridFIA uses Pydantic v2 for type-safe configuration management. Settings can be loaded from files, environment variables, or created programmatically.

Overview

Class	Description
GridFIASettings	Main settings class
CalculationConfig	Individual calculation configuration
ProcessingConfig	Processing parameters
VisualizationConfig	Visualization parameters
OutputFormat	Supported output formats

Quick Start

from gridfia import GridFIA, GridFIASettings
from gridfia.config import CalculationConfig

# Use default settings
api = GridFIA()

# Load from file
api = GridFIA(config="config/production.yaml")

# Programmatic configuration
settings = GridFIASettings(
    output_dir="results",
    calculations=[
        CalculationConfig(name="species_richness", enabled=True),
        CalculationConfig(name="shannon_diversity", enabled=True),
    ]
)
api = GridFIA(config=settings)

GridFIASettings

Main settings class for GridFIA application.

Bases: BaseSettings

Main settings class for GridFIA application.

app_name class-attribute instance-attribute

app_name: str = 'GridFIA'

debug class-attribute instance-attribute

debug: bool = Field(default=False, description='Enable debug mode')

verbose class-attribute instance-attribute

verbose: bool = Field(default=False, description='Enable verbose output')

data_dir class-attribute instance-attribute

data_dir: Path = Field(default=Path('data'), description='Base directory for data files')

output_dir class-attribute instance-attribute

output_dir: Path = Field(default=Path('output'), description='Base directory for output files')

cache_dir class-attribute instance-attribute

cache_dir: Path = Field(default=Path('.cache'), description='Directory for caching intermediate results')

visualization class-attribute instance-attribute

visualization: VisualizationConfig = Field(default_factory=VisualizationConfig)

processing class-attribute instance-attribute

processing: ProcessingConfig = Field(default_factory=ProcessingConfig)

calculations class-attribute instance-attribute

calculations: List[CalculationConfig] = Field(default_factory=lambda: [CalculationConfig(name='species_richness', parameters={'biomass_threshold': 0.0}), CalculationConfig(name='total_biomass', enabled=False), CalculationConfig(name='shannon_diversity', enabled=False)], min_length=1, description='List of calculations to perform (must not be empty)')

species_codes class-attribute instance-attribute

species_codes: List[str] = Field(default_factory=list, description='List of valid species codes')

get_output_path

get_output_path(filename: str) -> Path

Get full output path for a filename.

get_temp_path

get_temp_path(filename: str) -> Path

Get temporary file path.

Attributes

Attribute	Type	Default	Description
app_name	str	"GridFIA"	Application name
debug	bool	False	Enable debug mode
verbose	bool	False	Enable verbose output
data_dir	Path	"data"	Base directory for data files
output_dir	Path	"output"	Base directory for output files
cache_dir	Path	".cache"	Directory for caching
visualization	VisualizationConfig	(defaults)	Visualization parameters
processing	ProcessingConfig	(defaults)	Processing parameters
calculations	List[CalculationConfig]	(defaults)	Calculations to perform
species_codes	List[str]	[]	Valid species codes

Environment Variables

Settings can be configured via environment variables with the GRIDFIA_ prefix:

export GRIDFIA_DEBUG=true
export GRIDFIA_VERBOSE=true
export GRIDFIA_OUTPUT_DIR=/data/results
export GRIDFIA_DATA_DIR=/data/input
export GRIDFIA_CACHE_DIR=/tmp/gridfia_cache

from gridfia import GridFIA

# Settings loaded from environment
api = GridFIA()
print(f"Debug: {api.settings.debug}")
print(f"Output: {api.settings.output_dir}")

Configuration Files

Settings can be loaded from YAML or JSON files:

YAML ConfigurationJSON Configuration

# config.yaml
app_name: GridFIA Analysis
debug: false
verbose: true
output_dir: results/
data_dir: data/

visualization:
  default_dpi: 300
  default_figure_size: [16, 12]
  color_maps:
    biomass: viridis
    diversity: plasma
    richness: Spectral_r

processing:
  max_workers: 4
  memory_limit_gb: 16.0

calculations:
  - name: species_richness
    enabled: true
    parameters:
      biomass_threshold: 0.5
  - name: shannon_diversity
    enabled: true
    output_format: geotiff
  - name: total_biomass
    enabled: true

{
  "app_name": "GridFIA Analysis",
  "debug": false,
  "verbose": true,
  "output_dir": "results/",
  "calculations": [
    {
      "name": "species_richness",
      "enabled": true,
      "parameters": {"biomass_threshold": 0.5}
    },
    {
      "name": "shannon_diversity",
      "enabled": true
    }
  ]
}

CalculationConfig

Configuration for individual forest metric calculations.

Bases: BaseModel

Configuration for forest metric calculations.

Attributes

Attribute	Type	Default	Description
name	str	(required)	Name of the calculation
enabled	bool	True	Whether calculation is enabled
parameters	Dict[str, Any]	{}	Calculation-specific parameters
output_format	OutputFormat	GEOTIFF	Output format for results
output_name	Optional[str]	None	Custom output filename

Example

from gridfia.config import CalculationConfig, OutputFormat

# Basic calculation
calc = CalculationConfig(name="species_richness")

# With parameters
calc = CalculationConfig(
    name="species_richness",
    enabled=True,
    parameters={"biomass_threshold": 1.0},
    output_format=OutputFormat.GEOTIFF,
    output_name="richness_map"
)

# Disabled calculation
calc = CalculationConfig(
    name="total_biomass",
    enabled=False
)

ProcessingConfig

Configuration for data processing parameters.

Bases: BaseModel

Configuration for data processing parameters.

validate_temp_dir classmethod

validate_temp_dir(v)

Ensure temp directory exists or can be created.

Attributes

Attribute	Type	Default	Description
max_workers	Optional[int]	None	Max worker processes (auto-detect)
memory_limit_gb	float	8.0	Memory limit in GB
temp_dir	Optional[Path]	None	Temporary directory

Example

from gridfia.config import ProcessingConfig
from pathlib import Path

# Default processing
config = ProcessingConfig()

# High-performance configuration
config = ProcessingConfig(
    max_workers=8,
    memory_limit_gb=32.0,
    temp_dir=Path("/fast_ssd/tmp")
)

VisualizationConfig

Configuration for visualization parameters.

Bases: BaseModel

Configuration for visualization parameters.

Attributes

Attribute	Type	Default	Description
default_dpi	int	300	Default DPI for images (72-600)
default_figure_size	Tuple[float, float]	(16, 12)	Figure size in inches
color_maps	Dict[str, str]	(see below)	Default colormaps
font_size	int	12	Default font size (8-24)

Default color maps:

{
    "biomass": "viridis",
    "diversity": "plasma",
    "richness": "Spectral_r"
}

Example

from gridfia.config import VisualizationConfig

# Publication-quality settings
config = VisualizationConfig(
    default_dpi=600,
    default_figure_size=(12, 10),
    font_size=14,
    color_maps={
        "biomass": "YlGn",
        "diversity": "RdYlBu",
        "richness": "Spectral"
    }
)

OutputFormat

Enum for supported output formats.

Bases: str, Enum

Supported output formats for calculation results.

Values

Value	String	Description
GEOTIFF	"geotiff"	GeoTIFF format (best for GIS)
ZARR	"zarr"	Zarr format (best for large outputs)
NETCDF	"netcdf"	NetCDF format (best for xarray)

Example

from gridfia.config import CalculationConfig, OutputFormat

# GeoTIFF output (default)
calc = CalculationConfig(
    name="species_richness",
    output_format=OutputFormat.GEOTIFF
)

# Zarr output for large datasets
calc = CalculationConfig(
    name="total_biomass",
    output_format=OutputFormat.ZARR
)

# NetCDF for xarray workflows
calc = CalculationConfig(
    name="shannon_diversity",
    output_format=OutputFormat.NETCDF
)

Helper Functions

load_settings

Load settings from file or environment.

PARAMETER	DESCRIPTION
config_file	Optional path to configuration file TYPE: Optional[Path] DEFAULT: None

RETURNS	DESCRIPTION
GridFIASettings	Configured settings instance

from gridfia.config import load_settings
from pathlib import Path

# Load from YAML file
settings = load_settings(Path("config/production.yaml"))

# Load from JSON file
settings = load_settings(Path("config/settings.json"))

# Load from environment/defaults
settings = load_settings()

save_settings

Save settings to file.

PARAMETER	DESCRIPTION
settings_obj	Settings to save TYPE: GridFIASettings
config_file	Path to save configuration TYPE: Path

from gridfia.config import GridFIASettings, save_settings, CalculationConfig
from pathlib import Path

settings = GridFIASettings(
    output_dir="results/",
    calculations=[
        CalculationConfig(name="species_richness", enabled=True),
        CalculationConfig(name="shannon_diversity", enabled=True),
    ]
)

# Save to JSON file
save_settings(settings, Path("config/my_settings.json"))

Usage Patterns

Complete Configuration Example

from gridfia import GridFIA, GridFIASettings
from gridfia.config import (
    CalculationConfig,
    ProcessingConfig,
    VisualizationConfig,
    OutputFormat
)
from pathlib import Path

# Create comprehensive settings
settings = GridFIASettings(
    app_name="Forest Diversity Analysis",
    debug=False,
    verbose=True,
    data_dir=Path("data"),
    output_dir=Path("results"),
    cache_dir=Path(".cache"),

    processing=ProcessingConfig(
        max_workers=4,
        memory_limit_gb=16.0
    ),

    visualization=VisualizationConfig(
        default_dpi=300,
        default_figure_size=(16, 12),
        font_size=12
    ),

    calculations=[
        CalculationConfig(
            name="species_richness",
            enabled=True,
            parameters={"biomass_threshold": 0.5},
            output_format=OutputFormat.GEOTIFF,
            output_name="richness"
        ),
        CalculationConfig(
            name="shannon_diversity",
            enabled=True,
            output_format=OutputFormat.GEOTIFF
        ),
        CalculationConfig(
            name="simpson_diversity",
            enabled=True
        ),
        CalculationConfig(
            name="total_biomass",
            enabled=True,
            output_format=OutputFormat.ZARR
        ),
    ]
)

# Use with GridFIA
api = GridFIA(config=settings)
results = api.calculate_metrics("data/forest.zarr")

Dynamic Configuration

from gridfia import GridFIASettings
from gridfia.config import CalculationConfig

# Start with defaults
settings = GridFIASettings()

# Modify settings
settings.output_dir = Path("new_results")
settings.processing.memory_limit_gb = 32.0

# Add calculations dynamically
available_calcs = ["species_richness", "shannon_diversity", "evenness"]
settings.calculations = [
    CalculationConfig(name=calc, enabled=True)
    for calc in available_calcs
]

Environment-Based Configuration

import os
from gridfia import GridFIA, GridFIASettings

# Set environment variables for different environments
if os.getenv("ENVIRONMENT") == "production":
    os.environ["GRIDFIA_OUTPUT_DIR"] = "/data/production/results"
    os.environ["GRIDFIA_DEBUG"] = "false"
else:
    os.environ["GRIDFIA_OUTPUT_DIR"] = "./dev_results"
    os.environ["GRIDFIA_DEBUG"] = "true"

# Settings automatically loaded from environment
api = GridFIA()

Validation

Pydantic automatically validates all configuration values:

from gridfia.config import GridFIASettings, VisualizationConfig
from pydantic import ValidationError

# Invalid DPI (must be 72-600)
try:
    config = VisualizationConfig(default_dpi=1000)
except ValidationError as e:
    print(f"Validation error: {e}")

# Empty calculations list (must have at least 1)
try:
    settings = GridFIASettings(calculations=[])
except ValidationError as e:
    print(f"Validation error: {e}")

See Also

• GridFIA Class - Main API using configuration
• Data Models - Related Pydantic models
• Calculations - Available calculation names