Skip to content

Terrestrial coupling index

Jump to bottom
ppharris edited this page Apr 17, 2020 · 4 revisions

Overview

This is a simple implementation of the terrestrial coupling index (TCI) described in Dirmeyer (2011), which quantifies the strength of coupling between land and atmosphere owing to soil moisture. Here the TCI corresponds to Eqn (1) of Dirmeyer (2011):

TCI_le = beta_le * sd_w

where TCI_le is the index with respect to latent heat flux, beta_le is the slope of correlation between latent heat and soil moisture and sd_w is the standard deviation of soil moisture. We calculate TCI for each meteorological season (DJF, MAM, JJA, SON) from monthly model outputs, so the index represents a mixture of inter-annual and intra-seasonal variability. We integrate soil moisture over the top 1 m as an approximation of the root zone (more specifically, over model soil layers that are entirely within the top 1 m).

Outputs

Running this recipe will output for each dataset in the recipe (see below) (i) a netCDF file containing spatial fields of TCI for each season, (ii) a plots of TCI for each season:

ESMValTool recipe

The recipe for this diagnostic is porcpy/recipes/recipe_tci.yml. It requires the following CMOR variables:

  • mrlsl (CMIP5) or mrsol (CMIP6): Total Water Content of Soil Layer (kg m-2)
  • hfss: Surface Upward Sensible Heat Flux (W m-2)
  • hfls: Surface Upward Latent Heat Flux (W m-2)

Using CMIP6 data currently requires manually changing the variable name and MIP table for soil moisture in the recipe:

      mrsol:
        preprocessor: soil_metre
        modeling_realm: [land]
        mip: Emon

The recipe defaults to using monthly data, but it will work with daily data by pointing to a different MIP table in the recipe, e.g., change mip: Amon to mip: day. In either case, we strongly recommend using the same data frequency across all input variables.

Input data are specified by lines in the datasets section of the recipe:

datasets:
  - {dataset: CNRM-CM5, project: CMIP5, exp: amip, ensemble: r1i1p1, start_year: 1980, end_year: 2000}
  - {dataset: MIROC5, project: CMIP5, exp: amip, ensemble: r1i1p1, start_year: 1980, end_year: 2000}

Additional lines can be added for different models, experiments, rip variants and analysis periods. A particular model can be included on multiple lines, e.g., for analysing different rip variants or years. Including lines more than once is likely to result in an error as the ESMValTool preprocessor will try to generate intermediate files with the same name but is not permitted to overwrite existing files. In the recipe as currently written, it's not possible to mix CMIP5 and CMIP6 models because of differences in the soil moisture variable specification mentioned above.

Main interface

ESMValTool provides a convenient preprocessor front-end to this diagnostic, but users can invoke it directly from their own code by calling driver routines in porcpy/diag_scripts/tci_terrestrial_coupling.py. Iris Cubes of TCI are returned by make_tci():

def make_tci(filename_sm, filename_hf, filename_tci,
             standard_name_sm="moisture_content_of_soil_layer",
             standard_name_hf="surface_upward_latent_heat_flux",
             standard_name_tci="terrestrial_coupling_index",
             varname_tci="tci",
             alpha=None):
    """Driver routine for calculating a terrestrial coupling index (TCI).

    Parameters
    ----------
    filename_sm : str
        Name of input netCDF file containing soil moisture time series.
    filename_hf : str
        Name of input netCDF file containing surface heat flux time series,
        e.g., sensible of latent heat.
    filename_tci : str
        Name of output netCDF file containing terrestrial coupling index for a
        selection of calendar seasons.  Any existing file with the same name
        will be clobbered.
    standard_name_sm : str, optional
        NetCDF standard_name for input soil moisture data.
    standard_name_hf : str, optional
        NetCDF standard_name name for input surface heat flux data.
    standard_name_tci : str, optional
       NetCDF standard_name for output TCI data.
    varname_tci : str, optional
        NetCDF variable name for output TCI data.
    alpha : float, optional
        Type I error rate (p-value) above which correlations are rejected in
        the calculation of TCI.  Values in the range (0, 1).

    Returns
    -------
    tci : iris.cube.Cube
        Terrestrial coupling index for a selection of seasons.

    """

Standard plots are made by calling plot_tci():

def plot_tci(data_tci, file_out_plot, title=None):
    """Output a plot of seasonal maps of terrestrial coupling index.

    Parameters
    ----------
    data_tci : iris.cube.Cube
        Cube of terrestrial coupling index to be plotted.  This must have the
        auxiliary coord "season", e.g., as added by
        iris.coord_categorisation.add_season().
    file_out_plot : str
        Output image file name.  Any existing file with this name will be
        clobbered.
    title : str, optional
        Title to be added to the overall plot as a fig.suptitle().  If absent,
        a basic title is added instead.

    """
Clone this wiki locally