API reference¶
This page provides an auto-generated summary of metsim’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.
MetSim¶
The main object of the MetSim package. The MetSim object is used to set up and launch forcing generation and/or disaggregation routines.
The MetSim object uses a class dictionary to refer to the model setup, which can be modified after instantiation if necessary. Before calling run or launch on the instance it is required to call the load function to ensure that all of the required parameters have been set and that the input data is sufficient to provide the output specified.
-
class
metsim.metsim.
MetSim
(params: dict, domain_slice={})[source]¶ MetSim handles the distribution of jobs that write to a common file by launching muliple processes and queueing up their writeback so that work can be done while IO is happening.
-
metsim.metsim.
add_prec_tri_vars
(domain)[source]¶ Check that variables for triangle precipitation method exist and have values that are within allowable ranges. Return these variables.
- Parameters
domain – Dataset of domain variables for given location.
- Returns
dur – Array of climatological monthly storm durations. [minutes]
t_pk – Array of climatological monthly times to storm peaks. [minutes]
-
metsim.metsim.
chunk_domain
(chunks, dims)[source]¶ Return a dictionary of chunk slices that can be used to decompose a grid
-
metsim.metsim.
wrap_run_cell
(func: callable, params: dict, ds: xarray.core.dataset.Dataset, state: xarray.core.dataset.Dataset, disagg: bool, out_times: pandas.core.indexes.datetimes.DatetimeIndex)[source]¶ Iterate over a chunk of the domain. This is wrapped so we can return a tuple of locs and df.
- Parameters
func (callable) – The function to call to do the work
params (dict) – Parameters from a MetSim object
ds (xr.Dataset) – Input forcings and domain
state (xr.Dataset) – State variables at the point of interest
disagg (bool) – Whether or not we should run a disagg routine
out_times (pd.DatetimeIndex) – Times to return (should be trimmed 1 day at each end from the given index)
- Returns
df_complete (pd.DataFrame) – A dataframe with the disaggregated data in it
df_base (pd.DataFrame) – A dataframe with the state data in it
Physics¶
physics
-
metsim.physics.
atm_pres
(elev: float, lr: float) → float[source]¶ Atmospheric pressure (Pa) as a function of elevation (m)
- 1
Iribane, J.V., and W.L. Godson, 1981. Atmospheric Thermodynamics, 2nd Edition. D. Reidel Publishing Company, Dordrecht, The Netherlands (p. 168)
- Parameters
elev – Elevation in meters
lr – Lapse rate (K/m)
- Returns
Atmospheric pressure (Pa)
- Return type
pressure
-
metsim.physics.
calc_pet
(rad: numpy.array, ta: numpy.array, dayl: numpy.array, pa: float, dt: float = 0.2) → numpy.array[source]¶ Calculates the potential evapotranspiration for aridity corrections in calc_vpd(), according to Kimball et al., 1997
- Parameters
rad – daylight average incident shortwave radiation (W/m2)
ta – daylight average air temperature (deg C)
dayl – daylength (s)
pa – air pressure (Pa)
dt – offset for saturation vapor pressure calculation
- Returns
Potential evapotranspiration (cm/day)
- Return type
pet
-
metsim.physics.
solar_geom
[source]¶ Flat earth assumption
- Parameters
elev – Elevation in meters
lat – Latitude in decimal format
lr – Lapse rate in K/m
- Returns
(tiny_rad_fract, daylength, flat_potrad, tt_max0)
- Return type
sg
-
metsim.physics.
svp
(temp: numpy.array, a: float = 0.61078, b: float = 17.269, c: float = 237.3)[source]¶ Compute the saturated vapor pressure.
- 2
Maidment, David R. Handbook of hydrology. McGraw-Hill Inc., 1992 Equation 4.2.2.
- Parameters
temp – Temperature (degrees Celsius)
a – (optional) parameter
b – (optional) parameter
c – (optional) parameter
- Returns
Saturated vapor pressure (Pa)
- Return type
svp
-
metsim.physics.
svp_slope
(temp: pandas.core.series.Series, a: float = 0.61078, b: float = 17.269, c: float = 237.3)[source]¶ Compute the gradient of the saturated vapor pressure as a function of temperature.
- 3
Maidment, David R. Handbook of hydrology. McGraw-Hill Inc., 1992. Equation 4.2.3.
- Parameters
temp – Temperature (degrees Celsius)
- Returns
Gradient of d(svp)/dT.
- Return type
dsvp_dT
MtClim¶
MTCLIM
Disagg¶
Disaggregates daily data down to finer grained data using some heuristics
-
metsim.disaggregate.
disaggregate
(df_daily: pandas.core.frame.DataFrame, params: dict, solar_geom: dict, t_begin: list = None, t_end: list = None) → pandas.core.frame.DataFrame[source]¶ Take a daily timeseries and scale it down to a finer time scale.
- Parameters
df_daily – Dataframe containing daily timeseries. Should be the result of one of the methods provided in the methods directory.
params – A dictionary containing the class parameters of the MetSim object.
solar_geom – A dictionary of solar geometry variables
t_begin – List of t_min and t_max for day previous to the start of df_daily. None indicates no extension of the record.
t_end – List of t_min and t_max for day after the end of df_daily. None indicates no extension of the record.
- Returns
A dataframe with sub-daily timeseries.
- Return type
df_disagg
-
metsim.disaggregate.
longwave
(air_temp: numpy.array, vapor_pressure: numpy.array, tskc: numpy.array, params: dict) → numpy.array[source]¶ Calculate longwave. This calculation can be performed using a variety of parameterizations for both the clear sky and cloud covered emissivity. Options for choosing these parameterizations should be passed in via the params argument.
For more information about the options provided in this function see:
- 1
Bohn, T.J., Livneh, B., Oyler, J.W., Running, S.W., Nijssen, B. and Lettenmaier, D.P., 2013. Global evaluation of MTCLIM and related algorithms for forcing of ecological and hydrological models. Agricultural and forest meteorology, 176, pp.38-49, doi:10.1016/j.agrformet.2013.03.003.
- Parameters
air_temp – Sub-daily temperature
vapor_pressure – Sub-daily vapor pressure
tskc – Daily cloud fraction
params – A dictionary of parameters, which contains information about which emissivity and cloud fraction methods to use.
- Returns
A sub-daily timeseries of the longwave radiation
- Return type
lwrad
-
metsim.disaggregate.
prec
(prec: pandas.core.series.Series, t_min: pandas.core.series.Series, ts: float, params: dict, month_of_year: int)[source]¶ Distributes sub-daily precipitation either evenly (uniform) or with a triangular (triangle) distribution, depending upon the chosen method.
- Note: The uniform disaggregation returns only through to the beginning of
the last day. Final values are filled in using a forward fill in the top level disaggregate function
- Parameters
prec – Daily timeseries of precipitation. [mm]
t_min – Daily timeseries of minimum daily temperature. [C]
ts – Timestep length to disaggregate down to. [minutes]
params – A dictionary of parameters, which contains information about which precipitation disaggregation method to use.
month_of_year – Timeseries of index of month of year
- Returns
A sub-daily timeseries of precipitation. [mm]
- Return type
prec
-
metsim.disaggregate.
pressure
(temp: numpy.array, elev: float, lr: float) → numpy.array[source]¶ Calculates air pressure.
- Parameters
temp – A sub-daily timeseries of temperature
elev – Elevation
lr – Lapse rate
- Returns
A sub-daily timeseries of air pressure (kPa)
- Return type
pressure
-
metsim.disaggregate.
relative_humidity
(vapor_pressure: numpy.array, temp: numpy.array) → numpy.array[source]¶ Calculate relative humidity from vapor pressure and temperature.
- Parameters
vapor_pressure – A sub-daily timeseries of vapor pressure
temp – A sub-daily timeseries of temperature
- Returns
A sub-daily timeseries of relative humidity
- Return type
rh
-
metsim.disaggregate.
set_min_max_hour
(tiny_rad_fract: numpy.array, yday: numpy.array, n_days: int, ts: int, params: dict) → Tuple[numpy.array][source]¶ Determine the time at which min and max temp is reached for each day.
- Parameters
tiny_rad_fract – Array of fraction of shortwave radiation received at a shortened timestep. This should be calculated by metsim.physics.solar_geom.
yday – Array of day of year for each simulated day.
n_days – Number of days in run.
ts – Timestep of run.
params – Dictionary of parameters to use. Must contain utc_offset and tmax_daylength_fraction.
- Returns
A tuple containing 2 timeseries, corresponding to time of min and max temp, respectively
- Return type
(t_t_min, t_t_max)
-
metsim.disaggregate.
shortwave
(sw_rad: numpy.array, daylength: numpy.array, day_of_year: numpy.array, tiny_rad_fract: numpy.array, params: dict) → numpy.array[source]¶ Disaggregate shortwave radiation down to a subdaily timeseries.
- Parameters
sw_rad – Daily incoming shortwave radiation
daylength – List of daylength time for each day of year
day_of_year – Timeseries of index of days since Jan-1
tiny_rad_fract – Fraction of the daily potential radiation during a radiation time step defined by SW_RAD_DT
params – Dictionary of parameters from the MetSim object
- Returns
A sub-daily timeseries of shortwave radiation.
- Return type
disaggrad
-
metsim.disaggregate.
specific_humidity
(vapor_pressure: numpy.array, air_pressure: numpy.array) → numpy.array[source]¶ Calculates specific humidity
- Parameters
vapor_pressure – A sub-daily timeseries of vapor pressure (kPa)
air_pressure – A sub-daily timeseries of air pressure (kPa)
- Returns
A sub-daily timeseries of specific humidity
- Return type
spec_humid
-
metsim.disaggregate.
temp
(t_min: numpy.array, t_max: numpy.array, out_len: int, t_t_min: numpy.array, t_t_max: numpy.array, ts: int, t_begin: list = None, t_end: list = None) → numpy.array[source]¶ Disaggregate temperature using a Hermite polynomial interpolation scheme.
- Parameters
t_min – Timeseries of daily minimum temperatures.
t_max – Timeseries of daily maximum temperatures.
out_len – Length of the required output vector.
t_t_min – Times at which minimum daily temperatures are reached.
t_t_max – Times at which maximum daily temperatures are reached.
ts – Timestep for disaggregation
t_begin – List of t_min and t_max for day previous to the start of df_daily. None indicates no extension of the record.
t_end – List of t_min and t_max for day after the end of df_daily. None indicates no extension of the record.
- Returns
A sub-daily timeseries of temperature.
- Return type
temps
-
metsim.disaggregate.
tskc
(tskc: numpy.array, ts: int, params: dict) → numpy.array[source]¶ Disaggregate cloud fraction with uniform interpolation
- Parameters
tskc – Daily cloud fraction
ts – Time step to disaggregate to (in minutes)
- Returns
Sub-daily timeseries of cloud fraction
- Return type
tskc
-
metsim.disaggregate.
vapor_pressure
(vp_daily: numpy.array, temp: numpy.array, t_t_min: numpy.array, n_out: int, ts: int) → numpy.array[source]¶ Calculate vapor pressure. First a linear interpolation of the daily values is calculated. Then this is compared to the saturated vapor pressure calculated using the disaggregated temperature. When the interpolated vapor pressure is greater than the calculated saturated vapor pressure, the interpolation is replaced with the saturation value.
- Parameters
vp_daily – Daily vapor pressure
temp – Sub-daily temperature
t_t_min – Timeseries of minimum daily temperature
n_out – Number of output observations
ts – Timestep to disaggregate down to
- Returns
A sub-daily timeseries of the vapor pressure
- Return type
vp
-
metsim.disaggregate.
wind
(wind: numpy.array, ts: int, params: dict) → numpy.array[source]¶ Wind is assumed constant throughout the day Note: this returns only through to the beginning of the
last day. Final values are filled in using a forward fill in the top level disaggregate function
- Parameters
wind – Daily timeseries of wind
ts – Timestep to disaggregate down to
- Returns
A sub-daily timeseries of wind
- Return type
wind