Skip to content

quickstart.rst

Latest commit

 

History

History
175 lines (123 loc) · 5.76 KB

quickstart.rst

File metadata and controls

175 lines (123 loc) · 5.76 KB

CMOR Quickstart (fremor)

This guide adapts the README for fre.cmor in NOAA-GFDL/fre-cli for the standalone fremorizer package. The fremor CLI rewrites climate model output with CMIP-compliant metadata ("CMORization") and supports both CMIP6 and CMIP7 workflows.

Comprehensive API and CLI reference material lives in :ref:`usage` and :ref:`commands`. Use this page when you want a concise, end-to-end reminder of what configuration is required and how to invoke each subcommand.

Documentation and References

Getting Started

Initialize CMOR resources

Before CMORizing data, use fremor init to set up required resources:

# Generate a CMIP6 config template and fetch CMIP6 tables
fremor init -m cmip6 -e exp_config.json -t cmip6-tables

# Generate a CMIP7 config template and fetch CMIP7 tables (fast mode)
fremor init -m cmip7 -e exp_config.json -t cmip7-tables --fast

# Only generate a config template (skip table fetching)
fremor init -m cmip6 -e exp_config.json

# Only fetch tables (skip config template)
fremor init -m cmip6 -t cmip6-tables

# Fetch a specific release tag
fremor init -m cmip6 -t cmip6-tables --tag 6.9.33

The init command:

  • Generates experiment configuration JSON templates with required CMIP metadata fields
  • Fetches official MIP tables from trusted GitHub repositories:
  • Supports both git clone (default) and tarball download (--fast) methods

External configuration

fremor relies on external CMIP metadata:

Required user inputs

  • Variable list (JSON) that maps local variable names to MIP names. A small example lives in the repository at fremorizer/tests/test_files/CMORbite_var_list.json.
  • Experiment configuration (JSON) supplying metadata such as calendar, grid, and the desired output directory structure. See fremorizer/tests/test_files/CMOR_input_example.json for CMIP6 or fremorizer/tests/test_files/CMOR_CMIP7_input_example.json for CMIP7.
  • Optional CMOR YAML if you want to batch multiple run calls via fremor yaml. These YAML files are part of the larger FRE workflow and are not shipped here; point -y/--yamlfile at your project-specific YAMLs.

Subcommands and Examples

The entry point to all subcommands is fremor:

fremor --help

init

Initialize CMOR resources by generating experiment configuration templates and/or fetching MIP tables from trusted sources.

# Generate config template and fetch tables
fremor init -m cmip6 -e exp_config.json -t cmip6-tables

# Use fast mode (tarball download instead of git clone)
fremor init -m cmip7 -e exp_config.json -t cmip7-tables --fast

# Fetch a specific release tag
fremor init -m cmip6 -t cmip6-tables --tag 6.9.33

run

Rewrite NetCDF files in a directory using a specific MIP table and experiment configuration.

fremor run --run_one --grid_label gr --grid_desc FOO_BAR_PLACEHOLD --nom_res "10000 km" \
    -d /path/to/input/netcdf/dir \
    -l fremorizer/tests/test_files/CMORbite_var_list.json \
    -r fremorizer/tests/test_files/cmip6-cmor-tables/Tables/CMIP6_Omon.json \
    -p fremorizer/tests/test_files/CMOR_input_example.json \
    -o /tmp/cmorized_output

yaml

Process multiple directories/tables using FRE-flavored YAML configuration. This is most useful inside a full FRE workflow.

fremor -v yaml --run_one --dry_run --output combined.yaml \
    --yamlfile /path/to/cmor.yaml \
    --experiment c96L65_am5f7b12r1_amip \
    --platform ncrc5.intel \
    --target prod-openmp

find

Search MIP tables for variable definitions.

fremor -v find --table_config_dir fremorizer/tests/test_files/cmip6-cmor-tables/Tables/ \
    --opt_var_name sos

varlist

Generate a variable list from a directory of NetCDF files. Optionally filter against a MIP table.

fremor varlist --dir_targ /path/to/data_dir \
    --output_variable_list simple_varlist.json \
    --mip_table fremorizer/tests/test_files/cmip6-cmor-tables/Tables/CMIP6_Omon.json

config

Scan a post-processing directory tree and emit the CMOR YAML plus per-component variable lists that fremor yaml consumes.

fremor config --pp_dir /path/to/pp \
    --mip_tables_dir /path/to/cmip7-cmor-tables/tables \
    --mip_era cmip7 \
    --exp_config /path/to/CMOR_CMIP7_input_example.json \
    --output_yaml cmor_config.yaml \
    --output_dir /path/to/cmor_output \
    --varlist_dir /path/to/varlists \
    --freq monthly --chunk 5yr --grid gn \
    --calendar noleap

In --dry_run mode, fremor yaml prints the generated fremor run calls without executing them. Pass --no-print_cli_call to print the equivalent Python cmor_run_subtool(...) invocation instead of the CLI command.