xbudget.collect.collect_budgets

xbudget.collect.collect_budgets(data, recipe, allow_rechunk=True, on_missing='warn')[source]

Materialize every budget term described by recipe into data.

The recipe dict is parsed into a typed expression tree (xbudget.nodes) and evaluated (xbudget.evaluate.evaluate_budgets()). It does not mutate recipe; it only adds derived variables to the dataset. Each derived variable is named by its term path with operator infixes dropped (e.g. heat_rhs_diffusion_lateral) and carries xbudget_path, xbudget_op, and provenance attributes. Query the result with xbudget.query.BudgetQuery.

Parameters:

  • data (xgcm.Grid or xr.Dataset) – Budget diagnostics to read from and write derived variables into, modified in place. A grid is required if the recipe uses difference or lateral_divergence operations.

  • recipe (dict) – A recipe in xbudget format (e.g. from load_preset_budget).

  • allow_rechunk (bool (default: True)) – Whether to temporarily rechunk when taking differences along a dimension, e.g. to compute flux divergences on center from fluxes on outer or tendencies on center from snapshots on outer.

  • on_missing ({"warn", "raise", "ignore"} (default: "warn")) – How to handle a required diagnostic that a term references but that is absent from data. "warn" (default) skips the term and emits one end-of-run summary UserWarning naming the missing diagnostics and the now-incomplete terms; "raise" raises MissingDiagnosticError so a recipe/dataset mismatch fails loudly; "ignore" skips silently. In every case the affected variables are stamped with xbudget_incomplete / xbudget_missing attributes (query them with xbudget.BudgetQuery.missing()), and a term declared optional in the recipe is exempt — its absence is expected and never alarms.

Returns:

data – The same object passed in, for convenience.

Return type:

xgcm.Grid or xr.Dataset

Examples

Load a preset recipe, collect its budgets into a grid, and query the result:

>>> recipe = xbudget.load_preset_budget(model="MOM6")
>>> xbudget.collect_budgets(grid, recipe)      # adds derived vars in place
>>> q = xbudget.BudgetQuery(grid, recipe)
>>> q.var("heat_rhs")                          # the closed RHS heat tendency
'heat_rhs'
>>> grid._ds["heat_rhs"].attrs["xbudget_path"]
['heat', 'rhs']