Configuration

Schema

Pydantic models for YAML configuration and defaults merging.

class elm_diagnostics.config.schema.PlotStyleConfig(**data)[source]

Bases: BaseModel

Parameters:
figsize: list[float]
dpi: int
palette: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.ClimatologyConfig(**data)[source]

Bases: BaseModel

Parameters:

  • include_climos (bool)

  • climo_start_year (int)

  • climo_end_year (int)

  • envelope (Literal['minmax', 'p10_p90', 'std'])

  • show_individual_years_threshold (int)

include_climos: bool
climo_start_year: int
climo_end_year: int
envelope: Literal['minmax', 'p10_p90', 'std']
show_individual_years_threshold: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.HovmullerConfig(**data)[source]

Bases: BaseModel

Parameters:

  • max_depth_m (float | None)

  • max_levels (int | None)

  • color_limit_method (Literal['full_range', 'quantile', 'sigma_clip'])

  • color_limit_quantile_low (float)

  • color_limit_quantile_high (float)

  • color_limit_sigma (float)

max_depth_m: float | None
max_levels: int | None
color_limit_method: Literal['full_range', 'quantile', 'sigma_clip']
color_limit_quantile_low: float
color_limit_quantile_high: float
color_limit_sigma: float
validate_depth_limits()[source]

Ensure max_levels and max_depth_m are mutually exclusive.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.PlotsConfig(**data)[source]

Bases: BaseModel

Parameters:
style: PlotStyleConfig
climatology: ClimatologyConfig
hovmuller: HovmullerConfig
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.ThumbnailConfig(**data)[source]

Bases: BaseModel

Parameters:
enabled: bool
size: list[int]
dpi: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.ReportSectionsConfig(**data)[source]

Bases: BaseModel

Parameters:

  • metadata (bool)

  • water_balance (bool)

  • energy_balance (bool)

  • carbon_balance (bool)

  • variable_groups (bool)

  • diagnostics (bool)

metadata: bool
water_balance: bool
energy_balance: bool
carbon_balance: bool
variable_groups: bool
diagnostics: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.GroupPlotTypesConfig(**data)[source]

Bases: BaseModel

Parameters:
timeseries: bool
hovmuller: bool
seasonal: bool
anomaly: bool
histogram: bool
diurnal: bool
property active_plot_types: list[str]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.VariableGroupConfig(**data)[source]

Bases: BaseModel

Parameters:
enabled: bool
variables: list[str]
plot_types: GroupPlotTypesConfig
hovmuller: HovmullerConfig | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.VariableSectionsConfig(**data)[source]

Bases: BaseModel

Parameters:

  • max_variables_per_group (int)

  • show_statistics_table (bool)

max_variables_per_group: int
show_statistics_table: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.BalanceSectionsConfig(**data)[source]

Bases: BaseModel

Parameters:

  • show_statistics_table (bool)

  • show_residual_percentage (bool)

show_statistics_table: bool
show_residual_percentage: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.ComparisonConfig(**data)[source]

Bases: BaseModel

Parameters:

  • show_delta_plots (bool)

  • side_by_side_layout (bool)

show_delta_plots: bool
side_by_side_layout: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.MetadataConfig(**data)[source]

Bases: BaseModel

Parameters:

  • show_configuration (bool)

  • show_run_info (bool)

  • show_generation_timestamp (bool)

show_configuration: bool
show_run_info: bool
show_generation_timestamp: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.PerformanceConfig(**data)[source]

Bases: BaseModel

Performance and memory tuning options.

Parameters:

  • chunk_size_mb (int)

  • lazy_evaluation (bool)

  • progress_verbosity (Literal['quiet', 'normal', 'verbose'])

  • slow_operation_threshold_seconds (int)

  • parallel_plot_workers (int)

chunk_size_mb: int
lazy_evaluation: bool
progress_verbosity: Literal['quiet', 'normal', 'verbose']
slow_operation_threshold_seconds: int
parallel_plot_workers: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.ReportConfig(**data)[source]

Bases: BaseModel

Parameters:
title_template: str
output_formats: list[str]
thumbnails: ThumbnailConfig
sections: ReportSectionsConfig
variable_sections: VariableSectionsConfig
balance_sections: BalanceSectionsConfig
comparison: ComparisonConfig
metadata: MetadataConfig
performance: PerformanceConfig
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.TimeConfig(**data)[source]

Bases: BaseModel

Parameters:

  • water_year_start_month (int)

  • analysis_start_year (int | None)

  • analysis_end_year (int | None)

water_year_start_month: int
analysis_start_year: int | None
analysis_end_year: int | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.WaterBalanceConfig(**data)[source]

Bases: BaseModel

Parameters:
storages: list[str]
inputs: list[str]
outputs: list[str]
et_components: list[str]
residual_against: str
frame: Literal['water_year', 'calendar']
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.CH4Config(**data)[source]

Bases: BaseModel

Parameters:
aerenchyma: list[str]
diffusion: list[str]
ebullition: list[str]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.CarbonBalanceConfig(**data)[source]

Bases: BaseModel

Parameters:
mode: Literal['auto', 'bgc', 'sp']
pools: list[str]
fluxes: list[str]
ch4: CH4Config
residual_against: str
frame: Literal['water_year', 'calendar']
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.EnergyBalanceConfig(**data)[source]

Bases: BaseModel

Parameters:
radiation: list[str]
turbulent: list[str]
ground: list[str]
storage: list[str]
errors: list[str]
frame: Literal['water_year', 'calendar']
cumulative: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.BalancesConfig(**data)[source]

Bases: BaseModel

Parameters:
water: WaterBalanceConfig
carbon: CarbonBalanceConfig
energy: EnergyBalanceConfig
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.IOConfig(**data)[source]

Bases: BaseModel

Parameters:
strict_combine: bool
chunk_mode: Literal['off', 'auto', 'manual']
chunk_target_mb: int
chunks: dict[str, int]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class elm_diagnostics.config.schema.Config(**data)[source]

Bases: BaseModel

Top-level configuration.

Parameters:
report: ReportConfig
plots: PlotsConfig
io: IOConfig
time: TimeConfig
balances: BalancesConfig
variable_groups: dict[str, VariableGroupConfig]
get_variable_group_hovmuller_config(varname)[source]

Get hovmuller config for a variable, merging group and global settings.

Parameters:

varname (str) – Variable name to look up

Returns:

Merged hovmuller config with group-specific overrides applied to global settings.

Return type:

HovmullerConfig

Notes

Group-specific settings override global settings only for fields that are explicitly set in the group config. If a variable appears in multiple groups, the first group with hovmuller settings takes precedence.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

elm_diagnostics.config.schema.load_defaults()[source]

Load the package-shipped defaults.yaml.

Return type:

dict[str, Any]

elm_diagnostics.config.schema.load_config(path=None)[source]

Load and validate configuration, merging user config over defaults.

Parameters:

path (str | Path | None) – Path to user config YAML. Falls back to ~/.config/elm-diagnostics/config.yaml if it exists, otherwise uses defaults only.

Return type:

Config