Reference

pyCAT Dataset

class pycat.io.Dataset(directory, filename, constraints=None, callback=None)

A Dataset is holding meta data for an iris.cube.Cube

temporal period and spatial extent as well as cube attributes can be set before actually retrieving data from disk

__init__(directory, filename, constraints=None, callback=None)

Args:

  • directory (str):
    path to the data
  • filename (str):
    glob pattern of data files

Kwargs:

  • constraints (iris.Constraint):
    any valid constraint on the data
  • callback (callable):
    a function to add metadata to the cube | function signature: (cube, field, filename)
adjustments

adjustments to correct the cube’s metadata, e.g. units, standard_name

Getter:returns the adjustments
Setter:sets the adjustments
Type:dict
extent

the spatial extent of the dataset

Getter:returns the extent
Setter:sets the extent
Type:tuple of 4 floats (north, east, south, west) in geographical coordinates that describe the bounding box
get_cube(extra_constraints=None)

return the cube of the Dataset constrainted by period and extent (if they have been set) and extra constraints given in the call

also all adjustments, i.e. units, standard_name, … are applied

Kwargs:

Returns:

the concatenated constrained cube of the Dataset
period

the temporal extent of the dataset

Getter:returns the period
Setter:sets the period
Type:tuple of two datetime.datetime (begin, end), where the begin is included but the end is excluded

Bias correction

class pycat.esd.BiasCorrector(call_func, observation, model, scenarios, reference_period=None, correction_period=None, time_unit='day', work_dir='/tmp', interpolator=<sphinx.ext.autodoc.importer._MockObject object>, save_regridded=False)

Bases: object

Base class for all bias correction classes

__init__(call_func, observation, model, scenarios, reference_period=None, correction_period=None, time_unit='day', work_dir='/tmp', interpolator=<sphinx.ext.autodoc.importer._MockObject object>, save_regridded=False)

Args:

  • call_func (callable):
    call signature: (obs_cube, ref_cube, sce_cubes, *args, **kwargs)
  • observation (io.Dataset):

    the observation dataset

  • model (io.Dataset):

    the model dataset

  • scenarios (io.Dataset or list of those)

    the scenarios that shall be bias corrected

Kwargs:

  • reference_period (tuple of datetime.datetime):
    the reference period that observations and model share; if not given, take it from the observation and model reference dataset, respectively
  • correction_period (tuple of datetime.datetime):
    the period for which the correction shall be done; if not given, take it from the scenario dataset
  • time_unit (str):
    correction will be performed on daily (day) or monthly (month) basis
  • interpolator:
    an available interpolation scheme for regridding to the observational dataset. Currently available schemes are:
  • work_dir (path):
    directory where intermediate files will be written
  • save_regridded (boolean):
    wheter regridded data shall be stored to disk (default: False)
correct(unit_list=None, *args, **kwargs)

assemble data that is given to the actual correction function

kwargs are passed to call_func()

Args:

  • unit_list (None, int, iterable):
    depending on self.time_unit this is interpreted as all days/months of year (None), single day/month (int) or list of days/months (iterable)
class pycat.esd.QuantileMapping(observation, model, scenarios, window=15, *args, **kwargs)

Bases: pycat.esd.BiasCorrector

convenience class for quantile mapping

__init__(observation, model, scenarios, window=15, *args, **kwargs)

Args:

  • call_func (callable):
    call signature: (obs_cube, ref_cube, sce_cubes, *args, **kwargs)
  • observation (io.Dataset):

    the observation dataset

  • model (io.Dataset):

    the model dataset

  • scenarios (io.Dataset or list of those)

    the scenarios that shall be bias corrected

Kwargs:

  • reference_period (tuple of datetime.datetime):
    the reference period that observations and model share; if not given, take it from the observation and model reference dataset, respectively
  • correction_period (tuple of datetime.datetime):
    the period for which the correction shall be done; if not given, take it from the scenario dataset
  • time_unit (str):
    correction will be performed on daily (day) or monthly (month) basis
  • interpolator:
    an available interpolation scheme for regridding to the observational dataset. Currently available schemes are:
  • work_dir (path):
    directory where intermediate files will be written
  • save_regridded (boolean):
    wheter regridded data shall be stored to disk (default: False)
class pycat.esd.ScaledDistributionMapping(observation, model, scenarios, *args, **kwargs)

