Command-Line Interface

CLI entry point for elm-diagnostics.

elm_diagnostics.cli.setup_logging(verbose=False, debug=False)[source]

Configure logging based on verbosity flags.

Return type:

None

Parameters:
elm_diagnostics.cli.validate_path(path, require_elm_files=True)[source]

Validate that a path exists and optionally contains ELM files.

Parameters:

  • path (str) – Path to validate.

  • require_elm_files (bool) – If True, check for ELM history files.

Returns:

Validated path object.

Return type:

Path

Raises:

typer.Exit – If path is invalid.

elm_diagnostics.cli.validate_config(config_path)[source]

Validate that a config file exists and is readable.

Return type:

Path

Parameters:

config_path (str)

elm_diagnostics.cli.complete_balance_type(incomplete)[source]

Auto-complete balance types.

Return type:

list[str]

Parameters:

incomplete (str)

elm_diagnostics.cli.complete_plot_kind(incomplete)[source]

Auto-complete plot kinds.

Return type:

list[str]

Parameters:

incomplete (str)

elm_diagnostics.cli.report(path=<typer.models.ArgumentInfo object>, compare=<typer.models.OptionInfo object>, out=<typer.models.OptionInfo object>, config=<typer.models.OptionInfo object>, last_n_years=<typer.models.OptionInfo object>, verbose=<typer.models.OptionInfo object>, debug=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Generate a full diagnostics report.

Creates an HTML report with water, carbon, and energy balance diagnostics, along with plots for individual variables. The report includes balance closure statistics, time series plots, seasonal cycles, and more.

Examples:

# Basic report elm-diagnostics report /path/to/elm/output

# Report using year window from config elm-diagnostics report /path/to/elm/output –config config.yaml

# Analyze only the last 5 years elm-diagnostics report /path/to/elm/output –last-n-years 5

# Comparison report elm-diagnostics report /path/to/exp –compare /path/to/control

# Custom output directory elm-diagnostics report /path/to/output –out my_report

Return type:

None

Parameters:
elm_diagnostics.cli.balance(kind=<typer.models.ArgumentInfo object>, path=<typer.models.ArgumentInfo object>, out=<typer.models.OptionInfo object>, config=<typer.models.OptionInfo object>, last_n_years=<typer.models.OptionInfo object>, verbose=<typer.models.OptionInfo object>, debug=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Compute and plot a single budget balance.

Calculates water, carbon, or energy balance closure and generates two-panel plots: cumulative components and decomposition.

Examples:

# Carbon balance, save to directory elm-diagnostics balance carbon /path/to/output –out ./results/

# Energy balance, all available years elm-diagnostics balance energy /path/to/output

# Water balance, last 3 years only elm-diagnostics balance water /path/to/output –last-n-years 3

Return type:

None

Parameters:
elm_diagnostics.cli.plot(varname=<typer.models.ArgumentInfo object>, path=<typer.models.ArgumentInfo object>, kind=<typer.models.OptionInfo object>, out=<typer.models.OptionInfo object>, config=<typer.models.OptionInfo object>, last_n_years=<typer.models.OptionInfo object>, verbose=<typer.models.OptionInfo object>, debug=<typer.models.OptionInfo object>, quiet=<typer.models.OptionInfo object>)[source]

Plot a single variable.

Generate various plot types for ELM output variables including time series, Hovmuller diagrams, seasonal cycles, annual anomalies, histograms, and diurnal cycles.

Examples:

# Time series plot (default) elm-diagnostics plot GPP /path/to/output

# Seasonal cycle elm-diagnostics plot RAIN /path/to/output –kind seasonal

# Save to file elm-diagnostics plot GPP /path/to/output –out gpp_timeseries.png

# Histogram with verbose output elm-diagnostics plot ER /path/to/output –kind histogram –verbose

# Plot only the last 10 years elm-diagnostics plot GPP /path/to/output –last-n-years 10

Return type:

None

Parameters: