CLIX Python Integration

CLIX Python Integration#

To integrate CLIX climate indicators into your own Python routines, there are two main approaches:

  1. Using the Python API via the pyku.clix.manager.ClimateIndicator class and the :py:func: pyku.clix.core.run_tool_from_dataset

  2. Calling the CLIX command-line interface (CLI) directly from within a Python script

Both methods allow you to calculate climate indicators programmatically, depending on whether you prefer an object-oriented API or a simple CLI-style invocation.

1. Using the Python API#

To use the run_tool_from_dataset() function, set up the input data and optional parameters as shown below.

Here is an example demonstrating how to use the ClimateIndicator class for calculating summer days:

import xarray as xr
from pathlib import Path

from pyku.clix.manager import ClimateIndicator
from pyku.clix.core import run_tool_from_datasets

# Define input file(s) and load them
base_dir = Path('/path/to/hyras/output/tasmax/v6-1/05/')
tasmax_file_name = 'tasmax_hyras_5_2010_v6-1.nc'
tasmax_file_path = base_dir / tasmax_file_name

ds = xr.open_dataset(tasmax_file_path)

# create list of datasets for the run_tool_from_datasets() function
ds_list = [ds]

# Define indicator name (e.g., 'txge25' for summer days)
indicator_name = 'txge25'

# Define frequency for calculation ('MS' -> monthly, 'YS' -> yearly etc.)
frequency = 'MS'

# Define parameters (use an empty dictionary for default indicator setup)
params = {}

# Example of using modified parameters/thresholds (uncomment to test)
# params = {'thresh': '25.6 degC', 'op': '>'}

# retrieve required args from ClimateIndicator
clind = ClimateIndicator(indicator_name, frequency, params)

# Show function name that is used to compute the indicator
print("Xclim function name:", clind.xclim_func_name)

# calculate indicator
result = run_tool_from_datasets(
         ds_list,
         clindicator=clind,
         )

# Save as NetCDF
# retrieve dataset from result dict
# key of dataset can be used to create filename:
for period, ds_out in results.items():
     sd, ed = period
     output_filename = Path(f"summer_days_{sd:%Y%m%d}-{ed:%Y%m%d}.nc")
     ds_out.to_netcdf(output_filename)

print(f"Indicator calculated and saved to {output_filename}")

2. Using the CLI within Python code#

Alternatively, CLIX can be used directly from within a Python program by calling its command-line interface (CLI) entry point. This is useful when you want to run CLIX as if it were executed from the terminal, but under programmatic control.

For example, the following snippet performs a calculation of the mean temperature indicator tmmean on a monthly frequency:

import pyku.clix.core as clix

# Define input file (or input directory)
ifile = 'input_file.nc'

# Define calculation frequency (e.g., 'month', 'year')
frequency = 'month'

# Define the indicator name (e.g., 'tmmean', 'txge25', etc.)
indicator = 'tmmean'

# Call CLIX main function with CLI-style arguments
clix.main(['-ifiles', ifile, '-frequency', frequency, indicator])

This approach internally executes the same routines used by the CLIX command-line tool, allowing seamless integration with other Python workflows or batch processing systems.

Summary: When to Use Which Approach#

Python API (`ClimateIndicator`)

  • Ideal for fine-grained control over input datasets, variable assignment, and parameters.

  • Full functionality from command-line tool, all arguments can be passed to run_tool_from_datasets

CLI Invocation (`clix.main`)

  • Convenient when running multiple indicators in sequence or integrating with scripts that already use CLI-style argument parsing.

  • Matches the behavior of the standalone clix command-line tool.