Bases: pycat.esd.BiasCorrector

convenience class for scaled distribution mapping

__init__(observation, model, scenarios, *args, **kwargs)

Args:

  • call_func (callable):
    call signature: (obs_cube, ref_cube, sce_cubes, *args, **kwargs)
  • observation (io.Dataset):

    the observation dataset

  • model (io.Dataset):

    the model dataset

  • scenarios (io.Dataset or list of those)

    the scenarios that shall be bias corrected

Kwargs:

  • reference_period (tuple of datetime.datetime):
    the reference period that observations and model share; if not given, take it from the observation and model reference dataset, respectively
  • correction_period (tuple of datetime.datetime):
    the period for which the correction shall be done; if not given, take it from the scenario dataset
  • time_unit (str):
    correction will be performed on daily (day) or monthly (month) basis
  • interpolator:
    an available interpolation scheme for regridding to the observational dataset. Currently available schemes are:
  • work_dir (path):
    directory where intermediate files will be written
  • save_regridded (boolean):
    wheter regridded data shall be stored to disk (default: False)

Bias correction functions

A bias correction function operates on 2 iris.cube.Cubes – observation, model reference – and a iris.cube.CubeList holding any desired number of future model iris.cube.Cubes. The correction will be applied to all future models with the same reference data.

Any correction function must have the following singature: obs_cube (iris.cube.Cube), mod_cube (iris.cube.Cube), sce_cubes (iris.cube.CubeList), *args, **kwargs

pycat.esd.methods.absolute_sdm(obs_cube, mod_cube, sce_cubes, *args, **kwargs)

apply absolute scaled distribution mapping to all scenario cubes assuming a normal distributed parameter

Args:

Kwargs:

  • cdf_threshold (float):
    limit of the cdf-values (default: .99999)
pycat.esd.methods.quantile_mapping(obs_cube, mod_cube, sce_cubes, *args, **kwargs)

Quantile Mapping

apply quantile mapping to all scenario cubes using the distributions of obs_cube and mod_cube

Args:

pycat.esd.methods.relative_sdm(obs_cube, mod_cube, sce_cubes, *args, **kwargs)

apply relative scaled distribution mapping to all scenario cubes assuming a gamma distributed parameter (with lower limit zero)

if one of obs, mod or sce data has less than min_samplesize valid values, the correction will NOT be performed but the original data is output

Args:

Kwargs:

  • lower_limit (float):
    assume values below lower_limit to be zero (default: 0.1)
  • cdf_threshold (float):
    limit of the cdf-values (default: .99999999)
  • min_samplesize (int):
    minimal number of samples (e.g. wet days) for the gamma fit (default: 10)
pycat.esd.methods.scaled_distribution_mapping(obs_cube, mod_cube, sce_cubes, *args, **kwargs)

Scaled Distribution Mapping

apply scaled distribution mapping to all scenario cubes

the method works differently for different meteorological parameters

  • air_temperature
    absolute_sdm() using normal distribution
  • precipitation_amount, surface_downwelling_shortwave_flux_in_air
    relative_sdm() using gamma distribution

Args:

Utilities

Utility functions needed for generating temporal constraints on iris.cube.Cubes

pycat.esd.utils.generate_day_constraint_with_window(day_of_year, window, calendar='standard')

generate two iris.Constraints for the time axis:

  1. for the exact day of the year over all years
  2. including all days over all years that lie within day_of_year ± window

Args:

  • day_of_year (int):
    day of the year in the given calendar
  • window (int):
    the size of the temporal window around the given day (in days)
  • calendar (str):
    a supported calendar: standard (default), gregorian, proleptic_gregorian, noleap, 365_day, all_leap, 366_day, 360_day
Returns:
a 2-tuple of iris.Constraints on the time axis
pycat.esd.utils.generate_month_constraint(month)

generate an iris.Constraint on the time-axis for a specified month

Args:

  • month (int):
    the desired month (1..jan, 12..dec)

Returns:

an iris.Constraint on the time-axis
pycat.esd.utils.generate_year_constraint_with_window(year, window)

generate a iris.Constraint on the time axis for specified year ± window

Args:

  • year (int):
    centered year for the constraint
  • window (int):
    number of years around the given year

Returns:

an iris.Constraint on the time-axis