Developer Guide: global_time_series

This page describes how zi-global-time-series is implemented. For the runtime parameters and output-facing behavior, see global_time_series.

Entry point and main flow

The CLI entry point is zppy_interfaces.global_time_series.__main__:main. The implementation follows this sequence:

  1. __main__._get_args() parses the command-line arguments and builds a zppy_interfaces.global_time_series.utils.Parameters instance.

  2. Parameters normalizes booleans, region aliases, and comma-separated plot selections, then validates that the request is internally consistent.

  3. main() optionally calls create_ocean_ts() when ocean-dependent classic plots are requested with use_ocn=True.

  4. main() then calls run_coupled_global().

  5. run_coupled_global() builds a zppy_interfaces.global_time_series.coupled_global.utils.RequestedVariables object, generates the plots, and optionally creates viewer HTML output.

Key modules

  • zppy_interfaces/global_time_series/__main__.py contains the CLI parser and the top-level control flow.

  • zppy_interfaces/global_time_series/utils.py defines Parameters and the request normalization logic.

  • zppy_interfaces/global_time_series/create_ocean_ts.py creates ocean support time series before plotting when needed.

  • zppy_interfaces/global_time_series/coupled_global/driver.py coordinates original plots, component plots, and viewer generation.

  • zppy_interfaces/global_time_series/coupled_global/eamxx_variables.py maps the canonical (EAM) variable names used by the classic plots onto the EAMxx variables they are read from or derived from, and detects which of the two models wrote the data.

  • zppy_interfaces/global_time_series/coupled_global/mode_pdf.py assembles cumulative PDFs when make_viewer=False.

  • zppy_interfaces/global_time_series/coupled_global/mode_viewer.py and the mix_viewer_* helpers build the viewer pages when make_viewer=True.

Developer notes

  • The classic plot names in plots_original are not the same thing as raw variable names, so the driver keeps them separate from the component-variable lists.

  • The classic plots are written in terms of canonical (EAM) variable names. DatasetWrapper is the only place that knows how those names map onto what is on disk: it detects EAMxx data from the variables it opened, and globalAnnualHelper then applies the EAMxx aliases and derivations from eamxx_variables.py (EAM derivations are hard-coded there). Supporting another model means extending that mapping, not the plotting code.

  • Land plots depend on zppy_land_fields.csv for the accepted variable set, grouping metadata, units, and long names.

  • The driver always writes output relative to results_dir, and viewer mode adds HTML pages on top of the figure generation rather than replacing the underlying plot production.