Relative Warming Rate
The Relative Warming Rate (RWR) is a diagnostic for assessing the strength of soil moisture limitation on evapotranspiration, by quantifying how rapidly the land surface warms relative to the overlying atmosphere during dry spells of at least 10 days. The RWR was described using global reanalyses and satellite observations by Gallego-Elvira et al (2016) and used to evaluate CMIP5 models in Gallego-Elvira et al (2019). The RWR code in this repository is merged directly from the dry_spell_rwr repository listed in the code availability statements of those papers.
Global observation-based estimates of soil moisture and evapotranspiration have large uncertainties and compatibility issues that make them difficult to use for climate model evaluation. The RWR was designed to use more routinely available observed and modelled variables to assess soil moisture–evapotranspiration relationships. The diagnostic calculates the difference between land surface and near-surface air temperature anomalies at 1200 LT on clear-sky days during rain-free dry spells. Composite difference in temperature anomalies (TD) is then calculated by averaging across multiple events as a function of day of dry spell, from which RWR is the slope of a linear regression of TD onto day number over days 2 to 10 of the dry spell. (The first dry day is labelled day 1, and is omitted to avoid the strong effect of interception evaporation on surface temperature.)
-
Gallego‐Elvira et al (2016) Global observational diagnosis of soil moisture control on the land surface energy balance. Geophys. Res. Letts., 43, 2623–2631, https://doi.org/10.1002/2016GL068178
-
Gallego-Elvira et al (2019) Evaluation of Regional‐Scale Soil Moisture‐Surface Flux Dynamics in Earth System Models Based on Satellite Observations of Land Surface Temperature, Geophys. Res. Letts., 46, 5480-5488, https://doi.org/10.1029/2019GL082962
Running this recipe will output for each dataset in the recipe (i) netCDF files containing daily input variables at 1200 LT, (ii) a text file of dry spell events and a netCDF file of a spatial field of RWR, and (iii) a standard plot of RWR:
The recipe for this diagnostic is porcpy/recipes/recipe_rwr.yml. It require the following CMOR variables at a 3hr frequency:
-
pr: Preipitation flux (kg m-2 s-1) -
tas: Near-Surface Air Temperature (K) -
tslsi: Surface Temperature Where Land or Sea Ice (K) -
rsds: Surface Downwelling Shortwave Radiation (W m-2) -
rsdscs: Surface Downwelling Clear-Sky Shortwave Radiation (W m-2)
and the following fixed field:
-
sftlf: Percentage of the grid cell occupied by land (including lakes) (%)
All calculations and output files are made on the native grid of the respective model; no spatial interpolation is performed on the data. The recipe defaults to calculating daily total precipitation from 0900 to 0900 LT and interpolating other variables to 1200 LT, but both of these changed in the recipe via local_time setting under the pr and tas variables. Similarly, the analysis period is chosen by setting the start_year and end_year of the tas variable, and both years are included in the analysis:
tas: &var_opt
start_year: 1979
end_year: 1980
local_time: 12.0
pr:
local_time: 9.0Input data are specified by lines in the datasets section of the recipe:
datasets:
- {dataset: CNRM-CM5, project: CMIP5, exp: amip, ensemble: r1i1p1}
- {dataset: MIROC5, project: CMIP5, exp: amip, ensemble: r1i1p1}Additional lines can be added for different models, experiments, and rip variants. A particular model can be included on multiple lines, e.g., for analysing different rip variants or experiments. 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.
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 the dry_spell_rwr package.
The daily netCDF files are created from the 3h input data by calling dry_spell_rwr.utc_to_lt.make_daily_var():
def make_daily_var(files_var, var_name, local_time, weights_func, land_grid,
metadata, ut_var,
file_reader=None, tsPad=(0, 0), tsType=TS_INST,
mdi=FMDI, scale=1.0, offset=0.0, file_out=None):
"""
Driver routine for generating a daily output file for a single
variable from sub-daily input files.
Parameters
----------
files_var : list of str
List of input netCDF file names sorted by time. It is assumed
that time is the record dimension and that these files describe a
complete time series when the data are concatenated.
var_name : str or list of str
Name(s) of variable(s) to be read from the input netCDF file. If
more than one name is passed, then the daily fields for those
variable are added together (np.sum) before being written to the
netCDF file. This is typically used to create total precip output
from separate rainfall and snowfall inputs.
local_time : float, hours in [0., 24.).
The local time of day that is passed to weights_func() and may be
used as part of the daily reduction (e.g., interpolation to
local_time, daily accumulation from local_time to local_time).
weights_func : function
Function that is used to calculate the reduction (e.g.,
interpolation) weights for each land point using a 3-day window.
Users will typically pass in other functions provided by this
module (e.g., <dry_spell_rwr.utc_to_lt.getweights()>), but are
free to define their own as long as those functions provide the
same call signature.
land_grid : <dry_spell_rwr.geogrid.LandGrid> instance
Object that describes the input grid and the mapping from input
grid to a vector of land points.
metadata : dict
Dictionary of metadata used to define the output netCDF file.
Some common examples are defined in <dry_spell_rwr.file_io>. The
dictionary must contain "name", "dtype", "dims", and "fill_value"
fields. It may optionally contain a dict "attributes", the
contents of which will be added as variable attributes.
ut_var : <cftime.utime> instance
Base time used for the time coordinate variable in the OUTPUT
netCDF file. It is really important that this is set correctly,
as it's read by subsequent steps of the dry spell analysis code.
It's up the the user to set this basetime correctly (see notes
below).
file_reader : function, optional
User supplied function to read the input netCDF files. Must have
the same call signature as
<dry_spell_rwr.utc_to_lt.default_file_reader()>.
tsPad : tuple, (npre,npost), optional
Number of times the first (last) time series field should be
duplicated at the start (end) of the series to create a time
series length that is an integer multiple of steps_perday (see
notes below).
tsType : int, optional
Indicate whether the input variable is a time series of means
(TS_MEAN) or instantaneous values (TS_INST, default).
mdi : float, optional
Missing data value of input netCDF variables. NB The missing data
value in the output netCDF file is dry_spell_rwr.FMDI.
scale, offset : floats, optional
Adjustments made to the daily data (xout = x * scale + offset)
before they are written to the output file. NB It's best to make
sure that the units metadata passed to this routine is consistent
with the adjusted data.
file_out : str, optional
Name for output netCDF file. If the file already exists, it will
be clobbered.
Notes
-----
The arguments weights_func, tsPad and ut_var must all be consistent
for this driver routine to give the correct output. Common values of
weights_func (such as <dry_spell_rwr.utc_to_lt.getweights()>) return
interpolation weights assuming that the subdaily time series start at
0000 UTC. If the time series start at a different time of day, e.g.,
0300 UTC, then either,
(1) tsPad should be used to force padding of the time series so that
it starts at a time consistent with weights_func, or,
(2) a weights_func should be passed that produces weights starting
at the correct time of day.
In practice, (1) is easier to do than (2). In either case, ut_var
should have a base time corresponding to midnight on the first date of
the interpolated output. This argument is never interrogated by the
interpolation code, it's simply written into the time coordinate
variable of the OUTPUT netCDF file. So, two time series starting at
0000 UTC and 0300 UTC respectively, would pass the same ut_var (e.g.,
"days since 2000-1-1 0:0:0") and use one of the methods above to
account for the different start times.
"""The dry spells events text file is created by calling dry_spell_rwr.make_dry_spells():
def make_dry_spells(file_precip, file_tas, pr_max=_PR_MAX, tas_min=_TAS_MIN,
dur_min=_DURATION_MIN, ante_pr_days=_DURATION_ANTE,
file_out_ann=None, file_out_seas=None):
"""
Driver routine for generating lists of dry spell events based on daily
precipiation and air temperature.
Parameters
----------
file_precip : str
Name of input netCDF file containing daily precipitation (mm).
file_tas : str
Name of input netCDF file containing daily air temperature (K).
pr_max : float, optional
A day is dry when pr is below this value (default=0.5 mm).
tas_min : float, optional
A day is warm whem tas is above this value (default=10 degC).
dur_min : int, optional
Minimum duration of dry spell in days (default=10).
ante_pr_days : int, optional
Numbers of days to cumulate antecedent rainfall (default=30).
file_out_ann : str, optional
Name of output text file containing dry spell event definitions
for all months.
file_out_seas : str, optional
Name of output text file containing dry spell event definitions
grouped by season.
Notes
-----
A dry spell event is a period of at least dur_min days with daily
precipitation P < pr_max and daily air temperature T > tas_min on
every day. It's up to the user to decide what daily air temperature
is most appropriate: mean, max, at local noon, etc.
"""The output netCDF file of RWR is generated by calling dry_spell_rwr.common_analysis.make_analysis():
def make_analysis(file_events, file_tslsi, file_tas,
file_rsds=None, file_rsdscs=None,
file_sftlf=None, modis_dir=None,
tslsi_name="tslsi", tas_name="tas",
rsds_name="rsds", rsdscs_name="rsdscs",
ut_tslsi=None, ut_tas=None, ut_model=None,
kw_rwr=None, kw_srex=None, kw_srex_rwr=None):
"""
Driver routine for running the dry spell temperature analysis for a
single land surface model. The various parts of this analysis are
common to all models and are usually different ways of dividing up
the events, e.g., by region/season/antecedent precipitation.
Parameters
----------
file_events : str
Name of input text file containing the global catalogue of dry
spells.
file_tslsi : str
Name of input netCDF file containing modelled daily land surface
temperature (K) at a local overpass time.
file_tas : str
Name of input netCDF file containing modelled daily near-surface
air temperature (K) at a local overpass time.
file_rsds : str, optional
Name of input netCDF file containing modelled daily surface
downwelling shortwave radiation (W/m2) at a local overpass time.
file_rsdscs : str, optional
Name of input netCDF file containing modelled daily surface
downwelling shortwave radiation under clear sky (W/m2) at a local
overpass time.
file_sftlf : str, optional
Name of input netCDF file describing the model grid.
modis_dir : str, optional
Directory containing 0.5deg MODIS Terra or Aqua LST observations.
This acts as a switch between offline LSM and online ESM analysis.
tslsi_name : str, optional
Name of land surface temperature variable in file_tslsi.
tas_name : str, optional
Name of near-surface air temperature variable in file_tas.
rsds_name : str, optional
Name of shortwave down variable in file_rsds.
rsdscs_name : str, optional
Name of clear sky shortwave down variable in file_rsdscs.
ut_tslsi : <cftime.utime> instance, optional
If set, this is used instead of the base time from the tslsi
daily input file.
ut_tas : <cftime.utime> instance, optional
If set, this is used instead of the base time from the tas
daily input file.
ut_model : <cftime.utime> instance, optional
If set, this is used instead of the base time from the rsds
daily input file for the ESM analysis.
kw_rwr : dict, optional
List of keyword arguments that will be passed to
calc_global_rwr(). If None then calc_global_rwr() will not be
called.
kw_srex : dict, optional
List of keyword arguments that will be passed to
calc_srex_compos(). If None then calc_srex_rwr() will not be
called.
kw_srex_rwr : dict, optional
List of keyword arguments that will be passed to
calc_srex_rwr(). If None then calc_srex_rwr() will not be
called.
"""The map of global RWR is produced by calling dry_spell_rwr.common_plots.common_plot_rwr_map():
def common_plot_rwr_map(file_rwr, file_grid, file_out, **kwargs):
"""
Make a standard RWR map and save as a PNG image.
Parameters
----------
file_rwr : str
Name of input netCDF file containing RWR data.
file_grid : str
Name of input netCDF file describing the input grid.
file_out : str
Output image file name. Any existing file will be clobbered.
"""